temporalio 0.2.0 → 0.4.0

data/lib/temporalio/worker.rb

@@ -6,11 +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/interceptor'
+require 'temporalio/worker/thread_pool'
 require 'temporalio/worker/tuner'
+require 'temporalio/worker/workflow_executor'
 
 module Temporalio
   # Worker for processing activities and workflows on a task queue.
@@ -19,13 +24,14 @@ module Temporalio
   # {run_all} is used for a collection of workers. These can wait until a block is complete or a {Cancellation} is
   # canceled.
   class Worker
-    # Options as returned from {options} for `**to_h`` splat use in {initialize}. See {initialize} for details.
-    Options = Struct.new(
+    Options = Data.define(
       :client,
       :task_queue,
       :activities,
-      :activity_executors,
+      :workflows,
       :tuner,
+      :activity_executors,
+      :workflow_executor,
       :interceptors,
       :build_id,
       :identity,
@@ -42,9 +48,19 @@ module Temporalio
       :max_task_queue_activities_per_second,
       :graceful_shutdown_period,
       :use_worker_versioning,
-      keyword_init: true
+      :disable_eager_activity_execution,
+      :illegal_workflow_calls,
+      :workflow_failure_exception_types,
+      :workflow_payload_codec_thread_pool,
+      :unsafe_workflow_io_enabled,
+      :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
     #   source files in `$LOADED_FEATURES`. Users may prefer to set the build ID to a better representation of the
     #   source.
@@ -108,7 +124,7 @@ module Temporalio
       runner.apply_thread_or_fiber_block(&block)
 
       # Reuse first worker logger
-      logger = workers.first&.options&.logger or raise # Help steep
+      logger = workers.first&.options&.logger or raise # Never nil
 
       # On cancel, initiate shutdown
       cancellation.add_cancel_callback do
@@ -121,16 +137,35 @@ module Temporalio
       block_result = nil
       loop do
         event = runner.next_event
+        # TODO(cretz): Consider improving performance instead of this case statement
         case event
         when Internal::Worker::MultiRunner::Event::PollSuccess
           # Successful poll
-          event.worker._on_poll_bytes(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 alaredy occurring)')
+          logger.error('Poll failure (beginning worker shutdown if not already occurring)')
           logger.error(event.error)
           first_error ||= event.error
           runner.initiate_shutdown
+        when Internal::Worker::MultiRunner::Event::WorkflowActivationDecoded
+          # Came back from a codec as decoded
+          event.workflow_worker.handle_activation(runner:, activation: event.activation, decoded: true)
+        when Internal::Worker::MultiRunner::Event::WorkflowActivationComplete
+          # An activation is complete
+          event.workflow_worker.handle_activation_complete(
+            runner:,
+            activation_completion: event.activation_completion,
+            encoded: event.encoded,
+            completion_complete_queue: event.completion_complete_queue
+          )
+        when Internal::Worker::MultiRunner::Event::WorkflowActivationCompletionComplete
+          # Completion complete, only need to log error if it occurs here
+          if event.error
+            logger.error("Activation completion failed to record on run ID #{event.run_id}")
+            logger.error(event.error)
+          end
         when Internal::Worker::MultiRunner::Event::PollerShutDown
           # Individual poller shut down. Nothing to do here until we support
           # worker status or something.
@@ -186,6 +221,9 @@ module Temporalio
         end
       end
 
+      # Notify each worker we're done with it
+      workers.each(&:_on_shutdown_complete)
+
       # If there was an shutdown-causing error, we raise that
       if !first_error.nil?
         raise first_error
@@ -194,27 +232,80 @@ module Temporalio
       end
     end
 
-    # @return [Options] Frozen options for this client which has the same attributes as {initialize}.
+    # @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.
+    def self.default_illegal_workflow_calls
+      @default_illegal_workflow_calls ||= begin
+        hash = {
+          'BasicSocket' => :all,
+          'Date' => %i[initialize today],
+          'DateTime' => %i[initialize now],
+          'Dir' => :all,
+          'Fiber' => [:set_scheduler],
+          'File' => :all,
+          'FileTest' => :all,
+          'FileUtils' => :all,
+          'Find' => :all,
+          'GC' => :all,
+          'IO' => [
+            :read
+            # Intentionally leaving out write so puts will work. We don't want to add heavy logic replacing stdout or
+            # trying to derive whether it's file vs stdout write.
+            #:write
+          ],
+          'Kernel' => %i[abort at_exit autoload autoload? eval exec exit fork gets load open rand readline readlines
+                         spawn srand system test trap],
+          'Net::HTTP' => :all,
+          'Pathname' => :all,
+          # TODO(cretz): Investigate why clock_gettime called from Timeout thread affects this code at all. Stack trace
+          # test executing activities inside a timeout will fail if clock_gettime is blocked.
+          'Process' => %i[abort argv0 daemon detach exec exit exit! fork kill setpriority setproctitle setrlimit setsid
+                          spawn times wait wait2 waitall warmup],
+          # TODO(cretz): Allow Ractor.current since exception formatting in error_highlight references it
+          # 'Ractor' => :all,
+          'Random::Base' => [:initialize],
+          'Resolv' => :all,
+          'SecureRandom' => :all,
+          'Signal' => :all,
+          'Socket' => :all,
+          'Tempfile' => :all,
+          '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]
+        } #: Hash[String, :all | Array[Symbol]]
+        hash.each_value(&:freeze)
+        hash.freeze
+      end
+    end
+
+    # @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.
     #
     # @param client [Client] Client for this worker.
     # @param task_queue [String] Task queue for this worker.
-    # @param activities [Array<Activity, Class<Activity>, Activity::Definition>] Activities for this worker.
-    # @param activity_executors [Hash<Symbol, Worker::ActivityExecutor>] Executors that activities can run within.
+    # @param activities [Array<Activity::Definition, Class<Activity::Definition>, Activity::Definition::Info>]
+    #   Activities for this worker.
+    # @param workflows [Array<Class<Workflow::Definition>>] Workflows for this worker.
     # @param tuner [Tuner] Tuner that controls the amount of concurrent activities/workflows that run at a time.
-    # @param interceptors [Array<Interceptor>] Interceptors specific to this worker. Note, interceptors set on the
-    #   client that include the {Interceptor} module are automatically included here, so no need to specify them again.
+    # @param activity_executors [Hash<Symbol, Worker::ActivityExecutor>] Executors that activities can run within.
+    # @param workflow_executor [WorkflowExecutor] Workflow executor that workflow tasks run within. This must be a
+    #   {WorkflowExecutor::ThreadPool} currently.
+    # @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,
     #   workflow caching and sticky queuing are disabled.
     # @param max_concurrent_workflow_task_polls [Integer] Maximum number of concurrent poll workflow task requests we
     #   will perform at a time on this worker's task queue.
-    # @param nonsticky_to_sticky_poll_ratio [Float] `max_concurrent_workflow_task_polls`` * this number = the number of
+    # @param nonsticky_to_sticky_poll_ratio [Float] `max_concurrent_workflow_task_polls` * this number = the number of
     #   max pollers that will be allowed for the nonsticky queue when sticky tasks are enabled. If both defaults are
     #   used, the sticky queue will allow 4 max pollers while the nonsticky queue will allow one. The minimum for either
     #   poller is 1, so if `max_concurrent_workflow_task_polls` is 1 and sticky queues are enabled, there will be 2
@@ -239,12 +330,38 @@ module Temporalio
     # @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 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
+    #   `workflow_failure_exception_type` on the workflow definition class itself. If {::Exception} is set, it
+    #   effectively will fail a workflow/update in all user exception cases.
+    # @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 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`.
     def initialize(
       client:,
       task_queue:,
       activities: [],
-      activity_executors: ActivityExecutor.defaults,
+      workflows: [],
       tuner: Tuner.create_fixed,
+      activity_executors: ActivityExecutor.defaults,
+      workflow_executor: WorkflowExecutor::ThreadPool.default,
       interceptors: [],
       build_id: Worker.default_build_id,
       identity: nil,
@@ -260,17 +377,26 @@ module Temporalio
       max_activities_per_second: nil,
       max_task_queue_activities_per_second: nil,
       graceful_shutdown_period: 0,
-      use_worker_versioning: false
+      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,
+      debug_mode: %w[true 1].include?(ENV['TEMPORAL_DEBUG'].to_s.downcase)
     )
-      # TODO(cretz): Remove when workflows come about
-      raise ArgumentError, 'Must have at least one activity' if activities.empty?
+      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:,
         activities:,
-        activity_executors:,
+        workflows:,
         tuner:,
+        activity_executors:,
+        workflow_executor:,
         interceptors:,
         build_id:,
         identity:,
@@ -286,51 +412,93 @@ module Temporalio
         max_activities_per_second:,
         max_task_queue_activities_per_second:,
         graceful_shutdown_period:,
-        use_worker_versioning:
+        use_worker_versioning:,
+        disable_eager_activity_execution:,
+        illegal_workflow_calls:,
+        workflow_failure_exception_types:,
+        workflow_payload_codec_thread_pool:,
+        unsafe_workflow_io_enabled:,
+        debug_mode:
       ).freeze
 
+      # Preload workflow definitions and some workflow settings for the bridge
+      workflow_definitions = Internal::Worker::WorkflowWorker.workflow_definitions(workflows)
+      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(
         client.connection._core_client,
         Internal::Bridge::Worker::Options.new(
           activity: !activities.empty?,
-          workflow: false,
+          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)
-          ),
+          tuner: tuner._to_bridge_options,
           build_id:,
           identity_override: identity,
           max_cached_workflows:,
           max_concurrent_workflow_task_polls:,
           nonsticky_to_sticky_poll_ratio:,
           max_concurrent_activity_task_polls:,
-          no_remote_activities:,
+          # For shutdown to work properly, we must disable remote activities
+          # ourselves if there are no activities
+          no_remote_activities: no_remote_activities || activities.empty?,
           sticky_queue_schedule_to_start_timeout:,
           max_heartbeat_throttle_interval:,
           default_heartbeat_throttle_interval:,
           max_worker_activities_per_second: max_activities_per_second,
           max_task_queue_activities_per_second:,
           graceful_shutdown_period:,
-          use_worker_versioning:
+          use_worker_versioning:,
+          nondeterminism_as_workflow_fail:,
+          nondeterminism_as_workflow_fail_for_types:
         )
       )
 
       # Collect interceptors from client and params
-      @all_interceptors = client.options.interceptors.select { |i| i.is_a?(Interceptor) } + interceptors
+      @activity_interceptors = (client.options.interceptors + interceptors).select do |i|
+        i.is_a?(Interceptor::Activity)
+      end
+      @workflow_interceptors = (client.options.interceptors + interceptors).select do |i|
+        i.is_a?(Interceptor::Workflow)
+      end
 
       # Cancellation for the whole worker
       @worker_shutdown_cancellation = Cancellation.new
 
       # Create workers
-      # TODO(cretz): Make conditional when workflows appear
-      @activity_worker = Internal::Worker::ActivityWorker.new(self, @bridge_worker)
+      unless activities.empty?
+        @activity_worker = Internal::Worker::ActivityWorker.new(worker: self,
+                                                                bridge_worker: @bridge_worker)
+      end
+      unless workflows.empty?
+        @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:
+        )
+      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.
@@ -338,6 +506,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.
     #
@@ -387,40 +574,30 @@ module Temporalio
     end
 
     # @!visibility private
-    def _all_interceptors
-      @all_interceptors
+    def _activity_interceptors
+      @activity_interceptors
     end
 
     # @!visibility private
-    def _on_poll_bytes(worker_type, bytes)
-      # TODO(cretz): Workflow workers
-      raise "Unrecognized worker type #{worker_type}" unless worker_type == :activity
-
-      @activity_worker.handle_task(Internal::Bridge::Api::ActivityTask::ActivityTask.decode(bytes))
-    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
-          )
+    def _on_poll_bytes(runner, worker_type, bytes)
+      case worker_type
+      when :activity
+        @activity_worker.handle_task(Internal::Bridge::Api::ActivityTask::ActivityTask.decode(bytes))
+      when :workflow
+        @workflow_worker.handle_activation(
+          runner:,
+          activation: Internal::Bridge::Api::WorkflowActivation::WorkflowActivation.decode(bytes),
+          decoded: false
         )
       else
-        raise ArgumentError, 'Tuner slot suppliers must be instances of Fixed or ResourceBased'
+        raise "Unrecognized worker type #{worker_type}"
       end
     end
+
+    # @!visibility private
+    def _on_shutdown_complete
+      @workflow_worker&.on_shutdown_complete
+      @workflow_worker = nil
+    end
   end
 end

data/lib/temporalio/workflow/activity_cancellation_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/bridge/api'
+
+module Temporalio
+  module Workflow
+    # Cancellation types for activities.
+    module ActivityCancellationType
+      # Initiate a cancellation request and immediately report cancellation to the workflow.
+      TRY_CANCEL = Internal::Bridge::Api::WorkflowCommands::ActivityCancellationType::TRY_CANCEL
+      # Wait for activity cancellation completion. Note that activity must heartbeat to receive a cancellation
+      # notification. This can block the cancellation for a long time if activity doesn't heartbeat or chooses to ignore
+      # the cancellation request.
+      WAIT_CANCELLATION_COMPLETED =
+        Internal::Bridge::Api::WorkflowCommands::ActivityCancellationType::WAIT_CANCELLATION_COMPLETED
+      # Do not request cancellation of the activity and immediately report cancellation to the workflow.
+      ABANDON = Internal::Bridge::Api::WorkflowCommands::ActivityCancellationType::ABANDON
+    end
+  end
+end

data/lib/temporalio/workflow/child_workflow_cancellation_type.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/bridge/api'
+
+module Temporalio
+  module Workflow
+    # Cancellation types for child workflows.
+    module ChildWorkflowCancellationType
+      # Do not request cancellation of the child workflow if already scheduled.
+      ABANDON = Internal::Bridge::Api::ChildWorkflow::ChildWorkflowCancellationType::ABANDON
+      # Initiate a cancellation request and immediately report cancellation to the parent.
+      TRY_CANCEL = Internal::Bridge::Api::ChildWorkflow::ChildWorkflowCancellationType::TRY_CANCEL
+      # Wait for child cancellation completion.
+      WAIT_CANCELLATION_COMPLETED =
+        Internal::Bridge::Api::ChildWorkflow::ChildWorkflowCancellationType::WAIT_CANCELLATION_COMPLETED
+      # Request cancellation of the child and wait for confirmation that the request was received.
+      WAIT_CANCELLATION_REQUESTED =
+        Internal::Bridge::Api::ChildWorkflow::ChildWorkflowCancellationType::WAIT_CANCELLATION_REQUESTED
+    end
+  end
+end

data/lib/temporalio/workflow/child_workflow_handle.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Temporalio
+  module Workflow
+    # Handle for interacting with a child workflow.
+    #
+    # This is created via {Workflow.start_child_workflow}, it is never instantiated directly.
+    class ChildWorkflowHandle
+      # @!visibility private
+      def initialize
+        raise NotImplementedError, 'Cannot instantiate a child handle directly'
+      end
+
+      # @return [String] ID for the workflow.
+      def id
+        raise NotImplementedError
+      end
+
+      # @return [String] Run ID for the workflow.
+      def first_execution_run_id
+        raise NotImplementedError
+      end
+
+      # Wait for the result.
+      #
+      # @return [Object] Result of the child workflow.
+      #
+      # @raise [Error::ChildWorkflowError] Workflow failed with +cause+ as the cause.
+      def result
+        raise NotImplementedError
+      end
+
+      # Signal the child workflow.
+      #
+      # @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)
+        raise NotImplementedError
+      end
+    end
+  end
+end