temporalio 1.4.1-arm64-darwin → 1.5.0-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 299db4f052146897db549842ef22ab84d662a1fbc3deed6035d7cad43b54d6ce
-  data.tar.gz: d7adfcd1a784f604fa11eeee214618e5f70c48b102f10a78f69d6b1ccb574ecf
+  metadata.gz: 8aa8c0bee6f2b29f0d8904f9ff8d760f6bfdd9fc62cf06035facf3fec26b9389
+  data.tar.gz: 7c4f6eba73d6db7bb18ef34e6e484ebeb3079d620f5d07b4b57a4b85caea1d78
 SHA512:
-  metadata.gz: 71b092c6f845d26e3a3ce9d61a29dff44ed92531a7f5496597a5f5e23e9ef1b06c468934d44b6384a22ea0ba6c5e45853681eb75ac31d17b6e42fcda15b2c3af
-  data.tar.gz: fe93b2979114f08b5dcf5f6f72a8843218ae4af1bc1b920863e48e9a00b86bf6d5e5664f78c001a3560667b3ce46172ffca9c99ab51dd235f296b90846ace030
+  metadata.gz: 5d0bdcb2881db7574690fa3c1fd589b1b9add3cfbed57b999334782558c18a56d2e0301cc16477092a389f0e5d1f4da8c1201debb0a12c4c3b72fb7131a179c7
+  data.tar.gz: c9c2d374808f319d6e01227cc9c76cf7c1f604710a842b6671ce61d5f2d20f267f41cd8212f2797cb290984aea5933972b969d6c0d5b7956fd40dacf0854043c

data/lib/temporalio/activity/definition.rb

@@ -155,6 +155,28 @@ module Temporalio
         # @return [Object, nil] Result hint
         attr_reader :result_hint
 
+        # Resolve an activity argument into a `[name, arg_hints, result_hint]` triple. Used by
+        # `Client#start_activity` to accept any of: a `Definition` subclass, an instance of one,
+        # an `Info`, a `Symbol` activity name, or a `String` activity name. Class/instance/Info
+        # inputs carry their definition's hints; Symbol/String inputs return `nil` hints.
+        #
+        # @param activity [Class<Definition>, Definition, Info, Symbol, String] Activity argument.
+        # @return [Array(String, Array[Object]?, Object?)] name, arg_hints, result_hint.
+        def self._type_and_hints_from_parameter(activity)
+          case activity
+          when String, Symbol
+            [activity.to_s, nil, nil]
+          when Class, Definition, Info
+            # Return or construct an Info -- needed because we want the checks in Info.initialize.
+            info = from_activity(activity)
+            raise ArgumentError, 'Cannot pass dynamic activity to start_activity' unless info.name
+
+            [info.name.to_s, info.arg_hints, info.result_hint]
+          else
+            raise ArgumentError, "#{activity} is not an activity class, instance, info, symbol, or string"
+          end
+        end
+
         # Obtain definition info representing the given activity, which can be a class, instance, or definition info.
         #
         # @param activity [Definition, Class<Definition>, Info] Activity to get info for.

data/lib/temporalio/activity/info.rb

@@ -7,11 +7,13 @@ module Temporalio
   module Activity
     Info = Data.define(
       :activity_id,
+      :activity_run_id,
       :activity_type,
       :attempt,
       :current_attempt_scheduled_time,
       :heartbeat_timeout,
       :local?,
+      :namespace,
       :priority,
       :retry_policy,
       :raw_heartbeat_details,
@@ -31,16 +33,21 @@ module Temporalio
     #
     # @!attribute activity_id
     #   @return [String] ID for the activity.
+    # @!attribute activity_run_id
+    #   @return [String, nil] Run ID for a standalone activity execution. nil for activities scheduled from a workflow.
+    #     WARNING: Standalone Activities are experimental.
     # @!attribute activity_type
     #   @return [String] Type name for the activity.
     # @!attribute attempt
-    #   @return [Integer] Attempt the activity is on.
+    #   @return [Integer] Attempt the activity is on. Attempts start at 1 and increment on each retry.
     # @!attribute current_attempt_scheduled_time
     #   @return [Time] When the current attempt was scheduled.
     # @!attribute heartbeat_timeout
     #   @return [Float, nil] Heartbeat timeout set by the caller.
     # @!attribute local?
     #   @return [Boolean] Whether the activity is a local activity or not.
+    # @!attribute namespace
+    #   @return [String] Namespace this activity is on.
     # @!attribute priority
     #   @return [Priority] The priority of this activity.
     # @!attribute retry_policy
@@ -64,17 +71,26 @@ module Temporalio
     #   @return [String] Task token uniquely identifying this activity. Note, this is a `ASCII-8BIT` encoded string, not
     #     a `UTF-8` encoded string nor a valid UTF-8 string.
     # @!attribute workflow_id
-    #   @return [String] Workflow ID that started this activity.
+    #   @return [String, nil] Workflow ID that started this activity. nil for standalone activities.
     # @!attribute workflow_namespace
-    #   @return [String] Namespace this activity is on.
+    #   @return [String, nil] Namespace of the workflow that scheduled this activity. Nil for standalone
+    #     activities. Prefer {#namespace}, which is always set.
+    #   @deprecated Use {#namespace} instead.
     # @!attribute workflow_run_id
-    #   @return [String] Workflow run ID that started this activity.
+    #   @return [String, nil] Workflow run ID that started this activity. nil for standalone activities.
     # @!attribute workflow_type
-    #   @return [String] Workflow type name that started this activity.
+    #   @return [String, nil] Workflow type name that started this activity. nil for standalone activities.
     #
     # @note WARNING: This class may have required parameters added to its constructor. Users should not instantiate this
     #   class or it may break in incompatible ways.
     class Info
+      # @return [Boolean] True if this activity was scheduled by a workflow execution; false for standalone activities.
+      #
+      # WARNING: Standalone Activities are experimental.
+      def in_workflow?
+        !workflow_id.nil?
+      end
+
       # Convert raw heartbeat details into Ruby types.
       #
       # Note, this live-converts every invocation.

data/lib/temporalio/client/activity_execution.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/client/activity_execution_status'
+require 'temporalio/client/pending_activity_state'
+require 'temporalio/internal/proto_utils'
+require 'temporalio/priority'
+require 'temporalio/retry_policy'
+require 'temporalio/search_attributes'
+require 'temporalio/worker_deployment_version'
+
+module Temporalio
+  class Client
+    # Info for a standalone activity execution. Returned by list_activities; extended by {Description}
+    # for describe results.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityExecution
+      # @return [Api::Activity::V1::ActivityExecutionListInfo, Api::Activity::V1::ActivityExecutionInfo]
+      #   Underlying protobuf info.
+      attr_reader :raw_info
+
+      # @!visibility private
+      def initialize(raw_info)
+        @raw_info = raw_info
+        @search_attributes = Internal::ProtoUtils::LazySearchAttributes.new(raw_info.search_attributes)
+      end
+
+      # @return [String] ID for the activity.
+      def activity_id
+        @raw_info.activity_id
+      end
+
+      # @return [String] Run ID for this activity execution attempt.
+      def activity_run_id
+        Internal::ProtoUtils.string_or(@raw_info.run_id, nil)
+      end
+
+      # @return [String] Type name of the activity.
+      def activity_type
+        @raw_info.activity_type&.name
+      end
+
+      # @return [Time, nil] When the activity was scheduled.
+      def schedule_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.schedule_time)
+      end
+
+      # @return [Time, nil] When the activity reached a terminal state.
+      def close_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.close_time)
+      end
+
+      # @return [ActivityExecutionStatus] Overall status for the activity.
+      def status
+        Internal::ProtoUtils.enum_to_int(Api::Enums::V1::ActivityExecutionStatus, @raw_info.status)
+      end
+
+      # @return [SearchAttributes, nil] Search attributes attached to this activity if any.
+      def search_attributes
+        @search_attributes.get
+      end
+
+      # @return [String] Task queue for the activity.
+      def task_queue
+        @raw_info.task_queue
+      end
+
+      # @return [Float, nil] How long this activity has been running across all attempts, in seconds.
+      def execution_duration
+        Internal::ProtoUtils.duration_to_seconds(@raw_info.execution_duration)
+      end
+
+      # Rich description of a standalone activity execution; returned by {ActivityHandle#describe}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      class Description < ActivityExecution
+        # @return [Api::WorkflowService::V1::DescribeActivityExecutionResponse] Underlying protobuf response.
+        attr_reader :raw_description
+
+        # @!visibility private
+        def initialize(raw_description, data_converter)
+          super(raw_description.info)
+          @raw_description = raw_description
+          @data_converter = data_converter
+        end
+
+        # @return [PendingActivityState, nil] More detailed breakdown of the running state when
+        #   the activity's status is RUNNING; nil otherwise.
+        def run_state
+          Internal::ProtoUtils.enum_to_int(Api::Enums::V1::PendingActivityState, @raw_info.run_state,
+                                           zero_means_nil: true)
+        end
+
+        # @return [Float, nil] Schedule-to-close timeout in seconds.
+        def schedule_to_close_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.schedule_to_close_timeout)
+        end
+
+        # @return [Float, nil] Schedule-to-start timeout in seconds.
+        def schedule_to_start_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.schedule_to_start_timeout)
+        end
+
+        # @return [Float, nil] Start-to-close timeout in seconds.
+        def start_to_close_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.start_to_close_timeout)
+        end
+
+        # @return [Float, nil] Heartbeat timeout in seconds.
+        def heartbeat_timeout
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.heartbeat_timeout)
+        end
+
+        # @return [Boolean] Whether the activity has recorded any heartbeat details.
+        def has_heartbeat_details? # rubocop:disable Naming/PredicatePrefix
+          !@raw_info.heartbeat_details&.payloads.nil? && !@raw_info.heartbeat_details.payloads.empty?
+        end
+
+        # Deserialized last-heartbeat details. Empty when no heartbeat has been recorded.
+        #
+        # @param hints [Array<Object>, nil] Hints, if any, to assist conversion.
+        # @return [Array<Object>] Converted details.
+        def heartbeat_details(hints: nil)
+          @data_converter.from_payloads(@raw_info.heartbeat_details, hints:)
+        end
+
+        # @return [RetryPolicy] Retry policy in effect for this activity.
+        def retry_policy
+          RetryPolicy._from_proto(@raw_info.retry_policy)
+        end
+
+        # @return [Time, nil] Time the last heartbeat was recorded.
+        def last_heartbeat_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.last_heartbeat_time)
+        end
+
+        # @return [Time, nil] Time the last attempt started.
+        def last_started_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.last_started_time)
+        end
+
+        # @return [Integer] Current attempt number. Attempts start at 1 and increment on each retry.
+        def attempt
+          @raw_info.attempt
+        end
+
+        # @return [Error::Failure, nil] Failure of the last failed attempt if any.
+        def last_failure
+          return nil unless @raw_info.last_failure
+
+          @data_converter.from_failure(@raw_info.last_failure)
+        end
+
+        # @return [Time, nil] Schedule time + schedule-to-close timeout.
+        def expiration_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.expiration_time)
+        end
+
+        # @return [String, nil] Identity of the worker that last picked up this activity.
+        def last_worker_identity
+          Internal::ProtoUtils.string_or(@raw_info.last_worker_identity, nil)
+        end
+
+        # @return [Float, nil] Time from last attempt failure to next retry, in seconds.
+        def current_retry_interval
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.current_retry_interval)
+        end
+
+        # @return [Time, nil] Time when the last attempt completed.
+        def last_attempt_complete_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.last_attempt_complete_time)
+        end
+
+        # @return [Time, nil] Time when the next attempt will be scheduled.
+        def next_attempt_schedule_time
+          Internal::ProtoUtils.timestamp_to_time(@raw_info.next_attempt_schedule_time)
+        end
+
+        # @return [WorkerDeploymentVersion, nil] Worker deployment version this activity was last dispatched to.
+        def last_deployment_version
+          raw = @raw_info.last_deployment_version
+          return nil unless raw
+
+          WorkerDeploymentVersion.new(
+            deployment_name: raw.deployment_name,
+            build_id: raw.build_id
+          )
+        end
+
+        # @return [Priority] Priority of this activity.
+        def priority
+          Priority._from_proto(@raw_info.priority)
+        end
+
+        # @return [String, nil] Reason given when cancellation was requested.
+        def canceled_reason
+          Internal::ProtoUtils.string_or(@raw_info.canceled_reason, nil)
+        end
+
+        # @return [String, nil] Static user-metadata summary on the activity.
+        def static_summary
+          user_metadata.first
+        end
+
+        # @return [String, nil] Static user-metadata details on the activity. May be in markdown format.
+        def static_details
+          user_metadata.last
+        end
+
+        private
+
+        def user_metadata
+          @user_metadata ||= Internal::ProtoUtils.from_user_metadata(
+            @raw_info.user_metadata, @data_converter
+          )
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/client/activity_execution_count.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Client
+    # Result of a {Client#count_activities} call.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityExecutionCount
+      # @return [Integer] Approximate number of activities matching the query. If the query had a group-by clause,
+      #   this is the sum of all the counts in {groups}.
+      attr_reader :count
+
+      # @return [Array<AggregationGroup>] Groups if the query had a group-by clause, or empty if not.
+      attr_reader :groups
+
+      # @!visibility private
+      def initialize(count, groups)
+        @count = count
+        @groups = groups
+      end
+
+      # Aggregation group if the activity count query had a group-by clause.
+      #
+      # WARNING: Standalone Activities are experimental.
+      class AggregationGroup
+        # @return [Integer] Approximate number of activities matching the query for this group.
+        attr_reader :count
+
+        # @return [Array<Object>] Search attribute values for this group.
+        attr_reader :group_values
+
+        # @!visibility private
+        def initialize(count, group_values)
+          @count = count
+          @group_values = group_values
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/client/activity_execution_status.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+
+module Temporalio
+  class Client
+    # Status of a standalone activity execution.
+    #
+    # WARNING: Standalone Activities are experimental.
+    module ActivityExecutionStatus
+      UNSPECIFIED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_UNSPECIFIED
+      RUNNING = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_RUNNING
+      COMPLETED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_COMPLETED
+      FAILED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_FAILED
+      CANCELED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_CANCELED
+      TERMINATED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_TERMINATED
+      TIMED_OUT = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_TIMED_OUT
+    end
+  end
+end

data/lib/temporalio/client/activity_handle.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/client/activity_execution'
+require 'temporalio/client/interceptor'
+require 'temporalio/error'
+
+module Temporalio
+  class Client
+    # Handle for interacting with a standalone activity. Usually created via {Client.activity_handle}
+    # or {Client#start_activity}.
+    #
+    # WARNING: Standalone Activities are experimental.
+    class ActivityHandle
+      # @return [String] ID for the activity.
+      attr_reader :id
+
+      # @return [String, nil] Run ID for this activity execution. When nil, this handle targets the latest run.
+      attr_reader :run_id
+
+      # @return [Object, nil] Result hint used when deserializing the activity's result. May be overridden per
+      #   {#result} call.
+      attr_reader :result_hint
+
+      # @!visibility private
+      def initialize(client:, id:, run_id:, result_hint:)
+        @client = client
+        @id = id
+        @run_id = run_id
+        @result_hint = result_hint
+      end
+
+      # Wait for the activity's outcome (result or failure). Internally long-polls
+      # PollActivityExecution and reissues until the activity reaches a terminal state, so this can
+      # block indefinitely for long-running activities.
+      #
+      # @param result_hint [Object, nil] Override the result hint. If nil, uses {#result_hint}.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @return [Object, nil] Deserialized activity result.
+      #
+      # @raise [Error::ActivityFailedError] With `cause` populated from the activity failure.
+      # @raise [Error::RPCError] RPC error from call.
+      def result(result_hint: nil, rpc_options: nil)
+        hint = result_hint || @result_hint
+        outcome = @client._impl.fetch_activity_outcome(
+          Interceptor::FetchActivityOutcomeInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            rpc_options:
+          )
+        )
+        _process_outcome(outcome, hint)
+      end
+
+      # Describe the activity.
+      #
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @return [ActivityExecution::Description] Activity description.
+      # @raise [Error::RPCError] RPC error from call.
+      def describe(rpc_options: nil)
+        @client._impl.describe_activity(
+          Interceptor::DescribeActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            rpc_options:
+          )
+        )
+      end
+
+      # Request cancellation of the activity.
+      #
+      # @param reason [String, nil] Optional cancellation reason recorded on the server.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @raise [Error::RPCError] RPC error from call.
+      def cancel(reason = nil, rpc_options: nil)
+        @client._impl.cancel_activity(
+          Interceptor::CancelActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            reason:,
+            rpc_options:
+          )
+        )
+        nil
+      end
+
+      # Terminate the activity (force-close).
+      #
+      # @param reason [String, nil] Optional termination reason recorded on the activity's failure outcome.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @raise [Error::RPCError] RPC error from call.
+      def terminate(reason = nil, rpc_options: nil)
+        @client._impl.terminate_activity(
+          Interceptor::TerminateActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            reason:,
+            rpc_options:
+          )
+        )
+        nil
+      end
+
+      private
+
+      def _process_outcome(outcome, hint)
+        raise Error, 'Activity completed but outcome is missing from server response' if outcome.nil?
+
+        case outcome.value
+        when :failure
+          cause = @client.data_converter.from_failure(outcome.failure)
+          raise Error::ActivityFailedError.new, cause: cause
+        when :result
+          @client.data_converter.from_payloads(outcome.result, hints: Array(hint)).first
+        else
+          raise Error, "Unknown activity outcome: #{outcome.value.inspect}"
+        end
+      end
+    end
+  end
+end

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