Module: ActiveJob::Temporal::Client

Defined in:
lib/activejob/temporal/client.rb

Overview

Note:

TLS Configuration Precedence config.tls takes precedence, followed by configured certificate file paths, then legacy environment variables.

Note:

Environment Variables

  • TEMPORAL_TLS_CERT: TLS certificate (PEM format, full content)
  • TEMPORAL_TLS_KEY: TLS private key (PEM format, full content)
  • TEMPORAL_TLS_SERVER_NAME: TLS server name for verification

Builds Temporal client connections.

This module encapsulates the logic for connecting to a Temporal cluster with optional TLS configuration. TLS options can be provided via configuration attributes or environment variables.

Examples:

Basic connection

config = ActiveJob::Temporal.config
client = Client.build(config)

TLS via environment variables

ENV["TEMPORAL_TLS_CERT"] = File.read("cert.pem")
ENV["TEMPORAL_TLS_KEY"] = File.read("key.pem")
ENV["TEMPORAL_TLS_SERVER_NAME"] = "temporal.example.com"
client = Client.build(config)

TLS via configuration object

ActiveJob::Temporal.configure do |config|
  config.tls = {
    client_cert: File.read("cert.pem"),
    client_private_key: File.read("key.pem"),
    domain: "temporal.example.com"
  }
end
client = ActiveJob::Temporal.client

Constant Summary collapse

TLS_OPTIONS_CLASS = 
if defined?(Temporalio::Client::Connection::TLSOptions)
  Temporalio::Client::Connection::TLSOptions
end
TLS_CERT_ENV =

Environment variable name for TLS certificate

"TEMPORAL_TLS_CERT"
TLS_KEY_ENV =

Environment variable name for TLS private key

"TEMPORAL_TLS_KEY"
TLS_SERVER_NAME_ENV =

Environment variable name for TLS server name

"TEMPORAL_TLS_SERVER_NAME"
TLS_SERVER_ROOT_CA_CERT_ENV =

Environment variable name for TLS root CA certificate

"TEMPORAL_TLS_SERVER_ROOT_CA_CERT"

Class Method Summary collapse

Class Method Details

.build(configuration) ⇒ Temporalio::Client

Builds and connects a Temporal client.

Creates a new Temporalio::Client instance connected to the configured Temporal cluster. TLS options are automatically included if present in configuration or environment variables.

Examples:

Basic usage

config = ActiveJob::Temporal::Configuration.new
config.target = "temporal.example.com:7233"
config.namespace = "production"
client = Client.build(config)

With TLS via environment variables

ENV["TEMPORAL_TLS_CERT"] = File.read("client.pem")
ENV["TEMPORAL_TLS_KEY"] = File.read("client-key.pem")
ENV["TEMPORAL_TLS_SERVER_NAME"] = "temporal.prod.example.com"
client = Client.build(config)
# Client will connect using mutual TLS

Handling connection failures

begin
  client = Client.build(config)
rescue ActiveJob::Temporal::TemporalConnectionError => e
  Rails.logger.fatal("Cannot connect to Temporal: #{e.message}")
  # Fall back to different adapter or alert operations team
end

Parameters:

  • configuration (Configuration) —

    Gem configuration object with target/namespace

Returns:

  • (Temporalio::Client) —

    Connected Temporal client

Raises:

  • (ActiveJob::Temporal::TemporalConnectionError) —

    if connection fails (includes target, namespace, and error message)

  • (OpenSSL::SSL::SSLError) —

    if TLS certificate validation fails

  • (OpenSSL::PKey::RSAError) —

    if TLS private key is invalid

  • (OpenSSL::X509::CertificateError) —

    if TLS certificate is malformed

  • (SocketError) —

    if target hostname cannot be resolved

  • (Errno::ECONNREFUSED) —

    if target port is not accepting connections

  • (Errno::ETIMEDOUT) —

    if connection times out



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/activejob/temporal/client.rb', line 104

def build(configuration)
  Temporalio::Client.connect(
    configuration.target,
    configuration.namespace,
    **connection_kwargs(configuration)
  )
rescue StandardError => e
  raise ActiveJob::Temporal::TemporalConnectionError,
        format(
          "Unable to connect to Temporal at %<target>s (namespace: %<namespace>s): %<error>s",
          target: configuration.target,
          namespace: configuration.namespace,
          error: e.message
        )
end

.resolve_api_key(configuration) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Resolves the API key: an explicit api_key wins, otherwise api_key_file is read - at connection build time, and again by ActiveJob::Temporal.refresh_api_key! when the token file rotates.



172
173
174
175
176
177
178
 
# File 'lib/activejob/temporal/client.rb', line 172

def resolve_api_key(configuration)
  inline = configuration.api_key if configuration.respond_to?(:api_key)
  return inline unless inline.nil? || inline.to_s.strip.empty?

  path = configuration.api_key_file if configuration.respond_to?(:api_key_file)
  read_tls_file(path)&.strip.presence
end