temporalio 0.1.1 → 0.2.0

data/lib/temporalio/client/connection.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'temporalio/client/connection/cloud_service'
+require 'temporalio/client/connection/operator_service'
+require 'temporalio/client/connection/workflow_service'
+require 'temporalio/internal/bridge'
+require 'temporalio/internal/bridge/client'
+require 'temporalio/runtime'
+require 'temporalio/version'
+
+module Temporalio
+  class Client
+    # Connection to Temporal server that is not namespace specific. Most users will use {Client.connect} instead of this
+    # directly.
+    class Connection
+      # Options as returned from {options} for +**to_h+ splat use in {initialize}. See {initialize} for details.
+      Options = Struct.new(
+        :target_host,
+        :api_key,
+        :tls,
+        :rpc_metadata,
+        :rpc_retry,
+        :identity,
+        :keep_alive,
+        :http_connect_proxy,
+        :runtime,
+        :lazy_connect,
+        keyword_init: true
+      )
+
+      # TLS options. All attributes are optional, and an empty options set just enables default TLS.
+      #
+      # @!attribute client_cert
+      #   @return [String, nil] Client certificate for mTLS. Must be combined with {client_private_key}.
+      # @!attribute client_private_key
+      #   @return [String, nil] Client private key for mTLS. Must be combined with {client_cert}.
+      # @!attribute server_root_ca_cert
+      #   @return [String, nil] Root CA certificate to validate the server certificate against. This is only needed for
+      #     self-hosted servers with self-signed server certificates.
+      # @!attribute domain
+      #   @return [String, nil] SNI override. This is only needed for self-hosted servers with certificates that do not
+      #     match the hostname being connected to.
+      TLSOptions = Struct.new(
+        :client_cert,
+        :client_private_key,
+        :server_root_ca_cert,
+        :domain,
+        keyword_init: true
+      )
+
+      # Retry options for server calls when retry is enabled (which it is by default on all high-level {Client} calls).
+      # For most users, the default is preferred.
+      #
+      # @!attribute initial_interval
+      #   @return [Float] Initial backoff interval, default 0.1.
+      # @!attribute randomization_factor
+      #   @return [Float] Randomization jitter to add, default 0.2.
+      # @!attribute multiplier
+      #   @return [Float] Backoff multiplier, default 1.5.
+      # @!attribute max_interval
+      #   @return [Float] Maximum backoff interval, default 5.0.
+      # @!attribute max_elapsed_time
+      #   @return [Float] Maximum total time, default 10.0. Can use 0 for no max.
+      # @!attribute max_retries
+      #   @return [Integer] Maximum number of retries, default 10.
+      RPCRetryOptions = Struct.new(
+        :initial_interval,
+        :randomization_factor,
+        :multiplier,
+        :max_interval,
+        :max_elapsed_time,
+        :max_retries,
+        keyword_init: true
+      ) do
+        def initialize(**kwargs)
+          # @type var kwargs: untyped
+          kwargs[:initial_interval] = 0.1 unless kwargs.key?(:initial_interval)
+          kwargs[:randomization_factor] = 0.2 unless kwargs.key?(:randomization_factor)
+          kwargs[:multiplier] = 1.5 unless kwargs.key?(:multiplier)
+          kwargs[:max_interval] = 5.0 unless kwargs.key?(:max_interval)
+          kwargs[:max_elapsed_time] = 10.0 unless kwargs.key?(:max_elapsed_time)
+          kwargs[:max_retries] = 10 unless kwargs.key?(:max_retries)
+          super
+        end
+      end
+
+      # Keep-alive options for client connections. For most users, the default is preferred.
+      #
+      # @!attribute interval
+      #   @return [Float] Interval to send HTTP2 keep alive pings, default 30.0.
+      # @!attribute timeout
+      #   @return [Float] Timeout that the keep alive must be responded to within or the connection will be closed,
+      #     default 15.0.
+      KeepAliveOptions = Struct.new(
+        :interval,
+        :timeout,
+        keyword_init: true
+      ) do
+        def initialize(**kwargs)
+          # @type var kwargs: untyped
+          kwargs[:interval] = 30.0 unless kwargs.key?(:interval)
+          kwargs[:timeout] = 15.0 unless kwargs.key?(:timeout)
+          super
+        end
+      end
+
+      # Options for HTTP CONNECT proxy for client connections.
+      #
+      # @!attribute target_host
+      #   @return [String] Target host:port for the HTTP CONNECT proxy.
+      # @!attribute basic_auth_user
+      #   @return [String, nil] User for HTTP basic auth for the proxy, must be combined with {basic_auth_pass}.
+      # @!attribute basic_auth_pass
+      #   @return [String, nil] Pass for HTTP basic auth for the proxy, must be combined with {basic_auth_user}.
+      HTTPConnectProxyOptions = Struct.new(
+        :target_host,
+        :basic_auth_user, # Optional
+        :basic_auth_pass, # Optional,
+        keyword_init: true
+      )
+
+      # @return [Options] Frozen options for this client which has the same attributes as {initialize}.
+      attr_reader :options
+
+      # @return [WorkflowService] Raw gRPC workflow service.
+      attr_reader :workflow_service
+
+      # @return [OperatorService] Raw gRPC operator service.
+      attr_reader :operator_service
+
+      # @return [CloudService] Raw gRPC cloud service.
+      attr_reader :cloud_service
+
+      # Connect to Temporal server. Most users will use {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.
+      #
+      # @param target_host [String] +host:port+ for the Temporal server. For local development, this is often
+      #   +localhost:7233+.
+      # @param api_key [String, 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.
+      # @param tls [Boolean, TLSOptions] If false, do not use TLS. If true, use system default TLS options. If TLS
+      #   options are present, those TLS options will be used.
+      # @param rpc_metadata [Hash<String, String>] Headers to use for all calls to the server. Keys here can be
+      #   overriden by per-call RPC metadata keys.
+      # @param rpc_retry [RPCRetryOptions] 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).
+      # @param identity [String] Identity for this client.
+      # @param keep_alive [KeepAliveOptions] Keep-alive options for the client connection. Can be set to +nil+ to
+      #   disable.
+      # @param http_connect_proxy [HTTPConnectProxyOptions, nil] Options for HTTP CONNECT proxy.
+      # @param runtime [Runtime] Runtime for this client.
+      # @param lazy_connect [Boolean] 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.
+      #
+      # @see Client.connect
+      def initialize(
+        target_host:,
+        api_key: nil,
+        tls: false,
+        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
+      )
+        @options = Options.new(
+          target_host:,
+          api_key:,
+          tls:,
+          rpc_metadata:,
+          rpc_retry:,
+          identity:,
+          keep_alive:,
+          http_connect_proxy:,
+          runtime:,
+          lazy_connect:
+        ).freeze
+        # Create core client now if not lazy
+        _core_client unless lazy_connect
+        # Create service instances
+        @workflow_service = WorkflowService.new(self)
+        @operator_service = OperatorService.new(self)
+        @cloud_service = CloudService.new(self)
+      end
+
+      # @return [String] Target host this connection is connected to.
+      def target_host
+        @options.target_host
+      end
+
+      # @return [String] Client identity.
+      def identity
+        @options.identity
+      end
+
+      # @return [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.
+      def connected?
+        !@core_client.nil?
+      end
+
+      # @!visibility private
+      def _core_client
+        # If lazy, this needs to be done under mutex
+        if @options.lazy_connect
+          @core_client_mutex ||= Mutex.new
+          @core_client_mutex.synchronize do
+            @core_client ||= new_core_client
+          end
+        else
+          @core_client ||= new_core_client
+        end
+      end
+
+      private
+
+      def new_core_client
+        Internal::Bridge.assert_fiber_compatibility!
+
+        options = Internal::Bridge::Client::Options.new(
+          target_host: @options.target_host,
+          client_name: 'temporal-ruby',
+          client_version: VERSION,
+          rpc_metadata: @options.rpc_metadata,
+          api_key: @options.api_key,
+          rpc_retry: Internal::Bridge::Client::RPCRetryOptions.new(
+            initial_interval: @options.rpc_retry.initial_interval,
+            randomization_factor: @options.rpc_retry.randomization_factor,
+            multiplier: @options.rpc_retry.multiplier,
+            max_interval: @options.rpc_retry.max_interval,
+            max_elapsed_time: @options.rpc_retry.max_elapsed_time,
+            max_retries: @options.rpc_retry.max_retries
+          ),
+          identity: @options.identity || "#{Process.pid}@#{Socket.gethostname}"
+        )
+        if @options.tls
+          options.tls = if @options.tls.is_a?(TLSOptions)
+                          Internal::Bridge::Client::TLSOptions.new(
+                            client_cert: @options.tls.client_cert, # steep:ignore
+                            client_private_key: @options.tls.client_private_key, # steep:ignore
+                            server_root_ca_cert: @options.tls.server_root_ca_cert, # steep:ignore
+                            domain: @options.tls.domain # steep:ignore
+                          )
+                        else
+                          Internal::Bridge::Client::TLSOptions.new
+                        end
+        end
+        if @options.keep_alive
+          options.keep_alive = Internal::Bridge::Client::KeepAliveOptions.new(
+            interval: @options.keep_alive.interval,
+            timeout: @options.keep_alive.timeout
+          )
+        end
+        if @options.http_connect_proxy
+          options.http_connect_proxy = Internal::Bridge::Client::HTTPConnectProxyOptions.new(
+            target_host: @options.http_connect_proxy.target_host,
+            basic_auth_user: @options.http_connect_proxy.basic_auth_user,
+            basic_auth_pass: @options.http_connect_proxy.basic_auth_pass
+          )
+        end
+        Internal::Bridge::Client.new(@options.runtime._core_runtime, options)
+      end
+    end
+  end
+end

data/lib/temporalio/client/interceptor.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Client
+    # Mixin for intercepting clients. Classes that +include+ this should implement their own {intercept_client} that
+    # returns their own instance of {Outbound}.
+    #
+    # @note Input classes herein may get new required fields added and therefore the constructors of the Input classes
+    # may change in backwards incompatible ways. Users should not try to construct Input classes themselves.
+    module Interceptor
+      # Method called when intercepting a client. This is called upon client creation.
+      #
+      # @param next_interceptor [Outbound] Next interceptor in the chain that should be called. This is usually passed
+      #   to {Outbound} constructor.
+      # @return [Outbound] Interceptor to be called for client calls.
+      def intercept_client(next_interceptor)
+        next_interceptor
+      end
+
+      # Input for {Outbound.start_workflow}.
+      StartWorkflowInput = Struct.new(
+        :workflow,
+        :args,
+        :workflow_id,
+        :task_queue,
+        :execution_timeout,
+        :run_timeout,
+        :task_timeout,
+        :id_reuse_policy,
+        :id_conflict_policy,
+        :retry_policy,
+        :cron_schedule,
+        :memo,
+        :search_attributes,
+        :start_delay,
+        :request_eager_start,
+        :headers,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.list_workflows}.
+      ListWorkflowsInput = Struct.new(
+        :query,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.count_workflows}.
+      CountWorkflowsInput = Struct.new(
+        :query,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.describe_workflow}.
+      DescribeWorkflowInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.fetch_workflow_history_events}.
+      FetchWorkflowHistoryEventsInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :wait_new_event,
+        :event_filter_type,
+        :skip_archival,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.signal_workflow}.
+      SignalWorkflowInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :signal,
+        :args,
+        :headers,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.query_workflow}.
+      QueryWorkflowInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :query,
+        :args,
+        :reject_condition,
+        :headers,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.start_workflow_update}.
+      StartWorkflowUpdateInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :update_id,
+        :update,
+        :args,
+        :wait_for_stage,
+        :headers,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.poll_workflow_update}.
+      PollWorkflowUpdateInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :update_id,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.cancel_workflow}.
+      CancelWorkflowInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :first_execution_run_id,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.terminate_workflow}.
+      TerminateWorkflowInput = Struct.new(
+        :workflow_id,
+        :run_id,
+        :first_execution_run_id,
+        :reason,
+        :details,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.heartbeat_async_activity}.
+      HeartbeatAsyncActivityInput = Struct.new(
+        :task_token_or_id_reference,
+        :details,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.complete_async_activity}.
+      CompleteAsyncActivityInput = Struct.new(
+        :task_token_or_id_reference,
+        :result,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.fail_async_activity}.
+      FailAsyncActivityInput = Struct.new(
+        :task_token_or_id_reference,
+        :error,
+        :last_heartbeat_details,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Input for {Outbound.report_cancellation_async_activity}.
+      ReportCancellationAsyncActivityInput = Struct.new(
+        :task_token_or_id_reference,
+        :details,
+        :rpc_metadata,
+        :rpc_timeout,
+        keyword_init: true
+      )
+
+      # Outbound interceptor for intercepting client calls. This should be extended by users needing to intercept client
+      # actions.
+      class Outbound
+        # @return [Outbound] Next interceptor in the chain.
+        attr_reader :next_interceptor
+
+        # Initialize outbound with the next interceptor in the chain.
+        #
+        # @param next_interceptor [Outbound] Next interceptor in the chain.
+        def initialize(next_interceptor)
+          @next_interceptor = next_interceptor
+        end
+
+        # Called for every {Client.start_workflow} and {Client.execute_workflow} call.
+        #
+        # @param input [StartWorkflowInput] Input.
+        # @return [WorkflowHandle] Workflow handle.
+        def start_workflow(input)
+          next_interceptor.start_workflow(input)
+        end
+
+        # Called for every {Client.list_workflows} call.
+        #
+        # @param input [ListWorkflowsInput] Input.
+        # @return [Enumerator<WorkflowExecution>] Enumerable workflow executions.
+        def list_workflows(input)
+          next_interceptor.list_workflows(input)
+        end
+
+        # Called for every {Client.count_workflows} call.
+        #
+        # @param input [CountWorkflowsInput] Input.
+        # @return [WorkflowExecutionCount] Workflow count.
+        def count_workflows(input)
+          next_interceptor.count_workflows(input)
+        end
+
+        # Called for every {WorkflowHandle.describe} call.
+        #
+        # @param input [DescribeWorkflowInput] Input.
+        # @return [WorkflowExecution::Description] Workflow description.
+        def describe_workflow(input)
+          next_interceptor.describe_workflow(input)
+        end
+
+        # Called everytime the client needs workflow history. This includes getting the result.
+        #
+        # @param input [FetchWorkflowHistoryEventsInput] Input.
+        # @return [Enumerator<Api::History::V1::HistoryEvent>] Event enumerator.
+        def fetch_workflow_history_events(input)
+          next_interceptor.fetch_workflow_history_events(input)
+        end
+
+        # Called for every {WorkflowHandle.signal} call.
+        #
+        # @param input [SignalWorkflowInput] Input.
+        def signal_workflow(input)
+          next_interceptor.signal_workflow(input)
+        end
+
+        # Called for every {WorkflowHandle.query} call.
+        #
+        # @param input [QueryWorkflowInput] Input.
+        # @return [Object, nil] Query result.
+        def query_workflow(input)
+          next_interceptor.query_workflow(input)
+        end
+
+        # Called for every {WorkflowHandle.start_update} call.
+        #
+        # @param input [StartWorkflowUpdateInput] Input.
+        # @return [WorkflowUpdateHandle] Update handle.
+        def start_workflow_update(input)
+          next_interceptor.start_workflow_update(input)
+        end
+
+        # Called when polling for update result.
+        #
+        # @param input [PollWorkflowUpdateInput] Input.
+        # @return [Api::Update::V1::Outcome] Update outcome.
+        def poll_workflow_update(input)
+          next_interceptor.poll_workflow_update(input)
+        end
+
+        # Called for every {WorkflowHandle.cancel} call.
+        #
+        # @param input [CancelWorkflowInput] Input.
+        def cancel_workflow(input)
+          next_interceptor.cancel_workflow(input)
+        end
+
+        # Called for every {WorkflowHandle.terminate} call.
+        #
+        # @param input [TerminateWorkflowInput] Input.
+        def terminate_workflow(input)
+          next_interceptor.terminate_workflow(input)
+        end
+
+        # Called for every {AsyncActivityHandle.heartbeat} call.
+        #
+        # @param input [HeartbeatAsyncActivityInput] Input.
+        def heartbeat_async_activity(input)
+          next_interceptor.heartbeat_async_activity(input)
+        end
+
+        # Called for every {AsyncActivityHandle.complete} call.
+        #
+        # @param input [CompleteAsyncActivityInput] Input.
+        def complete_async_activity(input)
+          next_interceptor.complete_async_activity(input)
+        end
+
+        # Called for every {AsyncActivityHandle.fail} call.
+        #
+        # @param input [FailAsyncActivityInput] Input.
+        def fail_async_activity(input)
+          next_interceptor.fail_async_activity(input)
+        end
+
+        # Called for every {AsyncActivityHandle.report_cancellation} call.
+        #
+        # @param input [ReportCancellationAsyncActivityInput] Input.
+        def report_cancellation_async_activity(input)
+          next_interceptor.report_cancellation_async_activity(input)
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/client/workflow_execution.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/client/workflow_execution_status'
+require 'temporalio/internal/proto_utils'
+require 'temporalio/search_attributes'
+
+module Temporalio
+  class Client
+    # Info for a single workflow execution run.
+    class WorkflowExecution
+      # @return [Api::Workflow::V1::WorkflowExecutionInfo] Underlying protobuf info.
+      attr_reader :raw_info
+
+      # @!visibility private
+      def initialize(raw_info, data_converter)
+        @raw_info = raw_info
+        @data_converter = data_converter
+      end
+
+      # @return [Time, nil] When the workflow was closed if closed.
+      def close_time
+        @raw_info.close_time&.to_time
+      end
+
+      # @return [Time, nil] When this workflow run started or should start.
+      def execution_time
+        @raw_info.execution_time&.to_time
+      end
+
+      # @return [Integer] Number of events in the history.
+      def history_length
+        @raw_info.history_length
+      end
+
+      # @return [String] ID for the workflow.
+      def id
+        @raw_info.execution.workflow_id
+      end
+
+      # @return [Hash<String, Object>, nil] Memo for the workflow.
+      def memo
+        @memo = Internal::ProtoUtils.memo_from_proto(@raw_info.memo, @data_converter) unless defined?(@memo)
+        @memo
+      end
+
+      # @return [String, nil] ID for the parent workflow if this was started as a child.
+      def parent_id
+        @raw_info.parent_execution&.workflow_id
+      end
+
+      # @return [String, nil] Run ID for the parent workflow if this was started as a child.
+      def parent_run_id
+        @raw_info.parent_execution&.run_id
+      end
+
+      # @return [String] Run ID for this workflow run.
+      def run_id
+        @raw_info.execution.run_id
+      end
+
+      # @return [SearchAttributes, nil] Current set of search attributes if any.
+      def search_attributes
+        unless defined?(@search_attributes)
+          @search_attributes = SearchAttributes.from_proto(@raw_info.search_attributes)
+        end
+        @search_attributes
+      end
+
+      # @return [Time] When the workflow was created.
+      def start_time
+        @raw_info.start_time.to_time
+      end
+
+      # @return [WorkflowExecutionStatus] Status for the workflow.
+      def status
+        Internal::ProtoUtils.enum_to_int(Api::Enums::V1::WorkflowExecutionStatus, @raw_info.status)
+      end
+
+      # @return [String] Task queue for the workflow.
+      def task_queue
+        @raw_info.task_queue
+      end
+
+      # @return [String] Type name for the workflow.
+      def workflow_type
+        @raw_info.type.name
+      end
+
+      # Description for a single workflow execution run.
+      class Description < WorkflowExecution
+        # @return [Api::WorkflowService::V1::DescribeWorkflowExecutionResponse] Underlying protobuf description.
+        attr_reader :raw_description
+
+        # @!visibility private
+        def initialize(raw_description, data_converter)
+          super(raw_description.workflow_execution_info, data_converter)
+          @raw_description = raw_description
+        end
+      end
+    end
+  end
+end