temporalio 0.3.0-x86_64-linux-musl → 0.5.0-x86_64-linux-musl

data/lib/temporalio/client.rb

@@ -8,17 +8,22 @@ require 'temporalio/client/connection'
 require 'temporalio/client/interceptor'
 require 'temporalio/client/schedule'
 require 'temporalio/client/schedule_handle'
+require 'temporalio/client/with_start_workflow_operation'
 require 'temporalio/client/workflow_execution'
 require 'temporalio/client/workflow_execution_count'
 require 'temporalio/client/workflow_handle'
 require 'temporalio/client/workflow_query_reject_condition'
+require 'temporalio/client/workflow_update_handle'
+require 'temporalio/client/workflow_update_wait_stage'
 require 'temporalio/common_enums'
 require 'temporalio/converters'
 require 'temporalio/error'
 require 'temporalio/internal/client/implementation'
+require 'temporalio/priority'
 require 'temporalio/retry_policy'
 require 'temporalio/runtime'
 require 'temporalio/search_attributes'
+require 'temporalio/versioning_override'
 require 'temporalio/workflow/definition'
 
 module Temporalio
@@ -45,6 +50,16 @@ module Temporalio
     # Options as returned from {options} for +**to_h+ splat use in {initialize}. See {initialize} for details.
     class Options; end # rubocop:disable Lint/EmptyClass
 
+    ListWorkflowPage = Data.define(:executions, :next_page_token)
+
+    # A page of workflow executions returned by {Client#list_workflow_page}.
+    #
+    # @!attribute executions
+    #   @return [Array<WorkflowExecution>] List of workflow executions in this page.
+    # @!attribute next_page_token
+    #   @return [String, nil] Token for the next page of results. nil if there are no more results.
+    class ListWorkflowPage; end # rubocop:disable Lint/EmptyClass
+
     # Connect to Temporal server. This is a shortcut for +Connection.new+ followed by +Client.new+.
     #
     # @param target_host [String] +host:port+ for the Temporal server. For local development, this is often
@@ -155,7 +170,7 @@ module Temporalio
         default_workflow_query_reject_condition:
       ).freeze
       # Initialize interceptors
-      @impl = interceptors.reverse_each.reduce(Internal::Client::Implementation.new(self)) do |acc, int|
+      @impl = interceptors.reverse_each.reduce(Internal::Client::Implementation.new(self)) do |acc, int| # steep:ignore
         int.intercept_client(acc)
       end
     end
@@ -191,6 +206,12 @@ module Temporalio
     # @param args [Array<Object>] Arguments to the workflow.
     # @param id [String] Unique identifier for the workflow execution.
     # @param task_queue [String] Task queue to run the workflow on.
+    # @param static_summary [String, nil] Fixed single-line summary for this workflow execution that may appear in
+    #   CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.
+    # @param static_details [String, nil] Fixed details for this workflow execution that may appear in CLI/UI. This can
+    #   be in Temporal markdown format and can be multiple lines. This is a fixed value on the workflow that cannot be
+    #   updated. For details that can be updated, use {Workflow.current_details=} within the workflow. This is currently
+    #   experimental.
     # @param execution_timeout [Float, nil] Total workflow execution timeout in seconds including retries and continue
     #   as new.
     # @param run_timeout [Float, nil] Timeout of a single workflow run in seconds.
@@ -207,6 +228,13 @@ module Temporalio
     #   with `cron_schedule`.
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
+    # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
+    #   This is currently experimental.
+    # @param priority [Priority] Priority of the workflow. This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+    #   workflow definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
+    #   definition has result hint, it is used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [WorkflowHandle] A workflow handle to the started workflow.
@@ -217,6 +245,8 @@ module Temporalio
       *args,
       id:,
       task_queue:,
+      static_summary: nil,
+      static_details: nil,
       execution_timeout: nil,
       run_timeout: nil,
       task_timeout: nil,
@@ -228,13 +258,22 @@ module Temporalio
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
+      versioning_override: nil,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil,
       rpc_options: nil
     )
+      # Take hints from definition if there is a definition
+      workflow, defn_arg_hints, defn_result_hint =
+        Workflow::Definition._workflow_type_and_hints_from_workflow_parameter(workflow)
       @impl.start_workflow(Interceptor::StartWorkflowInput.new(
                              workflow:,
                              args:,
                              workflow_id: id,
                              task_queue:,
+                             static_summary:,
+                             static_details:,
                              execution_timeout:,
                              run_timeout:,
                              task_timeout:,
@@ -247,6 +286,10 @@ module Temporalio
                              start_delay:,
                              request_eager_start:,
                              headers: {},
+                             versioning_override:,
+                             priority:,
+                             arg_hints: arg_hints || defn_arg_hints,
+                             result_hint: result_hint || defn_result_hint,
                              rpc_options:
                            ))
     end
@@ -257,6 +300,12 @@ module Temporalio
     # @param args [Array<Object>] Arguments to the workflow.
     # @param id [String] Unique identifier for the workflow execution.
     # @param task_queue [String] Task queue to run the workflow on.
+    # @param static_summary [String, nil] Fixed single-line summary for this workflow execution that may appear in
+    #   CLI/UI. This can be in single-line Temporal markdown format. This is currently experimental.
+    # @param static_details [String, nil] Fixed details for this workflow execution that may appear in CLI/UI. This can
+    #   be in Temporal markdown format and can be multiple lines. This is a fixed value on the workflow that cannot be
+    #   updated. For details that can be updated, use {Workflow.current_details=} within the workflow. This is currently
+    #   experimental.
     # @param execution_timeout [Float, nil] Total workflow execution timeout in seconds including retries and continue
     #   as new.
     # @param run_timeout [Float, nil] Timeout of a single workflow run in seconds.
@@ -273,6 +322,13 @@ module Temporalio
     #   with `cron_schedule`.
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
+    # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
+    #   This is currently experimental.
+    # @param priority [Priority] Priority for the workflow. This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+    #   workflow definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
+    #   definition has result hint, it is used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [Object] Successful result of the workflow.
@@ -284,6 +340,8 @@ module Temporalio
       *args,
       id:,
       task_queue:,
+      static_summary: nil,
+      static_details: nil,
       execution_timeout: nil,
       run_timeout: nil,
       task_timeout: nil,
@@ -295,6 +353,10 @@ module Temporalio
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
+      versioning_override: nil,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil,
       rpc_options: nil
     )
       start_workflow(
@@ -302,6 +364,8 @@ module Temporalio
         *args,
         id:,
         task_queue:,
+        static_summary:,
+        static_details:,
         execution_timeout:,
         run_timeout:,
         task_timeout:,
@@ -313,6 +377,10 @@ module Temporalio
         search_attributes:,
         start_delay:,
         request_eager_start:,
+        versioning_override:,
+        priority:,
+        arg_hints:,
+        result_hint:,
         rpc_options:
       ).result
     end
@@ -324,14 +392,140 @@ module Temporalio
     #   interactions occur on the latest of the workflow ID.
     # @param first_execution_run_id [String, nil] First execution run ID used for some calls like cancellation and
     #   termination to ensure the affected workflow is only within the same chain as this given run ID.
+    # @param result_hint [Object, nil] Converter hint for the workflow's result.
     #
     # @return [WorkflowHandle] The workflow handle.
     def workflow_handle(
       workflow_id,
       run_id: nil,
-      first_execution_run_id: nil
+      first_execution_run_id: nil,
+      result_hint: nil
+    )
+      WorkflowHandle.new(
+        client: self, id: workflow_id, run_id:, result_run_id: run_id, first_execution_run_id:, result_hint:
+      )
+    end
+
+    # Start an update, possibly starting the workflow at the same time if it doesn't exist (depending upon ID conflict
+    # policy). Note that in some cases this may fail but the workflow will still be started, and the handle can then be
+    # retrieved on the start workflow operation.
+    #
+    # @param update [Workflow::Definition::Update, Symbol, String] Update definition or name.
+    # @param args [Array<Object>] Update arguments.
+    # @param start_workflow_operation [WithStartWorkflowOperation] Required with-start workflow operation. This must
+    #   have an `id_conflict_policy` set.
+    # @param wait_for_stage [WorkflowUpdateWaitStage] Required stage to wait until returning. ADMITTED is not
+    #   currently supported. See https://docs.temporal.io/workflows#update for more details.
+    # @param id [String] ID of the update.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for update arguments if any. If unset/nil and the
+    #   update definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for update result if any. If unset/nil and the update
+    #   definition has result hint, it is used by default.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [WorkflowUpdateHandle] The update handle.
+    # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists and conflict/reuse policy does not allow.
+    # @raise [Error::WorkflowUpdateRPCTimeoutOrCanceledError] This update call timed out or was canceled. This doesn't
+    #   mean the update itself was timed out or canceled, and this doesn't mean the workflow did not start.
+    # @raise [Error::RPCError] RPC error from call.
+    def start_update_with_start_workflow(
+      update,
+      *args,
+      start_workflow_operation:,
+      wait_for_stage:,
+      id: SecureRandom.uuid,
+      arg_hints: nil,
+      result_hint: nil,
+      rpc_options: nil
+    )
+      update, defn_arg_hints, defn_result_hint = Workflow::Definition::Update._name_and_hints_from_parameter(update)
+      @impl.start_update_with_start_workflow(
+        Interceptor::StartUpdateWithStartWorkflowInput.new(
+          update_id: id,
+          update:,
+          args:,
+          wait_for_stage:,
+          start_workflow_operation:,
+          arg_hints: arg_hints || defn_arg_hints,
+          result_hint: result_hint || defn_result_hint,
+          headers: {},
+          rpc_options:
+        )
+      )
+    end
+
+    # Start an update, possibly starting the workflow at the same time if it doesn't exist (depending upon ID conflict
+    # policy), and wait for update result. This is a shortcut for {start_update_with_start_workflow} +
+    # {WorkflowUpdateHandle.result}.
+    #
+    # @param update [Workflow::Definition::Update, Symbol, String] Update definition or name.
+    # @param args [Array<Object>] Update arguments.
+    # @param start_workflow_operation [WithStartWorkflowOperation] Required with-start workflow operation. This must
+    #   have an `id_conflict_policy` set.
+    # @param id [String] ID of the update.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for update arguments if any. If unset/nil and the
+    #   update definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for update result if any. If unset/nil and the update
+    #   definition has result hint, it is used by default.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [Object] Successful update result.
+    # @raise [Error::WorkflowUpdateFailedError] If the update failed.
+    # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists and conflict/reuse policy does not allow.
+    # @raise [Error::WorkflowUpdateRPCTimeoutOrCanceledError] This update call timed out or was canceled. This doesn't
+    #   mean the update itself was timed out or canceled, and this doesn't mean the workflow did not start.
+    # @raise [Error::RPCError] RPC error from call.
+    def execute_update_with_start_workflow(
+      update,
+      *args,
+      start_workflow_operation:,
+      id: SecureRandom.uuid,
+      arg_hints: nil,
+      result_hint: nil,
+      rpc_options: nil
+    )
+      start_update_with_start_workflow(
+        update,
+        *args,
+        start_workflow_operation:,
+        wait_for_stage: WorkflowUpdateWaitStage::COMPLETED,
+        id:,
+        arg_hints:,
+        result_hint:,
+        rpc_options:
+      ).result
+    end
+
+    # Send a signal, possibly starting the workflow at the same time if it doesn't exist.
+    #
+    # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
+    # @param args [Array<Object>] Signal arguments.
+    # @param start_workflow_operation [WithStartWorkflowOperation] Required with-start workflow operation. This may not
+    #   support all `id_conflict_policy` options.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for signal arguments if any. If unset/nil and the
+    #   signal definition has arg hints, those are used by default.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [WorkflowHandle] A workflow handle to the workflow.
+    # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists and conflict/reuse policy does not allow.
+    # @raise [Error::RPCError] RPC error from call.
+    def signal_with_start_workflow(
+      signal,
+      *args,
+      start_workflow_operation:,
+      arg_hints: nil,
+      rpc_options: nil
     )
-      WorkflowHandle.new(client: self, id: workflow_id, run_id:, result_run_id: run_id, first_execution_run_id:)
+      signal, defn_arg_hints = Workflow::Definition::Signal._name_and_hints_from_parameter(signal)
+      @impl.signal_with_start_workflow(
+        Interceptor::SignalWithStartWorkflowInput.new(
+          signal:,
+          args:,
+          start_workflow_operation:,
+          arg_hints: arg_hints || defn_arg_hints,
+          rpc_options:
+        )
+      )
     end
 
     # List workflows.
@@ -345,7 +539,40 @@ module Temporalio
     #
     # @see https://docs.temporal.io/visibility
     def list_workflows(query = nil, rpc_options: nil)
-      @impl.list_workflows(Interceptor::ListWorkflowsInput.new(query:, rpc_options:))
+      next_page_token = nil
+      Enumerator.new do |yielder|
+        loop do
+          list_workflow_page_input = Interceptor::ListWorkflowPageInput.new(
+            query: query,
+            rpc_options: rpc_options,
+            next_page_token: next_page_token,
+            page_size: nil
+          )
+          page = @impl.list_workflow_page(list_workflow_page_input)
+          page.executions.each { |execution| yielder << execution }
+          next_page_token = page.next_page_token
+          break if (next_page_token || '').empty?
+        end
+      end
+    end
+
+    # List workflows one page at a time.
+    #
+    # @param query [String, nil] A Temporal visibility list filter.
+    # @param page_size [Integer, nil] Maximum number of results to return.
+    # @param next_page_token [String, nil] Token for the next page of results. If not set, the first page is returned.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [ListWorkflowPage] Page of workflow executions, along with a next_page_token to keep fetching.
+    #
+    # @raise [Error::RPCError] RPC error from call.
+    #
+    # @see https://docs.temporal.io/visibility
+    def list_workflow_page(query = nil, page_size: nil, next_page_token: nil, rpc_options: nil)
+      @impl.list_workflow_page(Interceptor::ListWorkflowPageInput.new(query:,
+                                                                      next_page_token:,
+                                                                      page_size:,
+                                                                      rpc_options:))
     end
 
     # Count workflows.

data/lib/temporalio/common_enums.rb

@@ -38,4 +38,18 @@ module Temporalio
     # Terminate the running workflow before starting a new one.
     TERMINATE_EXISTING = Api::Enums::V1::WorkflowIdConflictPolicy::WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING
   end
+
+  # Specifies when a workflow might move from a worker of one Build Id to another.
+  #
+  # WARNING: Experimental API.
+  module VersioningBehavior
+    # Unspecified versioning behavior. By default, workers opting into worker versioning will
+    # be required to specify a behavior.
+    UNSPECIFIED = Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_UNSPECIFIED
+    # The workflow will be pinned to the current Build ID unless manually moved.
+    PINNED = Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_PINNED
+    # The workflow will automatically move to the latest version (default Build ID of the task
+    # queue) when the next task is dispatched.
+    AUTO_UPGRADE = Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_AUTO_UPGRADE
+  end
 end