clara-temporalio 0.4.3

data/lib/temporalio/internal/worker/workflow_worker.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require 'temporalio/api/payload_visitor'
+require 'temporalio/error'
+require 'temporalio/internal/worker/workflow_instance'
+require 'temporalio/scoped_logger'
+require 'temporalio/workflow'
+require 'temporalio/workflow/definition'
+require 'timeout'
+
+module Temporalio
+  module Internal
+    module Worker
+      # Worker for handling workflow activations. Most activation work is delegated to the workflow executor.
+      class WorkflowWorker
+        def self.workflow_definitions(workflows, should_enforce_versioning_behavior:)
+          workflows.each_with_object({}) do |workflow, hash|
+            # Load definition
+            defn = begin
+              if workflow.is_a?(Workflow::Definition::Info)
+                workflow
+              else
+                Workflow::Definition::Info.from_class(workflow)
+              end
+            rescue StandardError
+              raise ArgumentError, "Failed loading workflow #{workflow}"
+            end
+
+            # Confirm name not in use
+            raise ArgumentError, "Multiple workflows named #{defn.name || '<dynamic>'}" if hash.key?(defn.name)
+
+            # Enforce versioning behavior is set when versioning is on
+            if should_enforce_versioning_behavior &&
+               defn.versioning_behavior == VersioningBehavior::UNSPECIFIED && !defn.dynamic_options_method
+              raise ArgumentError, "Workflow #{defn.name} must specify a versioning behavior"
+            end
+
+            hash[defn.name] = defn
+          end
+        end
+
+        def self.bridge_workflow_failure_exception_type_options(
+          workflow_failure_exception_types:,
+          workflow_definitions:
+        )
+          as_fail = workflow_failure_exception_types.any? do |t|
+            t.is_a?(Class) && t >= Workflow::NondeterminismError
+          end
+          as_fail_for_types = workflow_definitions.values.map do |defn|
+            next unless defn.failure_exception_types.any? { |t| t.is_a?(Class) && t >= Workflow::NondeterminismError }
+
+            # If they tried to do this on a dynamic workflow and haven't already set worker-level option, warn
+            unless defn.name || as_fail
+              warn('Note, dynamic workflows cannot trap non-determinism errors, so worker-level ' \
+                   'workflow_failure_exception_types should be set to capture that if that is the intention')
+            end
+            defn.name
+          end.compact
+          [as_fail, as_fail_for_types]
+        end
+
+        def initialize(
+          bridge_worker:,
+          namespace:,
+          task_queue:,
+          workflow_definitions:,
+          workflow_executor:,
+          logger:,
+          data_converter:,
+          metric_meter:,
+          workflow_interceptors:,
+          disable_eager_activity_execution:,
+          illegal_workflow_calls:,
+          workflow_failure_exception_types:,
+          workflow_payload_codec_thread_pool:,
+          unsafe_workflow_io_enabled:,
+          debug_mode:,
+          assert_valid_local_activity:, on_eviction: nil
+        )
+          @executor = workflow_executor
+
+          payload_codec = data_converter.payload_codec
+          @workflow_payload_codec_thread_pool = workflow_payload_codec_thread_pool
+          if !Fiber.current_scheduler && payload_codec && !@workflow_payload_codec_thread_pool
+            raise ArgumentError, 'Must have workflow payload codec thread pool if providing codec and not using fibers'
+          end
+
+          # If there is a payload codec, we need to build encoding and decoding visitors
+          if payload_codec
+            @payload_encoding_visitor = Api::PayloadVisitor.new(skip_search_attributes: true) do |payload_or_payloads|
+              apply_codec_on_payload_visit(payload_or_payloads) { |payloads| payload_codec.encode(payloads) }
+            end
+            @payload_decoding_visitor = Api::PayloadVisitor.new(skip_search_attributes: true) do |payload_or_payloads|
+              apply_codec_on_payload_visit(payload_or_payloads) { |payloads| payload_codec.decode(payloads) }
+            end
+          end
+
+          @state = State.new(
+            workflow_definitions:,
+            bridge_worker:,
+            logger:,
+            metric_meter:,
+            data_converter:,
+            deadlock_timeout: debug_mode ? nil : 2.0,
+            # TODO(cretz): Make this more performant for the default set?
+            illegal_calls: WorkflowInstance::IllegalCallTracer.frozen_validated_illegal_calls(
+              illegal_workflow_calls || {}
+            ),
+            namespace:,
+            task_queue:,
+            disable_eager_activity_execution:,
+            workflow_interceptors:,
+            workflow_failure_exception_types: workflow_failure_exception_types.map do |t|
+              unless t.is_a?(Class) && t < Exception
+                raise ArgumentError, 'All failure types must classes inheriting Exception'
+              end
+
+              t
+            end.freeze,
+            unsafe_workflow_io_enabled:,
+            assert_valid_local_activity:
+          )
+          @state.on_eviction = on_eviction if on_eviction
+
+          # Validate worker
+          @executor._validate_worker(self, @state)
+        end
+
+        def handle_activation(runner:, activation:, decoded:)
+          # Encode in background if not encoded but it needs to be
+          if @payload_encoding_visitor && !decoded
+            if Fiber.current_scheduler
+              Fiber.schedule { decode_activation(runner, activation) }
+            else
+              @workflow_payload_codec_thread_pool.execute { decode_activation(runner, activation) }
+            end
+          else
+            @executor._activate(activation, @state) do |activation_completion|
+              runner.apply_workflow_activation_complete(workflow_worker: self, activation_completion:, encoded: false)
+            end
+          end
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # Should never happen, executors are expected to trap things
+          @state.logger.error("Failed issuing activation on workflow run ID: #{activation.run_id}")
+          @state.logger.error(e)
+        end
+
+        def handle_activation_complete(runner:, activation_completion:, encoded:, completion_complete_queue:)
+          if @payload_encoding_visitor && !encoded
+            if Fiber.current_scheduler
+              Fiber.schedule { encode_activation_completion(runner, activation_completion) }
+            else
+              @workflow_payload_codec_thread_pool.execute do
+                encode_activation_completion(runner, activation_completion)
+              end
+            end
+          else
+            @state.bridge_worker.async_complete_workflow_activation(
+              activation_completion.run_id, activation_completion.to_proto, completion_complete_queue
+            )
+          end
+        end
+
+        def on_shutdown_complete
+          @state.evict_all
+        end
+
+        private
+
+        def decode_activation(runner, activation)
+          @payload_decoding_visitor.run(activation)
+          runner.apply_workflow_activation_decoded(workflow_worker: self, activation:)
+        end
+
+        def encode_activation_completion(runner, activation_completion)
+          @payload_encoding_visitor.run(activation_completion)
+          runner.apply_workflow_activation_complete(workflow_worker: self, activation_completion:, encoded: true)
+        end
+
+        def apply_codec_on_payload_visit(payload_or_payloads, &)
+          case payload_or_payloads
+          when Temporalio::Api::Common::V1::Payload
+            new_payloads = yield [payload_or_payloads]
+            payload_or_payloads.metadata = new_payloads.first.metadata
+            payload_or_payloads.data = new_payloads.first.data
+          when Enumerable
+            payload_or_payloads.replace(yield payload_or_payloads) # steep:ignore
+          else
+            raise 'Unrecognized visitor type'
+          end
+        end
+
+        class State
+          attr_reader :workflow_definitions, :bridge_worker, :logger, :metric_meter, :data_converter, :deadlock_timeout,
+                      :illegal_calls, :namespace, :task_queue, :disable_eager_activity_execution,
+                      :workflow_interceptors, :workflow_failure_exception_types, :unsafe_workflow_io_enabled,
+                      :assert_valid_local_activity
+
+          attr_writer :on_eviction
+
+          def initialize(
+            workflow_definitions:, bridge_worker:, logger:, metric_meter:, data_converter:, deadlock_timeout:,
+            illegal_calls:, namespace:, task_queue:, disable_eager_activity_execution:,
+            workflow_interceptors:, workflow_failure_exception_types:, unsafe_workflow_io_enabled:,
+            assert_valid_local_activity:
+          )
+            @workflow_definitions = workflow_definitions
+            @bridge_worker = bridge_worker
+            @logger = logger
+            @metric_meter = metric_meter
+            @data_converter = data_converter
+            @deadlock_timeout = deadlock_timeout
+            @illegal_calls = illegal_calls
+            @namespace = namespace
+            @task_queue = task_queue
+            @disable_eager_activity_execution = disable_eager_activity_execution
+            @workflow_interceptors = workflow_interceptors
+            @workflow_failure_exception_types = workflow_failure_exception_types
+            @unsafe_workflow_io_enabled = unsafe_workflow_io_enabled
+            @assert_valid_local_activity = assert_valid_local_activity
+
+            @running_workflows = {}
+            @running_workflows_mutex = Mutex.new
+          end
+
+          # This can never be called at the same time for the same run ID on the same state object
+          def get_or_create_running_workflow(run_id, &)
+            instance = @running_workflows_mutex.synchronize { @running_workflows[run_id] }
+            # If instance is not there, we create it out of lock then store it under lock
+            unless instance
+              instance = yield
+              @running_workflows_mutex.synchronize { @running_workflows[run_id] = instance }
+            end
+            instance
+          end
+
+          def evict_running_workflow(run_id, cache_remove_job)
+            @running_workflows_mutex.synchronize { @running_workflows.delete(run_id) }
+            @on_eviction&.call(run_id, cache_remove_job)
+          end
+
+          def evict_all
+            @running_workflows_mutex.synchronize { @running_workflows.clear }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/internal.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Temporalio
+  # @!visibility private
+  module Internal
+  end
+end

data/lib/temporalio/metric.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/metric'
+
+module Temporalio
+  # Metric that can be recorded from a metric meter. This is obtained via {Meter.create_metric}. The metric meter is
+  # obtained via workflow environment, activity context, or from the {Runtime} if in neither of those. This class is
+  # effectively abstract and will fail if `initialize` is attempted.
+  class Metric
+    # @!visibility private
+    def initialize
+      raise NotImplementedError, 'Metric is abstract, implementations override initialize'
+    end
+
+    # Record a value for the metric. For counters, this adds to any existing. For histograms, this records into proper
+    # buckets. For gauges, this sets the value. The value type must match the expectation.
+    #
+    # @param value [Numeric] Value to record. For counters and duration-based histograms, this value cannot be negative.
+    # @param additional_attributes [Hash{String, Symbol => String, Integer, Float, Boolean}, nil] Additional attributes
+    #   on this specific record. For better performance for attribute reuse, users are encouraged to use
+    #   {with_additional_attributes} to make a copy of this metric with those attributes.
+    def record(value, additional_attributes: nil)
+      raise NotImplementedError
+    end
+
+    # Create a copy of this metric but with the given additional attributes. This is more performant than providing
+    # attributes on each {record} call.
+    #
+    # @param additional_attributes [Hash{String, Symbol => String, Integer, Float, Boolean}] Attributes to set on the
+    #   resulting metric.
+    # @return [Metric] Copy of this metric with the additional attributes.
+    def with_additional_attributes(additional_attributes)
+      raise NotImplementedError
+    end
+
+    # @return [:counter, :histogram, :gauge] Metric type.
+    def metric_type
+      raise NotImplementedError
+    end
+
+    # @return [String] Metric name.
+    def name
+      raise NotImplementedError
+    end
+
+    # @return [String, nil] Metric description.
+    def description
+      raise NotImplementedError
+    end
+
+    # @return [String, nil] Metric unit.
+    def unit
+      raise NotImplementedError
+    end
+
+    # @return [:integer, :float, :duration] Metric value type.
+    def value_type
+      raise NotImplementedError
+    end
+
+    # Meter for creating metrics to record values on. This is obtained via workflow environment, activity context, or
+    # from the {Runtime} if in neither of those. This class is effectively abstract and will fail if `initialize` is
+    # attempted.
+    class Meter
+      # @return [Meter] A no-op instance of {Meter}.
+      def self.null
+        Internal::Metric::NullMeter.instance
+      end
+
+      # @!visibility private
+      def initialize
+        raise NotImplementedError, 'Meter is abstract, implementations override initialize'
+      end
+
+      # Create a new metric. Only certain metric types are accepted and only value types can work with certain metric
+      # types.
+      #
+      # @param metric_type [:counter, :histogram, :gauge] Metric type. Counters can only have `:integer` value types,
+      #   histograms can have `:integer`, `:float`, or :duration` value types, and gauges can have `:integer` or
+      #   `:float` value types.
+      # @param name [String] Metric name.
+      # @param description [String, nil] Metric description.
+      # @param unit [String, nil] Metric unit.
+      # @param value_type [:integer, :float, :duration] Metric value type. `:integer` works for all metric types,
+      #   `:float` works for `:histogram` and `:gauge` metric types, and `:duration` only works for `:histogram` metric
+      #   types.
+      # @return [Metric] Created metric.
+      def create_metric(
+        metric_type,
+        name,
+        description: nil,
+        unit: nil,
+        value_type: :integer
+      )
+        raise NotImplementedError
+      end
+
+      # Create a copy of this meter but with the given additional attributes. This is more performant than providing
+      # attributes on each {record} call.
+      #
+      # @param additional_attributes [Hash{String, Symbol => String, Integer, Float, Boolean}] Attributes to set on the
+      #   resulting meter.
+      # @return [Meter] Copy of this meter with the additional attributes.
+      def with_additional_attributes(additional_attributes)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/temporalio/priority.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+
+module Temporalio
+  Priority = Data.define(
+    :priority_key
+  )
+
+  # Priority contains metadata that controls relative ordering of task processing when tasks are
+  # backlogged in a queue. Initially, Priority will be used in activity and workflow task
+  # queues, which are typically where backlogs exist. Priority is (for now) attached to
+  # workflows and activities. Activities and child workflows inherit Priority from the workflow
+  # that created them, but may override fields when they are started or modified. For each field
+  # of a Priority on an activity/workflow, not present or equal to zero/empty string means to
+  # inherit the value from the calling workflow, or if there is no calling workflow, then use
+  # the default (documented on the field).
+  #
+  # The overall semantics of Priority are:
+  # 1. First, consider "priority_key": lower number goes first.
+  # (more will be added here later).
+  #
+  # @!attribute priority_key
+  #   @return [Integer, nil] The priority key, which is a positive integer from 1 to n, where
+  #     smaller integers correspond to higher priorities (tasks run sooner). In general, tasks in a
+  #     queue should be processed in close to priority order, although small deviations are possible.
+  #     The maximum priority value (minimum priority) is determined by server configuration, and
+  #     defaults to 5.
+  #
+  #     The default priority is (min+max)/2. With the default max of 5 and min of 1, that comes
+  #     out to 3.
+  class Priority
+    # @!visibility private
+    def self._from_proto(priority)
+      return default if priority.nil?
+
+      new(priority_key: priority.priority_key.zero? ? nil : priority.priority_key)
+    end
+
+    # The default priority instance.
+    #
+    # @return [Priority] The default priority
+    def self.default
+      @default ||= new(priority_key: nil)
+    end
+
+    # @!visibility private
+    def _to_proto
+      return nil if priority_key.nil?
+
+      Temporalio::Api::Common::V1::Priority.new(priority_key: priority_key || 0)
+    end
+
+    # @return [Boolean] True if this priority is empty/default
+    def empty?
+      priority_key.nil?
+    end
+  end
+end

data/lib/temporalio/retry_policy.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'temporalio/internal/proto_utils'
+
+module Temporalio
+  RetryPolicy = Data.define(
+    :initial_interval,
+    :backoff_coefficient,
+    :max_interval,
+    :max_attempts,
+    :non_retryable_error_types
+  )
+
+  # Options for retrying workflows and activities.
+  #
+  # @!attribute initial_interval
+  #   @return [Float] Backoff interval in seconds for the first retry. Default 1.0.
+  # @!attribute backoff_coefficient
+  #   @return [Float] Coefficient to multiply previous backoff interval by to get new interval. Default 2.0.
+  # @!attribute max_interval
+  #   @return [Float, nil] Maximum backoff interval in seconds between retries. Default 100x `initial_interval`.
+  # @!attribute max_attempts
+  #   @return [Integer] Maximum number of attempts. If `0`, the default, there is no maximum.
+  # @!attribute non_retryable_error_types
+  #   @return [Array<String>, nil] List of error types that are not retryable.
+  class RetryPolicy
+    # @!visibility private
+    def self._from_proto(raw_policy)
+      RetryPolicy.new(
+        initial_interval: Internal::ProtoUtils.duration_to_seconds(raw_policy.initial_interval) || raise, # Never nil
+        backoff_coefficient: raw_policy.backoff_coefficient,
+        max_interval: Internal::ProtoUtils.duration_to_seconds(raw_policy.maximum_interval),
+        max_attempts: raw_policy.maximum_attempts,
+        non_retryable_error_types: raw_policy.non_retryable_error_types&.to_a
+      )
+    end
+
+    # Create retry policy.
+    #
+    # @param initial_interval [Float] Backoff interval in seconds for the first retry. Default 1.0.
+    # @param backoff_coefficient [Float] Coefficient to multiply previous backoff interval by to get new interval.
+    #   Default 2.0.
+    # @param max_interval [Float, nil] Maximum backoff interval in seconds between retries. Default 100x
+    #   `initial_interval`.
+    # @param max_attempts [Integer] Maximum number of attempts. If `0`, the default, there is no maximum.
+    # @param non_retryable_error_types [Array<String>, nil] List of error types that are not retryable.
+    def initialize(
+      initial_interval: 1.0,
+      backoff_coefficient: 2.0,
+      max_interval: nil,
+      max_attempts: 0,
+      non_retryable_error_types: nil
+    )
+      super
+    end
+
+    # @!visibility private
+    def _to_proto
+      raise 'Initial interval cannot be negative' if initial_interval.negative?
+      raise 'Backoff coefficient cannot be less than 1' if backoff_coefficient < 1
+      raise 'Max interval cannot be negative' if max_interval&.negative?
+      raise 'Max interval cannot be less than initial interval' if max_interval && max_interval < initial_interval
+      raise 'Max attempts cannot be negative' if max_attempts.negative?
+
+      Api::Common::V1::RetryPolicy.new(
+        initial_interval: Internal::ProtoUtils.seconds_to_duration(initial_interval),
+        backoff_coefficient:,
+        maximum_interval: Internal::ProtoUtils.seconds_to_duration(max_interval),
+        maximum_attempts: max_attempts,
+        non_retryable_error_types:
+      )
+    end
+  end
+end

data/lib/temporalio/runtime/metric_buffer.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Temporalio
+  class Runtime
+    # Metric buffer for use with a runtime to capture metrics. Only one metric buffer can be associated with a runtime
+    # and {retrieve_updates} cannot be called before the runtime is created. Once runtime created, users should
+    # regularly call {retrieve_updates} to drain the buffer.
+    #
+    # @note WARNING: It is important that the buffer size is set to a high number and that {retrieve_updates} is called
+    #   regularly to drain the buffer. If the buffer is full, metric updates will be dropped and an error will be
+    #   logged.
+    class MetricBuffer
+      # Enumerates for the duration format.
+      module DurationFormat
+        # Durations are millisecond integers.
+        MILLISECONDS = :milliseconds
+
+        # Durations are second floats.
+        SECONDS = :seconds
+      end
+
+      Update = Data.define(:metric, :value, :attributes)
+
+      # Metric buffer update.
+      #
+      # @note WARNING: The constructor of this class should not be invoked by users and may change in incompatible ways
+      #   in the future.
+      #
+      # @!attribute metric
+      #   @return [Metric] Metric for this update. For performance reasons, this is created lazily on first use and is
+      #     the same object each time an update on this metric exists.
+      # @!attribute value
+      #   @return [Integer, Float] Metric value for this update.
+      # @!attribute attributes
+      #   @return [Hash{String => String, Integer, Float, Boolean}] Attributes for this value as a frozen hash.
+      #     For performance reasons this is sometimes the same hash if the attribute set is reused at a metric level.
+      class Update # rubocop:disable Lint/EmptyClass
+        # DEV NOTE: This class is instantiated inside Rust, be careful changing it.
+      end
+
+      Metric = Data.define(:name, :description, :unit, :kind)
+
+      # Metric definition present on an update.
+      #
+      # @!attribute name
+      #   @return [String] Name of the metric.
+      # @!attribute description
+      #   @return [String, nil] Description of the metric if any.
+      # @!attribute unit
+      #   @return [String, nil] Unit of the metric if any.
+      # @!attribute kind
+      #   @return [:counter, :histogram, :gauge] Kind of the metric.
+      class Metric # rubocop:disable Lint/EmptyClass
+        # DEV NOTE: This class is instantiated inside Rust, be careful changing it.
+      end
+
+      # Create a metric buffer with the given size.
+      #
+      # @note WARNING: It is important that the buffer size is set to a high number and is drained regularly. See
+      #   {MetricBuffer} warning.
+      #
+      # @param buffer_size [Integer] Maximum size of the buffer before metrics will be dropped.
+      # @param duration_format [DurationFormat] How durations are represented.
+      def initialize(buffer_size, duration_format: DurationFormat::MILLISECONDS)
+        @buffer_size = buffer_size
+        @duration_format = duration_format
+        @runtime = nil
+      end
+
+      # Drain the buffer and return all metric updates.
+      #
+      # @note WARNING: It is important that this is called regularly. See {MetricBuffer} warning.
+      #
+      # @return [Array<Update>] Updates since last time this was called.
+      def retrieve_updates
+        raise 'Attempting to retrieve updates before runtime created' unless @runtime
+
+        @runtime._core_runtime.retrieve_buffered_metrics(@duration_format == DurationFormat::SECONDS)
+      end
+
+      # @!visibility private
+      def _buffer_size
+        @buffer_size
+      end
+
+      # @!visibility private
+      def _set_runtime(runtime)
+        raise 'Metric buffer already attached to a runtime' if @runtime
+
+        @runtime = runtime
+      end
+    end
+  end
+end