temporalio 0.3.0 → 0.5.0

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

@@ -4,6 +4,7 @@ require 'json'
 require 'temporalio'
 require 'temporalio/activity/definition'
 require 'temporalio/api'
+require 'temporalio/converters/payload_converter'
 require 'temporalio/converters/raw_value'
 require 'temporalio/error'
 require 'temporalio/internal/bridge/api'
@@ -23,6 +24,7 @@ require 'temporalio/internal/worker/workflow_instance/scheduler'
 require 'temporalio/retry_policy'
 require 'temporalio/scoped_logger'
 require 'temporalio/worker/interceptor'
+require 'temporalio/worker_deployment_version'
 require 'temporalio/workflow/info'
 require 'temporalio/workflow/update_info'
 require 'timeout'
@@ -53,9 +55,10 @@ module Temporalio
         attr_reader :context, :logger, :info, :scheduler, :disable_eager_activity_execution, :pending_activities,
                     :pending_timers, :pending_child_workflow_starts, :pending_child_workflows,
                     :pending_external_signals, :pending_external_cancels, :in_progress_handlers, :payload_converter,
-                    :failure_converter, :cancellation, :continue_as_new_suggested, :current_history_length,
-                    :current_history_size, :replaying, :random, :signal_handlers, :query_handlers, :update_handlers,
-                    :context_frozen
+                    :failure_converter, :cancellation, :continue_as_new_suggested, :current_deployment_version,
+                    :current_history_length, :current_history_size, :replaying, :random,
+                    :signal_handlers, :query_handlers, :update_handlers, :context_frozen, :assert_valid_local_activity
+        attr_accessor :io_enabled, :current_details
 
         def initialize(details)
           # Initialize general state
@@ -66,6 +69,7 @@ module Temporalio
           @logger = ReplaySafeLogger.new(logger: details.logger, instance: self)
           @logger.scoped_values_getter = proc { scoped_logger_info }
           @runtime_metric_meter = details.metric_meter
+          @io_enabled = details.unsafe_workflow_io_enabled
           @scheduler = Scheduler.new(self)
           @payload_converter = details.payload_converter
           @failure_converter = details.failure_converter
@@ -87,7 +91,7 @@ module Temporalio
           @current_history_length = 0
           @current_history_size = 0
           @replaying = false
-          @failure_exception_types = details.workflow_failure_exception_types + @definition.failure_exception_types
+          @workflow_failure_exception_types = details.workflow_failure_exception_types
           @signal_handlers = HandlerHash.new(
             details.definition.signals,
             Workflow::Definition::Signal
@@ -104,6 +108,12 @@ module Temporalio
           end
           @query_handlers = HandlerHash.new(details.definition.queries, Workflow::Definition::Query)
           @update_handlers = HandlerHash.new(details.definition.updates, Workflow::Definition::Update)
+          @definition_options = Workflow::DefinitionOptions.new(
+            failure_exception_types: details.definition.failure_exception_types,
+            versioning_behavior: details.definition.versioning_behavior
+          )
+
+          @assert_valid_local_activity = details.assert_valid_local_activity
 
           # Create all things needed from initial job
           @init_job = details.initial_activation.jobs.find { |j| !j.initialize_workflow.nil? }&.initialize_workflow
@@ -115,6 +125,7 @@ module Temporalio
               continued_run_id: ProtoUtils.string_or(@init_job.continued_from_execution_run_id),
               cron_schedule: ProtoUtils.string_or(@init_job.cron_schedule),
               execution_timeout: ProtoUtils.duration_to_seconds(@init_job.workflow_execution_timeout),
+              headers: ProtoUtils.headers_from_proto_map(@init_job.headers, @payload_converter) || {},
               last_failure: if @init_job.continued_failure
                               @failure_converter.from_failure(@init_job.continued_failure, @payload_converter)
                             end,
@@ -129,10 +140,17 @@ module Temporalio
                           workflow_id: @init_job.parent_workflow_info.workflow_id
                         )
                       end,
+              priority: Priority._from_proto(@init_job.priority),
               retry_policy: (RetryPolicy._from_proto(@init_job.retry_policy) if @init_job.retry_policy),
+              root: if @init_job.root_workflow
+                      Workflow::Info::RootInfo.new(
+                        run_id: @init_job.root_workflow.run_id,
+                        workflow_id: @init_job.root_workflow.workflow_id
+                      )
+                    end,
               run_id: details.initial_activation.run_id,
               run_timeout: ProtoUtils.duration_to_seconds(@init_job.workflow_run_timeout),
-              start_time: ProtoUtils.timestamp_to_time(details.initial_activation.timestamp) || raise,
+              start_time: ProtoUtils.timestamp_to_time(@init_job.start_time) || raise,
               task_queue: details.task_queue,
               task_timeout: ProtoUtils.duration_to_seconds(@init_job.workflow_task_timeout) || raise,
               workflow_id: @init_job.workflow_id,
@@ -228,6 +246,9 @@ module Temporalio
           @commands = []
           @current_activation_error = nil
           @continue_as_new_suggested = activation.continue_as_new_suggested
+          @current_deployment_version = WorkerDeploymentVersion._from_bridge(
+            activation.deployment_version_for_current_task
+          )
           @current_history_length = activation.history_length
           @current_history_size = activation.history_size_bytes
           @replaying = activation.is_replaying
@@ -277,7 +298,9 @@ module Temporalio
           else
             Bridge::Api::WorkflowCompletion::WorkflowActivationCompletion.new(
               run_id: activation.run_id,
-              successful: Bridge::Api::WorkflowCompletion::Success.new(commands: @commands)
+              successful: Bridge::Api::WorkflowCompletion::Success.new(
+                commands: @commands, versioning_behavior: @definition_options.versioning_behavior
+              )
             )
           end
         ensure
@@ -289,7 +312,8 @@ module Temporalio
           # Convert workflow arguments
           @workflow_arguments = convert_args(payload_array: @init_job.arguments,
                                              method_name: :execute,
-                                             raw_args: @definition.raw_args)
+                                             raw_args: @definition.raw_args,
+                                             arg_hints: @definition.arg_hints)
 
           # Initialize interceptors
           @inbound = @interceptors.reverse_each.reduce(InboundImplementation.new(self)) do |acc, int|
@@ -298,11 +322,24 @@ module Temporalio
           @inbound.init(OutboundImplementation.new(self))
 
           # Create the user instance
-          if @definition.init
-            @definition.workflow_class.new(*@workflow_arguments)
-          else
-            @definition.workflow_class.new
+          instance = if @definition.init
+                       @definition.workflow_class.new(*@workflow_arguments)
+                     else
+                       @definition.workflow_class.new
+                     end
+
+          # Run Dynamic config getter
+          if @definition.dynamic_options_method
+            dynamic_options = instance.send(@definition.dynamic_options_method)
+            if dynamic_options&.versioning_behavior
+              @definition_options.versioning_behavior = dynamic_options.versioning_behavior
+            end
+            if dynamic_options&.failure_exception_types
+              @definition_options.failure_exception_types = dynamic_options.failure_exception_types
+            end
           end
+
+          instance
         end
 
         def apply(job)
@@ -348,7 +385,10 @@ module Temporalio
         end
 
         def apply_signal(job)
-          defn = signal_handlers[job.signal_name] || signal_handlers[nil]
+          # Get signal definition, falling back to dynamic if not present and not reserved
+          defn = signal_handlers[job.signal_name]
+          defn = signal_handlers[nil] if !defn && !Internal::ProtoUtils.reserved_name?(job.signal_name)
+
           handler_exec =
             if defn
               HandlerExecution.new(name: job.signal_name, update_id: nil, unfinished_policy: defn.unfinished_policy)
@@ -381,43 +421,49 @@ module Temporalio
         end
 
         def apply_query(job)
-          # TODO(cretz): __temporal_workflow_metadata
-          defn = case job.query_type
-                 when '__stack_trace'
-                   Workflow::Definition::Query.new(
-                     name: '__stack_trace',
-                     to_invoke: proc { scheduler.stack_trace }
-                   )
-                 else
-                   query_handlers[job.query_type] || query_handlers[nil]
-                 end
+          result_hint = nil
           schedule do
-            unless defn
-              raise "Query handler for #{job.query_type} expected but not found, " \
-                    "known queries: [#{query_handlers.keys.compact.sort.join(', ')}]"
-            end
+            # If it's a built-in, run it without interceptors, otherwise do normal behavior
+            result = if job.query_type == '__stack_trace'
+                       # Use raw value built from default converter because we don't want to use user-conversion
+                       Converters::RawValue.new(Converters::PayloadConverter.default.to_payload(scheduler.stack_trace))
+                     elsif job.query_type == '__temporal_workflow_metadata'
+                       # Use raw value built from default converter because we don't want to use user-conversion
+                       Converters::RawValue.new(Converters::PayloadConverter.default.to_payload(workflow_metadata))
+                     else
+                       # Get query definition, falling back to dynamic if not present and not reserved
+                       defn = query_handlers[job.query_type]
+                       defn = query_handlers[nil] if !defn && !Internal::ProtoUtils.reserved_name?(job.query_type)
+
+                       unless defn
+                         raise "Query handler for #{job.query_type} expected but not found, " \
+                               "known queries: [#{query_handlers.keys.compact.sort.join(', ')}]"
+                       end
+                       result_hint = defn.result_hint
+
+                       with_context_frozen do
+                         @inbound.handle_query(
+                           Temporalio::Worker::Interceptor::Workflow::HandleQueryInput.new(
+                             id: job.query_id,
+                             query: job.query_type,
+                             args: begin
+                               convert_handler_args(payload_array: job.arguments, defn:)
+                             rescue StandardError => e
+                               raise "Failed converting query input arguments: #{e}"
+                             end,
+                             definition: defn,
+                             headers: ProtoUtils.headers_from_proto_map(job.headers, @payload_converter) || {}
+                           )
+                         )
+                       end
+                     end
 
-            result = with_context_frozen do
-              @inbound.handle_query(
-                Temporalio::Worker::Interceptor::Workflow::HandleQueryInput.new(
-                  id: job.query_id,
-                  query: job.query_type,
-                  args: begin
-                    convert_handler_args(payload_array: job.arguments, defn:)
-                  rescue StandardError => e
-                    raise "Failed converting query input arguments: #{e}"
-                  end,
-                  definition: defn,
-                  headers: ProtoUtils.headers_from_proto_map(job.headers, @payload_converter) || {}
-                )
-              )
-            end
             add_command(
               Bridge::Api::WorkflowCommands::WorkflowCommand.new(
                 respond_to_query: Bridge::Api::WorkflowCommands::QueryResult.new(
                   query_id: job.query_id,
                   succeeded: Bridge::Api::WorkflowCommands::QuerySuccess.new(
-                    response: @payload_converter.to_payload(result)
+                    response: @payload_converter.to_payload(result, hint: result_hint)
                   )
                 )
               )
@@ -435,7 +481,10 @@ module Temporalio
         end
 
         def apply_update(job)
-          defn = update_handlers[job.name] || update_handlers[nil]
+          # Get update definition, falling back to dynamic if not present and not reserved
+          defn = update_handlers[job.name]
+          defn = update_handlers[nil] if !defn && !Internal::ProtoUtils.reserved_name?(job.name)
+
           handler_exec =
             (HandlerExecution.new(name: job.name, update_id: job.id, unfinished_policy: defn.unfinished_policy) if defn)
           schedule(handler_exec:) do
@@ -503,7 +552,7 @@ module Temporalio
               Bridge::Api::WorkflowCommands::WorkflowCommand.new(
                 update_response: Bridge::Api::WorkflowCommands::UpdateResponse.new(
                   protocol_instance_id: job.protocol_instance_id,
-                  completed: @payload_converter.to_payload(result)
+                  completed: @payload_converter.to_payload(result, hint: defn.result_hint)
                 )
               )
             )
@@ -527,13 +576,13 @@ module Temporalio
           result = @inbound.execute(
             Temporalio::Worker::Interceptor::Workflow::ExecuteInput.new(
               args: @workflow_arguments,
-              headers: ProtoUtils.headers_from_proto_map(@init_job.headers, @payload_converter) || {}
+              headers: @info.headers
             )
           )
           add_command(
             Bridge::Api::WorkflowCommands::WorkflowCommand.new(
               complete_workflow_execution: Bridge::Api::WorkflowCommands::CompleteWorkflowExecution.new(
-                result: @payload_converter.to_payload(result)
+                result: @payload_converter.to_payload(result, hint: @definition.result_hint)
               )
             )
           )
@@ -561,14 +610,19 @@ module Temporalio
         def on_top_level_exception(err)
           if err.is_a?(Workflow::ContinueAsNewError)
             @logger.debug('Workflow requested continue as new')
+            workflow_type, defn_arg_hints, =
+              if err.workflow
+                Workflow::Definition._workflow_type_and_hints_from_workflow_parameter(err.workflow)
+              else
+                [nil, @definition.arg_hints, nil]
+              end
             add_command(
               Bridge::Api::WorkflowCommands::WorkflowCommand.new(
                 continue_as_new_workflow_execution: Bridge::Api::WorkflowCommands::ContinueAsNewWorkflowExecution.new(
-                  workflow_type: if err.workflow
-                                   Workflow::Definition._workflow_type_from_workflow_parameter(err.workflow)
-                                 end,
+                  workflow_type:,
                   task_queue: err.task_queue,
-                  arguments: ProtoUtils.convert_to_payload_array(payload_converter, err.args),
+                  arguments: ProtoUtils.convert_to_payload_array(payload_converter, err.args,
+                                                                 hints: err.arg_hints || defn_arg_hints),
                   workflow_run_timeout: ProtoUtils.seconds_to_duration(err.run_timeout),
                   workflow_task_timeout: ProtoUtils.seconds_to_duration(err.task_timeout),
                   memo: ProtoUtils.memo_to_proto_hash(err.memo, payload_converter),
@@ -606,9 +660,9 @@ module Temporalio
         end
 
         def failure_exception?(err)
-          err.is_a?(Error::Failure) || err.is_a?(Timeout::Error) || @failure_exception_types.any? do |cls|
-            err.is_a?(cls)
-          end
+          err.is_a?(Error::Failure) || err.is_a?(Timeout::Error) ||
+            @workflow_failure_exception_types&.any? { |cls| err.is_a?(cls) } ||
+            @definition_options.failure_exception_types&.any? { |cls| err.is_a?(cls) }
         end
 
         def with_context_frozen(&)
@@ -623,11 +677,12 @@ module Temporalio
             payload_array:,
             method_name: defn.to_invoke.is_a?(Symbol) ? defn.to_invoke : nil,
             raw_args: defn.raw_args,
+            arg_hints: defn.arg_hints,
             ignore_first_param: defn.name.nil? # Dynamic
           )
         end
 
-        def convert_args(payload_array:, method_name:, raw_args:, ignore_first_param: false)
+        def convert_args(payload_array:, method_name:, raw_args:, arg_hints:, ignore_first_param: false)
           # Just in case it is not an array
           payload_array = payload_array.to_ary
 
@@ -667,10 +722,34 @@ module Temporalio
           if raw_args
             payload_array.map { |p| Converters::RawValue.new(p) }
           else
-            ProtoUtils.convert_from_payload_array(@payload_converter, payload_array)
+            ProtoUtils.convert_from_payload_array(@payload_converter, payload_array, hints: arg_hints)
           end
         end
 
+        def workflow_metadata
+          Temporalio::Api::Sdk::V1::WorkflowMetadata.new(
+            definition: Temporalio::Api::Sdk::V1::WorkflowDefinition.new(
+              type: info.workflow_type,
+              query_definitions: query_handlers.values.map do |defn|
+                Temporalio::Api::Sdk::V1::WorkflowInteractionDefinition.new(
+                  name: defn.name || '', description: defn.description || ''
+                )
+              end,
+              signal_definitions: signal_handlers.values.map do |defn|
+                Temporalio::Api::Sdk::V1::WorkflowInteractionDefinition.new(
+                  name: defn.name || '', description: defn.description || ''
+                )
+              end,
+              update_definitions: update_handlers.values.map do |defn|
+                Temporalio::Api::Sdk::V1::WorkflowInteractionDefinition.new(
+                  name: defn.name || '', description: defn.description || ''
+                )
+              end
+            ),
+            current_details: current_details || ''
+          )
+        end
+
         def scoped_logger_info
           @scoped_logger_info ||= {
             attempt: info.attempt,

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

@@ -13,7 +13,7 @@ module Temporalio
     module Worker
       # Worker for handling workflow activations. Most activation work is delegated to the workflow executor.
       class WorkflowWorker
-        def self.workflow_definitions(workflows)
+        def self.workflow_definitions(workflows, should_enforce_versioning_behavior:)
           workflows.each_with_object({}) do |workflow, hash|
             # Load definition
             defn = begin
@@ -29,15 +29,58 @@ module Temporalio
             # 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 initialize(worker:, bridge_worker:, workflow_definitions:)
-          @executor = worker.options.workflow_executor
+        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 }
 
-          payload_codec = worker.options.client.data_converter.payload_codec
-          @workflow_payload_codec_thread_pool = worker.options.workflow_payload_codec_thread_pool
+            # 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
@@ -55,29 +98,32 @@ module Temporalio
           @state = State.new(
             workflow_definitions:,
             bridge_worker:,
-            logger: worker.options.logger,
-            metric_meter: worker.options.client.connection.options.runtime.metric_meter,
-            data_converter: worker.options.client.data_converter,
-            deadlock_timeout: worker.options.debug_mode ? nil : 2.0,
+            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(
-              worker.options.illegal_workflow_calls || {}
+              illegal_workflow_calls || {}
             ),
-            namespace: worker.options.client.namespace,
-            task_queue: worker.options.task_queue,
-            disable_eager_activity_execution: worker.options.disable_eager_activity_execution,
-            workflow_interceptors: worker._workflow_interceptors,
-            workflow_failure_exception_types: worker.options.workflow_failure_exception_types.map do |t|
-              unless t.is_a?(Class) && t < Exception
+            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
+            end.freeze,
+            unsafe_workflow_io_enabled:,
+            assert_valid_local_activity:
           )
+          @state.on_eviction = on_eviction if on_eviction
 
           # Validate worker
-          @executor._validate_worker(worker, @state)
+          @executor._validate_worker(self, @state)
         end
 
         def handle_activation(runner:, activation:, decoded:)
@@ -147,12 +193,16 @@ module Temporalio
         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
+                      :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:
+            workflow_interceptors:, workflow_failure_exception_types:, unsafe_workflow_io_enabled:,
+            assert_valid_local_activity:
           )
             @workflow_definitions = workflow_definitions
             @bridge_worker = bridge_worker
@@ -166,6 +216,8 @@ module Temporalio
             @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
@@ -182,8 +234,9 @@ module Temporalio
             instance
           end
 
-          def evict_running_workflow(run_id)
+          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

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/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