temporalio 0.3.0-x86_64-linux → 0.5.0-x86_64-linux

data/lib/temporalio/worker.rb

@@ -6,12 +6,16 @@ require 'temporalio/client'
 require 'temporalio/error'
 require 'temporalio/internal/bridge'
 require 'temporalio/internal/bridge/worker'
+require 'temporalio/internal/proto_utils'
 require 'temporalio/internal/worker/activity_worker'
 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'
@@ -32,7 +36,6 @@ module Temporalio
       :activity_executors,
       :workflow_executor,
       :interceptors,
-      :build_id,
       :identity,
       :logger,
       :max_cached_workflows,
@@ -46,15 +49,20 @@ 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
     )
 
     # Options as returned from {options} for `**to_h` splat use in {initialize}. See {initialize} for details.
+    #
+    # Note, the `client` within can be replaced via client setter.
     class Options; end # rubocop:disable Lint/EmptyClass
 
     # @return [String] Memoized default build ID. This default value is built as a checksum of all of the loaded Ruby
@@ -85,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.
@@ -137,7 +153,8 @@ module Temporalio
         case event
         when Internal::Worker::MultiRunner::Event::PollSuccess
           # Successful poll
-          event.worker._on_poll_bytes(runner, event.worker_type, event.bytes)
+          event.worker #: Worker
+               ._on_poll_bytes(runner, event.worker_type, event.bytes)
         when Internal::Worker::MultiRunner::Event::PollFailure
           # Poll failure, this causes shutdown of all workers
           logger.error('Poll failure (beginning worker shutdown if not already occurring)')
@@ -227,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 = {
@@ -267,14 +285,14 @@ 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
       end
     end
 
-    # @return [Options] Frozen options for this client which has the same attributes as {initialize}.
+    # @return [Options] Options for this worker which has the same attributes as {initialize}.
     attr_reader :options
 
     # Create a new worker. At least one activity or workflow must be present.
@@ -291,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,
@@ -322,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
@@ -343,6 +358,15 @@ module Temporalio
     # @param workflow_payload_codec_thread_pool [ThreadPool, nil] Thread pool to run payload codec encode/decode within.
     #   This is required if a payload codec exists and the worker is not fiber based. Codecs can potentially block
     #   execution which is why they need to be run in the background.
+    # @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`.
@@ -355,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,
@@ -369,15 +392,20 @@ 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?
 
+      Internal::ProtoUtils.assert_non_reserved_name(task_queue)
+
       @options = Options.new(
         client:,
         task_queue:,
@@ -387,7 +415,6 @@ module Temporalio
         activity_executors:,
         workflow_executor:,
         interceptors:,
-        build_id:,
         identity:,
         logger:,
         max_cached_workflows:,
@@ -401,29 +428,29 @@ 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)
-      nondeterminism_as_workflow_fail = workflow_failure_exception_types.any? do |t|
-        t.is_a?(Class) && t >= Workflow::NondeterminismError
-      end
-      nondeterminism_as_workflow_fail_for_types = workflow_definitions.values.map do |defn|
-        next unless defn.failure_exception_types.any? { |t| t.is_a?(Class) && t >= Workflow::NondeterminismError }
-
-        # If they tried to do this on a dynamic workflow and haven't already set worker-level option, warn
-        unless defn.name || nondeterminism_as_workflow_fail
-          warn('Note, dynamic workflows cannot trap non-determinism errors, so worker-level ' \
-               'workflow_failure_exception_types should be set to capture that if that is the intention')
-        end
-        defn.name
-      end.compact
+      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:
+        )
 
       # Create the bridge worker
       @bridge_worker = Internal::Bridge::Worker.new(
@@ -433,17 +460,12 @@ module Temporalio
           workflow: !workflows.empty?,
           namespace: client.namespace,
           task_queue:,
-          tuner: Internal::Bridge::Worker::TunerOptions.new(
-            workflow_slot_supplier: to_bridge_slot_supplier_options(tuner.workflow_slot_supplier),
-            activity_slot_supplier: to_bridge_slot_supplier_options(tuner.activity_slot_supplier),
-            local_activity_slot_supplier: to_bridge_slot_supplier_options(tuner.local_activity_slot_supplier)
-          ),
-          build_id:,
+          tuner: tuner._to_bridge_options,
           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?,
@@ -453,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
         )
       )
 
@@ -476,13 +498,31 @@ module Temporalio
                                                                 bridge_worker: @bridge_worker)
       end
       unless workflows.empty?
-        @workflow_worker = Internal::Worker::WorkflowWorker.new(worker: self,
-                                                                bridge_worker: @bridge_worker,
-                                                                workflow_definitions:)
+        @workflow_worker = Internal::Worker::WorkflowWorker.new(
+          bridge_worker: @bridge_worker,
+          namespace: client.namespace,
+          task_queue:,
+          workflow_definitions:,
+          workflow_executor:,
+          logger:,
+          data_converter: client.data_converter,
+          metric_meter: client.connection.options.runtime.metric_meter,
+          workflow_interceptors: @workflow_interceptors,
+          disable_eager_activity_execution:,
+          illegal_workflow_calls:,
+          workflow_failure_exception_types:,
+          workflow_payload_codec_thread_pool:,
+          unsafe_workflow_io_enabled:,
+          debug_mode:,
+          assert_valid_local_activity: ->(activity) { _assert_valid_local_activity(activity) }
+        )
       end
 
       # Validate worker
       @bridge_worker.validate
+
+      # Mutex needed for accessing and replacing a client
+      @client_mutex = Mutex.new
     end
 
     # @return [String] Task queue set on the worker options.
@@ -490,6 +530,25 @@ module Temporalio
       @options.task_queue
     end
 
+    # @return [Client] Client for this worker. This is the same as {Options.client} in {options}, but surrounded by a
+    #   mutex to be safe for client replacement in {client=}.
+    def client
+      @client_mutex.synchronize { @options.client }
+    end
+
+    # Replace the worker's client. When this is called, the client is replaced on the internal worker which means any
+    # new calls will be made on the new client (but existing calls will still complete on the previous one). This is
+    # commonly used for providing a new client with updated authentication credentials.
+    #
+    # @param new_client [Client] New client to use for new calls.
+    def client=(new_client)
+      @client_mutex.synchronize do
+        @bridge_worker.replace_client(new_client.connection._core_client)
+        @options = @options.with(client: new_client)
+        new_client
+      end
+    end
+
     # Run this worker until cancellation or optional block completes. When the cancellation or block is complete, the
     # worker is shut down. This will return the block result if everything successful or raise an error if not.
     #
@@ -543,11 +602,6 @@ module Temporalio
       @activity_interceptors
     end
 
-    # @!visibility private
-    def _workflow_interceptors
-      @workflow_interceptors
-    end
-
     # @!visibility private
     def _on_poll_bytes(runner, worker_type, bytes)
       case worker_type
@@ -570,28 +624,16 @@ module Temporalio
       @workflow_worker = nil
     end
 
-    private
-
-    def to_bridge_slot_supplier_options(slot_supplier)
-      if slot_supplier.is_a?(Tuner::SlotSupplier::Fixed)
-        Internal::Bridge::Worker::TunerSlotSupplierOptions.new(
-          fixed_size: slot_supplier.slots,
-          resource_based: nil
-        )
-      elsif slot_supplier.is_a?(Tuner::SlotSupplier::ResourceBased)
-        Internal::Bridge::Worker::TunerSlotSupplierOptions.new(
-          fixed_size: nil,
-          resource_based: Internal::Bridge::Worker::TunerResourceBasedSlotSupplierOptions.new(
-            target_mem_usage: slot_supplier.tuner_options.target_memory_usage,
-            target_cpu_usage: slot_supplier.tuner_options.target_cpu_usage,
-            min_slots: slot_supplier.slot_options.min_slots,
-            max_slots: slot_supplier.slot_options.max_slots,
-            ramp_throttle: slot_supplier.slot_options.ramp_throttle
-          )
-        )
-      else
-        raise ArgumentError, 'Tuner slot suppliers must be instances of Fixed or ResourceBased'
+    # @!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