temporalio 0.2.0 → 0.4.0

data/lib/temporalio/client/workflow_update_handle.rb

@@ -36,8 +36,7 @@ module Temporalio
       # Wait for and return the result of the update. The result may already be known in which case no network call is
       # made. Otherwise the result will be polled for until it is returned.
       #
-      # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-      # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
       #
@@ -45,13 +44,12 @@ module Temporalio
       # @raise [Error::WorkflowUpdateRPCTimeoutOrCanceledError] This update call timed out or was canceled. This doesn't
       #   mean the update itself was timed out or canceled.
       # @raise [Error::RPCError] RPC error from call.
-      def result(rpc_metadata: nil, rpc_timeout: nil)
+      def result(rpc_options: nil)
         @known_outcome ||= @client._impl.poll_workflow_update(Interceptor::PollWorkflowUpdateInput.new(
                                                                 workflow_id:,
                                                                 run_id: workflow_run_id,
                                                                 update_id: id,
-                                                                rpc_metadata:,
-                                                                rpc_timeout:
+                                                                rpc_options:
                                                               ))
 
         if @known_outcome.failure

data/lib/temporalio/client.rb

@@ -6,10 +6,15 @@ require 'temporalio/api'
 require 'temporalio/client/async_activity_handle'
 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'
@@ -17,6 +22,7 @@ require 'temporalio/internal/client/implementation'
 require 'temporalio/retry_policy'
 require 'temporalio/runtime'
 require 'temporalio/search_attributes'
+require 'temporalio/workflow/definition'
 
 module Temporalio
   # Client for accessing Temporal.
@@ -30,17 +36,18 @@ module Temporalio
   # synchronous and asynchronous contexts. Internally they use callbacks based on {::Queue} which means they are
   # Fiber-compatible.
   class Client
-    # Options as returned from {options} for +**to_h+ splat use in {initialize}. See {initialize} for details.
-    Options = Struct.new(
+    Options = Data.define(
       :connection,
       :namespace,
       :data_converter,
       :interceptors,
       :logger,
-      :default_workflow_query_reject_condition,
-      keyword_init: true
+      :default_workflow_query_reject_condition
     )
 
+    # Options as returned from {options} for +**to_h+ splat use in {initialize}. See {initialize} for details.
+    class Options; 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
@@ -151,7 +158,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
@@ -183,10 +190,16 @@ module Temporalio
 
     # Start a workflow and return its handle.
     #
-    # @param workflow [Workflow, String] Name of the workflow
+    # @param workflow [Class<Workflow::Definition>, String, Symbol] Workflow definition class or workflow name.
     # @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.
@@ -197,14 +210,13 @@ module Temporalio
     #   is set to terminate if running.
     # @param retry_policy [RetryPolicy, nil] Retry policy for the workflow.
     # @param cron_schedule [String, nil] Cron schedule. Users should use schedules instead of this.
-    # @param memo [Hash<String, Object>, nil] Memo for the workflow.
+    # @param memo [Hash{String, Symbol => Object}, nil] Memo for the workflow.
     # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow.
     # @param start_delay [Float, nil] Amount of time in seconds to wait before starting the workflow. This does not work
     #   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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-    # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [WorkflowHandle] A workflow handle to the started workflow.
     # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists.
@@ -214,6 +226,8 @@ module Temporalio
       *args,
       id:,
       task_queue:,
+      static_summary: nil,
+      static_details: nil,
       execution_timeout: nil,
       run_timeout: nil,
       task_timeout: nil,
@@ -225,14 +239,15 @@ module Temporalio
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
-      rpc_metadata: nil,
-      rpc_timeout: nil
+      rpc_options: nil
     )
       @impl.start_workflow(Interceptor::StartWorkflowInput.new(
-                             workflow:,
+                             workflow: Workflow::Definition._workflow_type_from_workflow_parameter(workflow),
                              args:,
                              workflow_id: id,
                              task_queue:,
+                             static_summary:,
+                             static_details:,
                              execution_timeout:,
                              run_timeout:,
                              task_timeout:,
@@ -245,17 +260,22 @@ module Temporalio
                              start_delay:,
                              request_eager_start:,
                              headers: {},
-                             rpc_metadata:,
-                             rpc_timeout:
+                             rpc_options:
                            ))
     end
 
     # Start a workflow and wait for its result. This is a shortcut for {start_workflow} + {WorkflowHandle.result}.
     #
-    # @param workflow [Workflow, String] Name of the workflow
+    # @param workflow [Class<Workflow::Definition>, Symbol, String] Workflow definition class or workflow name.
     # @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.
@@ -266,14 +286,13 @@ module Temporalio
     #   is set to terminate if running.
     # @param retry_policy [RetryPolicy, nil] Retry policy for the workflow.
     # @param cron_schedule [String, nil] Cron schedule. Users should use schedules instead of this.
-    # @param memo [Hash<String, Object>, nil] Memo for the workflow.
+    # @param memo [Hash{String, Symbol => Object}, nil] Memo for the workflow.
     # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow.
     # @param start_delay [Float, nil] Amount of time in seconds to wait before starting the workflow. This does not work
     #   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 rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-    # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [Object] Successful result of the workflow.
     # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists.
@@ -284,6 +303,8 @@ module Temporalio
       *args,
       id:,
       task_queue:,
+      static_summary: nil,
+      static_details: nil,
       execution_timeout: nil,
       run_timeout: nil,
       task_timeout: nil,
@@ -295,14 +316,15 @@ module Temporalio
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
-      rpc_metadata: nil,
-      rpc_timeout: nil
+      rpc_options: nil
     )
       start_workflow(
         workflow,
         *args,
         id:,
         task_queue:,
+        static_summary:,
+        static_details:,
         execution_timeout:,
         run_timeout:,
         task_timeout:,
@@ -314,8 +336,7 @@ module Temporalio
         search_attributes:,
         start_delay:,
         request_eager_start:,
-        rpc_metadata:,
-        rpc_timeout:
+        rpc_options:
       ).result
     end
 
@@ -336,52 +357,195 @@ module Temporalio
       WorkflowHandle.new(client: self, id: workflow_id, run_id:, result_run_id: run_id, first_execution_run_id:)
     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 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,
+      rpc_options: nil
+    )
+      @impl.start_update_with_start_workflow(
+        Interceptor::StartUpdateWithStartWorkflowInput.new(
+          update_id: id,
+          update: Workflow::Definition::Update._name_from_parameter(update),
+          args:,
+          wait_for_stage:,
+          start_workflow_operation:,
+          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 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,
+      rpc_options: nil
+    )
+      start_update_with_start_workflow(
+        update,
+        *args,
+        start_workflow_operation:,
+        wait_for_stage: WorkflowUpdateWaitStage::COMPLETED,
+        id:,
+        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 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:,
+      rpc_options: nil
+    )
+      @impl.signal_with_start_workflow(
+        Interceptor::SignalWithStartWorkflowInput.new(
+          signal: Workflow::Definition::Signal._name_from_parameter(signal),
+          args:,
+          start_workflow_operation:,
+          rpc_options:
+        )
+      )
+    end
+
     # List workflows.
     #
     # @param query [String, nil] A Temporal visibility list filter.
-    # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-    # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [Enumerator<WorkflowExecution>] Enumerable workflow executions.
     #
     # @raise [Error::RPCError] RPC error from call.
     #
     # @see https://docs.temporal.io/visibility
-    def list_workflows(
-      query = nil,
-      rpc_metadata: nil,
-      rpc_timeout: nil
-    )
-      @impl.list_workflows(Interceptor::ListWorkflowsInput.new(
-                             query:,
-                             rpc_metadata:,
-                             rpc_timeout:
-                           ))
+    def list_workflows(query = nil, rpc_options: nil)
+      @impl.list_workflows(Interceptor::ListWorkflowsInput.new(query:, rpc_options:))
     end
 
     # Count workflows.
     #
     # @param query [String, nil] A Temporal visibility list filter.
-    # @param rpc_metadata [Hash<String, String>, nil] Headers to include on the RPC call.
-    # @param rpc_timeout [Float, nil] Number of seconds before timeout.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [WorkflowExecutionCount] Count of workflows.
     #
     # @raise [Error::RPCError] RPC error from call.
     #
     # @see https://docs.temporal.io/visibility
-    def count_workflows(
-      query = nil,
-      rpc_metadata: nil,
-      rpc_timeout: nil
+    def count_workflows(query = nil, rpc_options: nil)
+      @impl.count_workflows(Interceptor::CountWorkflowsInput.new(query:, rpc_options:))
+    end
+
+    # Create a schedule and return its handle.
+    #
+    # @param id [String] Unique identifier of the schedule.
+    # @param schedule [Schedule] Schedule to create.
+    # @param trigger_immediately [Boolean]  If true, trigger one action immediately when creating the schedule.
+    # @param backfills [Array<Schedule::Backfill>] Set of time periods to take actions on as if that time passed right
+    #   now.
+    # @param memo [Hash<String, Object>, nil] Memo for the schedule. Memo for a scheduled workflow is part of the
+    #   schedule action.
+    # @param search_attributes [SearchAttributes, nil] Search attributes for the schedule. Search attributes for a
+    #   scheduled workflow are part of the scheduled action.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [ScheduleHandle] A handle to the created schedule.
+    # @raise [Error::ScheduleAlreadyRunningError] If a schedule with this ID is already running.
+    # @raise [Error::RPCError] RPC error from call.
+    def create_schedule(
+      id,
+      schedule,
+      trigger_immediately: false,
+      backfills: [],
+      memo: nil,
+      search_attributes: nil,
+      rpc_options: nil
     )
-      @impl.count_workflows(Interceptor::CountWorkflowsInput.new(
-                              query:,
-                              rpc_metadata:,
-                              rpc_timeout:
+      @impl.create_schedule(Interceptor::CreateScheduleInput.new(
+                              id:,
+                              schedule:,
+                              trigger_immediately:,
+                              backfills:,
+                              memo:,
+                              search_attributes:,
+                              rpc_options:
                             ))
     end
 
+    # Get a schedule handle to an existing schedule for the given ID.
+    #
+    # @param id [String] Schedule ID to get a handle to.
+    # @return [ScheduleHandle] The schedule handle.
+    def schedule_handle(id)
+      ScheduleHandle.new(client: self, id:)
+    end
+
+    # List schedules.
+    #
+    # Note, this list is eventually consistent. Therefore if a schedule is added or deleted, it may not be available in
+    # the list immediately.
+    #
+    # @param query [String] A Temporal visibility list filter.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [Enumerator<Schedule::List::Description>] Enumerable schedules.
+    #
+    # @raise [Error::RPCError] RPC error from call.
+    #
+    # @see https://docs.temporal.io/visibility
+    def list_schedules(query = nil, rpc_options: nil)
+      @impl.list_schedules(Interceptor::ListSchedulesInput.new(query:, rpc_options:))
+    end
+
     # Get an async activity handle.
     #
     # @param task_token_or_id_reference [String, ActivityIDReference] Task token string or activity ID reference.
@@ -400,5 +564,44 @@ module Temporalio
     def _impl
       @impl
     end
+
+    # Set of RPC options for RPC calls.
+    class RPCOptions
+      # @return [Hash<String, String>, nil] Headers to include on the RPC call.
+      attr_accessor :metadata
+
+      # @return [Float, nil] Number of seconds before timeout of the RPC call.
+      attr_accessor :timeout
+
+      # @return [Cancellation, nil] Cancellation to use to potentially cancel the call. If canceled, the RPC will return
+      #   {Error::CanceledError}.
+      attr_accessor :cancellation
+
+      # @return [Boolean, nil] Whether to override the default retry option which decides whether to retry calls
+      #   implicitly when known transient error codes are reached. By default when this is nil, high-level calls retry
+      #   known transient error codes and low-level/direct calls do not.
+      attr_accessor :override_retry
+
+      # Create RPC options.
+      #
+      # @param metadata [Hash<String, String>, nil] Headers to include on the RPC call.
+      # @param timeout [Float, nil] Number of seconds before timeout of the RPC call.
+      # @param cancellation [Cancellation, nil] Cancellation to use to potentially cancel the call. If canceled, the RPC
+      #   will return {Error::CanceledError}.
+      # @param override_retry [Boolean, nil] Whether to override the default retry option which decides whether to retry
+      #   calls implicitly when known transient error codes are reached. By default when this is nil, high-level calls
+      #   retry known transient error codes and low-level/direct calls do not.
+      def initialize(
+        metadata: nil,
+        timeout: nil,
+        cancellation: nil,
+        override_retry: nil
+      )
+        @metadata = metadata
+        @timeout = timeout
+        @cancellation = cancellation
+        @override_retry = override_retry
+      end
+    end
   end
 end

data/lib/temporalio/common_enums.rb

@@ -7,18 +7,35 @@ module Temporalio
   #
   # @see https://docs.temporal.io/workflows#workflow-id-reuse-policy
   module WorkflowIDReusePolicy
+    # Allow starting a workflow execution using the same workflow ID.
     ALLOW_DUPLICATE = Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE
+    # Allow starting a workflow execution using the same workflow ID, only when the last execution's final state is one
+    # of terminated, canceled, timed out, or failed.
     ALLOW_DUPLICATE_FAILED_ONLY =
       Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY
+    # Do not permit re-use of the workflow ID for this workflow. Future start workflow requests could potentially change
+    # the policy, allowing re-use of the workflow ID.
     REJECT_DUPLICATE = Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE
+    # This option is {WorkflowIDConflictPolicy::TERMINATE_EXISTING} but is here for backwards compatibility. If
+    # specified, it acts like {ALLOW_DUPLICATE}, but also the {WorkflowIDConflictPolicy} on the request is treated as
+    # {WorkflowIDConflictPolicy::TERMINATE_EXISTING}. If no running workflow, then the behavior is the same as
+    # {ALLOW_DUPLICATE}.
+    #
+    # @deprecated Use {WorkflowIDConflictPolicy::TERMINATE_EXISTING} instead.
     TERMINATE_IF_RUNNING = Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING
   end
 
   # How already-running workflows of the same ID are handled on start.
+  #
+  # @see https://docs.temporal.io/workflows#workflow-id-conflict-policy
   module WorkflowIDConflictPolicy
+    # Unset.
     UNSPECIFIED = Api::Enums::V1::WorkflowIdConflictPolicy::WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED
+    # Don't start a new workflow, instead fail with already-started error.
     FAIL = Api::Enums::V1::WorkflowIdConflictPolicy::WORKFLOW_ID_CONFLICT_POLICY_FAIL
+    # Don't start a new workflow, instead return a workflow handle for the running workflow.
     USE_EXISTING = Api::Enums::V1::WorkflowIdConflictPolicy::WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING
+    # Terminate the running workflow before starting a new one.
     TERMINATE_EXISTING = Api::Enums::V1::WorkflowIdConflictPolicy::WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING
   end
 end