temporalio 0.4.0-x86_64-linux → 0.6.0-x86_64-linux

data/lib/temporalio/client/workflow_handle.rb

@@ -48,13 +48,21 @@ module Temporalio
       # @return [String, nil] First execution run ID.
       attr_reader :first_execution_run_id
 
+      # Result hint for the result of this workflow. If this handle was created via {Client.start_workflow}, this is set
+      # from there (either via result hint on that call or workflow definition's result hint). Otherwise, the result
+      # hint is set by the creator of the handle.
+      #
+      # @return [Object, nil] Result hint.
+      attr_reader :result_hint
+
       # @!visibility private
-      def initialize(client:, id:, run_id:, result_run_id:, first_execution_run_id:)
+      def initialize(client:, id:, run_id:, result_run_id:, first_execution_run_id:, result_hint:)
         @client = client
         @id = id
         @run_id = run_id
         @result_run_id = result_run_id
         @first_execution_run_id = first_execution_run_id
+        @result_hint = result_hint
       end
 
       # Wait for the result of the workflow.
@@ -64,6 +72,8 @@ module Temporalio
       #
       # @param follow_runs [Boolean] If +true+, workflow runs will be continually fetched across retries and continue as
       #   new until the latest one is found. If +false+, the first result is used.
+      # @param result_hint [Object, nil] Override the result hint for the result. If unset/nil, uses one on the handle
+      #   itself.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object] Result of the workflow after being converted by the data converter.
@@ -71,7 +81,7 @@ module Temporalio
       # @raise [Error::WorkflowFailedError] Workflow failed with +cause+ as the cause.
       # @raise [Error::WorkflowContinuedAsNewError] Workflow continued as new and +follow_runs+ is +false+.
       # @raise [Error::RPCError] RPC error from call.
-      def result(follow_runs: true, rpc_options: nil)
+      def result(follow_runs: true, result_hint: nil, rpc_options: nil)
         # Wait on the close event, following as needed
         hist_run_id = result_run_id
         loop do
@@ -91,7 +101,7 @@ module Temporalio
             hist_run_id = attrs.new_execution_run_id
             next if follow_runs && hist_run_id && !hist_run_id.empty?
 
-            return @client.data_converter.from_payloads(attrs.result).first
+            return @client.data_converter.from_payloads(attrs.result, hints: Array(@result_hint || result_hint)).first
           when :EVENT_TYPE_WORKFLOW_EXECUTION_FAILED
             attrs = event.workflow_execution_failed_event_attributes
             hist_run_id = attrs.new_execution_run_id
@@ -212,18 +222,22 @@ module Temporalio
       #
       # @param signal [Workflow::Definition::Signal, Symbol, String] Signal definition or name.
       # @param args [Array<Object>] Signal arguments.
+      # @param arg_hints [Array<Object>, nil] Signal argument hints. If unset/nil and a signal definition is passed,
+      #   uses the ones on the signal definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @raise [Error::RPCError] RPC error from call.
       #
       # @note Handles created as a result of {Client.start_workflow} will signal the latest workflow with the same
       #   workflow ID even if it is unrelated to the started workflow.
-      def signal(signal, *args, rpc_options: nil)
+      def signal(signal, *args, arg_hints: nil, rpc_options: nil)
+        signal, defn_arg_hints = Workflow::Definition::Signal._name_and_hints_from_parameter(signal)
         @client._impl.signal_workflow(Interceptor::SignalWorkflowInput.new(
                                         workflow_id: id,
                                         run_id:,
-                                        signal: Workflow::Definition::Signal._name_from_parameter(signal),
+                                        signal:,
                                         args:,
+                                        arg_hints: arg_hints || defn_arg_hints,
                                         headers: {},
                                         rpc_options:
                                       ))
@@ -235,6 +249,10 @@ module Temporalio
       # @param query [Workflow::Definition::Query, Symbol, String] Query definition or name.
       # @param args [Array<Object>] Query arguments.
       # @param reject_condition [WorkflowQueryRejectCondition, nil] Condition for rejecting the query.
+      # @param arg_hints [Array<Object>, nil] Query argument hints. If unset/nil and a query definition is passed,
+      #   uses the ones on the query definition if present.
+      # @param result_hint [Object, nil] Query result hints. If unset/nil and a query definition is passed, uses the
+      #   one on the query definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Query result.
@@ -249,14 +267,19 @@ module Temporalio
         query,
         *args,
         reject_condition: @client.options.default_workflow_query_reject_condition,
+        arg_hints: nil,
+        result_hint: nil,
         rpc_options: nil
       )
+        query, defn_arg_hints, defn_result_hint = Workflow::Definition::Query._name_and_hints_from_parameter(query)
         @client._impl.query_workflow(Interceptor::QueryWorkflowInput.new(
                                        workflow_id: id,
                                        run_id:,
-                                       query: Workflow::Definition::Query._name_from_parameter(query),
+                                       query:,
                                        args:,
                                        reject_condition:,
+                                       arg_hints: arg_hints || defn_arg_hints,
+                                       result_hint: result_hint || defn_result_hint,
                                        headers: {},
                                        rpc_options:
                                      ))
@@ -270,6 +293,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] Update argument hints. If unset/nil and am update definition is passed,
+      #   uses the ones on the update definition if present.
+      # @param result_hint [Object, nil] Update result hints. If unset/nil and an update definition is passed, uses the
+      #   one on the update definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [WorkflowUpdateHandle] The update handle.
@@ -285,15 +312,20 @@ module Temporalio
         *args,
         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)
         @client._impl.start_workflow_update(Interceptor::StartWorkflowUpdateInput.new(
                                               workflow_id: self.id,
                                               run_id:,
                                               update_id: id,
-                                              update: Workflow::Definition::Update._name_from_parameter(update),
+                                              update:,
                                               args:,
                                               wait_for_stage:,
+                                              arg_hints: arg_hints || defn_arg_hints,
+                                              result_hint: result_hint || defn_result_hint,
                                               headers: {},
                                               rpc_options:
                                             ))
@@ -305,6 +337,10 @@ module Temporalio
       # @param update [Workflow::Definition::Update, Symbol, String] Update definition or name.
       # @param args [Array<Object>] Update arguments.
       # @param id [String] ID of the update.
+      # @param arg_hints [Array<Object>, nil] Update argument hints. If unset/nil and am update definition is passed,
+      #   uses the ones on the update definition if present.
+      # @param result_hint [Object, nil] Update result hints. If unset/nil and an update definition is passed, uses the
+      #   one on the update definition if present.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
@@ -316,12 +352,14 @@ module Temporalio
       #
       # @note Handles created as a result of {Client.start_workflow} will send updates the latest workflow with the same
       #   workflow ID even if it is unrelated to the started workflow.
-      def execute_update(update, *args, id: SecureRandom.uuid, rpc_options: nil)
+      def execute_update(update, *args, id: SecureRandom.uuid, arg_hints: nil, result_hint: nil, rpc_options: nil)
         start_update(
           update,
           *args,
           wait_for_stage: WorkflowUpdateWaitStage::COMPLETED,
           id:,
+          arg_hints:,
+          result_hint:,
           rpc_options:
         ).result
       end
@@ -331,15 +369,17 @@ module Temporalio
       # @param id [String] ID of the update.
       # @param specific_run_id [String, nil] Workflow run ID to get update handle for. Default is the {run_id}. Most
       #   users will not need to set this and instead use the one on the class.
+      # @param result_hint [Object, nil] Result hint for the update result to set on the handle.
       #
       # @return [WorkflowUpdateHandle] The update handle.
-      def update_handle(id, specific_run_id: run_id)
+      def update_handle(id, specific_run_id: run_id, result_hint: nil)
         WorkflowUpdateHandle.new(
           client: @client,
           id:,
           workflow_id: self.id,
           workflow_run_id: specific_run_id,
-          known_outcome: nil
+          known_outcome: nil,
+          result_hint:
         )
       end
 

data/lib/temporalio/client/workflow_update_handle.rb

@@ -18,13 +18,17 @@ module Temporalio
       # @return [String, nil] Run ID for the workflow.
       attr_reader :workflow_run_id
 
+      # @return [Object, nil] Result hint if one set when the handle was created.
+      attr_reader :result_hint
+
       # @!visibility private
-      def initialize(client:, id:, workflow_id:, workflow_run_id:, known_outcome:)
+      def initialize(client:, id:, workflow_id:, workflow_run_id:, known_outcome:, result_hint:)
         @client = client
         @id = id
         @workflow_id = workflow_id
         @workflow_run_id = workflow_run_id
         @known_outcome = known_outcome
+        @result_hint = result_hint
       end
 
       # @return [Boolean] True if the result is already known and {result} will not make a blocking call, false if
@@ -36,6 +40,7 @@ module Temporalio
       # Wait for and return the result of the update. The result may already be known in which case no network call is
       # made. Otherwise the result will be polled for until it is returned.
       #
+      # @param result_hint [Object, nil] If not nil, overrides handle-level result hint for getting the result.
       # @param rpc_options [RPCOptions, nil] Advanced RPC options.
       #
       # @return [Object, nil] Update result.
@@ -44,7 +49,7 @@ module Temporalio
       # @raise [Error::WorkflowUpdateRPCTimeoutOrCanceledError] This update call timed out or was canceled. This doesn't
       #   mean the update itself was timed out or canceled.
       # @raise [Error::RPCError] RPC error from call.
-      def result(rpc_options: nil)
+      def result(result_hint: nil, rpc_options: nil)
         @known_outcome ||= @client._impl.poll_workflow_update(Interceptor::PollWorkflowUpdateInput.new(
                                                                 workflow_id:,
                                                                 run_id: workflow_run_id,
@@ -56,7 +61,8 @@ module Temporalio
           raise Error::WorkflowUpdateFailedError.new, cause: @client.data_converter.from_failure(@known_outcome.failure)
         end
 
-        results = @client.data_converter.from_payloads(@known_outcome.success)
+        results = @client.data_converter.from_payloads(@known_outcome.success,
+                                                       hints: Array(result_hint || @result_hint))
         warn("Expected 0 or 1 update result, got #{results.size}") if results.size > 1
         results.first
       end

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,16 @@ 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
-          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
+          time = Temporalio::Workflow.now.dup
+          # 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: timestamp)
+            span.finish(end_timestamp: time)
           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