temporalio 1.4.1 → 1.5.0

data/lib/temporalio/client/activity_id_reference.rb

@@ -6,26 +6,61 @@ require 'temporalio/error'
 
 module Temporalio
   class Client
-    # Reference to an existing activity by its workflow ID, run ID, and activity ID.
+    # Reference to an activity for use with {Client#async_activity_handle}. There are two shapes,
+    # depending on whether the activity is run in a workflow, or as a standalone activity.
+    #
+    # 1. Activity run in a workflow -- use {ActivityIDReference#initialize}:
+    #    `ActivityIDReference.new(workflow_id:, run_id:, activity_id:)`.
+    #
+    # 2. Standalone Activity (started  via {Client#start_activity}): use the class factory
+    #    {ActivityIDReference.for_standalone}: `ActivityIDReference.for_standalone(activity_id:, activity_run_id:)`.
     class ActivityIDReference
-      # @return [String] ID for the workflow.
+      # @return [String] ID for the activity.
+      attr_reader :activity_id
+
+      # @return [String, nil] Activity run ID. Set only for standalone activity references.
+      attr_reader :activity_run_id
+
+      # @return [String, nil] ID for the workflow. Set only for workflow-run activity references.
       attr_reader :workflow_id
 
-      # @return [String, nil] Run ID for the workflow.
+      # @return [String, nil] Run ID for the workflow. Set only for workflow-run activity references.
       attr_reader :run_id
 
-      # @return [String] ID for the activity.
-      attr_reader :activity_id
+      # Construct a standalone activity reference.
+      #
+      # WARNING: Standalone Activities are experimental.
+      #
+      # @param activity_id [String] ID for the activity.
+      # @param activity_run_id [String, nil] Run ID for the activity execution. nil targets the latest run.
+      # @return [ActivityIDReference] A reference suitable for {Client#async_activity_handle}.
+      def self.for_standalone(activity_id:, activity_run_id: nil)
+        allocate.tap do |ref|
+          ref.instance_variable_set(:@activity_id, activity_id)
+          ref.instance_variable_set(:@activity_run_id, activity_run_id)
+          ref.instance_variable_set(:@workflow_id, nil)
+          ref.instance_variable_set(:@run_id, nil)
+        end
+      end
 
-      # Create an activity ID reference.
+      # Construct a workflow-run activity reference.
       #
       # @param workflow_id [String] ID for the workflow.
       # @param run_id [String, nil] Run ID for the workflow.
-      # @param activity_id [String] ID for the workflow.
+      # @param activity_id [String] ID for the activity.
+      # @return [ActivityIDReference] A reference suitable for {Client#async_activity_handle}.
       def initialize(workflow_id:, run_id:, activity_id:)
         @workflow_id = workflow_id
         @run_id = run_id
         @activity_id = activity_id
+        @activity_run_id = nil
+      end
+
+      # @return [Boolean] True if this reference is the standalone-form (activity_run_id without workflow_id).
+      #
+      # WARNING: Standalone Activities are experimental.
+      def standalone?
+        @workflow_id.nil?
       end
     end
   end

data/lib/temporalio/client/interceptor.rb

@@ -259,6 +259,87 @@ module Temporalio
         :rpc_options
       )
 
+      # Input for {Outbound.start_activity}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      StartActivityInput = Data.define(
+        :activity,
+        :args,
+        :activity_id,
+        :task_queue,
+        :schedule_to_close_timeout,
+        :schedule_to_start_timeout,
+        :start_to_close_timeout,
+        :heartbeat_timeout,
+        :id_reuse_policy,
+        :id_conflict_policy,
+        :retry_policy,
+        :search_attributes,
+        :static_summary,
+        :static_details,
+        :headers,
+        :priority,
+        :start_delay,
+        :arg_hints,
+        :result_hint,
+        :rpc_options
+      )
+
+      # Input for {Outbound.describe_activity}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      DescribeActivityInput = Data.define(
+        :activity_id,
+        :activity_run_id,
+        :rpc_options
+      )
+
+      # Input for {Outbound.cancel_activity}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      CancelActivityInput = Data.define(
+        :activity_id,
+        :activity_run_id,
+        :reason,
+        :rpc_options
+      )
+
+      # Input for {Outbound.terminate_activity}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      TerminateActivityInput = Data.define(
+        :activity_id,
+        :activity_run_id,
+        :reason,
+        :rpc_options
+      )
+
+      # Input for {Outbound.list_activities}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      ListActivitiesInput = Data.define(
+        :query,
+        :rpc_options
+      )
+
+      # Input for {Outbound.count_activities}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      CountActivitiesInput = Data.define(
+        :query,
+        :rpc_options
+      )
+
+      # Input for {Outbound.fetch_activity_outcome}. Used by `ActivityHandle#result` for long-polling
+      # the activity outcome via `PollActivityExecution`.
+      #
+      # WARNING: Standalone Activities are experimental.
+      FetchActivityOutcomeInput = Data.define(
+        :activity_id,
+        :activity_run_id,
+        :rpc_options
+      )
+
       # Outbound interceptor for intercepting client calls. This should be extended by users needing to intercept client
       # actions.
       class Outbound
@@ -467,6 +548,74 @@ module Temporalio
         def report_cancellation_async_activity(input)
           next_interceptor.report_cancellation_async_activity(input)
         end
+
+        # Called for every {Client.start_activity} and {Client.execute_activity} call.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [StartActivityInput] Input.
+        # @return [ActivityHandle] Activity handle.
+        def start_activity(input)
+          next_interceptor.start_activity(input)
+        end
+
+        # Called for every {ActivityHandle.describe} call.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [DescribeActivityInput] Input.
+        # @return [ActivityExecution::Description] Activity description.
+        def describe_activity(input)
+          next_interceptor.describe_activity(input)
+        end
+
+        # Called for every {ActivityHandle.cancel} call.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [CancelActivityInput] Input.
+        def cancel_activity(input)
+          next_interceptor.cancel_activity(input)
+        end
+
+        # Called for every {ActivityHandle.terminate} call.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [TerminateActivityInput] Input.
+        def terminate_activity(input)
+          next_interceptor.terminate_activity(input)
+        end
+
+        # Called for every {Client.list_activities} call.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [ListActivitiesInput] Input.
+        # @return [Enumerator<ActivityExecution>] Activity executions.
+        def list_activities(input)
+          next_interceptor.list_activities(input)
+        end
+
+        # Called for every {Client.count_activities} call.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [CountActivitiesInput] Input.
+        # @return [ActivityExecutionCount] Activity count.
+        def count_activities(input)
+          next_interceptor.count_activities(input)
+        end
+
+        # Called by {ActivityHandle.result} to long-poll the activity outcome.
+        #
+        # WARNING: Standalone Activities are experimental.
+        #
+        # @param input [FetchActivityOutcomeInput] Input.
+        # @return [Api::Activity::V1::ActivityExecutionOutcome] Activity outcome.
+        def fetch_activity_outcome(input)
+          next_interceptor.fetch_activity_outcome(input)
+        end
       end
     end
   end

data/lib/temporalio/client/pending_activity_state.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+
+module Temporalio
+  class Client
+    # More detailed breakdown of a running activity's state.
+    #
+    # WARNING: Standalone Activities are experimental.
+    module PendingActivityState
+      SCHEDULED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_SCHEDULED
+      STARTED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_STARTED
+      CANCEL_REQUESTED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_CANCEL_REQUESTED
+      PAUSED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_PAUSED
+      PAUSE_REQUESTED = Api::Enums::V1::PendingActivityState::PENDING_ACTIVITY_STATE_PAUSE_REQUESTED
+    end
+  end
+end

data/lib/temporalio/client/with_start_workflow_operation.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'temporalio/common_enums'
+require 'temporalio/priority'
 
 module Temporalio
   class Client
@@ -24,6 +25,7 @@ module Temporalio
         :memo,
         :search_attributes,
         :start_delay,
+        :priority,
         :arg_hints,
         :result_hint,
         :headers
@@ -40,6 +42,8 @@ module Temporalio
       #
       # Note, for {Client.start_update_with_start_workflow} and {Client.execute_update_with_start_workflow},
       # `id_conflict_policy` is required.
+      #
+      # @param priority [Priority] Priority of the workflow that may be started. This is currently experimental.
       def initialize(
         workflow,
         *args,
@@ -57,6 +61,7 @@ module Temporalio
         memo: nil,
         search_attributes: nil,
         start_delay: nil,
+        priority: Priority.default,
         arg_hints: nil,
         result_hint: nil,
         headers: {}
@@ -80,6 +85,7 @@ module Temporalio
           memo:,
           search_attributes:,
           start_delay:,
+          priority:,
           arg_hints: arg_hints || defn_arg_hints,
           result_hint: result_hint || defn_result_hint,
           headers:

data/lib/temporalio/client.rb

@@ -3,6 +3,7 @@
 require 'google/protobuf/well_known_types'
 require 'logger'
 require 'temporalio/api'
+require 'temporalio/client/activity_handle'
 require 'temporalio/client/async_activity_handle'
 require 'temporalio/client/connection'
 require 'temporalio/client/interceptor'
@@ -478,6 +479,209 @@ module Temporalio
       )
     end
 
+    # Get a handle for an existing standalone activity. Useful when the activity was started elsewhere
+    # (a different process, or by another client) and you have only its ID.
+    #
+    # WARNING: Standalone Activities are experimental.
+    #
+    # @param activity_id [String] ID for the activity.
+    # @param activity_run_id [String, nil] Run ID for the activity execution. If nil, operations target the
+    #   latest run of the given activity ID.
+    # @param result_hint [Object, nil] Converter hint for the activity's result. Set this when you know what
+    #   type the activity returns so {ActivityHandle#result}'s deserialization uses the right hint.
+    #
+    # @return [ActivityHandle] The activity handle.
+    def activity_handle(activity_id, activity_run_id: nil, result_hint: nil)
+      ActivityHandle.new(client: self, id: activity_id, run_id: activity_run_id, result_hint:)
+    end
+
+    # Start a standalone activity execution and return its handle.
+    #
+    # WARNING: Standalone Activities are experimental.
+    #
+    # @param activity [Class<Activity::Definition>, Activity::Definition, Activity::Definition::Info, Symbol, String]
+    #   Activity definition, definition class or activity name.
+    # @param args [Array<Object>] Arguments to the activity.
+    # @param id [String] Unique identifier for the activity execution.
+    # @param task_queue [String] Task queue to run the activity on.
+    # @param schedule_to_close_timeout [Float, nil] Schedule-to-close timeout in seconds. Either this or
+    #   `start_to_close_timeout` must be specified.
+    # @param schedule_to_start_timeout [Float, nil] Schedule-to-start timeout in seconds.
+    # @param start_to_close_timeout [Float, nil] Start-to-close timeout in seconds. Either this or
+    #   `schedule_to_close_timeout` must be specified.
+    # @param heartbeat_timeout [Float, nil] Heartbeat timeout in seconds.
+    # @param id_reuse_policy [ActivityIDReusePolicy] Controls behavior when an activity with the same ID
+    #   was previously run and has reached a terminal state. Defaults to `ALLOW_DUPLICATE`.
+    # @param id_conflict_policy [ActivityIDConflictPolicy] Controls behavior when an activity with the same ID
+    #   is currently running. Defaults to `FAIL` (reject the start attempt).
+    # @param retry_policy [RetryPolicy, nil] Retry policy for the activity.
+    # @param search_attributes [SearchAttributes, nil] Search attributes for the activity.
+    # @param static_summary [String, nil] Fixed single-line summary for this activity execution.
+    # @param static_details [String, nil] Fixed details for this activity execution. May be in markdown format.
+    # @param priority [Priority] Priority for the activity. This is currently experimental.
+    # @param start_delay [Float, nil] Time (in seconds) to wait before dispatching the first activity task. This delay
+    #   is not applied to retry attempts. `nil` or `0` means no delay. Negative values raise `ArgumentError`.
+    #   This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Argument hints.
+    # @param result_hint [Object, nil] Result hint.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [ActivityHandle] Handle to the started activity.
+    # @raise [Error::ActivityAlreadyStartedError] Activity already exists with this ID.
+    # @raise [Error::RPCError] RPC error from call.
+    def start_activity(
+      activity,
+      *args,
+      id:,
+      task_queue:,
+      schedule_to_close_timeout: nil,
+      schedule_to_start_timeout: nil,
+      start_to_close_timeout: nil,
+      heartbeat_timeout: nil,
+      id_reuse_policy: ActivityIDReusePolicy::ALLOW_DUPLICATE,
+      id_conflict_policy: ActivityIDConflictPolicy::FAIL,
+      retry_policy: nil,
+      search_attributes: nil,
+      static_summary: nil,
+      static_details: nil,
+      priority: Priority.default,
+      start_delay: nil,
+      arg_hints: nil,
+      result_hint: nil,
+      rpc_options: nil
+    )
+      activity_name, defn_arg_hints, defn_result_hint =
+        Activity::Definition::Info._type_and_hints_from_parameter(activity)
+      @impl.start_activity(Interceptor::StartActivityInput.new(
+                             activity: activity_name,
+                             args:,
+                             activity_id: id,
+                             task_queue:,
+                             schedule_to_close_timeout:,
+                             schedule_to_start_timeout:,
+                             start_to_close_timeout:,
+                             heartbeat_timeout:,
+                             id_reuse_policy:,
+                             id_conflict_policy:,
+                             retry_policy:,
+                             search_attributes:,
+                             static_summary:,
+                             static_details:,
+                             headers: {},
+                             priority:,
+                             start_delay:,
+                             arg_hints: arg_hints || defn_arg_hints,
+                             result_hint: result_hint || defn_result_hint,
+                             rpc_options:
+                           ))
+    end
+
+    # Start a standalone activity execution and wait for its result. Shortcut for
+    # {start_activity} + {ActivityHandle#result}.
+    #
+    # WARNING: Standalone Activities are experimental.
+    #
+    # @param activity [Class<Activity::Definition>, Activity::Definition, Activity::Definition::Info, Symbol, String]
+    #   Activity definition, definition class or activity name.
+    # @param args [Array<Object>] Arguments to the activity.
+    # @param id [String] Unique identifier for the activity execution.
+    # @param task_queue [String] Task queue to run the activity on.
+    # @param schedule_to_close_timeout [Float, nil] Schedule-to-close timeout in seconds. Either this or
+    #   `start_to_close_timeout` must be specified.
+    # @param schedule_to_start_timeout [Float, nil] Schedule-to-start timeout in seconds.
+    # @param start_to_close_timeout [Float, nil] Start-to-close timeout in seconds. Either this or
+    #   `schedule_to_close_timeout` must be specified.
+    # @param heartbeat_timeout [Float, nil] Heartbeat timeout in seconds.
+    # @param id_reuse_policy [ActivityIDReusePolicy] Controls behavior when an activity with the same ID
+    #   was previously run and has reached a terminal state. Defaults to `ALLOW_DUPLICATE`.
+    # @param id_conflict_policy [ActivityIDConflictPolicy] Controls behavior when an activity with the same ID
+    #   is currently running. Defaults to `FAIL` (reject the start attempt).
+    # @param retry_policy [RetryPolicy, nil] Retry policy for the activity.
+    # @param search_attributes [SearchAttributes, nil] Search attributes for the activity.
+    # @param static_summary [String, nil] Fixed single-line summary for this activity execution.
+    # @param static_details [String, nil] Fixed details for this activity execution. May be in markdown format.
+    # @param priority [Priority] Priority for the activity. This is currently experimental.
+    # @param start_delay [Float, nil] Time (in seconds) to wait before dispatching the first activity task. This delay
+    #   is not applied to retry attempts. `nil` or `0` means no delay. Negative values raise `ArgumentError`.
+    #   This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Argument hints.
+    # @param result_hint [Object, nil] Result hint.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [Object, nil] Successful result of the activity.
+    # @raise [Error::ActivityAlreadyStartedError] Activity already exists with this ID.
+    # @raise [Error::ActivityFailedError] With `cause` populated from the activity failure.
+    # @raise [Error::RPCError] RPC error from call.
+    def execute_activity(
+      activity,
+      *args,
+      id:,
+      task_queue:,
+      schedule_to_close_timeout: nil,
+      schedule_to_start_timeout: nil,
+      start_to_close_timeout: nil,
+      heartbeat_timeout: nil,
+      id_reuse_policy: ActivityIDReusePolicy::ALLOW_DUPLICATE,
+      id_conflict_policy: ActivityIDConflictPolicy::FAIL,
+      retry_policy: nil,
+      search_attributes: nil,
+      static_summary: nil,
+      static_details: nil,
+      priority: Priority.default,
+      start_delay: nil,
+      arg_hints: nil,
+      result_hint: nil,
+      rpc_options: nil
+    )
+      start_activity(
+        activity,
+        *args,
+        id:,
+        task_queue:,
+        schedule_to_close_timeout:,
+        schedule_to_start_timeout:,
+        start_to_close_timeout:,
+        heartbeat_timeout:,
+        id_reuse_policy:,
+        id_conflict_policy:,
+        retry_policy:,
+        search_attributes:,
+        static_summary:,
+        static_details:,
+        priority:,
+        start_delay:,
+        arg_hints:,
+        result_hint:,
+        rpc_options:
+      ).result
+    end
+
+    # List standalone activities matching a visibility query.
+    #
+    # WARNING: Standalone Activities are experimental.
+    #
+    # @param query [String] Visibility list filter.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [Enumerator<ActivityExecution>] Lazy enumerable of matching activity executions.
+    # @raise [Error::RPCError] RPC error from call.
+    def list_activities(query, rpc_options: nil)
+      @impl.list_activities(Interceptor::ListActivitiesInput.new(query:, rpc_options:))
+    end
+
+    # Count standalone activities matching a visibility query.
+    #
+    # WARNING: Standalone Activities are experimental.
+    #
+    # @param query [String] Visibility list filter.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [ActivityExecutionCount] Count of activities (with per-group counts if the query had a group-by clause).
+    # @raise [Error::RPCError] RPC error from call.
+    def count_activities(query, rpc_options: nil)
+      @impl.count_activities(Interceptor::CountActivitiesInput.new(query:, rpc_options:))
+    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.

data/lib/temporalio/common_enums.rb

@@ -84,6 +84,34 @@ module Temporalio
       Api::Enums::V1::SuggestContinueAsNewReason::SUGGEST_CONTINUE_AS_NEW_REASON_TOO_MANY_UPDATES
   end
 
+  # Controls behavior when an activity with the same ID was previously run and is now closed.
+  #
+  # WARNING: Standalone Activities are experimental.
+  #
+  # @see https://docs.temporal.io/activities
+  module ActivityIDReusePolicy
+    # Always allow starting an activity using the same activity ID.
+    ALLOW_DUPLICATE = Api::Enums::V1::ActivityIdReusePolicy::ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE
+    # Allow starting an activity using the same ID only when the last activity execution was not successful.
+    ALLOW_DUPLICATE_FAILED_ONLY =
+      Api::Enums::V1::ActivityIdReusePolicy::ACTIVITY_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY
+    # Do not permit re-use of the ID for this activity. Future start requests could potentially change the policy,
+    # allowing re-use of the ID.
+    REJECT_DUPLICATE = Api::Enums::V1::ActivityIdReusePolicy::ACTIVITY_ID_REUSE_POLICY_REJECT_DUPLICATE
+  end
+
+  # Controls behavior when an activity with the same ID is currently running.
+  #
+  # WARNING: Standalone Activities are experimental.
+  #
+  # @see https://docs.temporal.io/activities
+  module ActivityIDConflictPolicy
+    # Don't start a new activity; instead fail with already-started error.
+    FAIL = Api::Enums::V1::ActivityIdConflictPolicy::ACTIVITY_ID_CONFLICT_POLICY_FAIL
+    # Don't start a new activity; instead return a handle for the running activity.
+    USE_EXISTING = Api::Enums::V1::ActivityIdConflictPolicy::ACTIVITY_ID_CONFLICT_POLICY_USE_EXISTING
+  end
+
   # Specifies when a workflow might move from a worker of one Build Id to another.
   module VersioningBehavior
     # Unspecified versioning behavior. By default, workers opting into worker versioning will

data/lib/temporalio/error/failure.rb

@@ -29,6 +29,28 @@ module Temporalio
       end
     end
 
+    # Error raised by a client when a standalone activity execution has already started.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityAlreadyStartedError < Failure
+      # @return [String] ID of the already-started activity.
+      attr_reader :activity_id
+
+      # @return [String] Activity type name of the already-started activity.
+      attr_reader :activity_type
+
+      # @return [String, nil] Run ID of the already-started activity if known.
+      attr_reader :activity_run_id
+
+      # @!visibility private
+      def initialize(activity_id:, activity_type:, activity_run_id:)
+        super('Activity execution already started')
+        @activity_id = activity_id
+        @activity_type = activity_type
+        @activity_run_id = activity_run_id
+      end
+    end
+
     # Error raised during workflow/activity execution.
     class ApplicationError < Failure
       # @return [Array<Object, nil>] User-defined details on the error.

data/lib/temporalio/error.rb

@@ -40,6 +40,17 @@ module Temporalio
       end
     end
 
+    # Error returned from {Client::ActivityHandle#result} when the activity did not complete successfully.
+    # The specific activity failure can be accessed via `cause`.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityFailedError < Error
+      # @!visibility private
+      def initialize(message = 'Activity execution failed')
+        super
+      end
+    end
+
     # Error that occurs when a workflow was continued as new.
     class WorkflowContinuedAsNewError < Error
       # @return [String] New execution run ID the workflow continued to.