temporalio 0.0.1 → 0.1.0

data/lib/temporalio/testing.rb

@@ -0,0 +1,175 @@
+require 'temporalio/bridge'
+require 'temporalio/connection'
+require 'temporalio/runtime'
+require 'temporalio/testing/workflow_environment'
+require 'temporalio/version'
+
+module Temporalio
+  module Testing
+    DEFAULT_NAMESPACE = 'default'.freeze
+
+    class << self
+      # Start a full Temporal server locally, downloading if necessary.
+      #
+      # This environment is good for testing full server capabilities, but does not support time
+      # skipping like {.start_time_skipping} does.
+      # {Temporalio::Testing::WorkflowEnvironment#supports_time_skipping} will always return `false`
+      # for this environment. {Temporalio::Testing::WorkflowEnvironment#sleep} will sleep the actual
+      # amount of time and {Temporalio::Testing::WorkflowEnvironment#get_current_time}` will return
+      # the current time.
+      #
+      # Internally, this uses [Temporalite](https://github.com/temporalio/temporalite). Which is a
+      # self-contained binary for Temporal using Sqlite persistence. This will download Temporalite
+      # to a temporary directory by default if it has not already been downloaded before and
+      # `:existing_path` is not set.
+      #
+      # In the future, the Temporalite implementation may be changed to another implementation.
+      # Therefore, all `temporalite_` prefixed parameters are Temporalite specific and may not apply
+      # to newer versions.
+      #
+      # @param namespace [String] Namespace name to use for this environment.
+      # @param ip [String] IP address to bind to, or 127.0.0.1 by default.
+      # @param port [Integer] Port number to bind to, or an OS-provided port by default.
+      # @param download_dir [String] Directory to download binary to if a download is needed. If
+      #   unset, this is the system's temporary directory.
+      # @param ui [Boolean] If `true`, will start a UI in Temporalite.
+      # @param temporalite_existing_path [String] Existing path to the Temporalite binary. If
+      #   present, no download will be attempted to fetch the binary.
+      # @param temporalite_database_filename [String] Path to the Sqlite database to use for
+      #   Temporalite. Unset default means only in-memory Sqlite will be used.
+      # @param temporalite_log_format [String] Log format for Temporalite.
+      # @param temporalite_log_level [String] Log level to use for Temporalite.
+      # @param temporalite_download_version [String] Specific Temporalite version to download.
+      #   Defaults to `default` which downloads the version known to work best with this SDK.
+      # @param temporalite_extra_args [Array<String>] Extra arguments for the Temporalite binary.
+      #
+      # @yield Optionally you can provide a block which will ensure that the environment has been
+      #   shut down after. The newly created {Temporalio::Testing::WorkflowEnvironment} will be
+      #   passed into the block as a single argument. Alternatively you will need to call
+      #   {Temporalio::Testing::WorkflowEnvironment#shutdown} explicitly after you're done with it.
+      #
+      # @return [Temporalio::Testing::WorkflowEnvironment] The newly started Temporalite workflow
+      #   environment.
+      def start_local_environment(
+        namespace: DEFAULT_NAMESPACE,
+        ip: '127.0.0.1',
+        port: nil,
+        download_dir: nil,
+        ui: false,
+        temporalite_existing_path: nil,
+        temporalite_database_filename: nil,
+        temporalite_log_format: 'pretty',
+        temporalite_log_level: 'warn',
+        temporalite_download_version: 'default',
+        temporalite_extra_args: [],
+        &block
+      )
+        # TODO: Sync with the SDK's logger level when implemented
+        runtime = Temporalio::Runtime.instance
+        server = Temporalio::Bridge::TestServer.start_temporalite(
+          runtime.core_runtime,
+          temporalite_existing_path,
+          'sdk-ruby',
+          Temporalio::VERSION,
+          temporalite_download_version,
+          download_dir,
+          namespace,
+          ip,
+          port,
+          temporalite_database_filename,
+          ui,
+          temporalite_log_format,
+          temporalite_log_level,
+          temporalite_extra_args,
+        )
+        env = init_workflow_environment_for(server, namespace)
+
+        return env unless block
+
+        run_server(server, env, &block)
+      end
+
+      # Start a time skipping workflow environment.
+      #
+      # Time can be manually skipped forward using {Temporalio::Testing::WorkflowEnvironment#sleep}.
+      # The currently known time can be obtained via
+      # {Temporalio::Testing::WorkflowEnvironment#get_current_time}.
+      #
+      # @note Auto time skipping is not yet implemented.
+      #
+      # Internally, this environment lazily downloads a test-server binary for the current OS/arch
+      # into the temp directory if it is not already there. Then the executable is started and will
+      # be killed when {Temporalio::Testing::WorkflowEnvironment#shutdown} is called (which is
+      # implicitly done if a block is provided to this method).
+      #
+      # Users can reuse this environment for testing multiple independent workflows, but not
+      # concurrently. Time skipping, which is automatically done when awaiting a workflow result
+      # (pending implementation) and manually done on
+      # {Temporalio::Testing::WorkflowEnvironment#sleep}, is global to the environment, not to the
+      # workflow under test.
+      #
+      # In the future, the test server implementation may be changed to another implementation.
+      # Therefore, all `test_server_` prefixed parameters are test server specific and may not apply
+      # to newer versions.
+      #
+      # @param port [Integer] Port number to bind to, or an OS-provided port by default.
+      # @param download_dir [String] Directory to download binary to if a download is needed.
+      #   If unset, this is the system's temporary directory.
+      # @param test_server_existing_path [String] Existing path to the test server binary. If
+      #   present, no download will be attempted to fetch the binary.
+      # @param test_server_download_version [String] Specific test server version to download.
+      #   Defaults to `default` which downloads the version known to work best with this SDK.
+      # @param test_server_extra_args [Array<String>] Extra arguments for the test server binary.
+      #
+      # @yield Optionally you can provide a block which will ensure that the environment has been
+      #   shut down after. The newly created {Temporalio::Testing::WorkflowEnvironment} will be
+      #   passed into the block as a single argument. Alternatively you will need to call
+      #   {Temporalio::Testing::WorkflowEnvironment#shutdown} explicitly after you're done with it.
+      #
+      # @return [Temporalio::Testing::WorkflowEnvironment] The newly started TestServer workflow
+      #   environment.
+      def start_time_skipping_environment(
+        port: nil,
+        download_dir: nil,
+        test_server_existing_path: nil,
+        test_server_download_version: 'default',
+        test_server_extra_args: [],
+        &block
+      )
+        # TODO: Use interceptors to inject a time skipping WorkflowHandle.
+        runtime = Temporalio::Runtime.instance
+        server = Temporalio::Bridge::TestServer.start(
+          runtime.core_runtime,
+          test_server_existing_path,
+          'sdk-ruby',
+          Temporalio::VERSION,
+          test_server_download_version,
+          download_dir,
+          port,
+          test_server_extra_args,
+        )
+        env = init_workflow_environment_for(server, DEFAULT_NAMESPACE)
+
+        return env unless block
+
+        run_server(server, env, &block)
+      end
+
+      private
+
+      def init_workflow_environment_for(server, namespace)
+        connection = Temporalio::Connection.new(server.target)
+        Temporalio::Testing::WorkflowEnvironment.new(server, connection, namespace)
+      rescue Temporalio::Bridge::Error # Shutdown if unable to connect to the server
+        server.shutdown
+        raise
+      end
+
+      def run_server(server, env, &block)
+        block.call(env)
+      ensure
+        server.shutdown
+      end
+    end
+  end
+end

data/lib/{temporal → temporalio}/timeout_type.rb

@@ -1,5 +1,5 @@
-module Temporal
-  # Type of timeout for {Temporal::TimeoutError}.
+module Temporalio
+  # Type of timeout for {Temporalio::TimeoutError}.
   module TimeoutType
     TYPES = [
       START_TO_CLOSE = :START_TO_CLOSE,

data/lib/temporalio/version.rb

@@ -0,0 +1,3 @@
+module Temporalio
+  VERSION = '0.1.0'.freeze
+end

data/lib/temporalio/worker/activity_runner.rb

@@ -0,0 +1,114 @@
+require 'google/protobuf/well_known_types'
+require 'temporalio/activity/context'
+require 'temporalio/activity/info'
+require 'temporalio/error/failure'
+require 'temporalio/errors'
+require 'temporalio/interceptor/activity_inbound'
+
+module Temporalio
+  class Worker
+    # The main class for handling activity processing. It is expected to be executed from
+    # some threaded or async executor's context since methods called here might be blocking
+    # and this should not affect the main worker reactor.
+    #
+    # @api private
+    class ActivityRunner
+      def initialize(
+        activity_class,
+        start,
+        task_queue,
+        task_token,
+        worker,
+        converter,
+        inbound_interceptors,
+        outbound_interceptors
+      )
+        @activity_class = activity_class
+        @start = start
+        @task_queue = task_queue
+        @task_token = task_token
+        @worker = worker
+        @converter = converter
+        @inbound_interceptors = inbound_interceptors
+        @outbound_interceptors = outbound_interceptors
+      end
+
+      def run
+        activity = activity_class.new(context)
+        args = converter.from_payload_array(start.input.to_a)
+        headers = converter.from_payload_map(start.header_fields)
+        input = Temporalio::Interceptor::ActivityInbound::ExecuteActivityInput.new(
+          activity: activity_class,
+          args: args,
+          headers: headers || {},
+        )
+
+        result = inbound_interceptors.invoke(:execute_activity, input) do |i|
+          activity.execute(*i.args)
+        end
+
+        converter.to_payload(result)
+      rescue StandardError => e
+        # Temporal server ignores cancellation failures that were not requested by the server.
+        # However within the SDK cancellations are also used during the worker shutdown. In order
+        # to provide a seamless handling experience (same error raised within the Activity) we are
+        # using the ActivityCancelled error and then swapping it with a CancelledError here.
+        #
+        # In the future this will be handled by the SDK Core — https://github.com/temporalio/sdk-core/issues/461
+        if e.is_a?(Temporalio::Error::ActivityCancelled) && e.by_request?
+          e = Temporalio::Error::CancelledError.new(e.message)
+        end
+
+        converter.to_failure(e)
+      end
+
+      def cancel(reason, by_request:)
+        context.cancel(reason, by_request: by_request)
+      end
+
+      private
+
+      attr_reader :activity_class, :start, :task_queue, :task_token, :worker, :converter,
+                  :inbound_interceptors, :outbound_interceptors
+
+      def context
+        return @context if @context
+
+        heartbeat_proc = ->(*details) { heartbeat(*details) }
+        @context = Temporalio::Activity::Context.new(
+          generate_activity_info,
+          heartbeat_proc,
+          outbound_interceptors,
+          shielded: activity_class._shielded,
+        )
+      end
+
+      def generate_activity_info
+        Temporalio::Activity::Info.new(
+          activity_id: start.activity_id,
+          activity_type: start.activity_type,
+          attempt: start.attempt,
+          current_attempt_scheduled_time: start.current_attempt_scheduled_time&.to_time,
+          heartbeat_details: converter.from_payload_array(start.heartbeat_details.to_a),
+          heartbeat_timeout: start.heartbeat_timeout&.to_f,
+          local: !start.is_local.nil?,
+          schedule_to_close_timeout: start.schedule_to_close_timeout&.to_f,
+          scheduled_time: start.scheduled_time&.to_time,
+          start_to_close_timeout: start.start_to_close_timeout&.to_f,
+          started_time: start.started_time&.to_time,
+          task_queue: task_queue,
+          task_token: task_token,
+          workflow_id: start.workflow_execution&.workflow_id,
+          workflow_namespace: start.workflow_namespace,
+          workflow_run_id: start.workflow_execution&.run_id,
+          workflow_type: start.workflow_type,
+        ).freeze
+      end
+
+      def heartbeat(*details)
+        payloads = converter.to_payload_array(details)
+        worker.record_activity_heartbeat(task_token, payloads)
+      end
+    end
+  end
+end

data/lib/temporalio/worker/activity_worker.rb

@@ -0,0 +1,164 @@
+require 'temporalio/error/failure'
+require 'temporalio/errors'
+require 'temporalio/interceptor'
+require 'temporalio/interceptor/chain'
+require 'temporalio/worker/activity_runner'
+
+module Temporalio
+  class Worker
+    # @api private
+    class ActivityWorker
+      def initialize(
+        task_queue,
+        worker,
+        activities,
+        converter,
+        interceptors,
+        executor,
+        graceful_timeout
+      )
+        @task_queue = task_queue
+        @worker = worker
+        @activities = prepare_activities(activities)
+        @converter = converter
+        @inbound_interceptors = Temporalio::Interceptor::Chain.new(
+          Temporalio::Interceptor.filter(interceptors, :activity_inbound),
+        )
+        @outbound_interceptors = Temporalio::Interceptor::Chain.new(
+          Temporalio::Interceptor.filter(interceptors, :activity_outbound),
+        )
+        @executor = executor
+        @graceful_timeout = graceful_timeout
+        @running_activities = {}
+        @cancellations = []
+        @drain_queue = Queue.new
+      end
+
+      def run(reactor)
+        # @type var outstanding_tasks: Array[Async::Task]
+        outstanding_tasks = []
+
+        loop do
+          activity_task = worker.poll_activity_task
+          outstanding_tasks << reactor.async do |async_task|
+            if activity_task.start
+              handle_start_activity(activity_task.task_token, activity_task.start)
+            elsif activity_task.cancel
+              handle_cancel_activity(activity_task.task_token, activity_task.cancel)
+            end
+          ensure
+            outstanding_tasks.delete(async_task)
+          end
+        end
+      rescue Temporalio::Bridge::Error::WorkerShutdown
+        # No need to re-raise this error, it's a part of a normal shutdown
+      ensure
+        outstanding_tasks.each(&:wait)
+        @cancelation_task&.wait
+        drain_queue.close
+      end
+
+      def setup_graceful_shutdown_timer(reactor)
+        if graceful_timeout
+          reactor.async do |async_task|
+            @cancelation_task = async_task.async do
+              sleep graceful_timeout
+              @running_activities.each_value do |activity_runner|
+                activity_runner.cancel('Worker is shutting down', by_request: false)
+              end
+            end
+          end
+        end
+      end
+
+      def drain
+        drain_queue.pop
+      end
+
+      private
+
+      attr_reader :task_queue, :worker, :activities, :converter, :inbound_interceptors,
+                  :outbound_interceptors, :executor, :graceful_timeout, :running_activities,
+                  :cancellations, :drain_queue
+
+      def prepare_activities(activities)
+        activities.each_with_object({}) do |activity, result|
+          unless activity.ancestors.include?(Temporalio::Activity)
+            raise ArgumentError, 'Activity must be a subclass of Temporalio::Activity'
+          end
+
+          if result[activity._name]
+            raise ArgumentError, "More than one activity named #{activity._name}"
+          end
+
+          result[activity._name] = activity
+          result
+        end
+      end
+
+      def lookup_activity(activity_type)
+        activities.fetch(activity_type) do
+          activity_names = activities.keys.sort.join(', ')
+          raise Temporalio::Error::ApplicationError.new(
+            "Activity #{activity_type} is not registered on this worker, available activities: #{activity_names}",
+            type: 'NotFoundError',
+          )
+        end
+      end
+
+      def run_activity(token, start)
+        activity_class = lookup_activity(start.activity_type)
+        runner = ActivityRunner.new(
+          activity_class,
+          start,
+          task_queue,
+          token,
+          worker,
+          converter,
+          inbound_interceptors,
+          outbound_interceptors,
+        )
+        running_activities[token] = runner
+        queue = Queue.new
+
+        executor.schedule do
+          queue << runner.run
+        end
+
+        queue.pop
+      rescue StandardError => e
+        converter.to_failure(e)
+      end
+
+      def handle_start_activity(task_token, start)
+        result = run_activity(task_token, start)
+
+        case result
+        when Temporalio::Api::Common::V1::Payload
+          worker.complete_activity_task_with_success(task_token, result)
+        when Temporalio::Api::Failure::V1::Failure
+          # only respond with a cancellation when it was requested, otherwise it's a regular failure
+          if result.canceled_failure_info && cancellations.include?(task_token)
+            worker.complete_activity_task_with_cancellation(task_token, result)
+          else
+            worker.complete_activity_task_with_failure(task_token, result)
+          end
+        end
+
+        running_activities.delete(task_token)
+        cancellations.delete(task_token)
+      end
+
+      def handle_cancel_activity(task_token, _cancel)
+        runner = running_activities.fetch(task_token) do
+          # TODO: Use logger instead when implemented
+          warn "Cannot find activity to cancel for token #{task_token}"
+          return # early escape
+        end
+
+        cancellations << task_token
+        runner&.cancel('Activity cancellation requested', by_request: true)
+      end
+    end
+  end
+end

data/lib/temporalio/worker/reactor.rb

@@ -0,0 +1,46 @@
+require 'async'
+
+module Temporalio
+  class Worker
+    # A shared async reactor.
+    #
+    # This class allows multiple workers to access the same Async reactor
+    # without forcing the SDK users to wrap their execution in an Async block. This
+    # is handled using a queue that is polled from within a running Async reactor,
+    # so all the blocks end up being executed within it.
+    #
+    # @api private
+    class Reactor
+      def initialize
+        @queue = Queue.new
+        @thread = nil
+        @mutex = Mutex.new
+      end
+
+      def async(&block)
+        ensure_reactor_thread
+        queue << block
+      end
+
+      private
+
+      attr_reader :queue, :mutex
+
+      def ensure_reactor_thread
+        mutex.synchronize do
+          @thread ||= Thread.new { run_loop }
+        end
+      end
+
+      def run_loop
+        reactor = Async::Reactor.new
+        reactor.run do |task|
+          loop do
+            block = queue.pop
+            task.async { |subtask| block.call(subtask) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/worker/runner.rb

@@ -0,0 +1,63 @@
+require 'temporalio/errors'
+
+module Temporalio
+  class Worker
+    # A class used to manage the lifecycle of running any number of workers.
+    #
+    # @api private
+    class Runner
+      def initialize(*workers)
+        if workers.empty?
+          raise ArgumentError, 'Must be initialized with at least one worker'
+        end
+
+        @workers = workers
+        @mutex = Mutex.new
+        @started = false
+        @shutdown = false
+      end
+
+      def run(&block)
+        @thread = Thread.current
+        @started = true
+        workers.each { |worker| worker.start(self) }
+
+        block ? block.call : sleep
+      rescue Temporalio::Error::WorkerShutdown
+        # Explicit shutdown requested, no need to raise
+      ensure
+        @shutdown = true
+        shutdown_workers
+      end
+
+      def shutdown(exception = Temporalio::Error::WorkerShutdown.new('Manual shutdown'))
+        mutex.synchronize do
+          return unless running?
+
+          @shutdown = true
+        end
+
+        # propagate shutdown to the running thread
+        thread&.raise(exception)
+      end
+
+      private
+
+      attr_reader :workers, :mutex, :thread
+
+      def running?
+        @started && !@shutdown
+      end
+
+      def shutdown_workers
+        # Protect shutdown from any outside raises
+        Thread.handle_interrupt(StandardError => :never) do
+          workers.map do |worker|
+            # Shut down each worker (and wait for it) concurrently in separate threads
+            Thread.new { worker.shutdown }
+          end.each(&:join)
+        end
+      end
+    end
+  end
+end