Class: Temporalio::Client::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/temporalio/client/connection.rb,
lib/temporalio/client/connection/service.rb,
lib/temporalio/client/connection/test_service.rb,
lib/temporalio/client/connection/cloud_service.rb,
lib/temporalio/client/connection/operator_service.rb,
lib/temporalio/client/connection/workflow_service.rb

Overview

Connection to Temporal server that is not namespace specific. Most users will use connect instead of this directly.

Defined Under Namespace

Modules: GrpcCompressionOptions Classes: CloudService, DnsLoadBalancingOptions, HTTPConnectProxyOptions, KeepAliveOptions, OperatorService, Options, PayloadLimitsOptions, RPCRetryOptions, Service, TLSOptions, TestService, WorkflowService

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(target_host:, api_key: nil, tls: nil, rpc_metadata: {}, rpc_retry: RPCRetryOptions.new, identity: "#{Process.pid}@#{Socket.gethostname}", keep_alive: KeepAliveOptions.new, http_connect_proxy: nil, runtime: Runtime.default, lazy_connect: false, dns_load_balancing: nil, grpc_compression: GrpcCompressionOptions::Gzip.new, payload_limits: PayloadLimitsOptions.new, around_connect: nil) ⇒ Connection

Connect to Temporal server. Most users will use Temporalio::Client.connect instead of this directly. Parameters here match Options returned from #options by intention so options can be dup'd, altered, splatted to create a new connection.

Parameters:

  • target_host (String) —

    host:port for the Temporal server. For local development, this is often localhost:7233.

  • api_key (String, nil) (defaults to: nil) —

    API key for Temporal. This becomes the Authorization HTTP header with "Bearer " prepended. This is only set if RPC metadata doesn't already have an authorization key.

  • tls (Boolean, TLSOptions, nil) (defaults to: nil) —

    If false, do not use TLS. If true, use system default TLS options. If TLS options are present, those TLS options will be used. If nil (the default), TLS will be auto-enabled if api_key is provided.

  • rpc_metadata (Hash<String, String>) (defaults to: {}) —

    Headers to use for all calls to the server. Keys here can be overriden by per-call RPC metadata keys.

  • rpc_retry (RPCRetryOptions) (defaults to: RPCRetryOptions.new) —

    Retry options for direct service calls (when opted in) or all high-level calls made by this client (which all opt-in to retries by default).

  • identity (String) (defaults to: "#{Process.pid}@#{Socket.gethostname}") —

    Identity for this client.

  • keep_alive (KeepAliveOptions) (defaults to: KeepAliveOptions.new) —

    Keep-alive options for the client connection. Can be set to nil to disable.

  • http_connect_proxy (HTTPConnectProxyOptions, nil) (defaults to: nil) —

    Options for HTTP CONNECT proxy.

  • runtime (Runtime) (defaults to: Runtime.default) —

    Runtime for this client.

  • lazy_connect (Boolean) (defaults to: false) —

    If true, there is no connection until the first call is attempted or a worker is created with it. Clients from lazy connections cannot be used for workers if they have not performed a connection.

  • dns_load_balancing (DnsLoadBalancingOptions, nil) (defaults to: nil) —

    DNS load balancing options for this connection. Default is nil (disabled). Silently disabled when http_connect_proxy is set, since the two are mutually exclusive.

  • grpc_compression (GrpcCompressionOptions::Gzip, GrpcCompressionOptions::None) (defaults to: GrpcCompressionOptions::Gzip.new) —

    Transport-level gRPC compression. Defaults to gzip. Set to Temporalio::Client::Connection::GrpcCompressionOptions::None to opt out.

  • payload_limits (PayloadLimitsOptions) (defaults to: PayloadLimitsOptions.new) —

    Payload size-limit options for this connection. Defaults to a PayloadLimitsOptions with the standard warning thresholds; see that type for the defaults and how to disable a warning. WARNING: This is experimental and may change in the future.

  • around_connect (Proc, nil) (defaults to: nil) —

    If present, this proc accepts two values: options and a block. The block must be yielded to only once with the options. The block does not return a meaningful value, nor should around_connect.

See Also:



244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/temporalio/client/connection.rb', line 244

def initialize(
  target_host:,
  api_key: nil,
  tls: nil,
  rpc_metadata: {},
  rpc_retry: RPCRetryOptions.new,
  identity: "#{Process.pid}@#{Socket.gethostname}",
  keep_alive: KeepAliveOptions.new,
  http_connect_proxy: nil,
  runtime: Runtime.default,
  lazy_connect: false,
  dns_load_balancing: nil,
  grpc_compression: GrpcCompressionOptions::Gzip.new,
  payload_limits: PayloadLimitsOptions.new,
  around_connect: nil
)
  @options = Options.new(
    target_host:,
    api_key:,
    tls:,
    rpc_metadata:,
    rpc_retry:,
    identity:,
    keep_alive:,
    http_connect_proxy:,
    runtime:,
    lazy_connect:,
    dns_load_balancing:,
    grpc_compression:,
    payload_limits:
  ).freeze
  @core_client_mutex = Mutex.new
  # Create core client now if not lazy, applying around_connect if present
  if around_connect
    # Technically around_connect can never run the block for whatever reason (i.e. plugin returning a mock
    # connection), so we don't enforce it
    around_connect.call(@options) do |options|
      @options = options
      _core_client unless lazy_connect
      nil
    end
  else
    _core_client unless lazy_connect
  end
  # Create service instances
  @workflow_service = WorkflowService.new(self)
  @operator_service = OperatorService.new(self)
  @cloud_service = CloudService.new(self)
end

Instance Attribute Details

#cloud_service ⇒ CloudService (readonly)

Returns Raw gRPC cloud service.

Returns:



207
208
209
 
# File 'lib/temporalio/client/connection.rb', line 207

def cloud_service
  @cloud_service
end

#operator_service ⇒ OperatorService (readonly)

Returns Raw gRPC operator service.

Returns:



204
205
206
 
# File 'lib/temporalio/client/connection.rb', line 204

def operator_service
  @operator_service
end

#options ⇒ Options (readonly)

Returns Frozen options for this client which has the same attributes as #initialize. Note that if #api_key= or #rpc_metadata= are updated, the options object is replaced with those changes (it is not mutated in place).

Returns:

  • (Options) —

    Frozen options for this client which has the same attributes as #initialize. Note that if #api_key= or #rpc_metadata= are updated, the options object is replaced with those changes (it is not mutated in place).



198
199
200
 
# File 'lib/temporalio/client/connection.rb', line 198

def options
  @options
end

#workflow_service ⇒ WorkflowService (readonly)

Returns Raw gRPC workflow service.

Returns:



201
202
203
 
# File 'lib/temporalio/client/connection.rb', line 201

def workflow_service
  @workflow_service
end

Instance Method Details

#api_key ⇒ String?

Returns API key. This is a shortcut for options.api_key.

Returns:

  • (String, nil) —

    API key. This is a shortcut for options.api_key.



311
312
313
 
# File 'lib/temporalio/client/connection.rb', line 311

def api_key
  @options.api_key
end

#api_key=(new_key) ⇒ Object

Set the API key for all future calls. This also makes a new object for #options with the changes.

Parameters:

  • new_key (String, nil) —

    New API key.



318
319
320
321
322
323
324
 
# File 'lib/temporalio/client/connection.rb', line 318

def api_key=(new_key)
  # Mutate the client if connected then mutate options
  @core_client_mutex.synchronize do
    @core_client&.update_api_key(new_key)
    @options = @options.with(api_key: new_key)
  end
end

#connected? ⇒ Boolean

Returns Whether this connection is connected. This is always true unless lazy_connect option was originally set, in which case this will be false until the first call is made.

Returns:

  • (Boolean) —

    Whether this connection is connected. This is always true unless lazy_connect option was originally set, in which case this will be false until the first call is made.



306
307
308
 
# File 'lib/temporalio/client/connection.rb', line 306

def connected?
  !@core_client.nil?
end

#identity ⇒ String

Returns Client identity.

Returns:

  • (String) —

    Client identity.



300
301
302
 
# File 'lib/temporalio/client/connection.rb', line 300

def identity
  @options.identity
end

#rpc_metadata ⇒ Hash<String, String>

Returns RPC metadata (aka HTTP headers). This is a shortcut for options.rpc_metadata.

Returns:

  • (Hash<String, String>) —

    RPC metadata (aka HTTP headers). This is a shortcut for options.rpc_metadata.



327
328
329
 
# File 'lib/temporalio/client/connection.rb', line 327

def rpc_metadata
  @options.rpc_metadata
end

#rpc_metadata=(rpc_metadata) ⇒ Object

Set the RPC metadata (aka HTTP headers) for all future calls. This also makes a new object for #options with the changes.

Parameters:

  • rpc_metadata (Hash<String, String>) —

    New API key.



335
336
337
338
339
340
341
 
# File 'lib/temporalio/client/connection.rb', line 335

def rpc_metadata=(rpc_metadata)
  # Mutate the client if connected then mutate options
  @core_client_mutex.synchronize do
    @core_client&.update_metadata(rpc_metadata)
    @options = @options.with(rpc_metadata: rpc_metadata)
  end
end

#target_host ⇒ String

Returns Target host this connection is connected to.

Returns:

  • (String) —

    Target host this connection is connected to.



295
296
297
 
# File 'lib/temporalio/client/connection.rb', line 295

def target_host
  @options.target_host
end