temporalio 1.4.0 → 1.5.0

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

data/lib/temporalio/client/connection.rb

@@ -24,7 +24,8 @@ module Temporalio
         :keep_alive,
         :http_connect_proxy,
         :runtime,
-        :lazy_connect
+        :lazy_connect,
+        :dns_load_balancing
       )
 
       # Options as returned from {options} for +**to_h+ splat use in {initialize}. See {initialize} for details.
@@ -132,6 +133,22 @@ module Temporalio
       #   @return [String, nil] Pass for HTTP basic auth for the proxy, must be combined with {basic_auth_user}.
       class HTTPConnectProxyOptions; end # rubocop:disable Lint/EmptyClass
 
+      DnsLoadBalancingOptions = Data.define(
+        :resolution_interval
+      )
+
+      # DNS load balancing options for client connections. When set, Core periodically re-resolves the target host's
+      # DNS records and round-robins requests across the resolved addresses. Mutually exclusive with
+      # {HTTPConnectProxyOptions} -- DNS load balancing is silently disabled when an HTTP CONNECT proxy is configured.
+      #
+      # @!attribute resolution_interval
+      #   @return [Float] How often to re-resolve DNS, in seconds. Default 30.0.
+      class DnsLoadBalancingOptions
+        def initialize(resolution_interval: 30.0)
+          super
+        end
+      end
+
       # @return [Options] Frozen options for this client which has the same attributes as {initialize}. Note that if
       #   {api_key=} or {rpc_metadata=} are updated, the options object is replaced with those changes (it is not
       #   mutated in place).
@@ -169,6 +186,8 @@ module Temporalio
       # @param lazy_connect [Boolean] If true, there is no connection until the first call is attempted or a worker
       #   is created with it. Clients from lazy connections cannot be used for workers if they have not performed a
       #   connection.
+      # @param dns_load_balancing [DnsLoadBalancingOptions, nil] DNS load balancing options for this connection. Default
+      #   is +nil+ (disabled). Silently disabled when +http_connect_proxy+ is set, since the two are mutually exclusive.
       # @param around_connect [Proc, nil] If present, this proc accepts two values: options and a block. The block must
       #   be yielded to only once with the options. The block does not return a meaningful value, nor should
       #   around_connect.
@@ -185,6 +204,7 @@ module Temporalio
         http_connect_proxy: nil,
         runtime: Runtime.default,
         lazy_connect: false,
+        dns_load_balancing: nil,
         around_connect: nil
       )
         @options = Options.new(
@@ -197,7 +217,8 @@ module Temporalio
           keep_alive:,
           http_connect_proxy:,
           runtime:,
-          lazy_connect:
+          lazy_connect:,
+          dns_load_balancing:
         ).freeze
         @core_client_mutex = Mutex.new
         # Create core client now if not lazy, applying around_connect if present
@@ -329,6 +350,11 @@ module Temporalio
             basic_auth_pass: @options.http_connect_proxy.basic_auth_pass
           )
         end
+        if (dns_load_balancing = @options.dns_load_balancing)
+          options.dns_load_balancing = Internal::Bridge::Client::DnsLoadBalancingOptions.new(
+            resolution_interval: dns_load_balancing.resolution_interval
+          )
+        end
         Internal::Bridge::Client.new(@options.runtime._core_runtime, options)
       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/schedule.rb

@@ -3,6 +3,7 @@
 require 'temporalio/api'
 require 'temporalio/converters'
 require 'temporalio/internal/proto_utils'
+require 'temporalio/priority'
 require 'temporalio/retry_policy'
 require 'temporalio/search_attributes'
 
@@ -175,6 +176,7 @@ module Temporalio
           :retry_policy,
           :memo,
           :search_attributes,
+          :priority,
           :arg_hints,
           :headers
         )
@@ -209,6 +211,8 @@ module Temporalio
         #   @return [Hash<String, Object>, nil] Memo for the workflow.
         # @!attribute search_attributes
         #   @return [SearchAttributes, nil] Search attributes for the workflow.
+        # @!attribute priority
+        #   @return [Priority] Priority of the workflow. This is currently experimental.
         # @!attribute arg_hints
         #   @return [Array<Object>, nil] Converter hints for workflow arguments. This is only user-set (e.g. on create)
         #     and is not persisted and therefore will not be set when describing a workflow.
@@ -239,6 +243,7 @@ module Temporalio
             # @param retry_policy [RetryPolicy, nil] Retry policy for the workflow.
             # @param memo [Hash<String, Object>, nil] Memo for the workflow.
             # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow.
+            # @param priority [Priority] Priority of the workflow. This is currently experimental.
             # @param headers [Hash<String, Object>, nil] Headers for the workflow.
             def new(
               workflow,
@@ -253,6 +258,7 @@ module Temporalio
               retry_policy: nil,
               memo: nil,
               search_attributes: nil,
+              priority: Priority.default,
               arg_hints: nil,
               headers: nil
             )
@@ -271,6 +277,7 @@ module Temporalio
                 retry_policy:,
                 memo:,
                 search_attributes:,
+                priority:,
                 arg_hints: arg_hints || defn_arg_hints,
                 headers:
               )
@@ -293,6 +300,7 @@ module Temporalio
               retry_policy: raw_info.retry_policy ? RetryPolicy._from_proto(raw_info.retry_policy) : nil,
               memo: Internal::ProtoUtils.memo_from_proto(raw_info.memo, data_converter),
               search_attributes: SearchAttributes._from_proto(raw_info.search_attributes),
+              priority: Priority._from_proto(raw_info.priority),
               headers: Internal::ProtoUtils.headers_from_proto(raw_info.header, data_converter)
             )
           end
@@ -312,6 +320,7 @@ module Temporalio
                 memo: Internal::ProtoUtils.memo_to_proto(memo, data_converter),
                 search_attributes: search_attributes&._to_proto,
                 header: Internal::ProtoUtils.headers_to_proto(headers, data_converter),
+                priority: priority._to_proto,
                 user_metadata: Internal::ProtoUtils.to_user_metadata(static_summary, static_details, data_converter)
               )
             )

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: