temporalio 0.0.2 → 0.1.0

data/lib/temporalio/interceptor/activity_inbound.rb

@@ -0,0 +1,22 @@
+module Temporalio
+  module Interceptor
+    # A mixin for implementing inbound Activity interceptors.
+    module ActivityInbound
+      class ExecuteActivityInput < Struct.new(
+        :activity,
+        :args,
+        :headers,
+        keyword_init: true,
+      ); end
+
+      # Interceptor for {Temporalio::Activity#execute}.
+      #
+      # @param input [ExecuteActivityInput]
+      #
+      # @return [any] Activity execution result
+      def execute_activity(input)
+        yield(input)
+      end
+    end
+  end
+end

data/lib/temporalio/interceptor/activity_outbound.rb

@@ -0,0 +1,24 @@
+module Temporalio
+  module Interceptor
+    # A mixin for implementing outbound Activity interceptors.
+    module ActivityOutbound
+      # Interceptor for {Temporalio::Activity::Context#info}.
+      #
+      # @yieldreturn Temporalio::Activity::Info
+      #
+      # @return [Temporalio::Activity::Info]
+      def activity_info
+        yield
+      end
+
+      # Interceptor for {Temporalio::Activity::Context#heartbeat}.
+      #
+      # @yieldparam Array[untyped]
+      #
+      # @param details [any] A list of details supplied with the heartbeat.
+      def heartbeat(*details)
+        yield(*details)
+      end
+    end
+  end
+end

data/lib/temporalio/interceptor/chain.rb

@@ -6,18 +6,18 @@ module Temporalio
         @interceptors = interceptors
       end
 
-      def invoke(method, input)
+      def invoke(method, *input)
         chain = interceptors.dup
 
-        traverse_chain = lambda do |i|
+        traverse_chain = lambda do |*i|
           if chain.empty?
-            yield(i)
+            yield(*i)
           else
-            chain.shift.public_send(method, i, &traverse_chain)
+            chain.shift.public_send(method, *i, &traverse_chain)
           end
         end
 
-        traverse_chain.call(input)
+        traverse_chain.call(*input)
       end
 
       private

data/lib/temporalio/interceptor/client.rb

@@ -1,9 +1,7 @@
 module Temporalio
   module Interceptor
-    # Base class for implementing Client side interceptors.
-    #
-    # @abstract
-    class Client
+    # A mixin for implementing Client side interceptors.
+    module Client
       class StartWorkflowInput < Struct.new(
         :workflow,
         :args,
@@ -80,6 +78,8 @@ module Temporalio
       # Interceptor for {Temporalio::Client#start_workflow}.
       #
       # @param input [StartWorkflowInput]
+      #
+      # @return [Temporalio::Client::WorkflowHandle] A handle to interact with the workflow.
       def start_workflow(input)
         yield(input)
       end
@@ -87,6 +87,8 @@ module Temporalio
       # Interceptor for {Temporalio::Client::WorkflowHandle#describe}.
       #
       # @param input [DescribeWorkflowInput]
+      #
+      # @return [Temporalio::Workflow::ExecutionInfo] Information about the workflow.
       def describe_workflow(input)
         yield(input)
       end
@@ -94,6 +96,8 @@ module Temporalio
       # Interceptor for {Temporalio::Client::WorkflowHandle#query}.
       #
       # @param input [QueryWorkflowInput]
+      #
+      # @return [any] Query result
       def query_workflow(input)
         yield(input)
       end

data/lib/temporalio/interceptor.rb

@@ -0,0 +1,22 @@
+require 'temporalio/interceptor/activity_inbound'
+require 'temporalio/interceptor/activity_outbound'
+
+module Temporalio
+  module Interceptor
+    # NOTE: Using #each_with_object here and below instead of a simple #select because RBS can't
+    #       reconcile that resulting array only has WorkflowInbound or WorkflowOutbound in it.
+    def self.filter(interceptors, type)
+      interceptor_class =
+        case type
+        when :activity_inbound
+          Temporalio::Interceptor::ActivityInbound
+        when :activity_outbound
+          Temporalio::Interceptor::ActivityOutbound
+        end
+
+      interceptors.each_with_object([]) do |i, result|
+        result << i if i.is_a?(interceptor_class)
+      end
+    end
+  end
+end

data/lib/temporalio/retry_policy.rb

@@ -24,13 +24,23 @@ module Temporalio
     # @return [Array<String>] List of error types that are not retryable.
     attr_reader :non_retriable_errors
 
+    def self.from_proto(proto)
+      new(
+        initial_interval: proto.initial_interval&.to_f&.round || 0,
+        backoff: proto.backoff_coefficient&.to_f || 0.0,
+        max_interval: proto.maximum_interval&.to_f&.round || 0,
+        max_attempts: proto.maximum_attempts || 1,
+        non_retriable_errors: proto.non_retryable_error_types || [],
+      ).freeze
+    end
+
     # @param initial_interval [Integer] Backoff interval (in seconds) for the first retry.
     # @param backoff [Float] Coefficient to multiply previous backoff interval by to get new
     #   interval.
     # @param max_interval [Integer] Maximum backoff interval between retries. Default 100x
     #   {#initial_interval}.
     # @param max_attempts [Integer] Maximum number of attempts. If 0, there is no maximum.
-    # @param non_retriable_errors [Array<String>] List of error types that are not retryable.
+    # @param non_retriable_errors [Array<Class, String>] List of error types that are not retryable.
     def initialize(
       initial_interval: 1,
       backoff: 2.0,
@@ -42,7 +52,7 @@ module Temporalio
       @backoff = backoff
       @max_interval = max_interval
       @max_attempts = max_attempts
-      @non_retriable_errors = non_retriable_errors
+      @non_retriable_errors = non_retriable_errors.map(&:to_s).compact
     end
 
     def validate!
@@ -75,7 +85,7 @@ module Temporalio
         backoff_coefficient: backoff,
         maximum_interval: max_interval ? Google::Protobuf::Duration.new(seconds: max_interval) : nil,
         maximum_attempts: max_attempts,
-        non_retryable_error_types: non_retriable_errors.map(&:name).compact,
+        non_retryable_error_types: non_retriable_errors,
       )
     end
   end

data/lib/temporalio/testing/time_skipping_handle.rb

@@ -0,0 +1,32 @@
+require 'forwardable'
+
+module Temporalio
+  module Testing
+    class TimeSkippingHandle
+      extend Forwardable
+
+      # Proxy all the WorkflowHandle calls to the original handle except for :result
+      def_delegators :handle, :id, :run_id, :result_run_id, :first_execution_run_id, :describe,
+                     :cancel, :query, :signal, :terminate
+
+      def initialize(handle, env)
+        @handle = handle
+        @env = env
+      end
+
+      def result(follow_runs: true, rpc_metadata: {}, rpc_timeout: nil)
+        env.with_time_skipping do
+          handle.result(
+            follow_runs: follow_runs,
+            rpc_metadata: rpc_metadata,
+            rpc_timeout: rpc_timeout,
+          )
+        end
+      end
+
+      private
+
+      attr_reader :handle, :env
+    end
+  end
+end

data/lib/temporalio/testing/time_skipping_interceptor.rb

@@ -0,0 +1,23 @@
+require 'temporalio/interceptor/client'
+require 'temporalio/testing/time_skipping_handle'
+
+module Temporalio
+  module Testing
+    class TimeSkippingInterceptor
+      include Temporalio::Interceptor::Client
+
+      def initialize(env)
+        @env = env
+      end
+
+      def start_workflow(input)
+        handle = yield(input)
+        Temporalio::Testing::TimeSkippingHandle.new(handle, env)
+      end
+
+      private
+
+      attr_reader :env
+    end
+  end
+end

data/lib/temporalio/testing/workflow_environment.rb

@@ -0,0 +1,112 @@
+require 'google/protobuf/well_known_types'
+require 'temporalio/client'
+require 'temporalio/testing/time_skipping_interceptor'
+
+module Temporalio
+  module Testing
+    # Workflow environment for testing workflows.
+    #
+    # Most developers will want to use the {Temporalio::Testing.start_time_skipping_environment} to
+    # start a test server process that automatically skips time as needed. Alternatively,
+    # {Temporalio::Testing.start_local_environment} may be used for a full, local Temporal server
+    # with more features.
+    #
+    # @note Unless using the above mentioned methods with an explicit block, you will need to call
+    # {#shutdown} after you're finished with this environment.
+    class WorkflowEnvironment
+      # @return [Temporalio::Connection] A connection to this environment.
+      attr_reader :connection
+
+      # @return [String] A namespace for this environment.
+      attr_reader :namespace
+
+      # @api private
+      def initialize(server, connection, namespace)
+        @server = server
+        @connection = connection
+        @namespace = namespace
+      end
+
+      # A default client to be used with this environment.
+      #
+      # @return [Temporalio::Client] A default client.
+      def client
+        @client ||= begin
+          # TODO: Add a workflow interceptor for interpreting assertion error
+          interceptors = [TimeSkippingInterceptor.new(self)]
+          Temporalio::Client.new(connection, namespace, interceptors: interceptors)
+        end
+      end
+
+      # Sleep in this environment.
+      #
+      # This awaits a regular {Kernel.sleep} in regular environments, or manually skips time in
+      # time-skipping environments.
+      #
+      # @param duration [Integer] Amount of time to sleep.
+      def sleep(duration)
+        return Kernel.sleep(duration) unless supports_time_skipping?
+
+        request = Temporalio::Api::TestService::V1::SleepRequest.new(
+          duration: Google::Protobuf::Duration.new(seconds: duration),
+        )
+        connection.test_service.unlock_time_skipping_with_sleep(request)
+
+        nil
+      end
+
+      # Get the current time known to this environment.
+      #
+      # For non-time-skipping environments this is simply the system time. For time-skipping
+      # environments this is whatever time has been skipped to.
+      #
+      # @return [Time]
+      def current_time
+        return Time.now unless supports_time_skipping?
+
+        connection.test_service.get_current_time&.time&.to_time
+      end
+
+      # Whether this environment supports time skipping.
+      #
+      # @return [Boolean]
+      def supports_time_skipping?
+        server.has_test_service?
+      end
+
+      # Shut down this environment.
+      def shutdown
+        server.shutdown
+      end
+
+      # Unlock time skipping.
+      #
+      # This will have no effect in an environment that does not support time-skipping (e.g.
+      # Temporalite).
+      #
+      # @yield A block to be called once time skipping has been unlocked.
+      #
+      # @return [any] The return value of the block.
+      def with_time_skipping
+        return yield unless supports_time_skipping?
+
+        begin
+          # Unlock to start time skipping, lock again to stop it
+          connection.test_service.unlock_time_skipping(
+            Temporalio::Api::TestService::V1::UnlockTimeSkippingRequest.new,
+          )
+
+          yield
+        ensure
+          connection.test_service.lock_time_skipping(
+            Temporalio::Api::TestService::V1::LockTimeSkippingRequest.new,
+          )
+        end
+      end
+
+      private
+
+      attr_reader :server
+    end
+  end
+end

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/temporalio/version.rb

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

data/lib/temporalio/worker/activity_runner.rb

@@ -3,6 +3,7 @@ require 'temporalio/activity/context'
 require 'temporalio/activity/info'
 require 'temporalio/error/failure'
 require 'temporalio/errors'
+require 'temporalio/interceptor/activity_inbound'
 
 module Temporalio
   class Worker
@@ -12,20 +13,39 @@ module Temporalio
     #
     # @api private
     class ActivityRunner
-      def initialize(activity_class, start, task_queue, task_token, worker, converter)
+      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)
-        input = converter.from_payload_array(start.input.to_a)
+        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 = activity.execute(*input)
+        result = inbound_interceptors.invoke(:execute_activity, input) do |i|
+          activity.execute(*i.args)
+        end
 
         converter.to_payload(result)
       rescue StandardError => e
@@ -48,7 +68,8 @@ module Temporalio
 
       private
 
-      attr_reader :activity_class, :start, :task_queue, :task_token, :worker, :converter
+      attr_reader :activity_class, :start, :task_queue, :task_token, :worker, :converter,
+                  :inbound_interceptors, :outbound_interceptors
 
       def context
         return @context if @context
@@ -57,6 +78,7 @@ module Temporalio
         @context = Temporalio::Activity::Context.new(
           generate_activity_info,
           heartbeat_proc,
+          outbound_interceptors,
           shielded: activity_class._shielded,
         )
       end