temporalio 1.4.0 → 1.5.0

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'
@@ -95,6 +96,9 @@ module Temporalio
     # @param runtime [Runtime] Runtime for this client.
     # @param lazy_connect [Boolean] If true, the client will not connect until the first call is attempted or a worker
     #   is created with it. Lazy clients cannot be used for workers if they have not performed a connection.
+    # @param dns_load_balancing [Connection::DnsLoadBalancingOptions, nil] DNS load balancing options for the
+    #   connection. Default is +nil+ (disabled). Silently disabled when +http_connect_proxy+ is set, since the two are
+    #   mutually exclusive.
     #
     # @return [Client] Connected client.
     #
@@ -116,7 +120,8 @@ module Temporalio
       keep_alive: Connection::KeepAliveOptions.new, # Set to nil to disable
       http_connect_proxy: nil,
       runtime: Runtime.default,
-      lazy_connect: false
+      lazy_connect: false,
+      dns_load_balancing: nil
     )
       # Prepare connection. The connection var is needed here so it can be used in callback for plugin.
       base_connection = nil
@@ -162,6 +167,7 @@ module Temporalio
         http_connect_proxy:,
         runtime:,
         lazy_connect:,
+        dns_load_balancing:,
         around_connect: # steep:ignore
       )
 
@@ -473,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

@@ -50,6 +50,22 @@ module Temporalio
     # workflow code.
     AUTO_UPGRADE =
       Api::Enums::V1::ContinueAsNewVersioningBehavior::CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_AUTO_UPGRADE
+    # Use the Ramping Version of the workflow's task queue at start time, regardless of the workflow's
+    # Target Version (according to f(workflow_id, ramp_percentage)). After the first workflow task completes,
+    # the workflow will use whatever Versioning Behavior it is annotated with. If there is no Ramping
+    # Version by the time that the first workflow task is dispatched, it will be sent to the Current Version.
+    #
+    # It is highly discouraged to use this if the workflow is annotated with AutoUpgrade behavior, because
+    # this setting ONLY applies to the first task of the workflow. If, after the first task, the workflow
+    # is AutoUpgrade, it will behave like a normal AutoUpgrade workflow and go to the Target Version, which
+    # may be the Current Version instead of the Ramping Version.
+    #
+    # Note that if the workflow being continued has a Pinned override, that override will be inherited by the
+    # new workflow run regardless of the ContinueAsNewVersioningBehavior specified in the continue-as-new
+    # command. Versioning Override always takes precedence until it's removed manually via
+    # UpdateWorkflowExecutionOptions.
+    USE_RAMPING_VERSION =
+      Api::Enums::V1::ContinueAsNewVersioningBehavior::CONTINUE_AS_NEW_VERSIONING_BEHAVIOR_USE_RAMPING_VERSION
   end
 
   # Specifies why the server suggests continue-as-new. This is currently experimental.
@@ -68,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.

data/lib/temporalio/internal/bridge/client.rb

@@ -16,7 +16,8 @@ module Temporalio
           :tls, # Optional
           :rpc_retry,
           :keep_alive, # Optional
-          :http_connect_proxy # Optional
+          :http_connect_proxy, # Optional
+          :dns_load_balancing # Optional
         )
 
         TLSOptions = Struct.new(
@@ -46,6 +47,10 @@ module Temporalio
           :basic_auth_pass # Optional
         )
 
+        DnsLoadBalancingOptions = Struct.new(
+          :resolution_interval
+        )
+
         def self.new(runtime, options)
           queue = Queue.new
           async_new(runtime, options, queue)