temporalio 0.4.0 → 0.5.0

data/lib/temporalio/client.rb

@@ -19,9 +19,11 @@ require 'temporalio/common_enums'
 require 'temporalio/converters'
 require 'temporalio/error'
 require 'temporalio/internal/client/implementation'
+require 'temporalio/priority'
 require 'temporalio/retry_policy'
 require 'temporalio/runtime'
 require 'temporalio/search_attributes'
+require 'temporalio/versioning_override'
 require 'temporalio/workflow/definition'
 
 module Temporalio
@@ -48,6 +50,16 @@ module Temporalio
     # Options as returned from {options} for +**to_h+ splat use in {initialize}. See {initialize} for details.
     class Options; end # rubocop:disable Lint/EmptyClass
 
+    ListWorkflowPage = Data.define(:executions, :next_page_token)
+
+    # A page of workflow executions returned by {Client#list_workflow_page}.
+    #
+    # @!attribute executions
+    #   @return [Array<WorkflowExecution>] List of workflow executions in this page.
+    # @!attribute next_page_token
+    #   @return [String, nil] Token for the next page of results. nil if there are no more results.
+    class ListWorkflowPage; end # rubocop:disable Lint/EmptyClass
+
     # Connect to Temporal server. This is a shortcut for +Connection.new+ followed by +Client.new+.
     #
     # @param target_host [String] +host:port+ for the Temporal server. For local development, this is often
@@ -216,6 +228,13 @@ module Temporalio
     #   with `cron_schedule`.
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
+    # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
+    #   This is currently experimental.
+    # @param priority [Priority] Priority of the workflow. This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+    #   workflow definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
+    #   definition has result hint, it is used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [WorkflowHandle] A workflow handle to the started workflow.
@@ -239,10 +258,17 @@ module Temporalio
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
+      versioning_override: nil,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil,
       rpc_options: nil
     )
+      # Take hints from definition if there is a definition
+      workflow, defn_arg_hints, defn_result_hint =
+        Workflow::Definition._workflow_type_and_hints_from_workflow_parameter(workflow)
       @impl.start_workflow(Interceptor::StartWorkflowInput.new(
-                             workflow: Workflow::Definition._workflow_type_from_workflow_parameter(workflow),
+                             workflow:,
                              args:,
                              workflow_id: id,
                              task_queue:,
@@ -260,6 +286,10 @@ module Temporalio
                              start_delay:,
                              request_eager_start:,
                              headers: {},
+                             versioning_override:,
+                             priority:,
+                             arg_hints: arg_hints || defn_arg_hints,
+                             result_hint: result_hint || defn_result_hint,
                              rpc_options:
                            ))
     end
@@ -292,6 +322,13 @@ module Temporalio
     #   with `cron_schedule`.
     # @param request_eager_start [Boolean] Potentially reduce the latency to start this workflow by encouraging the
     #   server to start it on a local worker running with this same client. This is currently experimental.
+    # @param versioning_override [VersioningOverride, nil] Override the version of the workflow.
+    #   This is currently experimental.
+    # @param priority [Priority] Priority for the workflow. This is currently experimental.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
+    #   workflow definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for result if any. If unset/nil and the workflow
+    #   definition has result hint, it is used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [Object] Successful result of the workflow.
@@ -316,6 +353,10 @@ module Temporalio
       search_attributes: nil,
       start_delay: nil,
       request_eager_start: false,
+      versioning_override: nil,
+      priority: Priority.default,
+      arg_hints: nil,
+      result_hint: nil,
       rpc_options: nil
     )
       start_workflow(
@@ -336,6 +377,10 @@ module Temporalio
         search_attributes:,
         start_delay:,
         request_eager_start:,
+        versioning_override:,
+        priority:,
+        arg_hints:,
+        result_hint:,
         rpc_options:
       ).result
     end
@@ -347,14 +392,18 @@ module Temporalio
     #   interactions occur on the latest of the workflow ID.
     # @param first_execution_run_id [String, nil] First execution run ID used for some calls like cancellation and
     #   termination to ensure the affected workflow is only within the same chain as this given run ID.
+    # @param result_hint [Object, nil] Converter hint for the workflow's result.
     #
     # @return [WorkflowHandle] The workflow handle.
     def workflow_handle(
       workflow_id,
       run_id: nil,
-      first_execution_run_id: nil
+      first_execution_run_id: nil,
+      result_hint: nil
     )
-      WorkflowHandle.new(client: self, id: workflow_id, run_id:, result_run_id: run_id, first_execution_run_id:)
+      WorkflowHandle.new(
+        client: self, id: workflow_id, run_id:, result_run_id: run_id, first_execution_run_id:, result_hint:
+      )
     end
 
     # Start an update, possibly starting the workflow at the same time if it doesn't exist (depending upon ID conflict
@@ -368,6 +417,10 @@ module Temporalio
     # @param wait_for_stage [WorkflowUpdateWaitStage] Required stage to wait until returning. ADMITTED is not
     #   currently supported. See https://docs.temporal.io/workflows#update for more details.
     # @param id [String] ID of the update.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for update arguments if any. If unset/nil and the
+    #   update definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for update result if any. If unset/nil and the update
+    #   definition has result hint, it is used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [WorkflowUpdateHandle] The update handle.
@@ -381,15 +434,20 @@ module Temporalio
       start_workflow_operation:,
       wait_for_stage:,
       id: SecureRandom.uuid,
+      arg_hints: nil,
+      result_hint: nil,
       rpc_options: nil
     )
+      update, defn_arg_hints, defn_result_hint = Workflow::Definition::Update._name_and_hints_from_parameter(update)
       @impl.start_update_with_start_workflow(
         Interceptor::StartUpdateWithStartWorkflowInput.new(
           update_id: id,
-          update: Workflow::Definition::Update._name_from_parameter(update),
+          update:,
           args:,
           wait_for_stage:,
           start_workflow_operation:,
+          arg_hints: arg_hints || defn_arg_hints,
+          result_hint: result_hint || defn_result_hint,
           headers: {},
           rpc_options:
         )
@@ -405,6 +463,10 @@ module Temporalio
     # @param start_workflow_operation [WithStartWorkflowOperation] Required with-start workflow operation. This must
     #   have an `id_conflict_policy` set.
     # @param id [String] ID of the update.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for update arguments if any. If unset/nil and the
+    #   update definition has arg hints, those are used by default.
+    # @param result_hint [Object, nil] Overrides converter hint for update result if any. If unset/nil and the update
+    #   definition has result hint, it is used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [Object] Successful update result.
@@ -418,6 +480,8 @@ module Temporalio
       *args,
       start_workflow_operation:,
       id: SecureRandom.uuid,
+      arg_hints: nil,
+      result_hint: nil,
       rpc_options: nil
     )
       start_update_with_start_workflow(
@@ -426,6 +490,8 @@ module Temporalio
         start_workflow_operation:,
         wait_for_stage: WorkflowUpdateWaitStage::COMPLETED,
         id:,
+        arg_hints:,
+        result_hint:,
         rpc_options:
       ).result
     end
@@ -436,6 +502,8 @@ module Temporalio
     # @param args [Array<Object>] Signal arguments.
     # @param start_workflow_operation [WithStartWorkflowOperation] Required with-start workflow operation. This may not
     #   support all `id_conflict_policy` options.
+    # @param arg_hints [Array<Object>, nil] Overrides converter hints for signal arguments if any. If unset/nil and the
+    #   signal definition has arg hints, those are used by default.
     # @param rpc_options [RPCOptions, nil] Advanced RPC options.
     #
     # @return [WorkflowHandle] A workflow handle to the workflow.
@@ -445,13 +513,16 @@ module Temporalio
       signal,
       *args,
       start_workflow_operation:,
+      arg_hints: nil,
       rpc_options: nil
     )
+      signal, defn_arg_hints = Workflow::Definition::Signal._name_and_hints_from_parameter(signal)
       @impl.signal_with_start_workflow(
         Interceptor::SignalWithStartWorkflowInput.new(
-          signal: Workflow::Definition::Signal._name_from_parameter(signal),
+          signal:,
           args:,
           start_workflow_operation:,
+          arg_hints: arg_hints || defn_arg_hints,
           rpc_options:
         )
       )
@@ -468,7 +539,40 @@ module Temporalio
     #
     # @see https://docs.temporal.io/visibility
     def list_workflows(query = nil, rpc_options: nil)
-      @impl.list_workflows(Interceptor::ListWorkflowsInput.new(query:, rpc_options:))
+      next_page_token = nil
+      Enumerator.new do |yielder|
+        loop do
+          list_workflow_page_input = Interceptor::ListWorkflowPageInput.new(
+            query: query,
+            rpc_options: rpc_options,
+            next_page_token: next_page_token,
+            page_size: nil
+          )
+          page = @impl.list_workflow_page(list_workflow_page_input)
+          page.executions.each { |execution| yielder << execution }
+          next_page_token = page.next_page_token
+          break if (next_page_token || '').empty?
+        end
+      end
+    end
+
+    # List workflows one page at a time.
+    #
+    # @param query [String, nil] A Temporal visibility list filter.
+    # @param page_size [Integer, nil] Maximum number of results to return.
+    # @param next_page_token [String, nil] Token for the next page of results. If not set, the first page is returned.
+    # @param rpc_options [RPCOptions, nil] Advanced RPC options.
+    #
+    # @return [ListWorkflowPage] Page of workflow executions, along with a next_page_token to keep fetching.
+    #
+    # @raise [Error::RPCError] RPC error from call.
+    #
+    # @see https://docs.temporal.io/visibility
+    def list_workflow_page(query = nil, page_size: nil, next_page_token: nil, rpc_options: nil)
+      @impl.list_workflow_page(Interceptor::ListWorkflowPageInput.new(query:,
+                                                                      next_page_token:,
+                                                                      page_size:,
+                                                                      rpc_options:))
     end
 
     # Count workflows.

data/lib/temporalio/common_enums.rb

@@ -38,4 +38,18 @@ module Temporalio
     # Terminate the running workflow before starting a new one.
     TERMINATE_EXISTING = Api::Enums::V1::WorkflowIdConflictPolicy::WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING
   end
+
+  # Specifies when a workflow might move from a worker of one Build Id to another.
+  #
+  # WARNING: Experimental API.
+  module VersioningBehavior
+    # Unspecified versioning behavior. By default, workers opting into worker versioning will
+    # be required to specify a behavior.
+    UNSPECIFIED = Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_UNSPECIFIED
+    # The workflow will be pinned to the current Build ID unless manually moved.
+    PINNED = Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_PINNED
+    # The workflow will automatically move to the latest version (default Build ID of the task
+    # queue) when the next task is dispatched.
+    AUTO_UPGRADE = Api::Enums::V1::VersioningBehavior::VERSIONING_BEHAVIOR_AUTO_UPGRADE
+  end
 end

data/lib/temporalio/contrib/open_telemetry.rb

@@ -452,16 +452,20 @@ module Temporalio
           attributes = { 'temporalWorkflowID' => Temporalio::Workflow.info.workflow_id,
                          'temporalRunID' => Temporalio::Workflow.info.run_id }.merge(attributes)
 
-          # Create span, which has to be done with illegal call disabling because OTel asks for full exception message
-          # which uses error highlighting and such which accesses File#path
+          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
-            time = Temporalio::Workflow.now
-            timestamp = (time.to_i * 1_000_000_000) + time.nsec
-            span = root.tracer.start_span(name, attributes:, links:, start_timestamp: timestamp, kind:) # steep:ignore
-            # Record exception if present
-            span.record_exception(exception) if exception
-            # Finish the span (returns self)
-            span.finish(end_timestamp: timestamp)
+            # 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

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

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

@@ -27,7 +27,7 @@ module Temporalio
         end
 
         # (see Encoding.to_payload)
-        def to_payload(value)
+        def to_payload(value, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           Api::Common::V1::Payload.new(
             metadata: { 'encoding' => ENCODING },
             data: JSON.generate(value, @generate_options).b
@@ -35,7 +35,7 @@ module Temporalio
         end
 
         # (see Encoding.from_payload)
-        def from_payload(payload)
+        def from_payload(payload, hint: nil) # rubocop:disable Lint/UnusedMethodArgument
           JSON.parse(payload.data, @parse_options)
         end
       end

data/lib/temporalio/converters/payload_converter/json_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)
 
           Api::Common::V1::Payload.new(
@@ -27,7 +27,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.rb

@@ -34,37 +34,47 @@ module Temporalio
       # Convert a Ruby value to a payload.
       #
       # @param value [Object] Ruby value.
+      # @param hint [Object, nil] Hint, if any, to assist conversion.
       # @return [Api::Common::V1::Payload] Converted payload.
-      def to_payload(value)
+      def to_payload(value, hint: nil)
         raise NotImplementedError
       end
 
       # Convert multiple Ruby values to a payload set.
       #
       # @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 payload set.
-      def to_payloads(values)
+      def to_payloads(values, hints: nil)
         Api::Common::V1::Payloads.new(
-          payloads: Array(values).map { |value| to_payload(value) }
+          payloads: Array(values).zip(Array(hints)).map { |value, hint| to_payload(value, hint:) }
         )
       end
 
       # Convert a payload to a Ruby value.
       #
       # @param payload [Api::Common::V1::Payload] Payload.
+      # @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
 
       # Convert a payload set to Ruby values.
       #
       # @param payloads [Api::Common::V1::Payloads, nil] 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>] Converted Ruby values.
-      def from_payloads(payloads)
+      def from_payloads(payloads, hints: nil)
         return [] unless payloads
 
-        payloads.payloads.map { |payload| from_payload(payload) }
+        payloads.payloads.zip(Array(hints)).map { |payload, hint| from_payload(payload, hint:) }
       end
     end
   end

data/lib/temporalio/error/failure.rb

@@ -46,6 +46,9 @@ module Temporalio
       # @return [Float, nil] Delay in seconds before the next activity retry attempt.
       attr_reader :next_retry_delay
 
+      # @return [Category] Error category.
+      attr_reader :category
+
       # Create an application error.
       #
       # @param message [String] Error message.
@@ -53,18 +56,33 @@ module Temporalio
       # @param type [String, nil] Error type.
       # @param non_retryable [Boolean] Whether this error should be considered non-retryable.
       # @param next_retry_delay [Float, nil] Specific amount of time to delay before next retry.
-      def initialize(message, *details, type: nil, non_retryable: false, next_retry_delay: nil)
+      # @param category [Category] Error category.
+      def initialize(
+        message,
+        *details,
+        type: nil,
+        non_retryable: false,
+        next_retry_delay: nil,
+        category: Category::UNSPECIFIED
+      )
         super(message)
         @details = details
         @type = type
         @non_retryable = non_retryable
         @next_retry_delay = next_retry_delay
+        @category = category
       end
 
       # @return [Boolean] Inverse of {non_retryable}.
       def retryable?
         !@non_retryable
       end
+
+      # Error category.
+      module Category
+        UNSPECIFIED = Api::Enums::V1::ApplicationErrorCategory::APPLICATION_ERROR_CATEGORY_UNSPECIFIED
+        BENIGN = Api::Enums::V1::ApplicationErrorCategory::APPLICATION_ERROR_CATEGORY_BENIGN
+      end
     end
 
     # Error raised on workflow/activity cancellation.

data/lib/temporalio/error.rb

@@ -27,7 +27,7 @@ module Temporalio
           e
         end
       else
-        err.set_backtrace(backtrace)
+        err.set_backtrace(backtrace) if backtrace
         err
       end
     end