temporalio 0.1.1 → 0.3.0

data/lib/temporalio/testing/workflow_environment.rb

@@ -1,112 +1,383 @@
-require 'google/protobuf/well_known_types'
+# frozen_string_literal: true
+
+require 'delegate'
+require 'temporalio/api'
+require 'temporalio/api/testservice/v1/request_response'
 require 'temporalio/client'
-require 'temporalio/testing/time_skipping_interceptor'
+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'
 
 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.
+    # Test environment with a Temporal server for running workflows and more.
     class WorkflowEnvironment
-      # @return [Temporalio::Connection] A connection to this environment.
-      attr_reader :connection
-
-      # @return [String] A namespace for this environment.
-      attr_reader :namespace
+      # @return [Client] Client for the server.
+      attr_reader :client
 
-      # @api private
-      def initialize(server, connection, namespace)
-        @server = server
-        @connection = connection
-        @namespace = namespace
-      end
-
-      # A default client to be used with this environment.
+      # Start a local dev server. This is a full Temporal dev server from the CLI that by default downloaded to tmp if
+      # not already present. The dev server is run as a child process. All options that start with +dev_server_+ are for
+      # this specific implementation and therefore are not stable and may be changed as the underlying implementation
+      # changes.
       #
-      # @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
+      # 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 namespace [String] Namespace for the server.
+      # @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 ip [String] IP to bind to.
+      # @param port [Integer, nil] Port to bind on, or +nil+ for random.
+      # @param ui [Boolean] If +true+, also starts the UI.
+      # @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.
+      # @param dev_server_database_filename [String, nil] Persistent SQLite filename to use across local server runs.
+      #   Default of +nil+ means in-memory only.
+      # @param dev_server_log_format [String] Log format for CLI dev server.
+      # @param dev_server_log_level [String] Log level for CLI dev server.
+      # @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.
+      #
+      # @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_local(
+        namespace: 'default',
+        data_converter: Converters::DataConverter.default,
+        interceptors: [],
+        logger: Logger.new($stdout, level: Logger::WARN),
+        default_workflow_query_reject_condition: nil,
+        ip: '127.0.0.1',
+        port: nil,
+        ui: false, # rubocop:disable Naming/MethodParameterName
+        runtime: Runtime.default,
+        dev_server_existing_path: nil,
+        dev_server_database_filename: nil,
+        dev_server_log_format: 'pretty',
+        dev_server_log_level: 'warn',
+        dev_server_download_version: 'default',
+        dev_server_download_dest_dir: nil,
+        dev_server_extra_args: [],
+        &
+      )
+        server_options = Internal::Bridge::Testing::EphemeralServer::StartDevServerOptions.new(
+          existing_path: dev_server_existing_path,
+          sdk_name: 'sdk-ruby',
+          sdk_version: VERSION,
+          download_version: dev_server_download_version,
+          download_dest_dir: dev_server_download_dest_dir,
+          namespace:,
+          ip:,
+          port:,
+          database_filename: dev_server_database_filename,
+          ui:,
+          log_format: dev_server_log_format,
+          log_level: dev_server_log_level,
+          extra_args: dev_server_extra_args
+        )
+        _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
 
-      # Sleep in this environment.
+      # 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.
       #
-      # This awaits a regular {Kernel.sleep} in regular environments, or manually skips time in
-      # time-skipping environments.
+      # 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 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),
+      # @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
         )
-        connection.test_service.unlock_time_skipping_with_sleep(request)
+      end
 
-        nil
+      # @!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(
+            core_server.target,
+            namespace,
+            data_converter:,
+            interceptors:,
+            logger:,
+            default_workflow_query_reject_condition:,
+            runtime:
+          )
+          server = Ephemeral.new(client, core_server, supports_time_skipping:)
+        rescue Exception # rubocop:disable Lint/RescueException
+          core_server.shutdown
+          raise
+        end
+        if block_given?
+          begin
+            yield server
+          ensure
+            server.shutdown
+          end
+        else
+          server
+        end
       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.
+      # Create workflow environment to an existing server with the given client.
       #
-      # @return [Time]
-      def current_time
-        return Time.now unless supports_time_skipping?
+      # @param client [Client] Client to existing server.
+      def initialize(client)
+        @client = client
+      end
 
-        connection.test_service.get_current_time&.time&.to_time
+      # Shutdown this workflow environment.
+      def shutdown
+        # Do nothing by default
       end
 
-      # Whether this environment supports time skipping.
-      #
-      # @return [Boolean]
+      # @return [Boolean] Whether this environment supports time skipping.
       def supports_time_skipping?
-        server.has_test_service?
+        false
       end
 
-      # Shut down this environment.
-      def shutdown
-        server.shutdown
+      # 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
 
-      # Unlock time skipping.
+      # Current time of the environment.
       #
-      # This will have no effect in an environment that does not support time-skipping (e.g.
-      # Temporalite).
+      # 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}.
       #
-      # @yield A block to be called once time skipping has been unlocked.
+      # @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.
       #
-      # @return [any] The return value of the block.
-      def with_time_skipping
-        return yield unless supports_time_skipping?
+      # @yield Block to run.
+      # @return [Object] Result of the block.
+      def auto_time_skipping_disabled(&)
+        raise 'Block required' unless block_given?
 
-        begin
-          # Unlock to start time skipping, lock again to stop it
-          connection.test_service.unlock_time_skipping(
-            Temporalio::Api::TestService::V1::UnlockTimeSkippingRequest.new,
+        yield
+      end
+
+      # @!visibility private
+      class Ephemeral < WorkflowEnvironment
+        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
 
-          yield
-        ensure
-          connection.test_service.lock_time_skipping(
-            Temporalio::Api::TestService::V1::LockTimeSkippingRequest.new,
+        # @!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
+      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
 
-      attr_reader :server
+      private_constant :TimeSkippingClientInterceptor
     end
   end
 end

data/lib/temporalio/testing.rb

@@ -1,175 +1,10 @@
-require 'temporalio/bridge'
-require 'temporalio/connection'
-require 'temporalio/runtime'
+# frozen_string_literal: true
+
+require 'temporalio/testing/activity_environment'
 require 'temporalio/testing/workflow_environment'
-require 'temporalio/version'
 
 module Temporalio
+  # Module for all testing environments.
   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,5 @@
+# frozen_string_literal: true
+
 module Temporalio
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.3.0'
 end