temporalio 0.0.0 → 0.0.1

data/lib/temporal/client/implementation.rb

@@ -0,0 +1,339 @@
+require 'socket'
+require 'temporal/api/workflowservice/v1/request_response_pb'
+require 'temporal/client/workflow_handle'
+require 'temporal/error/failure'
+require 'temporal/error/workflow_failure'
+require 'temporal/interceptor/chain'
+require 'temporal/timeout_type'
+require 'temporal/version'
+require 'temporal/workflow/execution_info'
+require 'temporal/workflow/id_reuse_policy'
+require 'temporal/workflow/query_reject_condition'
+
+module Temporal
+  class Client
+    class Implementation
+      def initialize(connection, namespace, converter, interceptors)
+        @connection = connection
+        @namespace = namespace
+        @converter = converter
+        @interceptor_chain = Interceptor::Chain.new(interceptors)
+        @identity = "#{Process.pid}@#{Socket.gethostname} (Ruby SDK v#{VERSION})"
+      end
+
+      def start_workflow(input)
+        interceptor_chain.invoke(:start_workflow, input) do |i|
+          handle_start_workflow(i)
+        end
+      end
+
+      def describe_workflow(input)
+        interceptor_chain.invoke(:describe_workflow, input) do |i|
+          handle_describe_workflow(i)
+        end
+      end
+
+      def query_workflow(input)
+        interceptor_chain.invoke(:query_workflow, input) do |i|
+          handle_query_workflow(i)
+        end
+      end
+
+      def signal_workflow(input)
+        interceptor_chain.invoke(:signal_workflow, input) do |i|
+          handle_signal_workflow(i)
+        end
+      end
+
+      def cancel_workflow(input)
+        interceptor_chain.invoke(:cancel_workflow, input) do |i|
+          handle_cancel_workflow(i)
+        end
+      end
+
+      def terminate_workflow(input)
+        interceptor_chain.invoke(:terminate_workflow, input) do |i|
+          handle_terminate_workflow(i)
+        end
+      end
+
+      def await_workflow_result(id, run_id, follow_runs, rpc_metadata, rpc_timeout)
+        rpc_params = { metadata: rpc_metadata, timeout: rpc_timeout }
+        request = Temporal::Api::WorkflowService::V1::GetWorkflowExecutionHistoryRequest.new(
+          namespace: namespace.to_s,
+          execution: Temporal::Api::Common::V1::WorkflowExecution.new(
+            workflow_id: id,
+            run_id: run_id || '',
+          ),
+          history_event_filter_type:
+            Temporal::Api::Enums::V1::HistoryEventFilterType::HISTORY_EVENT_FILTER_TYPE_CLOSE_EVENT,
+          wait_new_event: true,
+          skip_archival: true,
+        )
+
+        loop do
+          response = connection.get_workflow_execution_history(request, **rpc_params)
+          next_run_id = catch(:next) do
+            # this will return out of the loop only if :next wasn't thrown
+            return process_workflow_result_from(response, follow_runs)
+          end
+          request.execution&.run_id = next_run_id if next_run_id
+        end
+      end
+
+      private
+
+      attr_reader :connection, :namespace, :converter, :interceptor_chain, :identity
+
+      def convert_headers(headers)
+        return if headers.empty?
+
+        Temporal::Api::Common::V1::Header.new(
+          fields: converter.to_payload_map(headers),
+        )
+      end
+
+      def handle_start_workflow(input)
+        input.retry_policy&.validate!
+
+        if input.memo
+          memo = Temporal::Api::Common::V1::Memo.new(fields: converter.to_payload_map(input.memo))
+        end
+
+        if input.search_attributes
+          search_attributes = Temporal::Api::Common::V1::SearchAttributes.new(
+            indexed_fields: converter.to_payload_map(input.search_attributes),
+          )
+        end
+
+        rpc_params = { metadata: input.rpc_metadata, timeout: input.rpc_timeout }
+        params = {
+          identity: identity,
+          request_id: SecureRandom.uuid,
+          namespace: namespace,
+          workflow_type: Temporal::Api::Common::V1::WorkflowType.new(name: input.workflow.to_s),
+          workflow_id: input.id,
+          task_queue: Temporal::Api::TaskQueue::V1::TaskQueue.new(name: input.task_queue.to_s),
+          input: converter.to_payloads(input.args),
+          workflow_execution_timeout: input.execution_timeout,
+          workflow_run_timeout: input.run_timeout,
+          workflow_task_timeout: input.task_timeout,
+          workflow_id_reuse_policy: Workflow::IDReusePolicy.to_raw(input.id_reuse_policy),
+          retry_policy: input.retry_policy&.to_proto,
+          cron_schedule: input.cron_schedule,
+          memo: memo,
+          search_attributes: search_attributes,
+          header: convert_headers(input.headers),
+        }
+
+        first_execution_run_id = nil
+        if input.start_signal
+          params.merge!(
+            signal_name: input.start_signal,
+            signal_input: converter.to_payloads(input.start_signal_args),
+          )
+
+          klass = Temporal::Api::WorkflowService::V1::SignalWithStartWorkflowExecutionRequest
+          request = klass.new(**params)
+
+          response = connection.signal_with_start_workflow_execution(request, **rpc_params)
+        else
+          klass = Temporal::Api::WorkflowService::V1::StartWorkflowExecutionRequest
+          request = klass.new(**params)
+
+          response = connection.start_workflow_execution(request, **rpc_params)
+          first_execution_run_id = response.run_id
+        end
+
+        Client::WorkflowHandle.new(
+          self,
+          input.id,
+          result_run_id: response.run_id,
+          first_execution_run_id: first_execution_run_id,
+        )
+      rescue Temporal::Bridge::Error => e
+        # TODO: Raise a better error from the bridge
+        if e.message.include?('AlreadyExists')
+          raise Temporal::Error::WorkflowExecutionAlreadyStarted, 'Workflow execution already started'
+        else
+          raise # re-raise
+        end
+      end
+
+      def handle_describe_workflow(input)
+        rpc_params = { metadata: input.rpc_metadata, timeout: input.rpc_timeout }
+        request = Temporal::Api::WorkflowService::V1::DescribeWorkflowExecutionRequest.new(
+          namespace: namespace.to_s,
+          execution: Temporal::Api::Common::V1::WorkflowExecution.new(
+            workflow_id: input.id,
+            run_id: input.run_id || '',
+          ),
+        )
+
+        response = connection.describe_workflow_execution(request, **rpc_params)
+
+        Workflow::ExecutionInfo.from_raw(response, converter)
+      end
+
+      def handle_query_workflow(input)
+        rpc_params = { metadata: input.rpc_metadata, timeout: input.rpc_timeout }
+        request = Temporal::Api::WorkflowService::V1::QueryWorkflowRequest.new(
+          namespace: namespace.to_s,
+          execution: Temporal::Api::Common::V1::WorkflowExecution.new(
+            workflow_id: input.id,
+            run_id: input.run_id,
+          ),
+          query: Temporal::Api::Query::V1::WorkflowQuery.new(
+            query_type: input.query.to_s,
+            query_args: converter.to_payloads(input.args),
+            header: convert_headers(input.headers),
+          ),
+          query_reject_condition: Workflow::QueryRejectCondition.to_raw(input.reject_condition),
+        )
+
+        response = connection.query_workflow(request, **rpc_params)
+
+        if response.query_rejected
+          status = Workflow::ExecutionStatus.from_raw(response.query_rejected.status)
+          raise Temporal::Error::QueryRejected, status
+        end
+
+        converter.from_payloads(response.query_result)&.first
+      rescue Temporal::Bridge::Error => e
+        # TODO: Raise a better error from the bridge
+        raise Temporal::Error::QueryFailed, e.message
+      end
+
+      def handle_signal_workflow(input)
+        rpc_params = { metadata: input.rpc_metadata, timeout: input.rpc_timeout }
+        request = Temporal::Api::WorkflowService::V1::SignalWorkflowExecutionRequest.new(
+          identity: identity,
+          request_id: SecureRandom.uuid,
+          namespace: namespace.to_s,
+          workflow_execution: Temporal::Api::Common::V1::WorkflowExecution.new(
+            workflow_id: input.id,
+            run_id: input.run_id || '',
+          ),
+          signal_name: input.signal.to_s,
+          input: converter.to_payloads(input.args),
+          header: convert_headers(input.headers),
+        )
+
+        connection.signal_workflow_execution(request, **rpc_params)
+
+        return
+      end
+
+      def handle_cancel_workflow(input)
+        rpc_params = { metadata: input.rpc_metadata, timeout: input.rpc_timeout }
+        request = Temporal::Api::WorkflowService::V1::RequestCancelWorkflowExecutionRequest.new(
+          identity: identity,
+          request_id: SecureRandom.uuid,
+          namespace: namespace.to_s,
+          workflow_execution: Temporal::Api::Common::V1::WorkflowExecution.new(
+            workflow_id: input.id,
+            run_id: input.run_id || '',
+          ),
+          first_execution_run_id: input.first_execution_run_id || '',
+          reason: input.reason,
+        )
+
+        connection.request_cancel_workflow_execution(request, **rpc_params)
+
+        return
+      end
+
+      def handle_terminate_workflow(input)
+        rpc_params = { metadata: input.rpc_metadata, timeout: input.rpc_timeout }
+        request = Temporal::Api::WorkflowService::V1::TerminateWorkflowExecutionRequest.new(
+          identity: identity,
+          namespace: namespace.to_s,
+          workflow_execution: Temporal::Api::Common::V1::WorkflowExecution.new(
+            workflow_id: input.id,
+            run_id: input.run_id || '',
+          ),
+          first_execution_run_id: input.first_execution_run_id || '',
+          reason: input.reason,
+          details: converter.to_payloads(input.args),
+        )
+
+        connection.terminate_workflow_execution(request, **rpc_params)
+
+        return
+      end
+
+      def process_workflow_result_from(response, follow_runs)
+        events = response.history&.events
+
+        if !events || events.empty?
+          throw(:next, nil) # next loop, same run_id
+        elsif events.length != 1
+          raise Temporal::Error, "Expected single close event, got #{events.length}"
+        end
+
+        event = events.first
+        raise Temporal::Error::UnexpectedResponse, 'Missing final history event' unless event
+
+        case event.event_type
+        when :EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED
+          attributes = event.workflow_execution_completed_event_attributes
+          follow(attributes&.new_execution_run_id) if follow_runs
+
+          # TODO: Handle incorrect payloads object
+          return converter.from_payloads(attributes&.result)&.first
+
+        when :EVENT_TYPE_WORKFLOW_EXECUTION_FAILED
+          attributes = event.workflow_execution_failed_event_attributes
+          follow(attributes&.new_execution_run_id) if follow_runs
+
+          raise Temporal::Error::WorkflowFailure.new(
+            cause: converter.from_failure(attributes&.failure),
+          )
+
+        when :EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED
+          attributes = event.workflow_execution_canceled_event_attributes
+
+          raise Temporal::Error::WorkflowFailure.new(
+            cause: Temporal::Error::CancelledError.new(
+              'Workflow execution cancelled',
+              details: converter.from_payloads(attributes&.details),
+            ),
+          )
+
+        when :EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED
+          attributes = event.workflow_execution_terminated_event_attributes
+
+          raise Temporal::Error::WorkflowFailure.new(
+            cause: Temporal::Error::TerminatedError.new(
+              attributes&.reason || 'Workflow execution terminated',
+            ),
+          )
+
+        when :EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT
+          attributes = event.workflow_execution_timed_out_event_attributes
+          follow(attributes&.new_execution_run_id) if follow_runs
+
+          raise Temporal::Error::WorkflowFailure.new(
+            cause: Temporal::Error::TimeoutError.new(
+              'Workflow execution timed out',
+              type: Temporal::TimeoutType::START_TO_CLOSE,
+            ),
+          )
+
+        when :EVENT_TYPE_WORKFLOW_EXECUTION_CONTINUED_AS_NEW
+          attributes = event.workflow_execution_continued_as_new_event_attributes
+          follow(attributes&.new_execution_run_id) if follow_runs
+
+          # TODO: Use more specific error and decode failure
+          raise Temporal::Error, 'Workflow execution continued as new'
+        end
+      end
+
+      def follow(new_run_id)
+        return if !new_run_id || new_run_id.empty?
+
+        throw(:next, new_run_id) # next loop with a new run_id
+      end
+    end
+  end
+end

data/lib/temporal/client/workflow_handle.rb

@@ -0,0 +1,243 @@
+require 'temporal/interceptor/client'
+require 'temporal/workflow/query_reject_condition'
+
+module Temporal
+  class Client
+    # Handle for interacting with a workflow.
+    #
+    # This is usually created via {Temporal::Client#workflow_handle} or returned
+    # from {Temporal::Client#start_workflow}.
+    class WorkflowHandle
+      # @return [String] ID for the workflow.
+      attr_reader :id
+
+      # Run ID used for {#signal} and {#query} calls if present to ensure the query or signal happen
+      # on this exact run.
+      #
+      # This is only set on handles created via {Temporal::Client#workflow_handle} with a `run_id`
+      # parameter. {Temporal::Client#start_workflow} does not set this value.
+      #
+      # This cannot be mutated. If a different run ID is needed, {Temporal::Client#workflow_handle}
+      # must be used instead.
+      #
+      # @return [String]
+      attr_reader :run_id
+
+      # Run ID used for {#result} calls if present to ensure result is for a workflow starting from
+      # this run.
+      #
+      # When this handle is created via {Temporal::Client#workflow_handle}, this is the same as
+      # `:run_id`. When this handle is created via {Temporal::Client#start_workflow}, this value
+      # will be the resulting run ID.
+      #
+      # This cannot be mutated. If a different run ID is needed, {Temporal::Client#workflow_handle}
+      # must be used instead.
+      #
+      # @return [String]
+      attr_reader :result_run_id
+
+      # Run ID used for {#cancel} and {#terminate} calls if present to ensure the cancel and
+      # terminate happen for a workflow ID started with this run ID.
+      #
+      # This can be set when using {Temporal::Client#workflow_handle}. When
+      # {Temporal::Client#start_workflow} is called without a start signal, this is set to the
+      # resulting run.
+      #
+      # This cannot be mutated. If a different first execution run ID is needed,
+      # {Temporal::Client#workflow_handle} must be used instead.
+      #
+      # @return [String]
+      attr_reader :first_execution_run_id
+
+      def initialize(client_impl, id, run_id: nil, result_run_id: nil, first_execution_run_id: nil)
+        @client_impl = client_impl
+        @id = id
+        @run_id = run_id
+        @result_run_id = result_run_id
+        @first_execution_run_id = first_execution_run_id
+      end
+
+      # Wait for result of the workflow.
+      #
+      # This will use {#result_run_id} if present to base the result on. To use another run ID,
+      # a new handle must be created via {Temporal::Client#workflow_handle}.
+      #
+      # @param follow_runs [Bool] If true (default), workflow runs will be continually fetched,
+      #   until the most recent one is found. If false, the first result is used.
+      # @param rpc_metadata [Hash<String, String>] Headers used on the RPC call.
+      #   Keys here override client-level RPC metadata keys.
+      # @param rpc_timeout [Integer] Optional RPC deadline to set for each RPC call. Note, this is
+      #   the timeout for each history RPC call not this overall function.
+      #
+      # @return [any] Result of the workflow after being converted by the data converter.
+      #
+      # @raise [Temporal::Error::WorkflowFailure] Workflow failed, was cancelled, was terminated, or
+      #   timed out. Use the {Temporal::Error::WorkflowFailure#cause} to see the underlying reason.
+      # @raise [StandardError] Other possible failures during result fetching.
+      def result(follow_runs: true, rpc_metadata: {}, rpc_timeout: nil)
+        client_impl.await_workflow_result(id, result_run_id, follow_runs, rpc_metadata, rpc_timeout)
+      end
+
+      # Get workflow details.
+      #
+      # This will get details for {#run_id} if present. To use a different run ID, create a new
+      # handle with via {Temporal::Client#workflow_handle}.
+      #
+      # @note Handles created as a result of {Temporal::Client#start_workflow} will describe the
+      #   latest workflow with the same workflow ID even if it is unrelated to the started workflow.
+      #
+      # @param rpc_metadata [Hash<String, String>] Headers used on the RPC call.
+      #   Keys here override client-level RPC metadata keys.
+      # @param rpc_timeout [Integer] Optional RPC deadline to set for each RPC call. Note, this is
+      #   the timeout for each history RPC call not this overall function.
+      #
+      # @return [Temporal::Workflow::ExecutionInfo] Workflow details.
+      #
+      # @raise [Temporal::Error::RPCError] Workflow details could not be fetched.
+      def describe(rpc_metadata: {}, rpc_timeout: nil)
+        input = Interceptor::Client::DescribeWorkflowInput.new(
+          id: id,
+          run_id: run_id,
+          rpc_metadata: rpc_metadata,
+          rpc_timeout: rpc_timeout,
+        )
+
+        client_impl.describe_workflow(input)
+      end
+
+      # Cancel the workflow.
+      #
+      # This will issue a cancellation for {#run_id} if present. This call will make sure to use the
+      # run chain starting from {#first_execution_run_id} if present. To create handles with these
+      # values, use {Temporal::Client#workflow_handle}.
+      #
+      # @note Handles created as a result of {Temporal::Client#start_workflow} with a start signal
+      #   will cancel the latest workflow with the same workflow ID even if it is unrelated to the
+      #   started workflow.
+      #
+      # @param reason [String] A reason for workflow cancellation.
+      # @param rpc_metadata [Hash<String, String>] Headers used on the RPC call.
+      #   Keys here override client-level RPC metadata keys.
+      # @param rpc_timeout [Integer] Optional RPC deadline to set for each RPC call.
+      #
+      # @raise [Temporal::Error::RPCError] Workflow could not be cancelled.
+      def cancel(reason = nil, rpc_metadata: {}, rpc_timeout: nil)
+        input = Interceptor::Client::CancelWorkflowInput.new(
+          id: id,
+          run_id: run_id,
+          first_execution_run_id: first_execution_run_id,
+          reason: reason,
+          rpc_metadata: rpc_metadata,
+          rpc_timeout: rpc_timeout,
+        )
+
+        client_impl.cancel_workflow(input)
+      end
+
+      # Query the workflow.
+      #
+      # This will query for {#run_id} if present. To use a different run ID, create a new handle
+      # with via {Temporal::Client#workflow_handle}.
+      #
+      # @note Handles created as a result of {Temporal::Client#start_workflow} will query the latest
+      #   workflow with the same workflow ID even if it is unrelated to the started workflow.
+      #
+      # @param query [String, Symbol] Query function or name on the workflow.
+      # @param args [any] Arguments to the query.
+      # @param reject_condition [Symbol] Condition for rejecting the query. Refer to
+      #   {Temporal::Workflow::QueryRejectCondition} for the list of allowed values.
+      # @param rpc_metadata [Hash<String, String>] Headers used on the RPC call.
+      #   Keys here override client-level RPC metadata keys.
+      # @param rpc_timeout [Integer] Optional RPC deadline to set for each RPC call.
+      #
+      # @return [any] Result of the query.
+      #
+      # @raise [Temporal::Error] A query reject condition was satisfied.
+      # @raise [Temporal::Error::RPCError] Workflow details could not be fetched.
+      def query(
+        query,
+        *args,
+        reject_condition: Workflow::QueryRejectCondition::NONE,
+        rpc_metadata: {},
+        rpc_timeout: nil
+      )
+        input = Interceptor::Client::QueryWorkflowInput.new(
+          id: id,
+          run_id: run_id,
+          query: query,
+          args: args,
+          reject_condition: reject_condition,
+          headers: {},
+          rpc_metadata: rpc_metadata,
+          rpc_timeout: rpc_timeout,
+        )
+
+        client_impl.query_workflow(input)
+      end
+
+      # Send a signal to the workflow.
+      #
+      # This will signal for {#run_id} if present. To use a different run ID, create a new handle
+      # with via {Temporal::Client#workflow_handle}.
+      #
+      # @note Handles created as a result of {Temporal::Client#start_workflow} will signal the
+      #   latest workflow with the same workflow ID even if it is unrelated to the started workflow.
+      #
+      # @param signal [String, Symbol] Signal function or name on the workflow.
+      # @param args [any] Arguments to the signal.
+      # @param rpc_metadata [Hash<String, String>] Headers used on the RPC call.
+      #   Keys here override client-level RPC metadata keys.
+      # @param rpc_timeout [Integer] Optional RPC deadline to set for each RPC call.
+      #
+      # @return [Temporal::Error::RPCError] Workflow could not be signalled.
+      def signal(signal, *args, rpc_metadata: {}, rpc_timeout: nil)
+        input = Interceptor::Client::SignalWorkflowInput.new(
+          id: id,
+          run_id: run_id,
+          signal: signal,
+          args: args,
+          headers: {},
+          rpc_metadata: rpc_metadata,
+          rpc_timeout: rpc_timeout,
+        )
+
+        client_impl.signal_workflow(input)
+      end
+
+      # Terminate the workflow.
+      #
+      # This will issue a termination for {#run_id} if present. This call will make sure to use the
+      # run chain starting from {#first_execution_run_id} if present. To create handles with these
+      # values, use {Temporal::Client#workflow_handle}.
+
+      # @note Handles created as a result of {Temporal::Client#start_workflow} with a start signal
+      #   will terminate the latest workflow with the same workflow ID even if it is unrelated to
+      #   the started workflow.
+      #
+      # @param reason [String] A reason for workflow termination.
+      # @param args [any] Details to store on the termination.
+      # @param rpc_metadata [Hash<String, String>] Headers used on the RPC call.
+      #   Keys here override client-level RPC metadata keys.
+      # @param rpc_timeout [Integer] Optional RPC deadline to set for each RPC call.
+      #
+      # @raise [Temporal::Error::RPCError] Workflow could not be terminated.
+      def terminate(reason = nil, args = nil, rpc_metadata: {}, rpc_timeout: nil)
+        input = Interceptor::Client::TerminateWorkflowInput.new(
+          id: id,
+          run_id: run_id,
+          first_execution_run_id: first_execution_run_id,
+          reason: reason,
+          args: args,
+          rpc_metadata: rpc_metadata,
+          rpc_timeout: rpc_timeout,
+        )
+
+        client_impl.terminate_workflow(input)
+      end
+
+      private
+
+      attr_reader :client_impl
+    end
+  end
+end