temporalio 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 268dababab1b3104d90484a92d2b31cf2716c0ccf8e174b86f957d7e78a7dc34
-  data.tar.gz: 4ac90452d338cda2967b8ab88f9fac481dc92a6ec8aa740be539067c9a5e07da
+  metadata.gz: 83bdaf2665c0e0870da1ad032bc014bb2a99970eee632c7349b5ebd35611bea3
+  data.tar.gz: 8bd6f029572ee2b46477306283a33480eaea57bf8bdac45ed094bcd6bc2110c8
 SHA512:
-  metadata.gz: 1cbb397fdb411c2d869e2deb6cc641e1840d272071e425b58da2d6bca9b39bea69428d6a20da60688325094cf4c8ddc0568033ec57e8772b42ca3594b6477a07
-  data.tar.gz: b1b91bb6f524008cf4b1c40d29c6e92c8e3bc22addf949c6b12aedd631e0314ea65770853f9a0076016a9540f10bb2e22a4170e606defd934187a1fcc9783774
+  metadata.gz: bc6cad44f81d64124fb61c16605f011ebace9a6121ef8e7d63b81dd88e4050da7e5aac376e326679c6d4da2f44d1a3a3fdcc4a5c21fd8335a3c5f22d40eeb27b
+  data.tar.gz: a04e3cebf85f26728de6445268cd3f88adc3614f4c02bc9bae3e05a566f2a0848cb6a8d61eba595d14eb651f6db5c89b471ef3fb4f71ad98e0d47591a2599dbf

data/README.md

@@ -1491,6 +1491,14 @@ E.g. show all test names while executing:
 
     bundle exec rake test TESTOPTS="--verbose"
 
+To list source tests excluded from Cloud, grouped by reason and note:
+
+    bundle exec rake test:cloud_inventory
+
+To run the Cloud-eligible suite against an envconfig-defined server:
+
+    bundle exec rake test:cloud
+
 ### Code Formatting and Type Checking
 
 This project uses `rubocop`:

data/Rakefile

@@ -27,6 +27,25 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb', 'extra/release/test/**/*_test.rb']
 end
 
+namespace :test do
+  desc 'List tests excluded from Temporal Cloud by reason'
+  task :cloud_inventory do
+    ENV['TESTOPTS'] = [
+      ENV.fetch('TESTOPTS', nil),
+      '--cloud-inventory',
+      '--name=/CloudTestInventoryTest#test_report/'
+    ].compact.join(' ')
+    Rake::Task[:test].invoke
+  end
+
+  desc 'Run tests eligible for Temporal Cloud using envconfig'
+  task :cloud do
+    ENV['TEMPORAL_TEST_ENV_CONFIG_SERVER'] = '1'
+    ENV['TESTOPTS'] = [ENV.fetch('TESTOPTS', nil), '--cloud'].compact.join(' ')
+    Rake::Task[:test].invoke
+  end
+end
+
 require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new

data/lib/temporalio/activity/info.rb

@@ -35,7 +35,6 @@ module Temporalio
     #   @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
@@ -85,8 +84,6 @@ module Temporalio
     #   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

data/lib/temporalio/client/activity_execution.rb

@@ -13,8 +13,6 @@ 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.
@@ -46,6 +44,12 @@ module Temporalio
         Internal::ProtoUtils.timestamp_to_time(@raw_info.schedule_time)
       end
 
+      # @return [Time, nil] When the first activity task was made available for dispatch. Equals
+      #   schedule_time + start_delay; equal to schedule_time when no start delay is set.
+      def execution_time
+        Internal::ProtoUtils.timestamp_to_time(@raw_info.execution_time)
+      end
+
       # @return [Time, nil] When the activity reached a terminal state.
       def close_time
         Internal::ProtoUtils.timestamp_to_time(@raw_info.close_time)
@@ -72,8 +76,6 @@ module Temporalio
       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
@@ -112,7 +114,17 @@ module Temporalio
           Internal::ProtoUtils.duration_to_seconds(@raw_info.heartbeat_timeout)
         end
 
-        # @return [Boolean] Whether the activity has recorded any heartbeat details.
+        # @return [Float, nil] Delay in seconds before the first activity task is made available for
+        #   dispatch. Not applied to retry attempts.
+        def start_delay
+          Internal::ProtoUtils.duration_to_seconds(@raw_info.start_delay)
+        end
+
+        # Whether heartbeat details are present on this description. False when the activity
+        # recorded none, and also when {ActivityHandle#describe} was called without
+        # `include_heartbeat_details:`.
+        #
+        # @return [Boolean] Whether heartbeat details are present.
         def has_heartbeat_details? # rubocop:disable Naming/PredicatePrefix
           !@raw_info.heartbeat_details&.payloads.nil? && !@raw_info.heartbeat_details.payloads.empty?
         end
@@ -125,6 +137,57 @@ module Temporalio
           @data_converter.from_payloads(@raw_info.heartbeat_details, hints:)
         end
 
+        # Whether the activity's input is present. False unless {ActivityHandle#describe} was
+        # called with `include_input:`.
+        #
+        # @return [Boolean] Whether input is present.
+        def has_input? # rubocop:disable Naming/PredicatePrefix
+          !@raw_description.input.nil?
+        end
+
+        # Deserialized activity input, one element per argument. Empty when no input is present.
+        #
+        # @param hints [Array<Object>, nil] Hints, if any, to assist conversion.
+        # @return [Array<Object>] Converted arguments.
+        def input(hints: nil)
+          @data_converter.from_payloads(@raw_description.input, hints:)
+        end
+
+        # Whether the activity closed with a successful result. False while the activity is still
+        # running, when it closed with a failure, and when {ActivityHandle#describe} was called
+        # without `include_outcome:`.
+        #
+        # @return [Boolean] Whether a result is present.
+        def has_result? # rubocop:disable Naming/PredicatePrefix
+          @raw_description.outcome&.value == :result
+        end
+
+        # Deserialized result the activity closed with. Nil when no result is present (still
+        # running, closed with a failure, or `include_outcome:` was not requested).
+        #
+        # @param result_hint [Object, nil] Hint, if any, to assist conversion.
+        # @return [Object, nil] Converted result.
+        def result(result_hint: nil)
+          return nil unless has_result?
+
+          @data_converter.from_payloads(
+            @raw_description.outcome.result, hints: Array(result_hint)
+          ).first
+        end
+
+        # Failure the activity closed with. Nil when the activity did not close with a failure or
+        # when {ActivityHandle#describe} was called without `include_outcome:`.
+        #
+        # This is the terminal outcome; {#last_failure} is the failure of the most recent attempt,
+        # which may be set while the activity is still retrying.
+        #
+        # @return [Error::Failure, nil] Converted failure.
+        def failure
+          return nil unless @raw_description.outcome&.value == :failure
+
+          @data_converter.from_failure(@raw_description.outcome.failure)
+        end
+
         # @return [RetryPolicy] Retry policy in effect for this activity.
         def retry_policy
           RetryPolicy._from_proto(@raw_info.retry_policy)
@@ -145,6 +208,20 @@ module Temporalio
           @raw_info.attempt
         end
 
+        # @return [Integer] Total number of heartbeats recorded across all attempts.
+        def total_heartbeat_count
+          @raw_info.total_heartbeat_count
+        end
+
+        # Whether a last failure is present on this description. False when the activity has no
+        # failed attempt, and also when {ActivityHandle#describe} was called without
+        # `include_last_failure:`.
+        #
+        # @return [Boolean] Whether a last failure is present.
+        def has_last_failure? # rubocop:disable Naming/PredicatePrefix
+          !@raw_info.last_failure.nil?
+        end
+
         # @return [Error::Failure, nil] Failure of the last failed attempt if any.
         def last_failure
           return nil unless @raw_info.last_failure
@@ -199,7 +276,7 @@ module Temporalio
         end
 
         # @return [String, nil] Static user-metadata summary on the activity.
-        def static_summary
+        def summary
           user_metadata.first
         end
 

data/lib/temporalio/client/activity_execution_count.rb

@@ -3,8 +3,6 @@
 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}.
@@ -20,8 +18,6 @@ module Temporalio
       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

data/lib/temporalio/client/activity_execution_options.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/proto_utils'
+require 'temporalio/priority'
+require 'temporalio/retry_policy'
+
+module Temporalio
+  class Client
+    # The resolved options of a standalone activity execution, as returned by
+    # {ActivityHandle#update_options}. Reflects the activity's options as the server resolved them
+    # after the update was applied.
+    #
+    # WARNING: Standalone Activities are experimental.
+    ActivityExecutionOptions = Data.define(
+      :task_queue,
+      :schedule_to_close_timeout,
+      :schedule_to_start_timeout,
+      :start_to_close_timeout,
+      :heartbeat_timeout,
+      :retry_policy,
+      :priority,
+      :start_delay
+    ) do
+      # @!visibility private
+      def self._from_proto(options)
+        new(
+          task_queue: Internal::ProtoUtils.string_or(options.task_queue&.name, nil),
+          schedule_to_close_timeout: Internal::ProtoUtils.duration_to_seconds(options.schedule_to_close_timeout),
+          schedule_to_start_timeout: Internal::ProtoUtils.duration_to_seconds(options.schedule_to_start_timeout),
+          start_to_close_timeout: Internal::ProtoUtils.duration_to_seconds(options.start_to_close_timeout),
+          heartbeat_timeout: Internal::ProtoUtils.duration_to_seconds(options.heartbeat_timeout),
+          retry_policy: options.retry_policy ? RetryPolicy._from_proto(options.retry_policy) : nil,
+          priority: Priority._from_proto(options.priority),
+          start_delay: Internal::ProtoUtils.duration_to_seconds(options.start_delay)
+        )
+      end
+    end
+  end
+end

data/lib/temporalio/client/activity_execution_status.rb

@@ -5,8 +5,6 @@ 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
@@ -15,6 +13,7 @@ module Temporalio
       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
+      PAUSED = Api::Enums::V1::ActivityExecutionStatus::ACTIVITY_EXECUTION_STATUS_PAUSED
     end
   end
 end

data/lib/temporalio/client/activity_handle.rb

@@ -2,15 +2,18 @@
 
 require 'temporalio/api'
 require 'temporalio/client/activity_execution'
+require 'temporalio/client/activity_execution_options'
+require 'temporalio/client/activity_options'
 require 'temporalio/client/interceptor'
 require 'temporalio/error'
+require 'temporalio/internal/proto_utils'
+require 'temporalio/priority'
+require 'temporalio/retry_policy'
 
 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
@@ -55,15 +58,35 @@ module Temporalio
 
       # Describe the activity.
       #
+      # The payload-bearing fields are opt-in because they can be arbitrarily large; request them
+      # only when needed. Each has a corresponding predicate on the returned description that
+      # reports whether the server supplied it.
+      #
+      # @param include_input [Boolean] If true and the activity received input, include the input.
+      # @param include_outcome [Boolean] If true and the activity is closed, include the outcome.
+      # @param include_heartbeat_details [Boolean] If true and the activity recorded heartbeat
+      #   details, include them.
+      # @param include_last_failure [Boolean] If true and the activity has a failed attempt, include
+      #   the last failure.
       # @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)
+      def describe(
+        include_input: false,
+        include_outcome: false,
+        include_heartbeat_details: false,
+        include_last_failure: false,
+        rpc_options: nil
+      )
         @client._impl.describe_activity(
           Interceptor::DescribeActivityInput.new(
             activity_id: id,
             activity_run_id: run_id,
+            include_input:,
+            include_outcome:,
+            include_heartbeat_details:,
+            include_last_failure:,
             rpc_options:
           )
         )
@@ -103,6 +126,107 @@ module Temporalio
         nil
       end
 
+      # Pause the activity. A paused activity is not scheduled or retried until it is unpaused via
+      # {#unpause}.
+      #
+      # WARNING: Standalone Activities are experimental.
+      #
+      # @param reason [String, nil] Optional reason recorded on the server.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @raise [Error::RPCError] RPC error from call.
+      def pause(reason = nil, rpc_options: nil)
+        @client._impl.pause_activity(
+          Interceptor::PauseActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            reason:,
+            rpc_options:
+          )
+        )
+        nil
+      end
+
+      # Unpause the activity, allowing it to be scheduled or retried again.
+      #
+      # WARNING: Standalone Activities are experimental.
+      #
+      # @param reason [String, nil] Optional reason recorded on the server.
+      # @param jitter [Float, nil] If set, the activity will start at a random time within this
+      #   duration (in seconds).
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      # @raise [Error::RPCError] RPC error from call.
+      def unpause(reason: nil, jitter: nil, rpc_options: nil)
+        @client._impl.unpause_activity(
+          Interceptor::UnpauseActivityInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            reason:,
+            jitter:,
+            rpc_options:
+          )
+        )
+        nil
+      end
+
+      # Update the activity's options. Only the options named by `updates` are changed; anything
+      # not named is left as-is.
+      #
+      # Updates are created from the keys on {ActivityOptions}, via {ActivityOptions::Key#value_set}
+      # to set an option or {ActivityOptions::Key#value_unset} to clear it.
+      #
+      # WARNING: Standalone Activities are experimental.
+      #
+      # @param updates [Array<ActivityOptions::Update>] The option updates to apply. At least one is
+      #   required unless `restore_original` is true. Each option may be named at most once.
+      # @param restore_original [Boolean] If true, restore the options to the originals the activity
+      #   was created with. Mutually exclusive with any update.
+      # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+      #
+      # @return [ActivityExecutionOptions] The activity options after the update.
+      #
+      # @raise [ArgumentError] If a non-update is given, if `restore_original` is combined with any
+      #   update, if no update is provided and `restore_original` is false, or if the same option is
+      #   named more than once.
+      # @raise [Error::RPCError] RPC error from call.
+      def update_options(*updates, restore_original: false, rpc_options: nil)
+        unless updates.all?(ActivityOptions::Update)
+          raise ArgumentError,
+                'Updates must be created via ActivityOptions::Key#value_set or #value_unset'
+        end
+
+        if restore_original && !updates.empty?
+          raise ArgumentError, 'restore_original cannot be combined with any option update'
+        elsif !restore_original && updates.empty?
+          raise ArgumentError,
+                'At least one option update must be given, or restore_original must be used'
+        end
+
+        by_path = updates.each_with_object({}) do |update, acc|
+          name = update.key.name
+          raise ArgumentError, "More than one update given for option #{name}" if acc.key?(name)
+
+          acc[name] = update
+        end
+
+        proto = Api::Activity::V1::ActivityOptions.new
+        by_path.each_value do |update|
+          # An unset update names its path but leaves the field absent, which is how the server is
+          # told to clear the option rather than set it to a value.
+          update.key._apply(proto, update.value) unless update.value.nil?
+        end
+
+        @client._impl.update_activity_options(
+          Interceptor::UpdateActivityOptionsInput.new(
+            activity_id: id,
+            activity_run_id: run_id,
+            activity_options: proto,
+            update_mask: Google::Protobuf::FieldMask.new(paths: by_path.keys),
+            restore_original:,
+            rpc_options:
+          )
+        )
+      end
+
       private
 
       def _process_outcome(outcome, hint)

data/lib/temporalio/client/activity_id_reference.rb

@@ -29,8 +29,6 @@ module Temporalio
 
       # 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}.
@@ -57,8 +55,6 @@ module Temporalio
       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

data/lib/temporalio/client/activity_options.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/internal/proto_utils'
+
+module Temporalio
+  class Client
+    # The activity options that {ActivityHandle#update_options} can change.
+    #
+    # Updates are created from the keys below, via {Key#value_set} to set an option or
+    # {Key#value_unset} to clear it. An option with no update is left untouched.
+    #
+    # WARNING: Standalone Activities are experimental.
+    module ActivityOptions
+      # Typed key for one updatable activity option. Use the keys on {ActivityOptions} rather than
+      # constructing these directly.
+      class Key
+        # @return [String] Field-mask path this key updates.
+        attr_reader :name
+
+        # @!visibility private
+        def initialize(name, &to_proto)
+          @name = name
+          @to_proto = to_proto
+          freeze
+        end
+
+        # Create an update that sets this option to the given value.
+        #
+        # @param value [Object] Value to set. Cannot be nil.
+        # @return [Update] Created update.
+        def value_set(value)
+          raise ArgumentError, 'Value cannot be nil, use value_unset' if value.nil?
+
+          Update.new(self, value)
+        end
+
+        # Create an update that clears this option server-side.
+        #
+        # @return [Update] Created update.
+        def value_unset
+          Update.new(self, nil)
+        end
+
+        # @!visibility private
+        def _apply(proto, value)
+          @to_proto.call(proto, value)
+        end
+      end
+
+      # A single change to an activity's options that can be separately applied.
+      class Update
+        # @return [Key] Key this update applies to.
+        attr_reader :key
+
+        # @return [Object, nil] Value to set, or `nil` to clear the option.
+        attr_reader :value
+
+        # Create an update. Users may find it easier to use {Key#value_set} and {Key#value_unset}.
+        #
+        # @param key [Key] Key to update.
+        # @param value [Object, nil] Value to set, or nil to clear the option.
+        def initialize(key, value)
+          raise ArgumentError, 'Key must be a key' unless key.is_a?(Key)
+
+          @key = key
+          @value = value
+          freeze
+        end
+      end
+
+      # @return [Key] New task queue.
+      TASK_QUEUE = Key.new('task_queue.name') do |proto, value|
+        proto.task_queue = Api::TaskQueue::V1::TaskQueue.new(name: value.to_s)
+      end
+
+      # @return [Key] New schedule-to-close timeout in seconds.
+      SCHEDULE_TO_CLOSE_TIMEOUT = Key.new('schedule_to_close_timeout') do |proto, value|
+        proto.schedule_to_close_timeout = Internal::ProtoUtils.seconds_to_duration(value)
+      end
+
+      # @return [Key] New schedule-to-start timeout in seconds.
+      SCHEDULE_TO_START_TIMEOUT = Key.new('schedule_to_start_timeout') do |proto, value|
+        proto.schedule_to_start_timeout = Internal::ProtoUtils.seconds_to_duration(value)
+      end
+
+      # @return [Key] New start-to-close timeout in seconds.
+      START_TO_CLOSE_TIMEOUT = Key.new('start_to_close_timeout') do |proto, value|
+        proto.start_to_close_timeout = Internal::ProtoUtils.seconds_to_duration(value)
+      end
+
+      # @return [Key] New heartbeat timeout in seconds.
+      HEARTBEAT_TIMEOUT = Key.new('heartbeat_timeout') do |proto, value|
+        proto.heartbeat_timeout = Internal::ProtoUtils.seconds_to_duration(value)
+      end
+
+      # @return [Key] New start delay in seconds.
+      START_DELAY = Key.new('start_delay') do |proto, value|
+        proto.start_delay = Internal::ProtoUtils.seconds_to_duration(value)
+      end
+
+      # @return [Key] New retry policy.
+      RETRY_POLICY = Key.new('retry_policy') do |proto, value|
+        proto.retry_policy = value._to_proto
+      end
+
+      # @return [Key] New priority.
+      PRIORITY = Key.new('priority') do |proto, value|
+        proto.priority = value._to_proto
+      end
+    end
+  end
+end