temporalio 0.1.0 → 0.2.0

data/lib/temporalio/testing/activity_environment.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'temporalio/activity'
+require 'temporalio/cancellation'
+require 'temporalio/converters/payload_converter'
+require 'temporalio/worker/activity_executor'
+
+module Temporalio
+  module Testing
+    # Test environment for testing activities.
+    #
+    # Users can create this environment and then use {run} to execute activities on it. Often, since mutable things like
+    # 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}.
+      def self.default_info
+        @default_info ||= Activity::Info.new(
+          activity_id: 'test',
+          activity_type: 'unknown',
+          attempt: 1,
+          current_attempt_scheduled_time: Time.at(0),
+          heartbeat_details: [],
+          heartbeat_timeout: nil,
+          local?: false,
+          schedule_to_close_timeout: 1.0,
+          scheduled_time: Time.at(0),
+          start_to_close_timeout: 1.0,
+          started_time: Time.at(0),
+          task_queue: 'test',
+          task_token: String.new('test', encoding: Encoding::ASCII_8BIT),
+          workflow_id: 'test',
+          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 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}.
+      # @param worker_shutdown_cancellation [Cancellation] Value for {Activity::Context#worker_shutdown_cancellation}.
+      # @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.
+      def initialize(
+        info: ActivityEnvironment.default_info,
+        on_heartbeat: nil,
+        cancellation: Cancellation.new,
+        worker_shutdown_cancellation: Cancellation.new,
+        payload_converter: Converters::PayloadConverter.default,
+        logger: Logger.new(nil),
+        activity_executors: Worker::ActivityExecutor.defaults
+      )
+        @info = info
+        @on_heartbeat = on_heartbeat
+        @cancellation = cancellation
+        @worker_shutdown_cancellation = worker_shutdown_cancellation
+        @payload_converter = payload_converter
+        @logger = logger
+        @activity_executors = activity_executors
+      end
+
+      # Run an activity and returns its result or raises its exception.
+      #
+      # @param activity [Activity, Class<Activity>, Activity::Definition] Activity to run.
+      # @param args [Array<Object>] Arguments to the activity.
+      # @return Activity result.
+      def run(activity, *args)
+        defn = Activity::Definition.from_activity(activity)
+        executor = @activity_executors[defn.executor]
+        raise ArgumentError, "Unknown executor: #{defn.executor}" if executor.nil?
+
+        queue = Queue.new
+        executor.execute_activity(defn) do
+          Activity::Context._current_executor = executor
+          executor.set_activity_context(defn, Context.new(
+                                                info: @info.dup,
+                                                on_heartbeat: @on_heartbeat,
+                                                cancellation: @cancellation,
+                                                worker_shutdown_cancellation: @worker_shutdown_cancellation,
+                                                payload_converter: @payload_converter,
+                                                logger: @logger
+                                              ))
+          queue.push([defn.proc.call(*args), nil])
+        rescue Exception => e # rubocop:disable Lint/RescueException Intentionally capturing all exceptions
+          queue.push([nil, e])
+        ensure
+          executor.set_activity_context(defn, nil)
+          Activity::Context._current_executor = nil
+        end
+
+        result, err = queue.pop
+        raise err unless err.nil?
+
+        result
+      end
+
+      # @!visibility private
+      class Context < Activity::Context
+        attr_reader :info, :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 = info
+          @on_heartbeat = on_heartbeat
+          @cancellation = cancellation
+          @worker_shutdown_cancellation = worker_shutdown_cancellation
+          @payload_converter = payload_converter
+          @logger = logger
+        end
+
+        # @!visibility private
+        def heartbeat(*details)
+          @on_heartbeat&.call(details)
+        end
+      end
+
+      private_constant :Context
+    end
+  end
+end

data/lib/temporalio/testing/workflow_environment.rb

@@ -1,112 +1,137 @@
-require 'google/protobuf/well_known_types'
+# frozen_string_literal: true
+
 require 'temporalio/client'
-require 'temporalio/testing/time_skipping_interceptor'
+require 'temporalio/converters'
+require 'temporalio/internal/bridge/testing'
+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
-
-      # @api private
-      def initialize(server, connection, namespace)
-        @server = server
-        @connection = connection
-        @namespace = namespace
-      end
+      # @return [Client] Client for the server.
+      attr_reader :client
 
-      # 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
-      end
-
-      # Sleep in this environment.
+      # 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.
       #
-      # This awaits a regular {Kernel.sleep} in regular environments, or manually skips time in
-      # time-skipping environments.
+      # @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.
       #
-      # @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.
+      # @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.
       #
-      # 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
+      # @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
+        )
+        core_server = Internal::Bridge::Testing::EphemeralServer.start_dev_server(runtime._core_runtime, server_options)
+        # 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)
+        rescue StandardError
+          core_server.shutdown
+          raise
+        end
+        if block_given?
+          begin
+            yield server
+          ensure
+            server.shutdown
+          end
+        else
+          server
+        end
       end
 
-      # Whether this environment supports time skipping.
+      # Create workflow environment to an existing server with the given client.
       #
-      # @return [Boolean]
-      def supports_time_skipping?
-        server.has_test_service?
+      # @param client [Client] Client to existing server.
+      def initialize(client)
+        @client = client
       end
 
-      # Shut down this environment.
+      # Shutdown this workflow environment.
       def shutdown
-        server.shutdown
+        # Do nothing by default
       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,
-          )
+      # @!visibility private
+      class Ephemeral < WorkflowEnvironment
+        def initialize(client, core_server)
+          super(client)
+          @core_server = core_server
+        end
 
-          yield
-        ensure
-          connection.test_service.lock_time_skipping(
-            Temporalio::Api::TestService::V1::LockTimeSkippingRequest.new,
-          )
+        # @!visibility private
+        def shutdown
+          @core_server.shutdown
         end
       end
-
-      private
-
-      attr_reader :server
     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.0'.freeze
+  VERSION = '0.2.0'
 end

data/lib/temporalio/worker/activity_executor/fiber.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'temporalio/error'
+require 'temporalio/worker/activity_executor'
+
+module Temporalio
+  class Worker
+    class ActivityExecutor
+      # Activity executor for scheduling activites as fibers.
+      class Fiber
+        # @return [Fiber] Default/shared Fiber executor instance.
+        def self.default
+          @default ||= new
+        end
+
+        # @see ActivityExecutor.initialize_activity
+        def initialize_activity(defn)
+          # If there is not a current scheduler, we're going to preemptively
+          # fail the registration
+          return unless ::Fiber.current_scheduler.nil?
+
+          raise ArgumentError, "Activity '#{defn.name}' wants a fiber executor but no current fiber scheduler"
+        end
+
+        # @see ActivityExecutor.initialize_activity
+        def execute_activity(_defn, &)
+          ::Fiber.schedule(&)
+        end
+
+        # @see ActivityExecutor.activity_context
+        def activity_context
+          ::Fiber[:temporal_activity_context]
+        end
+
+        # @see ActivityExecutor.set_activity_context
+        def set_activity_context(defn, context)
+          ::Fiber[:temporal_activity_context] = context
+          # If they have opted in to raising on cancel, wire that up
+          return unless defn.cancel_raise
+
+          fiber = ::Fiber.current
+          context&.cancellation&.add_cancel_callback do
+            fiber.raise(Error::CanceledError.new('Activity canceled'))
+          end
+        end
+      end
+    end
+  end
+end