temporalio 0.2.0 → 0.3.0

data/lib/temporalio/search_attributes.rb

@@ -7,7 +7,7 @@ module Temporalio
   #
   # This is represented as a mapping of {SearchAttributes::Key} to object values. This is not a hash though it does have
   # a few hash-like methods and can be converted to a hash via {#to_h}. In some situations, such as in workflows, this
-  # class is frozen.
+  # class is immutable for outside use.
   class SearchAttributes
     # Key for a search attribute.
     class Key
@@ -20,7 +20,7 @@ module Temporalio
       def initialize(name, type)
         raise ArgumentError, 'Invalid type' unless Api::Enums::V1::IndexedValueType.lookup(type)
 
-        @name = name
+        @name = name.to_s
         @type = type
       end
 
@@ -104,28 +104,54 @@ module Temporalio
         @key = key
         @value = value
       end
+
+      # @!visibility private
+      def _to_proto_pair
+        SearchAttributes._to_proto_pair(key, value)
+      end
     end
 
     # @!visibility private
-    def self.from_proto(proto)
-      return nil unless proto
-      raise ArgumentError, 'Expected proto search attribute' unless proto.is_a?(Api::Common::V1::SearchAttributes)
-
-      SearchAttributes.new(proto.indexed_fields.map do |key_name, payload| # rubocop:disable Style/MapToHash
-        key = Key.new(key_name, IndexedValueType::PROTO_VALUES[payload.metadata['type']])
-        value = value_from_payload(payload)
-        [key, value]
-      end.to_h)
+    def self._from_proto(proto, disable_mutations: false, never_nil: false)
+      return nil unless proto || never_nil
+
+      attrs = if proto
+                unless proto.is_a?(Api::Common::V1::SearchAttributes)
+                  raise ArgumentError, 'Expected proto search attribute'
+                end
+
+                SearchAttributes.new(proto.indexed_fields.map do |key_name, payload| # rubocop:disable Style/MapToHash
+                  key = Key.new(key_name, IndexedValueType::PROTO_VALUES[payload.metadata['type']])
+                  value = _value_from_payload(payload)
+                  [key, value]
+                end.to_h)
+              else
+                SearchAttributes.new
+              end
+      attrs._disable_mutations = disable_mutations
+      attrs
     end
 
     # @!visibility private
-    def self.value_from_payload(payload)
+    def self._value_from_payload(payload)
       value = Converters::PayloadConverter.default.from_payload(payload)
       # Time needs to be converted
       value = Time.iso8601(value) if payload.metadata['type'] == 'DateTime' && value.is_a?(String)
       value
     end
 
+    # @!visibility private
+    def self._to_proto_pair(key, value)
+      # We use a default converter, but if type is a time, we need ISO format
+      value = value.iso8601 if key.type == IndexedValueType::TIME && value.is_a?(Time)
+
+      # Convert to payload
+      payload = Converters::PayloadConverter.default.to_payload(value)
+      payload.metadata['type'] = IndexedValueType::PROTO_NAMES[key.type]
+
+      [key.name, payload]
+    end
+
     # Create a search attribute collection.
     #
     # @param existing [SearchAttributes, Hash<Key, Object>, nil] Existing collection. This can be another
@@ -149,6 +175,7 @@ module Temporalio
     # @param key [Key] A key to set. This must be a {Key} and the value must be proper for the {Key#type}.
     # @param value [Object, nil] The value to set. If `nil`, the key is removed. The value must be proper for the `key`.
     def []=(key, value)
+      _assert_mutations_enabled
       # Key must be a Key
       raise ArgumentError, 'Key must be a key' unless key.is_a?(Key)
 
@@ -162,33 +189,37 @@ module Temporalio
 
     # Get a search attribute value for a key.
     #
-    # @param key [Key, String] The key to find. If this is a {Key}, it will use key equality (i.e. name and type) to
-    #   search. If this is a {::String}, the type is not checked when finding the proper key.
+    # @param key [Key, String, Symbol] The key to find. If this is a {Key}, it will use key equality (i.e. name and
+    #   type) to search. If this is a {::String}, the type is not checked when finding the proper key.
     # @return [Object, nil] Value if found or `nil` if not.
     def [](key)
       # Key must be a Key or a string
-      if key.is_a?(Key)
+      case key
+      when Key
         @raw_hash[key]
-      elsif key.is_a?(String)
-        @raw_hash.find { |hash_key, _| hash_key.name == key }&.last
+      when String, Symbol
+        @raw_hash.find { |hash_key, _| hash_key.name == key.to_s }&.last
       else
-        raise ArgumentError, 'Key must be a key or string'
+        raise ArgumentError, 'Key must be a key or string/symbol'
       end
     end
 
     # Delete a search attribute key
     #
-    # @param key [Key, String] The key to delete. Regardless of whether this is a {Key} or a {::String}, the key with
-    #   the matching name will be deleted. This means a {Key} with a matching name but different type may be deleted.
+    # @param key [Key, String, Symbol] The key to delete. Regardless of whether this is a {Key} or a {::String}, the key
+    #   with the matching name will be deleted. This means a {Key} with a matching name but different type may be
+    #   deleted.
     def delete(key)
+      _assert_mutations_enabled
       # Key must be a Key or a string, but we delete all values for the
       # name no matter what
-      name = if key.is_a?(Key)
+      name = case key
+             when Key
                key.name
-             elsif key.is_a?(String)
-               key
+             when String, Symbol
+               key.to_s
              else
-               raise ArgumentError, 'Key must be a key or string'
+               raise ArgumentError, 'Key must be a key or string/symbol'
              end
       @raw_hash.delete_if { |hash_key, _| hash_key.name == name }
     end
@@ -205,7 +236,9 @@ module Temporalio
 
     # @return [SearchAttributes] Copy of the search attributes.
     def dup
-      SearchAttributes.new(self)
+      attrs = SearchAttributes.new(self)
+      attrs._disable_mutations = false
+      attrs
     end
 
     # @return [Boolean] Whether the set of attributes is empty.
@@ -225,6 +258,7 @@ module Temporalio
     # @param updates [Update] Updates created via {Key#value_set} or {Key#value_unset}.
     # @return [SearchAttributes] New collection.
     def update(*updates)
+      _assert_mutations_enabled
       attrs = dup
       attrs.update!(*updates)
       attrs
@@ -234,27 +268,36 @@ module Temporalio
     #
     # @param updates [Update] Updates created via {Key#value_set} or {Key#value_unset}.
     def update!(*updates)
+      _assert_mutations_enabled
       updates.each do |update|
         raise ArgumentError, 'Update must be an update' unless update.is_a?(Update)
 
-        self[update.key] = update.value
+        if update.value.nil?
+          delete(update.key)
+        else
+          self[update.key] = update.value
+        end
       end
     end
 
     # @!visibility private
-    def to_proto
-      Api::Common::V1::SearchAttributes.new(
-        indexed_fields: @raw_hash.to_h do |key, value|
-          # We use a default converter, but if type is a time, we need ISO format
-          value = value.iso8601 if key.type == IndexedValueType::TIME
+    def _to_proto
+      Api::Common::V1::SearchAttributes.new(indexed_fields: _to_proto_hash)
+    end
+
+    # @!visibility private
+    def _to_proto_hash
+      @raw_hash.to_h { |key, value| SearchAttributes._to_proto_pair(key, value) }
+    end
 
-          # Convert to payload
-          payload = Converters::PayloadConverter.default.to_payload(value)
-          payload.metadata['type'] = IndexedValueType::PROTO_NAMES[key.type]
+    # @!visibility private
+    def _assert_mutations_enabled
+      raise 'Search attribute mutations disabled' if @disable_mutations
+    end
 
-          [key.name, payload]
-        end
-      )
+    # @!visibility private
+    def _disable_mutations=(value)
+      @disable_mutations = value
     end
 
     # Type for a search attribute key/value.

data/lib/temporalio/testing/activity_environment.rb

@@ -67,11 +67,11 @@ module Temporalio
 
       # 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?
 

data/lib/temporalio/testing/workflow_environment.rb

@@ -1,8 +1,14 @@
 # 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/version'
 
@@ -63,7 +69,8 @@ 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: [],
+        &
       )
         server_options = Internal::Bridge::Testing::EphemeralServer::StartDevServerOptions.new(
           existing_path: dev_server_existing_path,
@@ -80,7 +87,96 @@ module Temporalio
           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)
+        _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
+        )
+      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.
+      #
+      # @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: [],
+        &
+      )
+        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
+        )
+        _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 +188,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 +216,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.3.0'
 end