temporalio 0.0.1 → 0.1.0

data/lib/temporalio/worker/sync_worker.rb

@@ -0,0 +1,124 @@
+require 'temporal/sdk/core/activity_task/activity_task_pb'
+require 'temporal/sdk/core/core_interface_pb'
+require 'temporal/sdk/core/workflow_activation/workflow_activation_pb'
+require 'temporal/sdk/core/workflow_completion/workflow_completion_pb'
+
+module Temporalio
+  class Worker
+    # This is a wrapper class for the Core Worker (provided via the Bridge) to abstract
+    # away its async nature allowing other modules/classes to interact with it without
+    # any callbacks (simplifying the code).
+    #
+    # CAUTION: This class will block the thread its running in unless it is used from
+    #          within an Async reactor.
+    #
+    # @api private
+    class SyncWorker
+      def initialize(core_worker)
+        @core_worker = core_worker
+      end
+
+      def poll_activity_task
+        with_queue do |done|
+          core_worker.poll_activity_task do |task, error|
+            done.call(task && Temporalio::Bridge::Api::ActivityTask::ActivityTask.decode(task), error)
+          end
+        end
+      end
+
+      def complete_activity_task_with_success(task_token, payload)
+        result = Temporalio::Bridge::Api::ActivityResult::ActivityExecutionResult.new(
+          completed: Temporalio::Bridge::Api::ActivityResult::Success.new(result: payload),
+        )
+
+        complete_activity_task(task_token, result)
+      end
+
+      def complete_activity_task_with_failure(task_token, failure)
+        result = Temporalio::Bridge::Api::ActivityResult::ActivityExecutionResult.new(
+          failed: Temporalio::Bridge::Api::ActivityResult::Failure.new(failure: failure),
+        )
+
+        complete_activity_task(task_token, result)
+      end
+
+      def complete_activity_task_with_cancellation(task_token, failure)
+        result = Temporalio::Bridge::Api::ActivityResult::ActivityExecutionResult.new(
+          cancelled: Temporalio::Bridge::Api::ActivityResult::Cancellation.new(failure: failure),
+        )
+
+        complete_activity_task(task_token, result)
+      end
+
+      def record_activity_heartbeat(task_token, payloads)
+        proto = Temporalio::Bridge::Api::CoreInterface::ActivityHeartbeat.new(
+          task_token: task_token,
+          details: payloads,
+        )
+        encoded_proto = Temporalio::Bridge::Api::CoreInterface::ActivityHeartbeat.encode(proto)
+
+        core_worker.record_activity_heartbeat(encoded_proto)
+      end
+
+      def poll_workflow_activation
+        with_queue do |done|
+          core_worker.poll_workflow_activation do |task, error|
+            done.call(task && Temporalio::Bridge::Api::WorkflowActivation::WorkflowActivation.decode(task), error)
+          end
+        end
+      end
+
+      def complete_workflow_activation_with_success(run_id, commands)
+        proto = Temporalio::Bridge::Api::WorkflowCompletion::WorkflowActivationCompletion.new(
+          run_id: run_id,
+          successful: Temporalio::Bridge::Api::WorkflowCompletion::Success.new(commands: commands),
+        )
+
+        complete_workflow_activation(proto)
+      end
+
+      def complete_workflow_activation_with_failure(run_id, failure)
+        proto = Temporalio::Bridge::Api::WorkflowCompletion::WorkflowActivationCompletion.new(
+          run_id: run_id,
+          failed: Temporalio::Bridge::Api::WorkflowCompletion::Failure.new(failure: failure),
+        )
+
+        complete_workflow_activation(proto)
+      end
+
+      private
+
+      attr_reader :core_worker
+
+      def with_queue(&block)
+        queue = Queue.new
+        done = ->(result, error = nil) { queue << [result, error] }
+        block.call(done)
+        (result, exception) = queue.pop
+        raise exception if exception
+
+        result
+      end
+
+      def complete_activity_task(task_token, result)
+        proto = Temporalio::Bridge::Api::CoreInterface::ActivityTaskCompletion.new(
+          task_token: task_token,
+          result: result,
+        )
+        encoded_proto = Temporalio::Bridge::Api::CoreInterface::ActivityTaskCompletion.encode(proto)
+
+        with_queue do |done|
+          core_worker.complete_activity_task(encoded_proto, &done)
+        end
+      end
+
+      def complete_workflow_activation(proto)
+        encoded_proto = Temporalio::Bridge::Api::WorkflowCompletion::WorkflowActivationCompletion.encode(proto)
+
+        with_queue do |done|
+          core_worker.complete_workflow_activation(encoded_proto, &done)
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/worker/thread_pool_executor.rb

@@ -0,0 +1,51 @@
+module Temporalio
+  class Worker
+    # A generic fixed thread pool.
+    #
+    # This is used to execute multiple activities concurrently and independenty of each other.
+    #
+    # @note This is a fixed thread pool that allocated threads eagerly and has an infinite buffer.
+    class ThreadPoolExecutor
+      # Generate new thread pool executor.
+      #
+      # @param size [Integer] Number of concurrently executing threads.
+      def initialize(size)
+        @queue = Queue.new
+        @pool = Array.new(size) do
+          Thread.new { poll }
+        end
+      end
+
+      # Execute a block of code inside of the threads.
+      #
+      # @yield Block of code to be executed.
+      def schedule(&block)
+        queue << block
+      end
+
+      # Stop the thread pool and wait for all threads to finish work.
+      def shutdown
+        pool.size.times do
+          schedule { throw EXIT_SYMBOL }
+        end
+
+        pool.each(&:join)
+      end
+
+      private
+
+      attr_reader :queue, :pool
+
+      EXIT_SYMBOL = :exit
+
+      def poll
+        catch(EXIT_SYMBOL) do
+          loop do
+            job = queue.pop
+            job.call
+          end
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/worker.rb

@@ -0,0 +1,204 @@
+require 'async'
+require 'temporalio/bridge'
+require 'temporalio/data_converter'
+require 'temporalio/runtime'
+require 'temporalio/worker/activity_worker'
+require 'temporalio/worker/runner'
+require 'temporalio/worker/sync_worker'
+require 'temporalio/worker/thread_pool_executor'
+
+module Temporalio
+  # Worker to process activities.
+  #
+  # Once created, workers can be run and shutdown explicitly via {#run} and {#shutdown}.
+  class Worker
+    # Run multiple workers and wait for them to be shut down.
+    #
+    # This will not return until shutdown is complete (and all running activities in all workers
+    # finished) and will raise if any of the workers raises a fatal error.
+    #
+    # @param workers [Array<Temporalio::Worker>] A list of the workers to be run.
+    # @param shutdown_signals [Array<String>] A list of process signals for the worker to stop on.
+    #   This argument can not be used with a custom block.
+    #
+    # @yield Optionally you can provide a block by the end of which all the workers will be shut
+    #   down. Any errors raised from this block will be re-raised by this method.
+    def self.run(*workers, shutdown_signals: [], &block)
+      unless shutdown_signals.empty?
+        if block
+          raise ArgumentError, 'Temporalio::Worker.run accepts :shutdown_signals or a block, but not both'
+        end
+
+        signal_queue = Queue.new
+
+        shutdown_signals.each do |signal|
+          Signal.trap(signal) { signal_queue.close }
+        end
+
+        block = -> { signal_queue.pop }
+      end
+
+      Runner.new(*workers).run(&block)
+    end
+
+    # Create a worker to process activities.
+    #
+    # @param connection [Temporalio::Connection] A connection to be used for this worker.
+    # @param namespace [String] A namespace.
+    # @param task_queue [String] A task queue.
+    # @param activities [Array<Class>] A list of activities (subclasses of {Temporalio::Activity}).
+    # @param data_converter [Temporalio::DataConverter] Data converter to use for all data conversions
+    #   to/from payloads.
+    # @param activity_executor [ThreadPoolExecutor] Concurrent executor for all activities. Defaults
+    #   to a {ThreadPoolExecutor} with `:max_concurrent_activities` available threads.
+    # @param interceptors [Array<Temporalio::Interceptor::ActivityInbound, Temporalio::Interceptor::ActivityOutbound>]
+    #   Collection of interceptors for this worker.
+    # @param max_concurrent_activities [Integer] Number of concurrently running activities.
+    # @param graceful_shutdown_timeout [Integer] Amount of time (in seconds) activities are given
+    #   after a shutdown to complete before they are cancelled. A default value of `nil` means that
+    #   activities are never cancelled when handling a shutdown.
+    #
+    # @raise [ArgumentError] When no activities have been provided.
+    def initialize(
+      connection,
+      namespace,
+      task_queue,
+      activities: [],
+      data_converter: Temporalio::DataConverter.new,
+      activity_executor: nil,
+      interceptors: [],
+      max_concurrent_activities: 100,
+      graceful_shutdown_timeout: nil
+    )
+      @started = false
+      @shutdown = false
+      @mutex = Mutex.new
+      @runtime = Temporalio::Runtime.instance
+      @activity_executor = activity_executor || ThreadPoolExecutor.new(max_concurrent_activities)
+      @core_worker = Temporalio::Bridge::Worker.create(
+        @runtime.core_runtime,
+        connection.core_connection,
+        namespace,
+        task_queue,
+        0, # maxCachedWorkflows disabled temporarily
+        # FIXME: expose enable_non_local_activities
+        activities.empty?,
+      )
+      sync_worker = Worker::SyncWorker.new(@core_worker)
+      @activity_worker =
+        unless activities.empty?
+          Worker::ActivityWorker.new(
+            task_queue,
+            sync_worker,
+            activities,
+            data_converter,
+            interceptors,
+            @activity_executor,
+            graceful_shutdown_timeout,
+          )
+        end
+
+      unless @activity_worker
+        raise ArgumentError, 'At least one activity must be specified'
+      end
+    end
+
+    # Run the worker and wait on it to be shut down.
+    #
+    # This will not return until shutdown is complete (and all running activities finished) and will
+    # raise if there is a worker fatal error. To run multiple workers use the class method {.run}.
+    #
+    # @note A worker is only intended to be started once. Initialize a new worker should you need to
+    #   run it again.
+    #
+    # @yield Optionally you can provide a block by the end of which the worker will shut itself
+    #   down. You can use this to stop a worker after some time has passed or any other arbitrary
+    #   implementation has completed. Any errors raised from this block will be re-raised by this
+    #   method.
+    def run(&block)
+      Runner.new(self).run(&block)
+    end
+
+    # Start the worker asynchronously in a shared runtime.
+    #
+    # This is an internal method for advanced use-cases for those intended to implement their own
+    # worker runner.
+    #
+    # @note A worker is only intended to be started once. Initialize a new worker should you need to
+    #   start it again.
+    #
+    # @api private
+    #
+    # @param runner [Temporalio::Worker::Runner] A runner to notify when the worker is shutting down.
+    def start(runner = nil)
+      mutex.synchronize do
+        raise 'Worker is already started' if started?
+
+        @started = true
+      end
+
+      @runner = runner
+      runtime.ensure_callback_loop
+
+      runtime.reactor.async do |task|
+        if activity_worker
+          task.async do |task|
+            activity_worker.run(task)
+          rescue StandardError => e
+            shutdown(e) # initiate shutdown because of a fatal error
+          end
+        end
+      end
+    end
+
+    # Initiate a worker shutdown and wait until complete.
+    #
+    # This can be called before the worker has even started and is safe for repeated invocations.
+    # This method will not return until the worker has completed shutting down.
+    #
+    # @param exception [Exception] An exception to be raised from {#run} or {.run} methods after a
+    #   shutdown procedure has completed.
+    def shutdown(exception = Temporalio::Error::WorkerShutdown.new('Manual shutdown'))
+      mutex.synchronize do
+        return unless running?
+
+        # Let the runner know we're shutting down, so it can stop other workers.
+        # This will cause a reentrant call to this method, but the mutex above will block that call.
+        runner&.shutdown(exception)
+
+        # Initiate Core shutdown, which will start dropping poll requests
+        core_worker.initiate_shutdown
+        # Start the graceful activity shutdown timer, which will cancel activities after the timeout
+        activity_worker&.setup_graceful_shutdown_timer(runtime.reactor)
+        # Wait for workers to drain any outstanding tasks
+        activity_worker&.drain
+        activity_executor.shutdown
+        # Finalize the shutdown by stopping the Core
+        core_worker.finalize_shutdown
+
+        @shutdown = true
+      end
+    end
+
+    # Whether the worker has been started.
+    #
+    # @return [Boolean]
+    def started?
+      @started
+    end
+
+    # Whether the worker is running.
+    #
+    # This is only `true` if the worker has been started and not yet shut down.
+    #
+    # @return [Boolean]
+    def running?
+      @started && !@shutdown
+    end
+
+    private
+
+    attr_reader :mutex, :runtime, :activity_executor, :core_worker, :activity_worker,
+                :runner
+  end
+end

data/lib/temporalio/workflow/async.rb

@@ -0,0 +1,46 @@
+require 'temporalio/workflow/future'
+
+module Temporalio
+  class Workflow
+    module Async
+      def self.run(&block)
+        Future.new do |future, resolve, reject|
+          Fiber.new do
+            Future.current = future
+            result = block.call
+            resolve.call(result)
+          rescue StandardError => e
+            reject.call(e)
+          end.resume
+        end
+      end
+
+      def self.all(*futures)
+        Future.new do |future, resolve, _reject|
+          future.on_cancel { futures.each(&:cancel) }
+
+          futures.each do |f|
+            f.then do
+              # Resolve the aggregate once all futures have been fulfilled (resolved or rejected)
+              resolve.call(nil) if futures.none?(&:pending?)
+            end
+          end
+        end
+      end
+
+      def self.any(*futures)
+        # This future is never rejected
+        Future.new do |future, resolve, _reject|
+          future.on_cancel { futures.each(&:cancel) }
+
+          futures.each do |f|
+            # Resolve the aggregate once the first future fulfills (resolved or rejected)
+            # NOTE: The the first completed future will be the resolved value and all subsequent
+            #       calls to `resolve` will have no effect.
+            f.then { resolve.call(f) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/{temporal → temporalio}/workflow/execution_info.rb

@@ -1,8 +1,8 @@
-require 'temporal/errors'
-require 'temporal/workflow/execution_status'
+require 'temporalio/errors'
+require 'temporalio/workflow/execution_status'
 require 'google/protobuf/well_known_types'
 
-module Temporal
+module Temporalio
   class Workflow
     class ExecutionInfo < Struct.new(
       :raw,
@@ -23,7 +23,7 @@ module Temporal
     )
       def self.from_raw(response, converter)
         raw_info = response.workflow_execution_info
-        raise Temporal::Error::UnexpectedResponse, 'missing workflow_execution_info' unless raw_info
+        raise Temporalio::Error::UnexpectedResponse, 'missing workflow_execution_info' unless raw_info
 
         new(
           raw: response,

data/lib/{temporal → temporalio}/workflow/execution_status.rb

@@ -1,4 +1,4 @@
-module Temporal
+module Temporalio
   class Workflow
     module ExecutionStatus
       STATUSES = [

data/lib/temporalio/workflow/future.rb

@@ -0,0 +1,138 @@
+module Temporalio
+  class Workflow
+    class Future
+      THREAD_KEY = :temporalio_workflow_future
+
+      class Rejected < StandardError; end
+
+      def self.current
+        Thread.current[THREAD_KEY]
+      end
+
+      def self.current=(future)
+        Thread.current[THREAD_KEY] = future
+      end
+
+      # Revist the reason for combining futures and cancellation scopes, maybe they are separate?
+      def initialize(&block)
+        @resolved = false
+        @value = nil
+        @rejected = false
+        @error = Rejected.new('Future rejected')
+        @cancel_requested = false
+        @blocked_fibers = []
+        @callbacks = []
+        @cancel_callbacks = []
+
+        # Chain cancellation into parent future if one exists
+        Future.current&.on_cancel { cancel }
+
+        # NOTE: resolve and reject methods are accessible via procs to avoid exposing
+        #       them via the public interface.
+        block.call(
+          self,
+          ->(value) { resolve(value) },
+          ->(error) { reject(error) },
+        )
+      end
+
+      def then(&block)
+        Future.new do |future, resolve, reject|
+          # @type var wrapped_block: ^() -> void
+          wrapped_block = -> do # rubocop:disable Style/Lambda
+            Fiber.new do
+              Future.current = future
+              # The block is provided the Future on which #then was called
+              result = block.call(self)
+              resolve.call(result)
+            rescue StandardError => e
+              reject.call(e)
+            end.resume
+          end
+
+          if pending?
+            callbacks << wrapped_block
+          else
+            wrapped_block.call
+          end
+        end
+      end
+
+      def on_cancel(&block)
+        if pending? && !cancel_requested?
+          cancel_callbacks << block
+        else
+          block.call
+        end
+      end
+
+      def pending?
+        !resolved? && !rejected?
+      end
+
+      def resolved?
+        @resolved
+      end
+
+      def rejected?
+        @rejected
+      end
+
+      def await
+        if pending?
+          blocked_fibers << Fiber.current
+          # yield into the parent fiber
+          Fiber.yield while pending?
+        end
+
+        raise error if rejected?
+
+        value
+      end
+
+      def cancel
+        return unless pending?
+        return if cancel_requested?
+
+        @cancel_requested = true
+        cancel_callbacks.each(&:call)
+      end
+
+      private
+
+      attr_reader :value, :error, :blocked_fibers, :callbacks, :cancel_callbacks
+
+      def cancel_requested?
+        @cancel_requested
+      end
+
+      # TODO: Run callbacks in a Fiber to allow blocking calls
+      def run_callbacks
+        callbacks.each(&:call)
+      end
+
+      # Unblock every fiber that this future is awaited on
+      def resume_fibers
+        blocked_fibers.each(&:resume)
+      end
+
+      def resolve(value)
+        return unless pending?
+
+        @value = value
+        @resolved = true
+        run_callbacks
+        resume_fibers
+      end
+
+      def reject(error)
+        return unless pending?
+
+        @error = error
+        @rejected = true
+        run_callbacks
+        resume_fibers
+      end
+    end
+  end
+end

data/lib/{temporal → temporalio}/workflow/id_reuse_policy.rb

@@ -1,10 +1,10 @@
 require 'temporal/api/enums/v1/workflow_pb'
 
-module Temporal
+module Temporalio
   class Workflow
     # How already-in-use workflow IDs are handled on start.
     #
-    # @see Temporal::Api::Enums::V1::WorkflowIdReusePolicy
+    # @see Temporalio::Api::Enums::V1::WorkflowIdReusePolicy
     class IDReusePolicy
       POLICIES = [
         ALLOW_DUPLICATE = :ALLOW_DUPLICATE,
@@ -14,13 +14,13 @@ module Temporal
       ].freeze
 
       API_MAP = {
-        Temporal::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE =>
+        Temporalio::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE =>
           ALLOW_DUPLICATE,
-        Temporal::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY =>
+        Temporalio::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY =>
           ALLOW_DUPLICATE_FAILED_ONLY,
-        Temporal::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE =>
+        Temporalio::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE =>
           REJECT_DUPLICATE,
-        Temporal::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING =>
+        Temporalio::Api::Enums::V1::WorkflowIdReusePolicy::WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING =>
           TERMINATE_IF_RUNNING,
       }.freeze
 

data/lib/temporalio/workflow/info.rb

@@ -0,0 +1,76 @@
+module Temporalio
+  class Workflow
+    # Class containing information about a workflow's parent.
+    class ParentInfo < Struct.new(
+      :namespace,
+      :run_id,
+      :workflow_id,
+      keyword_init: true,
+    )
+      # @!attribute [r] namespace
+      #   @return [String] Namespace of the parent workflow.
+      # @!attribute [r] run_id
+      #   @return [String] Run ID of the parent workflow.
+      # @!attribute [r] workflow_id
+      #   @return [String] ID of the parent workflow.
+    end
+
+    # Class containing information about a workflow.
+    class Info < Struct.new(
+      :attempt,
+      :continued_run_id,
+      :cron_schedule,
+      :execution_timeout,
+      :headers,
+      :namespace,
+      :parent,
+      :raw_memo,
+      :retry_policy,
+      :run_id,
+      :run_timeout,
+      :search_attributes,
+      :start_time,
+      :task_queue,
+      :task_timeout,
+      :workflow_id,
+      :workflow_type,
+      keyword_init: true,
+    )
+      # @!attribute [r] attempt
+      #   @return [Integer] Attempt of executing the workflow.
+      # @!attribute [r] continued_run_id
+      #   @return [String] Run id of the previous workflow which continued-as-new or retired or cron
+      #     executed into this workflow, if any.
+      # @!attribute [r] cron_schedule
+      #   @return [String] Cron schedule of the workflow.
+      # @!attribute [r] execution_timeout
+      #   @return [Float] Execution timeout of the workflow (in seconds).
+      # @!attribute [r] headers
+      #   @return [Hash<String, any>] Headers for the workflow.
+      # @!attribute [r] namespace
+      #   @return [String] Namespace of the workflow.
+      # @!attribute [r] parent
+      #   @return [Temporalio::Workflow::ParentInfo] Info of the parent workflow.
+      # @!attribute [r] raw_memo
+      #   @return [Hash<String, any>] Memo for the workflow.
+      # @!attribute [r] retry_policy
+      #   @return [Temporalio::RetryPolicy] RetryPolicy of the workflow.
+      # @!attribute [r] run_id
+      #   @return [String] Run ID of the workflow.
+      # @!attribute [r] run_timeout
+      #   @return [Float] Run timeout of the workflow (in seconds).
+      # @!attribute [r] search_attributes
+      #   @return [Hash<String, String>] Search attributes of the workflow.
+      # @!attribute [r] start_time
+      #   @return [Time] Start time of the workflow.
+      # @!attribute [r] task_queue
+      #   @return [String] Task queue of the workflow.
+      # @!attribute [r] task_timeout
+      #   @return [Float] Task timeout of the workflow (in seconds).
+      # @!attribute [r] workflow_id
+      #   @return [String] ID of the workflow.
+      # @!attribute [r] workflow_type
+      #   @return [String] Type of the workflow.
+    end
+  end
+end