temporalio 0.2.0-x86_64-darwin

data/lib/temporalio/testing/activity_environment.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+require 'temporalio/cancellation'
+require 'temporalio/converters/payload_converter'
+require 'temporalio/worker/activity_executor'
+
+module Temporalio
+  module Testing
+    # Test environment for testing activities.
+    #
+    # Users can create this environment and then use {run} to execute activities on it. Often, since mutable things like
+    # cancellation can be set, users create this for each activity that is run. There is no real performance penalty for
+    # creating an environment for every run.
+    class ActivityEnvironment
+      # @return [Activity::Info] The activity info used by default. This is frozen, but can be dup'd and mutated to pass
+      #   in to {initialize}.
+      def self.default_info
+        @default_info ||= Activity::Info.new(
+          activity_id: 'test',
+          activity_type: 'unknown',
+          attempt: 1,
+          current_attempt_scheduled_time: Time.at(0),
+          heartbeat_details: [],
+          heartbeat_timeout: nil,
+          local?: false,
+          schedule_to_close_timeout: 1.0,
+          scheduled_time: Time.at(0),
+          start_to_close_timeout: 1.0,
+          started_time: Time.at(0),
+          task_queue: 'test',
+          task_token: String.new('test', encoding: Encoding::ASCII_8BIT),
+          workflow_id: 'test',
+          workflow_namespace: 'default',
+          workflow_run_id: 'test-run',
+          workflow_type: 'test'
+        ).freeze
+      end
+
+      # Create a test environment for activities.
+      #
+      # @param info [Activity::Info] Value for {Activity::Context#info}.
+      # @param on_heartbeat [Proc(Array), nil] Proc that is called with all heartbeat details when
+      #   {Activity::Context#heartbeat} is called.
+      # @param cancellation [Cancellation] Value for {Activity::Context#cancellation}.
+      # @param worker_shutdown_cancellation [Cancellation] Value for {Activity::Context#worker_shutdown_cancellation}.
+      # @param payload_converter [Converters::PayloadConverter] Value for {Activity::Context#payload_converter}.
+      # @param logger [Logger] Value for {Activity::Context#logger}.
+      # @param activity_executors [Hash<Symbol, Worker::ActivityExecutor>] Executors that activities can run within.
+      def initialize(
+        info: ActivityEnvironment.default_info,
+        on_heartbeat: nil,
+        cancellation: Cancellation.new,
+        worker_shutdown_cancellation: Cancellation.new,
+        payload_converter: Converters::PayloadConverter.default,
+        logger: Logger.new(nil),
+        activity_executors: Worker::ActivityExecutor.defaults
+      )
+        @info = info
+        @on_heartbeat = on_heartbeat
+        @cancellation = cancellation
+        @worker_shutdown_cancellation = worker_shutdown_cancellation
+        @payload_converter = payload_converter
+        @logger = logger
+        @activity_executors = activity_executors
+      end
+
+      # Run an activity and returns its result or raises its exception.
+      #
+      # @param activity [Activity, Class<Activity>, Activity::Definition] Activity to run.
+      # @param args [Array<Object>] Arguments to the activity.
+      # @return Activity result.
+      def run(activity, *args)
+        defn = Activity::Definition.from_activity(activity)
+        executor = @activity_executors[defn.executor]
+        raise ArgumentError, "Unknown executor: #{defn.executor}" if executor.nil?
+
+        queue = Queue.new
+        executor.execute_activity(defn) do
+          Activity::Context._current_executor = executor
+          executor.set_activity_context(defn, Context.new(
+                                                info: @info.dup,
+                                                on_heartbeat: @on_heartbeat,
+                                                cancellation: @cancellation,
+                                                worker_shutdown_cancellation: @worker_shutdown_cancellation,
+                                                payload_converter: @payload_converter,
+                                                logger: @logger
+                                              ))
+          queue.push([defn.proc.call(*args), nil])
+        rescue Exception => e # rubocop:disable Lint/RescueException Intentionally capturing all exceptions
+          queue.push([nil, e])
+        ensure
+          executor.set_activity_context(defn, nil)
+          Activity::Context._current_executor = nil
+        end
+
+        result, err = queue.pop
+        raise err unless err.nil?
+
+        result
+      end
+
+      # @!visibility private
+      class Context < Activity::Context
+        attr_reader :info, :cancellation, :worker_shutdown_cancellation, :payload_converter, :logger
+
+        def initialize( # rubocop:disable Lint/MissingSuper
+          info: ActivityEnvironment.default_info,
+          on_heartbeat: nil,
+          cancellation: Cancellation.new,
+          worker_shutdown_cancellation: Cancellation.new,
+          payload_converter: Converters::PayloadConverter.default,
+          logger: Logger.new(nil)
+        )
+          @info = info
+          @on_heartbeat = on_heartbeat
+          @cancellation = cancellation
+          @worker_shutdown_cancellation = worker_shutdown_cancellation
+          @payload_converter = payload_converter
+          @logger = logger
+        end
+
+        # @!visibility private
+        def heartbeat(*details)
+          @on_heartbeat&.call(details)
+        end
+      end
+
+      private_constant :Context
+    end
+  end
+end

data/lib/temporalio/testing/workflow_environment.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'temporalio/client'
+require 'temporalio/converters'
+require 'temporalio/internal/bridge/testing'
+require 'temporalio/runtime'
+require 'temporalio/version'
+
+module Temporalio
+  module Testing
+    # Test environment with a Temporal server for running workflows and more.
+    class WorkflowEnvironment
+      # @return [Client] Client for the server.
+      attr_reader :client
+
+      # Start a local dev server. This is a full Temporal dev server from the CLI that by default downloaded to tmp if
+      # not already present. The dev server is run as a child process. All options that start with +dev_server_+ are for
+      # this specific implementation and therefore are not stable and may be changed as the underlying implementation
+      # changes.
+      #
+      # If a block is given it is passed the environment and the environment is shut down after. If a block is not
+      # given, the environment is returned and {shutdown} needs to be called manually.
+      #
+      # @param namespace [String] Namespace for the server.
+      # @param data_converter [Converters::DataConverter] Data converter for the client.
+      # @param interceptors [Array<Client::Interceptor>] Interceptors for the client.
+      # @param logger [Logger] Logger for the client.
+      # @param default_workflow_query_reject_condition [WorkflowQueryRejectCondition, nil] Default rejection condition
+      #   for the client.
+      # @param ip [String] IP to bind to.
+      # @param port [Integer, nil] Port to bind on, or +nil+ for random.
+      # @param ui [Boolean] If +true+, also starts the UI.
+      # @param runtime [Runtime] Runtime for the server and client.
+      # @param dev_server_existing_path [String, nil] Existing CLI path to use instead of downloading and caching to
+      #   tmp.
+      # @param dev_server_database_filename [String, nil] Persistent SQLite filename to use across local server runs.
+      #   Default of +nil+ means in-memory only.
+      # @param dev_server_log_format [String] Log format for CLI dev server.
+      # @param dev_server_log_level [String] Log level for CLI dev server.
+      # @param dev_server_download_version [String] Version of dev server to download and cache.
+      # @param dev_server_download_dest_dir [String, nil] Where to download. Defaults to tmp.
+      # @param dev_server_extra_args [Array<String>] Any extra arguments for the CLI dev server.
+      #
+      # @yield [environment] If a block is given, it is called with the environment and upon complete the environment is
+      #   shutdown.
+      # @yieldparam environment [WorkflowEnvironment] Environment that is shut down upon block completion.
+      #
+      # @return [WorkflowEnvironment, Object] Started local server environment with client if there was no block given,
+      #   or block result if block was given.
+      def self.start_local(
+        namespace: 'default',
+        data_converter: Converters::DataConverter.default,
+        interceptors: [],
+        logger: Logger.new($stdout, level: Logger::WARN),
+        default_workflow_query_reject_condition: nil,
+        ip: '127.0.0.1',
+        port: nil,
+        ui: false, # rubocop:disable Naming/MethodParameterName
+        runtime: Runtime.default,
+        dev_server_existing_path: nil,
+        dev_server_database_filename: nil,
+        dev_server_log_format: 'pretty',
+        dev_server_log_level: 'warn',
+        dev_server_download_version: 'default',
+        dev_server_download_dest_dir: nil,
+        dev_server_extra_args: []
+      )
+        server_options = Internal::Bridge::Testing::EphemeralServer::StartDevServerOptions.new(
+          existing_path: dev_server_existing_path,
+          sdk_name: 'sdk-ruby',
+          sdk_version: VERSION,
+          download_version: dev_server_download_version,
+          download_dest_dir: dev_server_download_dest_dir,
+          namespace:,
+          ip:,
+          port:,
+          database_filename: dev_server_database_filename,
+          ui:,
+          log_format: dev_server_log_format,
+          log_level: dev_server_log_level,
+          extra_args: dev_server_extra_args
+        )
+        core_server = Internal::Bridge::Testing::EphemeralServer.start_dev_server(runtime._core_runtime, server_options)
+        # Try to connect, shutdown if we can't
+        begin
+          client = Client.connect(
+            core_server.target,
+            namespace,
+            data_converter:,
+            interceptors:,
+            logger:,
+            default_workflow_query_reject_condition:,
+            runtime:
+          )
+          server = Ephemeral.new(client, core_server)
+        rescue StandardError
+          core_server.shutdown
+          raise
+        end
+        if block_given?
+          begin
+            yield server
+          ensure
+            server.shutdown
+          end
+        else
+          server
+        end
+      end
+
+      # Create workflow environment to an existing server with the given client.
+      #
+      # @param client [Client] Client to existing server.
+      def initialize(client)
+        @client = client
+      end
+
+      # Shutdown this workflow environment.
+      def shutdown
+        # Do nothing by default
+      end
+
+      # @!visibility private
+      class Ephemeral < WorkflowEnvironment
+        def initialize(client, core_server)
+          super(client)
+          @core_server = core_server
+        end
+
+        # @!visibility private
+        def shutdown
+          @core_server.shutdown
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/testing.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'temporalio/testing/activity_environment'
+require 'temporalio/testing/workflow_environment'
+
+module Temporalio
+  # Module for all testing environments.
+  module Testing
+  end
+end

data/lib/temporalio/version.rb

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

data/lib/temporalio/worker/activity_executor/fiber.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'temporalio/error'
+require 'temporalio/worker/activity_executor'
+
+module Temporalio
+  class Worker
+    class ActivityExecutor
+      # Activity executor for scheduling activites as fibers.
+      class Fiber
+        # @return [Fiber] Default/shared Fiber executor instance.
+        def self.default
+          @default ||= new
+        end
+
+        # @see ActivityExecutor.initialize_activity
+        def initialize_activity(defn)
+          # If there is not a current scheduler, we're going to preemptively
+          # fail the registration
+          return unless ::Fiber.current_scheduler.nil?
+
+          raise ArgumentError, "Activity '#{defn.name}' wants a fiber executor but no current fiber scheduler"
+        end
+
+        # @see ActivityExecutor.initialize_activity
+        def execute_activity(_defn, &)
+          ::Fiber.schedule(&)
+        end
+
+        # @see ActivityExecutor.activity_context
+        def activity_context
+          ::Fiber[:temporal_activity_context]
+        end
+
+        # @see ActivityExecutor.set_activity_context
+        def set_activity_context(defn, context)
+          ::Fiber[:temporal_activity_context] = context
+          # If they have opted in to raising on cancel, wire that up
+          return unless defn.cancel_raise
+
+          fiber = ::Fiber.current
+          context&.cancellation&.add_cancel_callback do
+            fiber.raise(Error::CanceledError.new('Activity canceled'))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+# Much of this logic taken from
+# https://github.com/ruby-concurrency/concurrent-ruby/blob/044020f44b36930b863b930f3ee8fa1e9f750469/lib/concurrent-ruby/concurrent/executor/ruby_thread_pool_executor.rb,
+# see MIT license at
+# https://github.com/ruby-concurrency/concurrent-ruby/blob/044020f44b36930b863b930f3ee8fa1e9f750469/LICENSE.txt
+
+module Temporalio
+  class Worker
+    class ActivityExecutor
+      # Activity executor for scheduling activities in their own thread. This implementation is a stripped down form of
+      # Concurrent Ruby's `CachedThreadPool`.
+      class ThreadPool < ActivityExecutor
+        # @return [ThreadPool] Default/shared thread pool executor instance with unlimited max threads.
+        def self.default
+          @default ||= new
+        end
+
+        # @!visibility private
+        def self._monotonic_time
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+
+        # Create a new thread pool executor that creates threads as needed.
+        #
+        # @param max_threads [Integer, nil] Maximum number of thread workers to create, or nil for unlimited max.
+        # @param idle_timeout [Float] Number of seconds before a thread worker with no work should be stopped. Note,
+        #   the check of whether a thread worker is idle is only done on each new activity.
+        def initialize(max_threads: nil, idle_timeout: 20) # rubocop:disable Lint/MissingSuper
+          @max_threads = max_threads
+          @idle_timeout = idle_timeout
+
+          @mutex = Mutex.new
+          @pool = []
+          @ready = []
+          @queue = []
+          @scheduled_task_count = 0
+          @completed_task_count = 0
+          @largest_length       = 0
+          @workers_counter = 0
+          @prune_interval = @idle_timeout / 2
+          @next_prune_time = ThreadPool._monotonic_time + @prune_interval
+        end
+
+        # @see ActivityExecutor.execute_activity
+        def execute_activity(_defn, &block)
+          @mutex.synchronize do
+            locked_assign_worker(&block) || locked_enqueue(&block)
+            @scheduled_task_count += 1
+            locked_prune_pool if @next_prune_time < ThreadPool._monotonic_time
+          end
+        end
+
+        # @see ActivityExecutor.activity_context
+        def activity_context
+          Thread.current[:temporal_activity_context]
+        end
+
+        # @see ActivityExecutor.set_activity_context
+        def set_activity_context(defn, context)
+          Thread.current[:temporal_activity_context] = context
+          # If they have opted in to raising on cancel, wire that up
+          return unless defn.cancel_raise
+
+          thread = Thread.current
+          context&.cancellation&.add_cancel_callback do
+            thread.raise(Error::CanceledError.new('Activity canceled')) if thread[:temporal_activity_context] == context
+          end
+        end
+
+        # @return [Integer] The largest number of threads that have been created in the pool since construction.
+        def largest_length
+          @mutex.synchronize { @largest_length }
+        end
+
+        # @return [Integer] The number of tasks that have been scheduled for execution on the pool since construction.
+        def scheduled_task_count
+          @mutex.synchronize { @scheduled_task_count }
+        end
+
+        # @return [Integer] The number of tasks that have been completed by the pool since construction.
+        def completed_task_count
+          @mutex.synchronize { @completed_task_count }
+        end
+
+        # @return [Integer] The number of threads that are actively executing tasks.
+        def active_count
+          @mutex.synchronize { @pool.length - @ready.length }
+        end
+
+        # @return [Integer] The number of threads currently in the pool.
+        def length
+          @mutex.synchronize { @pool.length }
+        end
+
+        # @return [Integer] The number of tasks in the queue awaiting execution.
+        def queue_length
+          @mutex.synchronize { @queue.length }
+        end
+
+        # Gracefully shutdown each thread when it is done with its current task. This should not be called until all
+        # workers using this executor are complete. This does not need to be called at all on program exit (e.g. for the
+        # global default).
+        def shutdown
+          @mutex.synchronize do
+            # Stop all workers
+            @pool.each(&:stop)
+          end
+        end
+
+        # Kill each thread. This should not be called until all workers using this executor are complete. This does not
+        # need to be called at all on program exit (e.g. for the global default).
+        def kill
+          @mutex.synchronize do
+            # Kill all workers
+            @pool.each(&:kill)
+            @pool.clear
+            @ready.clear
+          end
+        end
+
+        # @!visibility private
+        def _remove_busy_worker(worker)
+          @mutex.synchronize { locked_remove_busy_worker(worker) }
+        end
+
+        # @!visibility private
+        def _ready_worker(worker, last_message)
+          @mutex.synchronize { locked_ready_worker(worker, last_message) }
+        end
+
+        # @!visibility private
+        def _worker_died(worker)
+          @mutex.synchronize { locked_worker_died(worker) }
+        end
+
+        # @!visibility private
+        def _worker_task_completed
+          @mutex.synchronize { @completed_task_count += 1 }
+        end
+
+        private
+
+        def locked_assign_worker(&block)
+          # keep growing if the pool is not at the minimum yet
+          worker, = @ready.pop || locked_add_busy_worker
+          if worker
+            worker << block
+            true
+          else
+            false
+          end
+        end
+
+        def locked_enqueue(&block)
+          @queue << block
+        end
+
+        def locked_add_busy_worker
+          return if @max_threads && @pool.size >= @max_threads
+
+          @workers_counter += 1
+          @pool << (worker = Worker.new(self, @workers_counter))
+          @largest_length = @pool.length if @pool.length > @largest_length
+          worker
+        end
+
+        def locked_prune_pool
+          now = ThreadPool._monotonic_time
+          stopped_workers = 0
+          while !@ready.empty? && (@pool.size - stopped_workers).positive?
+            worker, last_message = @ready.first
+            break unless now - last_message > @idle_timeout
+
+            stopped_workers += 1
+            @ready.shift
+            worker << :stop
+
+          end
+
+          @next_prune_time = ThreadPool._monotonic_time + @prune_interval
+        end
+
+        def locked_remove_busy_worker(worker)
+          @pool.delete(worker)
+        end
+
+        def locked_ready_worker(worker, last_message)
+          block = @queue.shift
+          if block
+            worker << block
+          else
+            @ready.push([worker, last_message])
+          end
+        end
+
+        def locked_worker_died(worker)
+          locked_remove_busy_worker(worker)
+          replacement_worker = locked_add_busy_worker
+          locked_ready_worker(replacement_worker, ThreadPool._monotonic_time) if replacement_worker
+        end
+
+        # @!visibility private
+        class Worker
+          def initialize(pool, id)
+            @queue = Queue.new
+            @thread = Thread.new(@queue, pool) do |my_queue, my_pool|
+              catch(:stop) do
+                loop do
+                  case block = my_queue.pop
+                  when :stop
+                    pool._remove_busy_worker(self)
+                    throw :stop
+                  else
+                    begin
+                      block.call
+                      my_pool._worker_task_completed
+                      my_pool._ready_worker(self, ThreadPool._monotonic_time)
+                    rescue StandardError => e
+                      # Ignore
+                      warn("Unexpected activity block error: #{e}")
+                    rescue Exception => e # rubocop:disable Lint/RescueException
+                      warn("Unexpected activity block exception: #{e}")
+                      my_pool._worker_died(self)
+                      throw :stop
+                    end
+                  end
+                end
+              end
+            end
+            @thread.name = "activity-thread-#{id}"
+          end
+
+          # @!visibility private
+          def <<(block)
+            @queue << block
+          end
+
+          # @!visibility private
+          def stop
+            @queue << :stop
+          end
+
+          # @!visibility private
+          def kill
+            @thread.kill
+          end
+        end
+
+        private_constant :Worker
+      end
+    end
+  end
+end

data/lib/temporalio/worker/activity_executor.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'temporalio/worker/activity_executor/fiber'
+require 'temporalio/worker/activity_executor/thread_pool'
+
+module Temporalio
+  class Worker
+    # Base class to be extended by activity executor implementations. Most users will not use this, but rather keep with
+    # the two defaults of thread pool and fiber executors.
+    class ActivityExecutor
+      # @return [Hash<Symbol, ActivityExecutor>] Default set of executors (immutable).
+      def self.defaults
+        @defaults ||= {
+          default: ThreadPool.default,
+          thread_pool: ThreadPool.default,
+          fiber: Fiber.default
+        }.freeze
+      end
+
+      # Initialize an activity. This is called on worker initialize for every activity that will use this executor. This
+      # allows executor implementations to do eager validation based on the definition. This does not have to be
+      # implemented and the default is a no-op.
+      #
+      # @param defn [Activity::Definition] Activity definition.
+      def initialize_activity(defn)
+        # Default no-op
+      end
+
+      # Execute the given block in the executor. The block is built to never raise and need no arguments. Implementers
+      # must implement this.
+      #
+      # @param defn [Activity::Definition] Activity definition.
+      # @yield Block to execute.
+      def execute_activity(defn, &)
+        raise NotImplementedError
+      end
+
+      # @return [Activity::Context, nil] Get the current activity context. This is called by users from inside the
+      #   activity. Implementers must implement this.
+      def activity_context
+        raise NotImplementedError
+      end
+
+      # Set the current activity context (or unset if nil). This is called by the system from within the block given to
+      # {execute_activity} with a context before user code is executed and with nil after user code is complete.
+      # Implementers must implement this.
+      #
+      # @param defn [Activity::Definition] Activity definition.
+      # @param context [Activity::Context, nil] The value to set.
+      def set_activity_context(defn, context)
+        raise NotImplementedError
+      end
+    end
+  end
+end