temporalio 0.3.0-x86_64-linux-musl → 0.5.0-x86_64-linux-musl

data/lib/temporalio/contrib/open_telemetry.rb

@@ -0,0 +1,474 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'opentelemetry' # This import will intentionally fail if the user does not have OTel gem available
+require 'temporalio/client/interceptor'
+require 'temporalio/converters/payload_converter'
+require 'temporalio/worker/interceptor'
+
+module Temporalio
+  module Contrib
+    module OpenTelemetry
+      # Tracing interceptor to add OpenTelemetry traces to clients, activities, and workflows.
+      class TracingInterceptor
+        include Client::Interceptor
+        include Worker::Interceptor::Activity
+        include Worker::Interceptor::Workflow
+
+        # @return [OpenTelemetry::Trace::Tracer] Tracer in use.
+        attr_reader :tracer
+
+        # Create interceptor.
+        #
+        # @param tracer [OpenTelemetry::Trace::Tracer] Tracer to use.
+        # @param header_key [String] Temporal header name to serialize spans to/from. Most users should not change this.
+        # @param propagator [Object] Propagator to use. Most users should not change this.
+        # @param always_create_workflow_spans [Boolean] When false, the default, spans are only created in workflows
+        #   when an overarching span from the client is present. In cases of starting a workflow elsewhere, e.g. CLI or
+        #   schedules, a client-created span is not present and workflow spans will not be created. Setting this to true
+        #   will create spans in workflows no matter what, but there is a risk of them being orphans since they may not
+        #   have a parent span after replaying.
+        def initialize(
+          tracer,
+          header_key: '_tracer-data',
+          propagator: ::OpenTelemetry::Context::Propagation::CompositeTextMapPropagator.compose_propagators(
+            [
+              ::OpenTelemetry::Trace::Propagation::TraceContext::TextMapPropagator.new,
+              ::OpenTelemetry::Baggage::Propagation::TextMapPropagator.new
+            ]
+          ),
+          always_create_workflow_spans: false
+        )
+          @tracer = tracer
+          @header_key = header_key
+          @propagator = propagator
+          @always_create_workflow_spans = always_create_workflow_spans
+        end
+
+        # @!visibility private
+        def intercept_client(next_interceptor)
+          ClientOutbound.new(self, next_interceptor)
+        end
+
+        # @!visibility private
+        def intercept_activity(next_interceptor)
+          ActivityInbound.new(self, next_interceptor)
+        end
+
+        # @!visibility private
+        def intercept_workflow(next_interceptor)
+          WorkflowInbound.new(self, next_interceptor)
+        end
+
+        # @!visibility private
+        def _apply_context_to_headers(headers, context: ::OpenTelemetry::Context.current)
+          carrier = {}
+          @propagator.inject(carrier, context:)
+          headers[@header_key] = carrier unless carrier.empty?
+        end
+
+        # @!visibility private
+        def _attach_context(headers)
+          context = _context_from_headers(headers)
+          ::OpenTelemetry::Context.attach(context) if context
+        end
+
+        # @!visibility private
+        def _context_from_headers(headers)
+          carrier = headers[@header_key]
+          @propagator.extract(carrier) if carrier.is_a?(Hash) && !carrier.empty?
+        end
+
+        # @!visibility private
+        def _with_started_span(
+          name:,
+          kind:,
+          attributes: nil,
+          outbound_input: nil
+        )
+          tracer.in_span(name, attributes:, kind:) do
+            _apply_context_to_headers(outbound_input.headers) if outbound_input
+            yield
+          end
+        end
+
+        # @!visibility private
+        def _always_create_workflow_spans
+          @always_create_workflow_spans
+        end
+
+        # @!visibility private
+        class ClientOutbound < Client::Interceptor::Outbound
+          def initialize(root, next_interceptor)
+            super(next_interceptor)
+            @root = root
+          end
+
+          # @!visibility private
+          def start_workflow(input)
+            @root._with_started_span(
+              name: "StartWorkflow:#{input.workflow}",
+              kind: :client,
+              attributes: { 'temporalWorkflowID' => input.workflow_id },
+              outbound_input: input
+            ) { super }
+          end
+
+          # @!visibility private
+          def start_update_with_start_workflow(input)
+            @root._with_started_span(
+              name: "UpdateWithStartWorkflow:#{input.update}",
+              kind: :client,
+              attributes: { 'temporalWorkflowID' => input.start_workflow_operation.options.id,
+                            'temporalUpdateID' => input.update_id },
+              outbound_input: input
+            ) do
+              # Also add to start headers
+              if input.headers[@header_key]
+                input.start_workflow_operation.options.headers[@header_key] = input.headers[@header_key]
+              end
+              super
+            end
+          end
+
+          # @!visibility private
+          def signal_with_start_workflow(input)
+            @root._with_started_span(
+              name: "SignalWithStartWorkflow:#{input.workflow}",
+              kind: :client,
+              attributes: { 'temporalWorkflowID' => input.start_workflow_operation.options.id },
+              outbound_input: input
+            ) do
+              # Also add to start headers
+              if input.headers[@header_key]
+                input.start_workflow_operation.options.headers[@header_key] = input.headers[@header_key]
+              end
+              super
+            end
+          end
+
+          # @!visibility private
+          def signal_workflow(input)
+            @root._with_started_span(
+              name: "SignalWorkflow:#{input.signal}",
+              kind: :client,
+              attributes: { 'temporalWorkflowID' => input.workflow_id },
+              outbound_input: input
+            ) { super }
+          end
+
+          # @!visibility private
+          def query_workflow(input)
+            @root._with_started_span(
+              name: "QueryWorkflow:#{input.query}",
+              kind: :client,
+              attributes: { 'temporalWorkflowID' => input.workflow_id },
+              outbound_input: input
+            ) { super }
+          end
+
+          # @!visibility private
+          def start_workflow_update(input)
+            @root._with_started_span(
+              name: "StartWorkflowUpdate:#{input.update}",
+              kind: :client,
+              attributes: { 'temporalWorkflowID' => input.workflow_id, 'temporalUpdateID' => input.update_id },
+              outbound_input: input
+            ) { super }
+          end
+        end
+
+        # @!visibility private
+        class ActivityInbound < Worker::Interceptor::Activity::Inbound
+          def initialize(root, next_interceptor)
+            super(next_interceptor)
+            @root = root
+          end
+
+          # @!visibility private
+          def execute(input)
+            @root._attach_context(input.headers)
+            info = Activity::Context.current.info
+            @root._with_started_span(
+              name: "RunActivity:#{info.activity_type}",
+              kind: :server,
+              attributes: {
+                'temporalWorkflowID' => info.workflow_id,
+                'temporalRunID' => info.workflow_run_id,
+                'temporalActivityID' => info.activity_id
+              }
+            ) { super }
+          end
+        end
+
+        # @!visibility private
+        class WorkflowInbound < Worker::Interceptor::Workflow::Inbound
+          def initialize(root, next_interceptor)
+            super(next_interceptor)
+            @root = root
+          end
+
+          # @!visibility private
+          def init(outbound)
+            # Set root on storage
+            Temporalio::Workflow.storage[:__temporal_opentelemetry_tracing_interceptor] = @root
+            super(WorkflowOutbound.new(@root, outbound))
+          end
+
+          # @!visibility private
+          def execute(input)
+            @root._attach_context(Temporalio::Workflow.info.headers)
+            Workflow.with_completed_span("RunWorkflow:#{Temporalio::Workflow.info.workflow_type}", kind: :server) do
+              super
+            ensure
+              Workflow.completed_span(
+                "CompleteWorkflow:#{Temporalio::Workflow.info.workflow_type}",
+                kind: :internal,
+                exception: $ERROR_INFO # steep:ignore
+              )
+            end
+          end
+
+          # @!visibility private
+          def handle_signal(input)
+            @root._attach_context(Temporalio::Workflow.info.headers)
+            Workflow.with_completed_span(
+              "HandleSignal:#{input.signal}",
+              links: _links_from_headers(input.headers),
+              kind: :server
+            ) do
+              super
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              Workflow.completed_span("FailHandleSignal:#{input.signal}", kind: :internal, exception: e)
+              raise
+            end
+          end
+
+          # @!visibility private
+          def handle_query(input)
+            @root._attach_context(Temporalio::Workflow.info.headers)
+            Workflow.with_completed_span(
+              "HandleQuery:#{input.query}",
+              links: _links_from_headers(input.headers),
+              kind: :server,
+              even_during_replay: true
+            ) do
+              super
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              Workflow.completed_span(
+                "FailHandleQuery:#{input.query}",
+                kind: :internal,
+                exception: e,
+                even_during_replay: true
+              )
+              raise
+            end
+          end
+
+          # @!visibility private
+          def validate_update(input)
+            @root._attach_context(Temporalio::Workflow.info.headers)
+            Workflow.with_completed_span(
+              "ValidateUpdate:#{input.update}",
+              attributes: { 'temporalUpdateID' => input.id },
+              links: _links_from_headers(input.headers),
+              kind: :server,
+              even_during_replay: true
+            ) do
+              super
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              Workflow.completed_span(
+                "FailValidateUpdate:#{input.update}",
+                attributes: { 'temporalUpdateID' => input.id },
+                kind: :internal,
+                exception: e,
+                even_during_replay: true
+              )
+              raise
+            end
+          end
+
+          # @!visibility private
+          def handle_update(input)
+            @root._attach_context(Temporalio::Workflow.info.headers)
+            Workflow.with_completed_span(
+              "HandleUpdate:#{input.update}",
+              attributes: { 'temporalUpdateID' => input.id },
+              links: _links_from_headers(input.headers),
+              kind: :server
+            ) do
+              super
+            rescue Exception => e # rubocop:disable Lint/RescueException
+              Workflow.completed_span(
+                "FailHandleUpdate:#{input.update}",
+                attributes: { 'temporalUpdateID' => input.id },
+                kind: :internal,
+                exception: e
+              )
+              raise
+            end
+          end
+
+          # @!visibility private
+          def _links_from_headers(headers)
+            context = @root._context_from_headers(headers)
+            span = ::OpenTelemetry::Trace.current_span(context) if context
+            if span && span != ::OpenTelemetry::Trace::Span::INVALID
+              [::OpenTelemetry::Trace::Link.new(span.context)]
+            else
+              []
+            end
+          end
+        end
+
+        # @!visibility private
+        class WorkflowOutbound < Worker::Interceptor::Workflow::Outbound
+          def initialize(root, next_interceptor)
+            super(next_interceptor)
+            @root = root
+          end
+
+          # @!visibility private
+          def execute_activity(input)
+            _apply_span_to_headers(input.headers,
+                                   Workflow.completed_span("StartActivity:#{input.activity}", kind: :client))
+            super
+          end
+
+          # @!visibility private
+          def execute_local_activity(input)
+            _apply_span_to_headers(input.headers,
+                                   Workflow.completed_span("StartActivity:#{input.activity}", kind: :client))
+            super
+          end
+
+          # @!visibility private
+          def initialize_continue_as_new_error(input)
+            # Just apply the current context to headers
+            @root._apply_context_to_headers(input.error.headers)
+            super
+          end
+
+          # @!visibility private
+          def signal_child_workflow(input)
+            _apply_span_to_headers(input.headers,
+                                   Workflow.completed_span("SignalChildWorkflow:#{input.signal}", kind: :client))
+            super
+          end
+
+          # @!visibility private
+          def signal_external_workflow(input)
+            _apply_span_to_headers(input.headers,
+                                   Workflow.completed_span("SignalExternalWorkflow:#{input.signal}", kind: :client))
+            super
+          end
+
+          # @!visibility private
+          def start_child_workflow(input)
+            _apply_span_to_headers(input.headers,
+                                   Workflow.completed_span("StartChildWorkflow:#{input.workflow}", kind: :client))
+            super
+          end
+
+          # @!visibility private
+          def _apply_span_to_headers(headers, span)
+            @root._apply_context_to_headers(headers, context: ::OpenTelemetry::Trace.context_with_span(span)) if span
+          end
+        end
+
+        private_constant :ClientOutbound
+        private_constant :ActivityInbound
+        private_constant :WorkflowInbound
+        private_constant :WorkflowOutbound
+      end
+
+      # Contains workflow methods that can be used for OpenTelemetry.
+      module Workflow
+        # Create a completed span and execute block with the span set on the context.
+        #
+        # @param name [String] Span name.
+        # @param attributes [Hash] Span attributes. These will have workflow and run ID automatically added.
+        # @param links [Array, nil] Span links.
+        # @param kind [Symbol, nil] Span kind.
+        # @param exception [Exception, nil] Exception to record on the span.
+        # @param even_during_replay [Boolean] Set to true to record this span even during replay. Most users should
+        #   never set this.
+        # @yield Block to call. It is UNSAFE to expect any parameters in this block.
+        # @return [Object] Result of the block.
+        def self.with_completed_span(
+          name,
+          attributes: {},
+          links: nil,
+          kind: nil,
+          exception: nil,
+          even_during_replay: false
+        )
+          span = completed_span(name, attributes:, links:, kind:, exception:, even_during_replay:)
+          if span
+            ::OpenTelemetry::Trace.with_span(span) do # rubocop:disable Style/ExplicitBlockArgument
+              # Yield with no parameters
+              yield
+            end
+          else
+            yield
+          end
+        end
+
+        # Create a completed span only if not replaying (or `even_during_replay` is true).
+        #
+        # @note WARNING: It is UNSAFE to rely on the result of this method as it may be different/absent on replay.
+        #
+        # @param name [String] Span name.
+        # @param attributes [Hash] Span attributes. These will have workflow and run ID automatically added.
+        # @param links [Array, nil] Span links.
+        # @param kind [Symbol, nil] Span kind.
+        # @param exception [Exception, nil] Exception to record on the span.
+        # @param even_during_replay [Boolean] Set to true to record this span even during replay. Most users should
+        #   never set this.
+        # @return [OpenTelemetry::Trace::Span, nil] Span if one was created. WARNING: It is UNSAFE to use this value.
+        def self.completed_span(
+          name,
+          attributes: {},
+          links: nil,
+          kind: nil,
+          exception: nil,
+          even_during_replay: false
+        )
+          # Get root interceptor, which also checks if in workflow
+          root = Temporalio::Workflow.storage[:__temporal_opentelemetry_tracing_interceptor] #: TracingInterceptor?
+          raise 'Tracing interceptor not configured' unless root
+
+          # Do nothing if replaying and not wanted during replay
+          return nil if !even_during_replay && Temporalio::Workflow::Unsafe.replaying?
+
+          # If there is no span on the context and the user hasn't opted in to always creating, do not create. This
+          # prevents orphans if there was no span originally created from the client start-workflow call.
+          if ::OpenTelemetry::Trace.current_span == ::OpenTelemetry::Trace::Span::INVALID &&
+             !root._always_create_workflow_spans
+            return nil
+          end
+
+          # Create attributes, adding user-defined ones
+          attributes = { 'temporalWorkflowID' => Temporalio::Workflow.info.workflow_id,
+                         'temporalRunID' => Temporalio::Workflow.info.run_id }.merge(attributes)
+
+          time = Temporalio::Workflow.now.dup
+          # Disable illegal call tracing because OTel asks for full exception message which uses error highlighting and
+          # such which accesses File#path, and they also use loggers accessing current time
+          Temporalio::Workflow::Unsafe.illegal_call_tracing_disabled do
+            # Disable durable scheduler because 1) synchronous/non-batch span processors in OTel use network (though
+            # could have just used Unafe.io_enabled for this if not for the next point) and 2) OTel uses Ruby Timeout
+            # which we don't want to use durable timers.
+            Temporalio::Workflow::Unsafe.durable_scheduler_disabled do
+              span = root.tracer.start_span(name, attributes:, links:, start_timestamp: time, kind:) # steep:ignore
+              # Record exception if present
+              span.record_exception(exception) if exception
+              # Finish the span (returns self)
+              span.finish(end_timestamp: time)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/temporalio/converters/data_converter.rb

@@ -40,9 +40,10 @@ module Temporalio
       # Convert a Ruby value to a payload and encode it.
       #
       # @param value [Object] Ruby value.
+      # @param hint [Object, nil] Hint, if any, to assist conversion.
       # @return [Api::Common::V1::Payload] Converted and encoded payload.
-      def to_payload(value)
-        payload = payload_converter.to_payload(value)
+      def to_payload(value, hint: nil)
+        payload = payload_converter.to_payload(value, hint:)
         payload = payload_codec.encode([payload]).first if payload_codec
         payload
       end
@@ -50,9 +51,13 @@ module Temporalio
       # Convert multiple Ruby values to a payload set and encode it.
       #
       # @param values [Object] Ruby values, converted to array via {::Array}.
+      # @param hints [Array<Object>, nil] Hints, if any, to assist conversion. Note, when using the default converter
+      #   that converts a payload at a time, hints for each value are taken from the array at that value's index. So if
+      #   there are fewer hints than values, some values will not have a hint. Similarly if there are more hints than
+      #   values, the trailing hints are not used.
       # @return [Api::Common::V1::Payloads] Converted and encoded payload set.
-      def to_payloads(values)
-        payloads = payload_converter.to_payloads(values)
+      def to_payloads(values, hints: nil)
+        payloads = payload_converter.to_payloads(values, hints:)
         payloads.payloads.replace(payload_codec.encode(payloads.payloads)) if payload_codec && !payloads.payloads.empty?
         payloads
       end
@@ -60,23 +65,28 @@ module Temporalio
       # Decode and convert a payload to a Ruby value.
       #
       # @param payload [Api::Common::V1::Payload] Encoded payload.
+      # @param hint [Object, nil] Hint, if any, to assist conversion.
       # @return [Object] Decoded and converted Ruby value.
-      def from_payload(payload)
+      def from_payload(payload, hint: nil)
         payload = payload_codec.decode([payload]).first if payload_codec
-        payload_converter.from_payload(payload)
+        payload_converter.from_payload(payload, hint:)
       end
 
       # Decode and convert a payload set to Ruby values.
       #
       # @param payloads [Api::Common::V1::Payloads, nil] Encoded payload set.
+      # @param hints [Array<Object>, nil] Hints, if any, to assist conversion. Note, when using the default converter
+      #   that converts a value at a time, hints for each payload are taken from the array at that payload's index. So
+      #   if there are fewer hints than payloads, some payloads will not have a hint. Similarly if there are more hints
+      #   than payloads, the trailing hints are not used.
       # @return [Array<Object>] Decoded and converted Ruby values.
-      def from_payloads(payloads)
+      def from_payloads(payloads, hints: nil)
         return [] unless payloads && !payloads.payloads.empty?
 
         if payload_codec && !payloads.payloads.empty?
           payloads = Api::Common::V1::Payloads.new(payloads: payload_codec.decode(payloads.payloads))
         end
-        payload_converter.from_payloads(payloads)
+        payload_converter.from_payloads(payloads, hints:)
       end
 
       # Convert a Ruby error to a Temporal failure and encode it.

data/lib/temporalio/converters/failure_converter.rb

@@ -45,7 +45,8 @@ module Temporalio
             type: error.type,
             non_retryable: error.non_retryable,
             details: converter.to_payloads(error.details),
-            next_retry_delay: Internal::ProtoUtils.seconds_to_duration(error.next_retry_delay)
+            next_retry_delay: Internal::ProtoUtils.seconds_to_duration(error.next_retry_delay),
+            category: error.category
           )
         when Error::TimeoutError
           failure.timeout_failure_info = Api::Failure::V1::TimeoutFailureInfo.new(
@@ -85,7 +86,7 @@ module Temporalio
           )
         else
           failure.application_failure_info = Api::Failure::V1::ApplicationFailureInfo.new(
-            type: error.class.name
+            type: error.class.name.to_s.split('::').last
           )
         end
 
@@ -132,7 +133,9 @@ module Temporalio
                     non_retryable: failure.application_failure_info.non_retryable,
                     next_retry_delay: Internal::ProtoUtils.duration_to_seconds(
                       failure.application_failure_info.next_retry_delay
-                    )
+                    ),
+                    category: Internal::ProtoUtils.enum_to_int(Api::Enums::V1::ApplicationErrorCategory,
+                                                               failure.application_failure_info.category)
                   )
                 elsif failure.timeout_failure_info
                   Error::TimeoutError.new(

data/lib/temporalio/converters/payload_converter/binary_null.rb

@@ -16,7 +16,7 @@ module Temporalio
         end
 
         # (see Encoding.to_payload)
-        def to_payload(value)
+        def to_payload(value, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           return nil unless value.nil?
 
           Api::Common::V1::Payload.new(
@@ -25,7 +25,7 @@ module Temporalio
         end
 
         # (see Encoding.from_payload)
-        def from_payload(payload) # rubocop:disable Lint/UnusedMethodArgument
+        def from_payload(payload, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           nil
         end
       end

data/lib/temporalio/converters/payload_converter/binary_plain.rb

@@ -16,7 +16,7 @@ module Temporalio
         end
 
         # (see Encoding.to_payload)
-        def to_payload(value)
+        def to_payload(value, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           return nil unless value.is_a?(String) && value.encoding == ::Encoding::ASCII_8BIT
 
           Temporalio::Api::Common::V1::Payload.new(
@@ -26,7 +26,7 @@ module Temporalio
         end
 
         # (see Encoding.from_payload)
-        def from_payload(payload)
+        def from_payload(payload, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           payload.data
         end
       end

data/lib/temporalio/converters/payload_converter/binary_protobuf.rb

@@ -17,7 +17,7 @@ module Temporalio
         end
 
         # (see Encoding.to_payload)
-        def to_payload(value)
+        def to_payload(value, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           return nil unless value.is_a?(Google::Protobuf::MessageExts)
 
           # @type var value: Google::Protobuf::MessageExts
@@ -28,7 +28,7 @@ module Temporalio
         end
 
         # (see Encoding.from_payload)
-        def from_payload(payload)
+        def from_payload(payload, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           type = payload.metadata['messageType']
           # @type var desc: untyped
           desc = Google::Protobuf::DescriptorPool.generated_pool.lookup(type)

data/lib/temporalio/converters/payload_converter/composite.rb

@@ -32,14 +32,15 @@ module Temporalio
         # Convert Ruby value to a payload by going over each encoding converter in order until one can convert.
         #
         # @param value [Object] Ruby value to convert.
+        # @param hint [Object, nil] Hint, if any, to assist conversion.
         # @return [Api::Common::V1::Payload] Converted payload.
         # @raise [ConverterNotFound] If no converters can process the value.
-        def to_payload(value)
+        def to_payload(value, hint: nil)
           # As a special case, raw values just return the payload within
           return value.payload if value.is_a?(RawValue)
 
           converters.each_value do |converter|
-            payload = converter.to_payload(value)
+            payload = converter.to_payload(value, hint:)
             return payload unless payload.nil?
           end
           raise ConverterNotFound, "Value of type #{value} has no known converter"
@@ -48,17 +49,18 @@ module Temporalio
         # Convert payload to Ruby value based on its +encoding+ metadata on the payload.
         #
         # @param payload [Api::Common::V1::Payload] Payload to convert.
+        # @param hint [Object, nil] Hint, if any, to assist conversion.
         # @return [Object] Converted Ruby value.
         # @raise [EncodingNotSet] If encoding not set on the metadata.
         # @raise [ConverterNotFound] If no converter found for the encoding.
-        def from_payload(payload)
+        def from_payload(payload, hint: nil)
           encoding = payload.metadata['encoding']
           raise EncodingNotSet, 'Missing payload encoding' unless encoding
 
           converter = converters[encoding]
           raise ConverterNotFound, "No converter for encoding #{encoding}" unless converter
 
-          converter.from_payload(payload)
+          converter.from_payload(payload, hint:)
         end
       end
     end

data/lib/temporalio/converters/payload_converter/encoding.rb

@@ -16,8 +16,9 @@ module Temporalio
         # handle it, the resulting payload must have +encoding+ metadata on the payload set to the value of {encoding}.
         #
         # @param value [Object] Ruby value to possibly convert.
+        # @param hint [Object, nil] Hint, if any, to assist conversion.
         # @return [Api::Common::V1::Payload, nil] Converted payload if it can handle it, +nil+ otherwise.
-        def to_payload(value)
+        def to_payload(value, hint: nil)
           raise NotImplementedError
         end
 
@@ -25,8 +26,9 @@ module Temporalio
         # will error if it cannot convert.
         #
         # @param payload [Api::Common::V1::Payload] Payload to convert.
+        # @param hint [Object, nil] Hint, if any, to assist conversion.
         # @return [Object] Converted Ruby value.
-        def from_payload(payload)
+        def from_payload(payload, hint: nil)
           raise NotImplementedError
         end
       end