temporalio 1.9.0-aarch64-linux → 1.10.0-aarch64-linux

data/lib/temporalio/internal/external_storage_references.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'temporalio/api'
+require 'temporalio/api/sdk/v1/external_storage'
+
+module Temporalio
+  module Internal
+    # The on-the-wire form of a payload that has been offloaded to external storage.
+    #
+    # An offloaded payload is replaced by one whose data is the proto-JSON form of an
+    # +ExternalStorageReference+. This shape is part of the wire contract and must not be changed unilaterally.
+    #
+    # @!visibility private
+    module ExternalStorageReferences
+      ENCODING = 'json/protobuf'
+      MESSAGE_TYPE = 'temporal.api.sdk.v1.ExternalStorageReference'
+
+      class << self
+        # @param payload [Api::Common::V1::Payload] Payload to check.
+        # @return [Boolean] Whether the payload is a reference to externally stored data.
+        def reference?(payload)
+          payload.metadata['encoding'] == ENCODING && payload.metadata['messageType'] == MESSAGE_TYPE
+        end
+
+        # @param payload [Api::Common::V1::Payload] Payload to parse.
+        # @return [Api::Sdk::V1::ExternalStorageReference, nil] Parsed reference, or nil if not a reference.
+        #
+        # TODO: Surface parse failures as a Temporal error instead of Google::Protobuf::ParseError. The runner is the
+        # right layer for it, since only the caller knows which payload failed; a malformed reference cannot name its
+        # own driver.
+        def parse_reference(payload)
+          return nil unless reference?(payload)
+
+          # Another SDK may add fields to the reference before this one knows about them, and an unknown field must
+          # not make an otherwise-valid payload unreadable.
+          Api::Sdk::V1::ExternalStorageReference.decode_json(
+            payload.data, ignore_unknown_fields: true
+          )
+        end
+
+        # @param driver_name [String] Name of the driver that stored the payload.
+        # @param claim_data [Hash<String, String>] Driver data identifying the stored payload.
+        # @param original_size_bytes [Integer] Encoded size of the payload that was offloaded.
+        # @return [Api::Common::V1::Payload] Reference payload that replaces the offloaded payload on the wire.
+        def create_reference_payload(driver_name:, claim_data:, original_size_bytes:)
+          reference = Api::Sdk::V1::ExternalStorageReference.new(
+            driver_name:, claim_data: claim_data.to_h
+          )
+          Api::Common::V1::Payload.new(
+            metadata: { 'encoding' => ENCODING.b, 'messageType' => MESSAGE_TYPE.b },
+            data: reference.to_json.b,
+            # The original size is kept so the server and UI can report what the payload would have been without
+            # having to fetch it from storage.
+            external_payloads: [
+              Api::Common::V1::Payload::ExternalPayloadDetails.new(size_bytes: original_size_bytes)
+            ]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -298,6 +298,7 @@ module Temporalio
             memo:,
             search_attributes:,
             priority:,
+            versioning_override:,
             arg_hints:,
             result_hint:
           )
@@ -323,6 +324,7 @@ module Temporalio
                 memo:,
                 search_attributes:,
                 priority:,
+                versioning_override:,
                 arg_hints: arg_hints || defn_arg_hints,
                 result_hint: result_hint || defn_result_hint,
                 headers: {}

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

@@ -367,7 +367,8 @@ module Temporalio
                   memo: ProtoUtils.memo_to_proto_hash(input.memo, @instance.payload_converter),
                   search_attributes: input.search_attributes&._to_proto,
                   cancellation_type: input.cancellation_type,
-                  priority: input.priority._to_proto
+                  priority: input.priority._to_proto,
+                  versioning_override: input.versioning_override&._to_proto
                 ),
                 user_metadata: ProtoUtils.to_user_metadata(
                   input.static_summary, input.static_details, @instance.payload_converter
@@ -415,14 +416,31 @@ module Temporalio
             when :failed
               # Remove cancel callback and handle failure
               input.cancellation.remove_cancel_callback(cancel_callback_key)
-              if resolution.failed.cause == :START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_WORKFLOW_ALREADY_EXISTS
+              case resolution.failed.cause
+              when :START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_WORKFLOW_ALREADY_EXISTS
                 raise Error::WorkflowAlreadyStartedError.new(
                   workflow_id: resolution.failed.workflow_id,
                   workflow_type: resolution.failed.workflow_type,
                   run_id: nil
                 )
+              when :START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_INVALID_VERSIONING_OVERRIDE
+                cause = Error::InvalidVersioningOverrideError.new
+              when :START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_NAMESPACE_NOT_FOUND
+                cause = Error::NamespaceNotFoundError.new
+              else
+                raise "Unknown child start fail cause: #{resolution.failed.cause}"
               end
-              raise "Unknown child start fail cause: #{resolution.failed.cause}"
+              # Core does not supply event IDs or a run ID when the child never started.
+              raise Error::ChildWorkflowError.new(
+                'Child workflow failed to start',
+                namespace: @instance.info.namespace,
+                workflow_id: resolution.failed.workflow_id,
+                run_id: '',
+                workflow_type: resolution.failed.workflow_type,
+                initiated_event_id: 0,
+                started_event_id: 0,
+                retry_state: nil
+              ), cause: cause
             when :cancelled
               # Remove cancel callback and handle cancel
               input.cancellation.remove_cancel_callback(cancel_callback_key)

data/lib/temporalio/testing/activity_environment.rb

@@ -152,7 +152,7 @@ module Temporalio
         end
 
         # @!visibility private
-        def heartbeat(*details)
+        def heartbeat(*details, detail_hints: nil) # rubocop:disable Lint/UnusedMethodArgument
           @on_heartbeat&.call(details)
         end
 

data/lib/temporalio/testing/workflow_environment.rb

@@ -23,8 +23,8 @@ module Temporalio
 
       # Start a local dev server. This is a full Temporal dev server from the CLI that by default downloaded to tmp if
       # not already present. The dev server is run as a child process. All options that start with +dev_server_+ are for
-      # this specific implementation and therefore are not stable and may be changed as the underlying implementation
-      # changes.
+      # this specific implementation. If that implementation changes, these options and their values may no longer be
+      # valid.
       #
       # If a block is given it is passed the environment and the environment is shut down after. If a block is not
       # given, the environment is returned and {shutdown} needs to be called manually.
@@ -124,8 +124,8 @@ module Temporalio
 
       # Start a time-skipping test server. This server can skip time but may not have all of the Temporal features of
       # the {start_local} form. By default, the server is downloaded to tmp if not already present. The test server is
-      # run as a child process. All options that start with +test_server_+ are for this specific implementation and
-      # therefore are not stable and may be changed as the underlying implementation changes.
+      # run as a child process. All options that start with +test_server_+ are for this specific implementation. If that
+      # implementation changes, these options and their values may no longer be valid.
       #
       # If a block is given it is passed the environment and the environment is shut down after. If a block is not
       # given, the environment is returned and {shutdown} needs to be called manually.

data/lib/temporalio/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Temporalio
-  VERSION = '1.9.0'
+  VERSION = '1.10.0'
 end

data/lib/temporalio/versioning_override.rb

@@ -3,7 +3,7 @@
 require 'temporalio/worker_deployment_version'
 
 module Temporalio
-  # Base class for version overrides that can be provided in start workflow options.
+  # Base class for version overrides that can be provided when starting workflows, including child workflows.
   # Used to control the versioning behavior of workflows started with this override.
   class VersioningOverride
     # @!visibility private
@@ -50,5 +50,32 @@ module Temporalio
         )
       end
     end
+
+    # Routes workflow tasks to a target deployment version until a task completes there, then clears the override.
+    # Subsequent tasks follow the workflow's normal versioning behavior.
+    #
+    # Requires Temporal Server 1.32.0 or later.
+    # WARNING: This override is experimental.
+    class OneTime < VersioningOverride
+      # @return [WorkerDeploymentVersion] Target worker deployment version.
+      attr_reader :target_version
+
+      # Create a one-time versioning override.
+      #
+      # @param target_version [WorkerDeploymentVersion] Target worker deployment version.
+      def initialize(target_version)
+        @target_version = target_version
+        super()
+      end
+
+      # @!visibility private
+      def _to_proto
+        Api::Workflow::V1::VersioningOverride.new(
+          one_time: Api::Workflow::V1::VersioningOverride::OneTimeOverride.new(
+            target_deployment_version: @target_version._to_proto
+          )
+        )
+      end
+    end
   end
 end

data/lib/temporalio/worker/interceptor.rb

@@ -295,6 +295,7 @@ module Temporalio
           :memo,
           :search_attributes,
           :priority,
+          :versioning_override,
           :arg_hints,
           :result_hint,
           :headers

data/lib/temporalio/workflow.rb

@@ -4,6 +4,7 @@ require 'random/formatter'
 require 'temporalio/error'
 require 'temporalio/internal/worker/workflow_instance'
 require 'temporalio/priority'
+require 'temporalio/versioning_override'
 require 'temporalio/workflow/activity_cancellation_type'
 require 'temporalio/workflow/child_workflow_cancellation_type'
 require 'temporalio/workflow/child_workflow_handle'
@@ -158,7 +159,7 @@ module Temporalio
     #   optimization on some servers that sends activities back to the same worker as the calling workflow if they can
     #   run there. If `false` (the default), eager execution may still be disabled at the worker level or may not be
     #   requested due to lack of available slots.
-    # @param priority [Priority] Priority of the activity. This is currently experimental.
+    # @param priority [Priority] Priority of the activity.
     # @param arg_hints [Array<Object>, nil] Overrides converter hints for arguments if any. If unset/nil and the
     #   activity 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 activity
@@ -214,6 +215,7 @@ module Temporalio
       memo: nil,
       search_attributes: nil,
       priority: Priority.default,
+      versioning_override: nil,
       arg_hints: nil,
       result_hint: nil
     )
@@ -221,7 +223,8 @@ module Temporalio
         workflow, *args,
         id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
         parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
-        retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, arg_hints:, result_hint:
+        retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, versioning_override:,
+        arg_hints:, result_hint:
       ).result
     end
 
@@ -424,7 +427,10 @@ module Temporalio
     # @param cron_schedule [String, nil] Cron schedule. Users should use schedules instead of this.
     # @param memo [Hash{String, Symbol => Object}, nil] Memo for the workflow.
     # @param search_attributes [SearchAttributes, nil] Search attributes for the workflow.
-    # @param priority [Priority] Priority of the workflow. This is currently experimental.
+    # @param priority [Priority] Priority of the workflow.
+    # @param versioning_override [VersioningOverride, nil] Override the child's versioning independently of its parent.
+    #   If unset, normal versioning inheritance applies. Requires Temporal Server 1.32.0 or later.
+    #   WARNING: This option is 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
@@ -432,6 +438,8 @@ module Temporalio
     #
     # @return [ChildWorkflowHandle] Workflow handle to the started workflow.
     # @raise [Error::WorkflowAlreadyStartedError] Workflow already exists for the ID.
+    # @raise [Error::ChildWorkflowError] Child could not start. The cause is {Error::InvalidVersioningOverrideError}
+    #   for an invalid versioning override or {Error::NamespaceNotFoundError} for a missing namespace.
     # @raise [Error::CanceledError] Starting of the child was canceled.
     def self.start_child_workflow(
       workflow,
@@ -452,6 +460,7 @@ module Temporalio
       memo: nil,
       search_attributes: nil,
       priority: Priority.default,
+      versioning_override: nil,
       arg_hints: nil,
       result_hint: nil
     )
@@ -459,7 +468,8 @@ module Temporalio
         workflow, *args,
         id:, task_queue:, static_summary:, static_details:, cancellation:, cancellation_type:,
         parent_close_policy:, execution_timeout:, run_timeout:, task_timeout:, id_reuse_policy:,
-        retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, arg_hints:, result_hint:
+        retry_policy:, cron_schedule:, memo:, search_attributes:, priority:, versioning_override:,
+        arg_hints:, result_hint:
       )
     end
 

data/rbi/temporalio/api/activity/v1/message.rbi

@@ -382,7 +382,9 @@ class Temporalio::Api::Activity::V1::ActivityExecutionInfo
       sdk_name: T.nilable(String),
       sdk_version: T.nilable(String),
       start_delay: T.nilable(Google::Protobuf::Duration),
-      execution_time: T.nilable(Google::Protobuf::Timestamp)
+      execution_time: T.nilable(Google::Protobuf::Timestamp),
+      propagated_nexus_serialization_context: T.nilable(Temporalio::Api::Nexus::V1::PropagatedSerializationContext),
+      eager_execution_accepted: T.nilable(T::Boolean)
     ).void
   end
   def initialize(
@@ -423,7 +425,9 @@ class Temporalio::Api::Activity::V1::ActivityExecutionInfo
     sdk_name: "",
     sdk_version: "",
     start_delay: nil,
-    execution_time: nil
+    execution_time: nil,
+    propagated_nexus_serialization_context: nil,
+    eager_execution_accepted: false
   )
   end
 
@@ -1060,6 +1064,39 @@ class Temporalio::Api::Activity::V1::ActivityExecutionInfo
   def clear_execution_time
   end
 
+  # Serialization context propagated from the Nexus caller that started this activity.
+  sig { returns(T.nilable(Temporalio::Api::Nexus::V1::PropagatedSerializationContext)) }
+  def propagated_nexus_serialization_context
+  end
+
+  # Serialization context propagated from the Nexus caller that started this activity.
+  sig { params(value: T.nilable(Temporalio::Api::Nexus::V1::PropagatedSerializationContext)).void }
+  def propagated_nexus_serialization_context=(value)
+  end
+
+  # Serialization context propagated from the Nexus caller that started this activity.
+  sig { void }
+  def clear_propagated_nexus_serialization_context
+  end
+
+  # Indicates whether eager execution was requested for this activity and accepted by the server
+# for its first task.
+  sig { returns(T::Boolean) }
+  def eager_execution_accepted
+  end
+
+  # Indicates whether eager execution was requested for this activity and accepted by the server
+# for its first task.
+  sig { params(value: T::Boolean).void }
+  def eager_execution_accepted=(value)
+  end
+
+  # Indicates whether eager execution was requested for this activity and accepted by the server
+# for its first task.
+  sig { void }
+  def clear_eager_execution_accepted
+  end
+
   sig { params(field: String).returns(T.untyped) }
   def [](field)
   end

data/rbi/temporalio/api/callback/v1/message.rbi

@@ -16,7 +16,8 @@ class Temporalio::Api::Callback::V1::CallbackInfo
       last_attempt_complete_time: T.nilable(Google::Protobuf::Timestamp),
       last_attempt_failure: T.nilable(Temporalio::Api::Failure::V1::Failure),
       next_attempt_schedule_time: T.nilable(Google::Protobuf::Timestamp),
-      blocked_reason: T.nilable(String)
+      blocked_reason: T.nilable(String),
+      request_id: T.nilable(String)
     ).void
   end
   def initialize(
@@ -27,7 +28,8 @@ class Temporalio::Api::Callback::V1::CallbackInfo
     last_attempt_complete_time: nil,
     last_attempt_failure: nil,
     next_attempt_schedule_time: nil,
-    blocked_reason: ""
+    blocked_reason: "",
+    request_id: ""
   )
   end
 
@@ -154,6 +156,24 @@ class Temporalio::Api::Callback::V1::CallbackInfo
   def clear_blocked_reason
   end
 
+  # Server-generated request ID used as an idempotency token when invoking callbacks.
+# It has no relation to caller-side request_id sent in operations like StartNexusOperationExecutionRequest.
+  sig { returns(String) }
+  def request_id
+  end
+
+  # Server-generated request ID used as an idempotency token when invoking callbacks.
+# It has no relation to caller-side request_id sent in operations like StartNexusOperationExecutionRequest.
+  sig { params(value: String).void }
+  def request_id=(value)
+  end
+
+  # Server-generated request ID used as an idempotency token when invoking callbacks.
+# It has no relation to caller-side request_id sent in operations like StartNexusOperationExecutionRequest.
+  sig { void }
+  def clear_request_id
+  end
+
   sig { params(field: String).returns(T.untyped) }
   def [](field)
   end