temporalio 1.1.0-aarch64-linux → 1.3.0-aarch64-linux

data/lib/temporalio/simple_plugin.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require 'temporalio/worker'
+
+module Temporalio
+  # Plugin that implements both {Client::Plugin} and {Worker::Plugin} and provides a simplified common set of settings
+  # for configuring both.
+  #
+  # WARNING: Plugins are experimental.
+  class SimplePlugin
+    include Client::Plugin
+    include Worker::Plugin
+
+    Options = Data.define(
+      :name,
+      :data_converter,
+      :client_interceptors,
+      :activities,
+      :workflows,
+      :worker_interceptors,
+      :workflow_failure_exception_types,
+      :run_context
+    )
+
+    # Options as returned from {options} representing the options passed to the constructor.
+    class Options; end # rubocop:disable Lint/EmptyClass
+
+    # @return [Options] Frozen options for this plugin which has the same attributes as {initialize}.
+    attr_reader :options
+
+    # Create a simple plugin.
+    #
+    # @param name [String] Required string name for this plugin.
+    # @param data_converter [Converters::DataConverter, Proc, nil] Data converter to apply to clients and workflow
+    #   replayers. This can be a proc that accepts the existing data converter and returns a new one.
+    # @param client_interceptors [Array<Client::Integerceptor>, Proc, nil] Client interceptors that are appended to the
+    #   existing client set (which means if they implement worker interceptors they are applied for the workers too). A
+    #   proc can be provided that accepts the existing array and returns a new one.
+    # @param activities [Array<Activity::Definition, Class<Activity::Definition>, Activity::Definition::Info>, Proc,
+    #   nil] Activities to append to each worker activity set. A proc can be provided that accepts the existing array
+    #   and returns a new one.
+    # @param workflows [Array<Class<Workflow::Definition>>, Proc, nil] Workflows to append to each worker workflow set.
+    #   A proc can be provided that accepts the existing array and returns a new one.
+    # @param worker_interceptors [Array<Interceptor::Activity, Interceptor::Workflow>, Proc, nil] Worker interceptors
+    #   that are appended to the existing worker or workflow replayer set. A proc can be provided that accepts the
+    #   existing array and returns a new one.
+    # @param workflow_failure_exception_types [Array<Class<Exception>>] Workflow failure exception types that are
+    #   appended to the existing worker or workflow replayer set. A proc can be provided that accepts the existing array
+    #   and returns a new one.
+    # @param run_context [Proc, nil] A proc that intercepts both {run_worker} or {with_workflow_replay_worker}. The proc
+    #   should accept two positional parameters: options and next_call. The options are either
+    #   {Worker::Plugin::RunWorkerOptions} or {Worker::Plugin::WithWorkflowReplayWorkerOptions}. The next_call is a proc
+    #   itself that accepts the options and returns a value. This run_context proc should return the result of the
+    #   next_call.
+    def initialize(
+      name:,
+      data_converter: nil,
+      client_interceptors: nil,
+      activities: nil,
+      workflows: nil,
+      worker_interceptors: nil,
+      workflow_failure_exception_types: nil,
+      run_context: nil
+    )
+      @options = Options.new(
+        name:,
+        data_converter:,
+        client_interceptors:,
+        activities:,
+        workflows:,
+        worker_interceptors:,
+        workflow_failure_exception_types:,
+        run_context:
+      ).freeze
+    end
+
+    # Implements {Client::Plugin#name} and {Worker::Plugin#name}.
+    def name
+      @options.name
+    end
+
+    # Implements {Client::Plugin#configure_client}.
+    def configure_client(options)
+      if (data_converter = _single_option(new: @options.data_converter, existing: options.data_converter,
+                                          type: Converters::DataConverter, name: 'data converter'))
+        options = options.with(data_converter:)
+      end
+      if (interceptors = _array_option(new: @options.client_interceptors, existing: options.interceptors,
+                                       name: 'client interceptor'))
+        options = options.with(interceptors:)
+      end
+      options
+    end
+
+    # Implements {Client::Plugin#connect_client}.
+    def connect_client(options, next_call)
+      next_call.call(options)
+    end
+
+    # Implements {Worker::Plugin#configure_worker}.
+    def configure_worker(options)
+      if (activities = _array_option(new: @options.activities, existing: options.activities, name: 'activity'))
+        options = options.with(activities:)
+      end
+      if (workflows = _array_option(new: @options.workflows, existing: options.workflows, name: 'workflow'))
+        options = options.with(workflows:)
+      end
+      if (interceptors = _array_option(new: @options.worker_interceptors, existing: options.interceptors,
+                                       name: 'worker interceptor'))
+        options = options.with(interceptors:)
+      end
+      if (workflow_failure_exception_types = _array_option(new: @options.workflow_failure_exception_types,
+                                                           existing: options.workflow_failure_exception_types,
+                                                           name: 'workflow failure exception types'))
+        options = options.with(workflow_failure_exception_types:)
+      end
+      options
+    end
+
+    # Implements {Worker::Plugin#run_worker}.
+    def run_worker(options, next_call)
+      if @options.run_context
+        @options.run_context.call(options, next_call) # steep:ignore NoMethod
+      else
+        next_call.call(options)
+      end
+    end
+
+    # Implements {Worker::Plugin#configure_workflow_replayer}.
+    def configure_workflow_replayer(options)
+      if (data_converter = _single_option(new: @options.data_converter, existing: options.data_converter,
+                                          type: Converters::DataConverter, name: 'data converter'))
+        options = options.with(data_converter:)
+      end
+      if (workflows = _array_option(new: @options.workflows, existing: options.workflows, name: 'workflow'))
+        options = options.with(workflows:)
+      end
+      if (interceptors = _array_option(new: @options.worker_interceptors, existing: options.interceptors,
+                                       name: 'worker interceptor'))
+        options = options.with(interceptors:)
+      end
+      if (workflow_failure_exception_types = _array_option(new: @options.workflow_failure_exception_types,
+                                                           existing: options.workflow_failure_exception_types,
+                                                           name: 'workflow failure exception types'))
+        options = options.with(workflow_failure_exception_types:)
+      end
+      options
+    end
+
+    # Implements {Worker::Plugin#with_workflow_replay_worker}.
+    def with_workflow_replay_worker(options, next_call)
+      if @options.run_context
+        @options.run_context.call(options, next_call) # steep:ignore NoMethod
+      else
+        next_call.call(options)
+      end
+    end
+
+    # @!visibility private
+    def _single_option(new:, existing:, type:, name:)
+      case new
+      when nil
+        nil
+      when Proc
+        new.call(existing).tap do |val| # steep:ignore NoMethod
+          raise "Instance of #{name} required" unless val.is_a?(type)
+        end
+      when type
+        new
+      else
+        raise "Unrecognized #{name} type #{new.class}"
+      end
+    end
+
+    # @!visibility private
+    def _array_option(new:, existing:, name:)
+      case new
+      when nil
+        nil
+      when Proc
+        new.call(existing).tap do |conv| # steep:ignore NoMethod
+          raise "Array for #{name} required" unless conv.is_a?(Array)
+        end
+      when Array
+        existing + new # steep:ignore NoMethod
+      else
+        raise "Unrecognized #{name} type #{new.class}"
+      end
+    end
+  end
+end

data/lib/temporalio/testing/workflow_environment.rb

@@ -2,6 +2,7 @@
 
 require 'delegate'
 require 'temporalio/api'
+require 'temporalio/api/operatorservice/v1/request_response'
 require 'temporalio/api/testservice/v1/request_response'
 require 'temporalio/client'
 require 'temporalio/client/connection/test_service'
@@ -264,6 +265,45 @@ module Temporalio
         Time.now
       end
 
+      # Create Nexus endpoint on this test environment.
+      #
+      # WARNING: Nexus support is experimental.
+      #
+      # @param name [String] Endpoint name.
+      # @param task_queue [String] Task queue for the endpoint.
+      # @return [Temporalio::Api::Nexus::V1::Endpoint] Created endpoint.
+      def create_nexus_endpoint(name:, task_queue:)
+        resp = client.connection.operator_service.create_nexus_endpoint(
+          Temporalio::Api::OperatorService::V1::CreateNexusEndpointRequest.new(
+            spec: Temporalio::Api::Nexus::V1::EndpointSpec.new(
+              name:,
+              target: Temporalio::Api::Nexus::V1::EndpointTarget.new(
+                worker: Temporalio::Api::Nexus::V1::EndpointTarget::Worker.new(
+                  namespace: client.namespace,
+                  task_queue:
+                )
+              )
+            )
+          )
+        )
+        resp.endpoint
+      end
+
+      # Delete Nexus endpoint on this test environment.
+      #
+      # WARNING: Nexus support is experimental.
+      #
+      # @param endpoint [Temporalio::Api::Nexus::V1::Endpoint] Endpoint to delete.
+      def delete_nexus_endpoint(endpoint)
+        client.connection.operator_service.delete_nexus_endpoint(
+          Temporalio::Api::OperatorService::V1::DeleteNexusEndpointRequest.new(
+            id: endpoint.id,
+            version: endpoint.version
+          )
+        )
+        nil
+      end
+
       # Run a block with automatic time skipping disabled. This just runs the block for environments that don't support
       # time skipping.
       #

data/lib/temporalio/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Temporalio
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
 end

data/lib/temporalio/versioning_override.rb

@@ -5,8 +5,6 @@ require 'temporalio/worker_deployment_version'
 module Temporalio
   # Base class for version overrides that can be provided in start workflow options.
   # Used to control the versioning behavior of workflows started with this override.
-  #
-  # WARNING: Experimental API.
   class VersioningOverride
     # @!visibility private
     def _to_proto

data/lib/temporalio/worker/deployment_options.rb

@@ -13,8 +13,6 @@ module Temporalio
 
     # Options for configuring the Worker Versioning feature.
     #
-    # WARNING: Deployment-based versioning is experimental and APIs may change.
-    #
     # @!attribute version
     #   @return [WorkerDeploymentVersion] The worker deployment version.
     # @!attribute use_worker_versioning

data/lib/temporalio/worker/interceptor.rb

@@ -300,6 +300,23 @@ module Temporalio
           :headers
         )
 
+        # Input for {Outbound.start_nexus_operation}.
+        #
+        # WARNING: Nexus support is experimental.
+        StartNexusOperationInput = Data.define(
+          :endpoint,
+          :service,
+          :operation,
+          :arg,
+          :schedule_to_close_timeout,
+          :cancellation_type,
+          :summary,
+          :cancellation,
+          :arg_hint,
+          :result_hint,
+          :headers
+        )
+
         # Outbound interceptor for intercepting outbound workflow calls. This should be extended by users needing to
         # intercept workflow calls.
         class Outbound
@@ -371,6 +388,16 @@ module Temporalio
           def start_child_workflow(input)
             @next_interceptor.start_child_workflow(input)
           end
+
+          # Start Nexus operation.
+          #
+          # WARNING: Nexus support is experimental.
+          #
+          # @param input [StartNexusOperationInput] Input.
+          # @return [Workflow::NexusOperationHandle] Nexus operation handle.
+          def start_nexus_operation(input)
+            @next_interceptor.start_nexus_operation(input)
+          end
         end
       end
     end

data/lib/temporalio/worker/plugin.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Worker
+    # Plugin mixin to include for configuring workers and workflow replayers, and intercepting the running of them.
+    #
+    # This is a low-level implementation that requires abstract methods herein to be implemented. Many implementers may
+    # prefer {SimplePlugin} which includes this.
+    #
+    # WARNING: Plugins are experimental.
+    module Plugin
+      RunWorkerOptions = Data.define(
+        :worker,
+        :cancellation,
+        :shutdown_signals,
+        :raise_in_block_on_shutdown
+      )
+
+      # Options for {run_worker}.
+      #
+      # The options contain the worker and some other options from {Worker#run}/{Worker.run_all}. Unlike other memebers
+      # in this class, mutating the worker member before invoking the next call in the chain has no effect.
+      #
+      # @note Additional required attributes of this class may be added in the future. Users should never instantiate
+      #   this class, but instead use `with` on it in {run_worker}.
+      class RunWorkerOptions; end # rubocop:disable Lint/EmptyClass
+
+      WithWorkflowReplayWorkerOptions = Data.define(
+        :worker
+      )
+
+      # Options for {with_workflow_replay_worker}.
+      #
+      # @note Additional required attributes of this class may be added in the future. Users should never instantiate
+      #   this class, but instead use `with` on it in {with_workflow_replay_worker}.
+      #
+      # @!attribute worker
+      #   @return [WorkflowReplayer::ReplayWorker] Replay worker.
+      class WithWorkflowReplayWorkerOptions; end # rubocop:disable Lint/EmptyClass
+
+      # @abstract
+      # @return [String] Name of the plugin.
+      def name
+        raise NotImplementedError
+      end
+
+      # Configure a worker.
+      #
+      # @abstract
+      # @param options [Options] Current immutable options set.
+      # @return [Options] Options to use, possibly updated from original.
+      def configure_worker(options)
+        raise NotImplementedError
+      end
+
+      # Run a worker.
+      #
+      # @abstract
+      # @param options [RunWorkerOptions] Current immutable options set.
+      # @param next_call [Proc] Proc for the next plugin in the chain to call. It accepts the options and returns an
+      #   arbitrary object that should also be returned from this method.
+      # @return [Object] Result of next_call.
+      def run_worker(options, next_call)
+        raise NotImplementedError
+      end
+
+      # Configure a workflow replayer.
+      #
+      # @abstract
+      # @param options [WorkflowReplayer::Options] Current immutable options set.
+      # @return [WorkflowReplayer::Options] Options to use, possibly updated from original.
+      def configure_workflow_replayer(options)
+        raise NotImplementedError
+      end
+
+      # Run a replay worker.
+      #
+      # @abstract
+      # @param options [WithWorkflowReplayWorkerOptions] Current immutable options set.
+      # @param next_call [Proc] Proc for the next plugin in the chain to call. It accepts the options and returns an
+      #   arbitrary object that should also be returned from this method.
+      # @return [Object] Result of next_call.
+      def with_workflow_replay_worker(options, next_call)
+        raise NotImplementedError
+      end
+    end
+  end
+end

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

@@ -49,7 +49,7 @@ module Temporalio
               # If not found, get a new one either by creating if not enough or find the one with the fewest.
               new_worker = if @workers.size < @max_threads
                              created_worker = Worker.new(self)
-                             @workers << Worker.new(self)
+                             @workers << created_worker
                              created_worker
                            else
                              @workers.min_by(&:workflow_count)

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/plugin'
 require 'temporalio/worker/poller_behavior'
 require 'temporalio/worker/thread_pool'
 require 'temporalio/worker/tuner'
@@ -24,6 +25,7 @@ module Temporalio
         :task_queue,
         :data_converter,
         :workflow_executor,
+        :plugins,
         :interceptors,
         :identity,
         :logger,
@@ -50,6 +52,8 @@ module Temporalio
       #   payloads.
       # @param workflow_executor [WorkflowExecutor] Workflow executor that workflow tasks run within. This must be a
       #   {WorkflowExecutor::ThreadPool} currently.
+      # @param plugins [Array<Plugin>] Plugins to use for configuring replayer and intercepting replay. WARNING: Plugins
+      #   are experimental.
       # @param interceptors [Array<Interceptor::Workflow>] Workflow interceptors.
       # @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
@@ -83,6 +87,7 @@ module Temporalio
         task_queue: 'ReplayTaskQueue',
         data_converter: Converters::DataConverter.default,
         workflow_executor: WorkflowExecutor::ThreadPool.default,
+        plugins: [],
         interceptors: [],
         identity: nil,
         logger: Logger.new($stdout, level: Logger::WARN),
@@ -100,6 +105,7 @@ module Temporalio
           task_queue:,
           data_converter:,
           workflow_executor:,
+          plugins:,
           interceptors:,
           identity:,
           logger:,
@@ -110,13 +116,18 @@ module Temporalio
           debug_mode:,
           runtime:
         ).freeze
+        # Apply plugins
+        Worker._validate_plugins!(plugins)
+        @options = plugins.reduce(@options) { |options, plugin| plugin.configure_workflow_replayer(options) }
+
         # Preload definitions and other settings
         @workflow_definitions = Internal::Worker::WorkflowWorker.workflow_definitions(
-          workflows, should_enforce_versioning_behavior: false
+          @options.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
+            workflow_failure_exception_types: @options.workflow_failure_exception_types,
+            workflow_definitions: @workflow_definitions
           )
         # If there is a block, we'll go ahead and assume it's for with_replay_worker
         with_replay_worker(&) if block_given? # steep:ignore
@@ -154,7 +165,18 @@ module Temporalio
       # @yield Block of code to run with a replay worker.
       # @yieldparam [ReplayWorker] Worker to run replays on. Note, only one workflow can replay at a time.
       # @yieldreturn [Object] Result of the block.
-      def with_replay_worker(&)
+      def with_replay_worker(&block)
+        # Apply plugins
+        run_block = proc do |options|
+          # @type var options: Plugin::WithWorkflowReplayWorkerOptions
+          block.call(options.worker)
+        end
+        run_block = options.plugins.reverse_each.reduce(run_block) do |next_call, plugin|
+          proc do |options|
+            plugin.with_workflow_replay_worker(options, next_call) # steep:ignore
+          end
+        end
+
         worker = ReplayWorker.new(
           options:,
           workflow_definitions: @workflow_definitions,
@@ -162,7 +184,7 @@ module Temporalio
           nondeterminism_as_workflow_fail_for_types: @nondeterminism_as_workflow_fail_for_types
         )
         begin
-          yield worker
+          run_block.call(Plugin::WithWorkflowReplayWorkerOptions.new(worker:))
         ensure
           worker._shutdown
         end
@@ -221,7 +243,8 @@ module Temporalio
               graceful_shutdown_period: 0.0,
               nondeterminism_as_workflow_fail:,
               nondeterminism_as_workflow_fail_for_types:,
-              deployment_options: Worker.default_deployment_options._to_bridge_options
+              deployment_options: Worker.default_deployment_options._to_bridge_options,
+              plugins: options.plugins.map(&:name).uniq.sort
             )
           )