temporalio 0.4.0-x86_64-darwin → 0.5.0-x86_64-darwin

data/lib/temporalio/worker/interceptor.rb

@@ -22,6 +22,7 @@ module Temporalio
         ExecuteInput = Data.define(
           :proc,
           :args,
+          :result_hint,
           :headers
         )
 
@@ -59,7 +60,8 @@ module Temporalio
 
         # Input for {Outbound.heartbeat}.
         HeartbeatInput = Data.define(
-          :details
+          :details,
+          :detail_hints
         )
 
         # Outbound interceptor for intercepting outbound activity calls. This should be extended by users needing to
@@ -216,6 +218,9 @@ module Temporalio
           :cancellation_type,
           :activity_id,
           :disable_eager_execution,
+          :priority,
+          :arg_hints,
+          :result_hint,
           :headers
         )
 
@@ -231,6 +236,8 @@ module Temporalio
           :cancellation,
           :cancellation_type,
           :activity_id,
+          :arg_hints,
+          :result_hint,
           :headers
         )
 
@@ -245,6 +252,7 @@ module Temporalio
           :signal,
           :args,
           :cancellation,
+          :arg_hints,
           :headers
         )
 
@@ -255,6 +263,7 @@ module Temporalio
           :signal,
           :args,
           :cancellation,
+          :arg_hints,
           :headers
         )
 
@@ -284,6 +293,9 @@ module Temporalio
           :cron_schedule,
           :memo,
           :search_attributes,
+          :priority,
+          :arg_hints,
+          :result_hint,
           :headers
         )
 

data/lib/temporalio/worker/poller_behavior.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Worker
+    # Base class for poller behaviors that control how polling scales.
+    class PollerBehavior
+      # @!visibility private
+      def _to_bridge_options
+        raise NotImplementedError, 'Subclasses must implement this method'
+      end
+
+      # A poller behavior that attempts to poll as long as a slot is available, up to the
+      # provided maximum. Cannot be less than two for workflow tasks, or one for other tasks.
+      class SimpleMaximum < PollerBehavior
+        # @return [Integer] Maximum number of concurrent poll requests.
+        attr_reader :maximum
+
+        # @param maximum [Integer] Maximum number of concurrent poll requests.
+        def initialize(maximum)
+          super()
+          @maximum = maximum
+        end
+
+        # @!visibility private
+        def _to_bridge_options
+          Internal::Bridge::Worker::PollerBehaviorSimpleMaximum.new(simple_maximum: @maximum)
+        end
+      end
+
+      # A poller behavior that automatically scales the number of pollers based on feedback
+      # from the server. A slot must be available before beginning polling.
+      class Autoscaling < PollerBehavior
+        # @return [Integer] Minimum number of poll calls (assuming slots are available).
+        attr_reader :minimum
+        # @return [Integer] Maximum number of poll calls that will ever be open at once.
+        attr_reader :maximum
+        # @return [Integer] Number of polls attempted initially before scaling kicks in.
+        attr_reader :initial
+
+        # @param minimum [Integer] Minimum number of poll calls (assuming slots are available).
+        # @param maximum [Integer] Maximum number of poll calls that will ever be open at once.
+        # @param initial [Integer] Number of polls attempted initially before scaling kicks in.
+        def initialize(minimum: 1, maximum: 100, initial: 5)
+          super()
+          @minimum = minimum
+          @maximum = maximum
+          @initial = initial
+        end
+
+        # @!visibility private
+        def _to_bridge_options
+          Internal::Bridge::Worker::PollerBehaviorAutoscaling.new(
+            minimum: @minimum,
+            maximum: @maximum,
+            initial: @initial
+          )
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/worker/thread_pool.rb

@@ -125,7 +125,7 @@ module Temporalio
 
       private
 
-      def locked_assign_worker(&block)
+      def locked_assign_worker(&block) # rubocop:disable Naming/PredicateMethod
         # keep growing if the pool is not at the minimum yet
         worker, = @ready.pop || locked_add_busy_worker
         if worker

data/lib/temporalio/worker/workflow_executor/thread_pool.rb

@@ -214,7 +214,8 @@ module Temporalio
                 disable_eager_activity_execution: worker_state.disable_eager_activity_execution,
                 illegal_calls: worker_state.illegal_calls,
                 workflow_failure_exception_types: worker_state.workflow_failure_exception_types,
-                unsafe_workflow_io_enabled: worker_state.unsafe_workflow_io_enabled
+                unsafe_workflow_io_enabled: worker_state.unsafe_workflow_io_enabled,
+                assert_valid_local_activity: worker_state.assert_valid_local_activity
               )
             )
           end

data/lib/temporalio/worker/workflow_replayer.rb

@@ -7,6 +7,7 @@ require 'temporalio/internal/bridge/worker'
 require 'temporalio/internal/worker/multi_runner'
 require 'temporalio/internal/worker/workflow_worker'
 require 'temporalio/worker/interceptor'
+require 'temporalio/worker/poller_behavior'
 require 'temporalio/worker/thread_pool'
 require 'temporalio/worker/tuner'
 require 'temporalio/worker/workflow_executor'
@@ -24,7 +25,6 @@ module Temporalio
         :data_converter,
         :workflow_executor,
         :interceptors,
-        :build_id,
         :identity,
         :logger,
         :illegal_workflow_calls,
@@ -51,9 +51,6 @@ module Temporalio
       # @param workflow_executor [WorkflowExecutor] Workflow executor that workflow tasks run within. This must be a
       #   {WorkflowExecutor::ThreadPool} currently.
       # @param interceptors [Array<Interceptor::Workflow>] Workflow interceptors.
-      # @param build_id [String] Unique identifier for the current runtime. This is best set as a unique value
-      #   representing all code and should change only when code does. This can be something like a git commit hash. If
-      #   unset, default is hash of known Ruby code.
       # @param identity [String, nil] Override the identity for this replater.
       # @param logger [Logger] Logger to use. Defaults to stdout with warn level. Callers setting this logger are
       #   responsible for closing it.
@@ -87,7 +84,6 @@ module Temporalio
         data_converter: Converters::DataConverter.default,
         workflow_executor: WorkflowExecutor::ThreadPool.default,
         interceptors: [],
-        build_id: Worker.default_build_id,
         identity: nil,
         logger: Logger.new($stdout, level: Logger::WARN),
         illegal_workflow_calls: Worker.default_illegal_workflow_calls,
@@ -105,7 +101,6 @@ module Temporalio
           data_converter:,
           workflow_executor:,
           interceptors:,
-          build_id:,
           identity:,
           logger:,
           illegal_workflow_calls:,
@@ -116,7 +111,9 @@ module Temporalio
           runtime:
         ).freeze
         # Preload definitions and other settings
-        @workflow_definitions = Internal::Worker::WorkflowWorker.workflow_definitions(workflows)
+        @workflow_definitions = Internal::Worker::WorkflowWorker.workflow_definitions(
+          workflows, should_enforce_versioning_behavior: false
+        )
         @nondeterminism_as_workflow_fail, @nondeterminism_as_workflow_fail_for_types =
           Internal::Worker::WorkflowWorker.bridge_workflow_failure_exception_type_options(
             workflow_failure_exception_types:, workflow_definitions: @workflow_definitions
@@ -207,12 +204,13 @@ module Temporalio
               tuner: Tuner.create_fixed(
                 workflow_slots: 2, activity_slots: 1, local_activity_slots: 1
               )._to_bridge_options,
-              build_id: options.build_id,
               identity_override: options.identity,
               max_cached_workflows: 2,
-              max_concurrent_workflow_task_polls: 1,
+              workflow_task_poller_behavior:
+                Temporalio::Worker::PollerBehavior::SimpleMaximum.new(2)._to_bridge_options,
               nonsticky_to_sticky_poll_ratio: 1.0,
-              max_concurrent_activity_task_polls: 1,
+              activity_task_poller_behavior:
+                Temporalio::Worker::PollerBehavior::SimpleMaximum.new(1)._to_bridge_options,
               no_remote_activities: true,
               sticky_queue_schedule_to_start_timeout: 1.0,
               max_heartbeat_throttle_interval: 1.0,
@@ -220,9 +218,9 @@ module Temporalio
               max_worker_activities_per_second: nil,
               max_task_queue_activities_per_second: nil,
               graceful_shutdown_period: 0.0,
-              use_worker_versioning: false,
               nondeterminism_as_workflow_fail:,
-              nondeterminism_as_workflow_fail_for_types:
+              nondeterminism_as_workflow_fail_for_types:,
+              deployment_options: Worker.default_deployment_options._to_bridge_options
             )
           )
 
@@ -245,7 +243,8 @@ module Temporalio
             workflow_payload_codec_thread_pool: options.workflow_payload_codec_thread_pool,
             unsafe_workflow_io_enabled: options.unsafe_workflow_io_enabled,
             debug_mode: options.debug_mode,
-            on_eviction: proc { |_, remove_job| @last_workflow_remove_job = remove_job } # steep:ignore
+            on_eviction: proc { |_, remove_job| @last_workflow_remove_job = remove_job }, # steep:ignore
+            assert_valid_local_activity: ->(_) {}
           )
 
           # Create the runner

data/lib/temporalio/worker.rb

@@ -12,7 +12,10 @@ require 'temporalio/internal/worker/multi_runner'
 require 'temporalio/internal/worker/workflow_instance'
 require 'temporalio/internal/worker/workflow_worker'
 require 'temporalio/worker/activity_executor'
+require 'temporalio/worker/deployment_options'
+require 'temporalio/worker/illegal_workflow_call_validator'
 require 'temporalio/worker/interceptor'
+require 'temporalio/worker/poller_behavior'
 require 'temporalio/worker/thread_pool'
 require 'temporalio/worker/tuner'
 require 'temporalio/worker/workflow_executor'
@@ -33,7 +36,6 @@ module Temporalio
       :activity_executors,
       :workflow_executor,
       :interceptors,
-      :build_id,
       :identity,
       :logger,
       :max_cached_workflows,
@@ -47,12 +49,14 @@ module Temporalio
       :max_activities_per_second,
       :max_task_queue_activities_per_second,
       :graceful_shutdown_period,
-      :use_worker_versioning,
       :disable_eager_activity_execution,
       :illegal_workflow_calls,
       :workflow_failure_exception_types,
       :workflow_payload_codec_thread_pool,
       :unsafe_workflow_io_enabled,
+      :deployment_options,
+      :workflow_task_poller_behavior,
+      :activity_task_poller_behavior,
       :debug_mode
     )
 
@@ -89,6 +93,14 @@ module Temporalio
       build_id
     end
 
+    # @return [DeploymentOptions] Default deployment options, which does not use worker versioning
+    #   or a deployment name, and sets the build id to the one from {self.default_build_id}.
+    def self.default_deployment_options
+      @default_deployment_options ||= DeploymentOptions.new(
+        version: WorkerDeploymentVersion.new(deployment_name: '', build_id: Worker.default_build_id)
+      )
+    end
+
     # Run all workers until cancellation or optional block completes. When the cancellation or block is complete, the
     # workers are shut down. This will return the block result if everything successful or raise an error if not. See
     # {run} for details on how worker shutdown works.
@@ -232,8 +244,9 @@ module Temporalio
       end
     end
 
-    # @return [Hash<String, [:all, Array<Symbol>]>] Default, immutable set illegal calls used for the
-    #   `illegal_workflow_calls` worker option. See the documentation of that option for more details.
+    # @return [Hash<String, [:all, Array<Symbol, IllegalWorkflowCallValidator>, IllegalWorkflowCallValidator]>] Default,
+    #   immutable set illegal calls used for the `illegal_workflow_calls` worker option. See the documentation of that
+    #   option for more details.
     def self.default_illegal_workflow_calls
       @default_illegal_workflow_calls ||= begin
         hash = {
@@ -272,7 +285,7 @@ module Temporalio
           'Thread' => %i[abort_on_exception= exit fork handle_interrupt ignore_deadlock= kill new pass
                          pending_interrupt? report_on_exception= start stop initialize join name= priority= raise run
                          terminate thread_variable_set wakeup],
-          'Time' => %i[initialize now]
+          'Time' => IllegalWorkflowCallValidator.default_time_validators
         } #: Hash[String, :all | Array[Symbol]]
         hash.each_value(&:freeze)
         hash.freeze
@@ -296,9 +309,6 @@ module Temporalio
     # @param interceptors [Array<Interceptor::Activity, Interceptor::Workflow>] Interceptors specific to this worker.
     #   Note, interceptors set on the client that include the {Interceptor::Activity} or {Interceptor::Workflow} module
     #   are automatically included here, so no need to specify them again.
-    # @param build_id [String] Unique identifier for the current runtime. This is best set as a unique value
-    #   representing all code and should change only when code does. This can be something like a git commit hash. If
-    #   unset, default is hash of known Ruby code.
     # @param identity [String, nil] Override the identity for this worker. If unset, client identity is used.
     # @param logger [Logger] Logger to override client logger with. Default is the client logger.
     # @param max_cached_workflows [Integer] Number of workflows held in cache for use by sticky task queue. If set to 0,
@@ -327,19 +337,19 @@ module Temporalio
     #   multiple workers on the same queue have different values set, they will thrash with the last poller winning.
     # @param graceful_shutdown_period [Float] Amount of time after shutdown is called that activities are given to
     #   complete before their tasks are canceled.
-    # @param use_worker_versioning [Boolean] If true, the `build_id` argument must be specified, and this worker opts
-    #   into the worker versioning feature. This ensures it only receives workflow tasks for workflows which it claims
-    #   to be compatible with. For more information, see https://docs.temporal.io/workers#worker-versioning.
     # @param disable_eager_activity_execution [Boolean] If true, disables eager activity execution. Eager activity
     #   execution is an optimization on some servers that sends activities back to the same worker as the calling
     #   workflow if they can run there. This should be set to true for `max_task_queue_activities_per_second` to work
     #   and in a future version of this API may be implied as such (i.e. this setting will be ignored if that setting is
     #   set).
-    # @param illegal_workflow_calls [Hash<String, [:all, Array<Symbol>]>] Set of illegal workflow calls that are
-    #   considered unsafe/non-deterministic and will raise if seen. The key of the hash is the fully qualified string
-    #   class name (no leading `::`). The value is either `:all` which means any use of the class, or an array of
-    #   symbols for methods on the class that cannot be used. The methods refer to either instance or class methods,
-    #   there is no way to differentiate at this time.
+    # @param illegal_workflow_calls [Hash<String,
+    #   [:all, Array<Symbol, IllegalWorkflowCallValidator>, IllegalWorkflowCallValidator]>] Set of illegal workflow
+    #   calls that are considered unsafe/non-deterministic and will raise if seen. The key of the hash is the fully
+    #   qualified string class name (no leading `::`). The value can be `:all` which means any use of the class is
+    #   illegal. The value can be an array of symbols/validators for methods on the class that cannot be used. The
+    #   methods refer to either instance or class methods, there is no way to differentiate at this time. Symbol method
+    #   names are the normal way to say the method cannot be used, validators are only for advanced situations. Finally,
+    #   for advanced situations, the hash value can be a class-level validator that is not tied to a specific method.
     # @param workflow_failure_exception_types [Array<Class<Exception>>] Workflow failure exception types. This is the
     #   set of exception types that, if a workflow-thrown exception extends, will cause the workflow/update to fail
     #   instead of suspending the workflow via task failure. These are applied in addition to the
@@ -351,6 +361,12 @@ module Temporalio
     # @param unsafe_workflow_io_enabled [Boolean] If false, the default, workflow code that invokes io_wait on the fiber
     #   scheduler will fail. Instead of setting this to true, users are encouraged to use {Workflow::Unsafe.io_enabled}
     #   with a block for narrower enabling of IO.
+    # @param deployment_options [DeploymentOptions, nil] Deployment options for the worker.
+    #   WARNING: This is an experimental feature and may change in the future.
+    # @param workflow_task_poller_behavior [PollerBehavior] Specify the behavior of workflow task
+    #   polling. Defaults to a 5-poller maximum.
+    # @param activity_task_poller_behavior [PollerBehavior] Specify the behavior of activity task
+    #   polling. Defaults to a 5-poller maximum.
     # @param debug_mode [Boolean] If true, deadlock detection is disabled. Deadlock detection will fail workflow tasks
     #   if they block the thread for too long. This defaults to true if the `TEMPORAL_DEBUG` environment variable is
     #   `true` or `1`.
@@ -363,7 +379,6 @@ module Temporalio
       activity_executors: ActivityExecutor.defaults,
       workflow_executor: WorkflowExecutor::ThreadPool.default,
       interceptors: [],
-      build_id: Worker.default_build_id,
       identity: nil,
       logger: client.options.logger,
       max_cached_workflows: 1000,
@@ -377,12 +392,14 @@ module Temporalio
       max_activities_per_second: nil,
       max_task_queue_activities_per_second: nil,
       graceful_shutdown_period: 0,
-      use_worker_versioning: false,
       disable_eager_activity_execution: false,
       illegal_workflow_calls: Worker.default_illegal_workflow_calls,
       workflow_failure_exception_types: [],
       workflow_payload_codec_thread_pool: nil,
       unsafe_workflow_io_enabled: false,
+      deployment_options: Worker.default_deployment_options,
+      workflow_task_poller_behavior: PollerBehavior::SimpleMaximum.new(max_concurrent_workflow_task_polls),
+      activity_task_poller_behavior: PollerBehavior::SimpleMaximum.new(max_concurrent_activity_task_polls),
       debug_mode: %w[true 1].include?(ENV['TEMPORAL_DEBUG'].to_s.downcase)
     )
       raise ArgumentError, 'Must have at least one activity or workflow' if activities.empty? && workflows.empty?
@@ -398,7 +415,6 @@ module Temporalio
         activity_executors:,
         workflow_executor:,
         interceptors:,
-        build_id:,
         identity:,
         logger:,
         max_cached_workflows:,
@@ -412,17 +428,25 @@ module Temporalio
         max_activities_per_second:,
         max_task_queue_activities_per_second:,
         graceful_shutdown_period:,
-        use_worker_versioning:,
         disable_eager_activity_execution:,
         illegal_workflow_calls:,
         workflow_failure_exception_types:,
         workflow_payload_codec_thread_pool:,
         unsafe_workflow_io_enabled:,
+        deployment_options:,
+        workflow_task_poller_behavior:,
+        activity_task_poller_behavior:,
         debug_mode:
       ).freeze
 
+      should_enforce_versioning_behavior =
+        deployment_options.use_worker_versioning &&
+        deployment_options.default_versioning_behavior == VersioningBehavior::UNSPECIFIED
       # Preload workflow definitions and some workflow settings for the bridge
-      workflow_definitions = Internal::Worker::WorkflowWorker.workflow_definitions(workflows)
+      workflow_definitions = Internal::Worker::WorkflowWorker.workflow_definitions(
+        workflows,
+        should_enforce_versioning_behavior: should_enforce_versioning_behavior
+      )
       nondeterminism_as_workflow_fail, nondeterminism_as_workflow_fail_for_types =
         Internal::Worker::WorkflowWorker.bridge_workflow_failure_exception_type_options(
           workflow_failure_exception_types:, workflow_definitions:
@@ -437,12 +461,11 @@ module Temporalio
           namespace: client.namespace,
           task_queue:,
           tuner: tuner._to_bridge_options,
-          build_id:,
           identity_override: identity,
           max_cached_workflows:,
-          max_concurrent_workflow_task_polls:,
+          workflow_task_poller_behavior: workflow_task_poller_behavior._to_bridge_options,
           nonsticky_to_sticky_poll_ratio:,
-          max_concurrent_activity_task_polls:,
+          activity_task_poller_behavior: activity_task_poller_behavior._to_bridge_options,
           # For shutdown to work properly, we must disable remote activities
           # ourselves if there are no activities
           no_remote_activities: no_remote_activities || activities.empty?,
@@ -452,9 +475,9 @@ module Temporalio
           max_worker_activities_per_second: max_activities_per_second,
           max_task_queue_activities_per_second:,
           graceful_shutdown_period:,
-          use_worker_versioning:,
           nondeterminism_as_workflow_fail:,
-          nondeterminism_as_workflow_fail_for_types:
+          nondeterminism_as_workflow_fail_for_types:,
+          deployment_options: deployment_options._to_bridge_options
         )
       )
 
@@ -490,7 +513,8 @@ module Temporalio
           workflow_failure_exception_types:,
           workflow_payload_codec_thread_pool:,
           unsafe_workflow_io_enabled:,
-          debug_mode:
+          debug_mode:,
+          assert_valid_local_activity: ->(activity) { _assert_valid_local_activity(activity) }
         )
       end
 
@@ -599,5 +623,17 @@ module Temporalio
       @workflow_worker&.on_shutdown_complete
       @workflow_worker = nil
     end
+
+    # @!visibility private
+    def _assert_valid_local_activity(activity)
+      unless @activity_worker.nil?
+        @activity_worker.assert_valid_activity(activity)
+        return
+      end
+
+      raise ArgumentError,
+            "Activity #{activity} " \
+            'is not registered on this worker, no available activities.'
+    end
   end
 end

data/lib/temporalio/worker_deployment_version.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/bridge/worker'
+
+module Temporalio
+  WorkerDeploymentVersion = Data.define(
+    :deployment_name,
+    :build_id
+  )
+
+  # Represents the version of a specific worker deployment.
+  #
+  # WARNING: Experimental API.
+  class WorkerDeploymentVersion
+    # Parse a version from a canonical string, which must be in the format
+    # `<deployment_name>.<build_id>`. Deployment name must not have a `.` in it.
+    #
+    # @param canonical [String] The canonical string representation of the version.
+    # @return [WorkerDeploymentVersion] The parsed version.
+    def self.from_canonical_string(canonical)
+      parts = canonical.split('.', 2)
+      if parts.length != 2
+        raise ArgumentError,
+              "Cannot parse version string: #{canonical}, must be in format <deployment_name>.<build_id>"
+      end
+      new(deployment_name: parts[0], build_id: parts[1])
+    end
+
+    # @!visibility private
+    def self._from_bridge(bridge)
+      return nil if bridge.nil?
+
+      new(deployment_name: bridge.deployment_name, build_id: bridge.build_id)
+    end
+
+    # Create WorkerDeploymentVersion.
+    #
+    # @param deployment_name [String] The name of the deployment.
+    # @param build_id [String] The build identifier specific to this worker build.
+    def initialize(deployment_name:, build_id:) # rubocop:disable Lint/UselessMethodDefinition
+      super
+    end
+
+    # Returns the canonical string representation of the version.
+    #
+    # @return [String]
+    def to_canonical_string
+      "#{deployment_name}.#{build_id}"
+    end
+
+    # @!visibility private
+    def _to_bridge_options
+      Internal::Bridge::Worker::WorkerDeploymentVersion.new(
+        deployment_name: deployment_name,
+        build_id: build_id
+      )
+    end
+
+    # @!visibility private
+    def _to_proto
+      Api::Deployment::V1::WorkerDeploymentVersion.new(
+        deployment_name: deployment_name,
+        build_id: build_id
+      )
+    end
+  end
+end

data/lib/temporalio/workflow/child_workflow_handle.rb

@@ -21,12 +21,18 @@ module Temporalio
         raise NotImplementedError
       end
 
+      # @return [Object, nil] Hint for the result if any.
+      def result_hint
+        raise NotImplementedError
+      end
+
       # Wait for the result.
       #
+      # @param result_hint [Object, nil] Override the result hint, or if nil uses the one on the handle.
       # @return [Object] Result of the child workflow.
       #
       # @raise [Error::ChildWorkflowError] Workflow failed with +cause+ as the cause.
-      def result
+      def result(result_hint: nil)
         raise NotImplementedError
       end
 
@@ -35,7 +41,9 @@ module Temporalio
       # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
       # @param args [Array<Object>] Signal args.
       # @param cancellation [Cancellation] Cancellation for canceling the signalling.
-      def signal(signal, *args, cancellation: Workflow.cancellation)
+      # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+      #   signal definition has arg hints, those are used by default.
+      def signal(signal, *args, cancellation: Workflow.cancellation, arg_hints: nil)
         raise NotImplementedError
       end
     end