temporalio 0.2.0 → 0.4.0

data/lib/temporalio/testing/activity_environment.rb

@@ -13,8 +13,8 @@ module Temporalio
     # 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}.
+      # @return [Activity::Info] The activity info used by default. This is frozen, but `with` can be used to make a new
+      #   instance with changes to pass in to {initialize}.
       def self.default_info
         @default_info ||= Activity::Info.new(
           activity_id: 'test',
@@ -34,12 +34,13 @@ module Temporalio
           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 info [Activity::Info] Value for {Activity::Context#info}. Users should not try to instantiate this
+      #   themselves, but rather use `with` on {default_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}.
@@ -47,6 +48,9 @@ module Temporalio
       # @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.
+      # @param metric_meter [Metric::Meter, nil] Value for {Activity::Context#metric_meter}, or nil to raise when
+      #   called.
+      # @param client [Client, nil] Value for {Activity::Context#client}, or nil to raise when called.
       def initialize(
         info: ActivityEnvironment.default_info,
         on_heartbeat: nil,
@@ -54,7 +58,9 @@ module Temporalio
         worker_shutdown_cancellation: Cancellation.new,
         payload_converter: Converters::PayloadConverter.default,
         logger: Logger.new(nil),
-        activity_executors: Worker::ActivityExecutor.defaults
+        activity_executors: Worker::ActivityExecutor.defaults,
+        metric_meter: nil,
+        client: nil
       )
         @info = info
         @on_heartbeat = on_heartbeat
@@ -63,15 +69,17 @@ module Temporalio
         @payload_converter = payload_converter
         @logger = logger
         @activity_executors = activity_executors
+        @metric_meter = metric_meter
+        @client = client
       end
 
       # Run an activity and returns its result or raises its exception.
       #
-      # @param activity [Activity, Class<Activity>, Activity::Definition] Activity to run.
+      # @param activity [Activity::Definition, Class<Activity::Definition>, Activity::Definition::Info] Activity to run.
       # @param args [Array<Object>] Arguments to the activity.
       # @return Activity result.
       def run(activity, *args)
-        defn = Activity::Definition.from_activity(activity)
+        defn = Activity::Definition::Info.from_activity(activity)
         executor = @activity_executors[defn.executor]
         raise ArgumentError, "Unknown executor: #{defn.executor}" if executor.nil?
 
@@ -80,14 +88,18 @@ module Temporalio
           Activity::Context._current_executor = executor
           executor.set_activity_context(defn, Context.new(
                                                 info: @info.dup,
+                                                instance:
+                                                  defn.instance.is_a?(Proc) ? defn.instance.call : defn.instance,
                                                 on_heartbeat: @on_heartbeat,
                                                 cancellation: @cancellation,
                                                 worker_shutdown_cancellation: @worker_shutdown_cancellation,
                                                 payload_converter: @payload_converter,
-                                                logger: @logger
+                                                logger: @logger,
+                                                metric_meter: @metric_meter,
+                                                client: @client
                                               ))
           queue.push([defn.proc.call(*args), nil])
-        rescue Exception => e # rubocop:disable Lint/RescueException Intentionally capturing all exceptions
+        rescue Exception => e # rubocop:disable Lint/RescueException -- Intentionally capturing all exceptions
           queue.push([nil, e])
         ensure
           executor.set_activity_context(defn, nil)
@@ -102,28 +114,44 @@ module Temporalio
 
       # @!visibility private
       class Context < Activity::Context
-        attr_reader :info, :cancellation, :worker_shutdown_cancellation, :payload_converter, :logger
+        attr_reader :info, :instance, :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:,
+          instance:,
+          on_heartbeat:,
+          cancellation:,
+          worker_shutdown_cancellation:,
+          payload_converter:,
+          logger:,
+          metric_meter:,
+          client:
         )
           @info = info
+          @instance = instance
           @on_heartbeat = on_heartbeat
           @cancellation = cancellation
           @worker_shutdown_cancellation = worker_shutdown_cancellation
           @payload_converter = payload_converter
           @logger = logger
+          @metric_meter = metric_meter
+          @client = client
         end
 
         # @!visibility private
         def heartbeat(*details)
           @on_heartbeat&.call(details)
         end
+
+        # @!visibility private
+        def metric_meter
+          @metric_meter or raise 'No metric meter configured in this test environment'
+        end
+
+        # @!visibility private
+        def client
+          @client or raise 'No client configured in this test environment'
+        end
       end
 
       private_constant :Context

data/lib/temporalio/testing/workflow_environment.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
+require 'delegate'
+require 'temporalio/api'
+require 'temporalio/api/testservice/v1/request_response'
 require 'temporalio/client'
+require 'temporalio/client/connection/test_service'
+require 'temporalio/client/workflow_handle'
 require 'temporalio/converters'
 require 'temporalio/internal/bridge/testing'
+require 'temporalio/internal/proto_utils'
 require 'temporalio/runtime'
+require 'temporalio/search_attributes'
 require 'temporalio/version'
 
 module Temporalio
@@ -28,8 +35,10 @@ module Temporalio
       # @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 port [Integer, nil] Port to bind on, or `nil` for random.
       # @param ui [Boolean] If +true+, also starts the UI.
+      # @param ui_port [Integer, nil] Port to bind on if `ui` is true, or `nil` for random.
+      # @param search_attributes [Array<SearchAttributes::Key>] Search attributes to make available on start.
       # @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.
@@ -40,6 +49,8 @@ module Temporalio
       # @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.
+      # @param dev_server_download_ttl [Float, nil] How long the automatic download should be cached for. If nil, cached
+      #   indefinitely.
       #
       # @yield [environment] If a block is given, it is called with the environment and upon complete the environment is
       #   shutdown.
@@ -56,6 +67,8 @@ module Temporalio
         ip: '127.0.0.1',
         port: nil,
         ui: false, # rubocop:disable Naming/MethodParameterName
+        ui_port: nil,
+        search_attributes: [],
         runtime: Runtime.default,
         dev_server_existing_path: nil,
         dev_server_database_filename: nil,
@@ -63,8 +76,19 @@ module Temporalio
         dev_server_log_level: 'warn',
         dev_server_download_version: 'default',
         dev_server_download_dest_dir: nil,
-        dev_server_extra_args: []
+        dev_server_extra_args: [],
+        dev_server_download_ttl: nil,
+        &
       )
+        # Add search attribute args
+        unless search_attributes.empty?
+          dev_server_extra_args += search_attributes.flat_map do |key|
+            raise 'Search attribute must be Key' unless key.is_a?(SearchAttributes::Key)
+
+            ['--search-attribute', "#{key.name}=#{SearchAttributes::IndexedValueType::PROTO_NAMES[key.type]}"]
+          end
+        end
+
         server_options = Internal::Bridge::Testing::EphemeralServer::StartDevServerOptions.new(
           existing_path: dev_server_existing_path,
           sdk_name: 'sdk-ruby',
@@ -76,11 +100,106 @@ module Temporalio
           port:,
           database_filename: dev_server_database_filename,
           ui:,
+          ui_port: ui ? ui_port : nil,
           log_format: dev_server_log_format,
           log_level: dev_server_log_level,
-          extra_args: dev_server_extra_args
+          extra_args: dev_server_extra_args,
+          download_ttl: dev_server_download_ttl
+        )
+        _with_core_server(
+          core_server: Internal::Bridge::Testing::EphemeralServer.start_dev_server(
+            runtime._core_runtime, server_options
+          ),
+          namespace:,
+          data_converter:,
+          interceptors:,
+          logger:,
+          default_workflow_query_reject_condition:,
+          runtime:,
+          supports_time_skipping: false,
+          & # steep:ignore
         )
-        core_server = Internal::Bridge::Testing::EphemeralServer.start_dev_server(runtime._core_runtime, server_options)
+      end
+
+      # Start a time-skipping test server. This server can skip time but may not have all of the Temporal features of
+      # the {start_local} form. By default, the server is downloaded to tmp if not already present. The test server is
+      # run as a child process. All options that start with +test_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 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 port [Integer, nil] Port to bind on, or +nil+ for random.
+      # @param runtime [Runtime] Runtime for the server and client.
+      # @param test_server_existing_path [String, nil] Existing CLI path to use instead of downloading and caching to
+      #   tmp.
+      # @param test_server_download_version [String] Version of test server to download and cache.
+      # @param test_server_download_dest_dir [String, nil] Where to download. Defaults to tmp.
+      # @param test_server_extra_args [Array<String>] Any extra arguments for the test server.
+      # @param test_server_download_ttl [Float, nil] How long the automatic download should be cached for. If nil,
+      #   cached indefinitely.
+      #
+      # @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_time_skipping(
+        data_converter: Converters::DataConverter.default,
+        interceptors: [],
+        logger: Logger.new($stdout, level: Logger::WARN),
+        default_workflow_query_reject_condition: nil,
+        port: nil,
+        runtime: Runtime.default,
+        test_server_existing_path: nil,
+        test_server_download_version: 'default',
+        test_server_download_dest_dir: nil,
+        test_server_extra_args: [],
+        test_server_download_ttl: nil,
+        &
+      )
+        server_options = Internal::Bridge::Testing::EphemeralServer::StartTestServerOptions.new(
+          existing_path: test_server_existing_path,
+          sdk_name: 'sdk-ruby',
+          sdk_version: VERSION,
+          download_version: test_server_download_version,
+          download_dest_dir: test_server_download_dest_dir,
+          port:,
+          extra_args: test_server_extra_args,
+          download_ttl: test_server_download_ttl
+        )
+        _with_core_server(
+          core_server: Internal::Bridge::Testing::EphemeralServer.start_test_server(
+            runtime._core_runtime, server_options
+          ),
+          namespace: 'default',
+          data_converter:,
+          interceptors:,
+          logger:,
+          default_workflow_query_reject_condition:,
+          runtime:,
+          supports_time_skipping: true,
+          & # steep:ignore
+        )
+      end
+
+      # @!visibility private
+      def self._with_core_server(
+        core_server:,
+        namespace:,
+        data_converter:,
+        interceptors:,
+        logger:,
+        default_workflow_query_reject_condition:,
+        runtime:,
+        supports_time_skipping:
+      )
         # Try to connect, shutdown if we can't
         begin
           client = Client.connect(
@@ -92,8 +211,8 @@ module Temporalio
             default_workflow_query_reject_condition:,
             runtime:
           )
-          server = Ephemeral.new(client, core_server)
-        rescue StandardError
+          server = Ephemeral.new(client, core_server, supports_time_skipping:)
+        rescue Exception # rubocop:disable Lint/RescueException
           core_server.shutdown
           raise
         end
@@ -120,18 +239,168 @@ module Temporalio
         # Do nothing by default
       end
 
+      # @return [Boolean] Whether this environment supports time skipping.
+      def supports_time_skipping?
+        false
+      end
+
+      # Advanced time.
+      #
+      # If this server supports time skipping, this will immediately advance time and return. If it does not, this is
+      # a standard {::sleep}.
+      #
+      # @param duration [Float] Duration seconds.
+      def sleep(duration)
+        Kernel.sleep(duration)
+      end
+
+      # Current time of the environment.
+      #
+      # If this server supports time skipping, this will be the current time as known to the environment. If it does
+      # not, this is a standard {::Time.now}.
+      #
+      # @return [Time] Current time.
+      def current_time
+        Time.now
+      end
+
+      # Run a block with automatic time skipping disabled. This just runs the block for environments that don't support
+      # time skipping.
+      #
+      # @yield Block to run.
+      # @return [Object] Result of the block.
+      def auto_time_skipping_disabled(&)
+        raise 'Block required' unless block_given?
+
+        yield
+      end
+
       # @!visibility private
       class Ephemeral < WorkflowEnvironment
-        def initialize(client, core_server)
+        def initialize(client, core_server, supports_time_skipping:)
+          # Add our interceptor at the end of the existing interceptors that skips time
+          client_options = client.options.with(
+            interceptors: client.options.interceptors + [TimeSkippingClientInterceptor.new(self)]
+          )
+          client = Client.new(**client_options.to_h) # steep:ignore
           super(client)
+
+          @auto_time_skipping = true
           @core_server = core_server
+          @test_service = Client::Connection::TestService.new(client.connection) if supports_time_skipping
         end
 
         # @!visibility private
         def shutdown
           @core_server.shutdown
         end
+
+        # @!visibility private
+        def supports_time_skipping?
+          !@test_service.nil?
+        end
+
+        # @!visibility private
+        def sleep(duration)
+          return super unless supports_time_skipping?
+
+          @test_service.unlock_time_skipping_with_sleep(
+            Api::TestService::V1::SleepRequest.new(duration: Internal::ProtoUtils.seconds_to_duration(duration))
+          )
+        end
+
+        # @!visibility private
+        def current_time
+          return super unless supports_time_skipping?
+
+          resp = @test_service.get_current_time(Google::Protobuf::Empty.new)
+          Internal::ProtoUtils.timestamp_to_time(resp.time) or raise 'Time missing'
+        end
+
+        # @!visibility private
+        def auto_time_skipping_disabled(&)
+          raise 'Block required' unless block_given?
+          return super unless supports_time_skipping?
+
+          already_disabled = @auto_time_skipping
+          @auto_time_skipping = false
+          begin
+            yield
+          ensure
+            @auto_time_skipping = true unless already_disabled
+          end
+        end
+
+        # @!visibility private
+        def time_skipping_unlocked(&)
+          # If disabled or unsupported, no locking/unlocking, just run and return
+          return yield if !supports_time_skipping? || !@auto_time_skipping
+
+          # Unlock to start time skipping, lock again to stop it
+          @test_service.unlock_time_skipping(Api::TestService::V1::UnlockTimeSkippingRequest.new)
+          user_code_success = false
+          begin
+            result = yield
+            user_code_success = true
+            result
+          ensure
+            # Lock it back
+            begin
+              @test_service.lock_time_skipping(Api::TestService::V1::LockTimeSkippingRequest.new)
+            rescue StandardError => e
+              # Re-raise if user code succeeded, otherwise swallow
+              raise if user_code_success
+
+              client.options.logger.error('Failed locking time skipping after error')
+              client.options.logger.error(e)
+            end
+          end
+        end
       end
+
+      private_constant :Ephemeral
+
+      # @!visibility private
+      class TimeSkippingClientInterceptor
+        include Client::Interceptor
+
+        def initialize(env)
+          @env = env
+        end
+
+        # @!visibility private
+        def intercept_client(next_interceptor)
+          Outbound.new(next_interceptor, @env)
+        end
+
+        # @!visibility private
+        class Outbound < Client::Interceptor::Outbound
+          def initialize(next_interceptor, env)
+            super(next_interceptor)
+            @env = env
+          end
+
+          # @!visibility private
+          def start_workflow(input)
+            TimeSkippingWorkflowHandle.new(super, @env)
+          end
+        end
+
+        # @!visibility private
+        class TimeSkippingWorkflowHandle < SimpleDelegator
+          def initialize(handle, env)
+            super(handle) # steep:ignore
+            @env = env
+          end
+
+          # @!visibility private
+          def result(follow_runs: true, rpc_options: nil)
+            @env.time_skipping_unlocked { super(follow_runs:, rpc_options:) }
+          end
+        end
+      end
+
+      private_constant :TimeSkippingClientInterceptor
     end
   end
 end

data/lib/temporalio/version.rb

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