From b61e0870eb657d9ef256022ac59a33f79039da2f Mon Sep 17 00:00:00 2001 From: Chris Constable Date: Mon, 16 Nov 2026 14:44:15 -0700 Subject: [PATCH 1/3] feat(extstore): decode extstore references that were encoded by a codec. --- changelog/added/decoding-cloakroom-ticket.md | 1 + .../temporalio/converters/data_converter.rb | 7 +- temporalio/lib/temporalio/error.rb | 16 +++++ .../internal/external_storage_references.rb | 30 +++++++++ .../internal/external_storage_runner.rb | 4 +- .../internal/worker/activity_worker.rb | 11 ++- .../internal/worker/workflow_worker.rb | 5 +- temporalio/rbi/temporalio/error.rbi | 7 ++ .../internal/external_storage_references.rbi | 12 ++++ temporalio/sig/temporalio/error.rbs | 4 ++ .../internal/external_storage_references.rbs | 6 ++ .../test/external_storage_runner_test.rb | 9 +++ temporalio/test/external_storage_test.rb | 67 +++++++++++++++++++ temporalio/test/sig/external_storage_test.rbs | 1 + .../test/sig/worker_external_storage_test.rbs | 6 +- .../test/worker_external_storage_test.rb | 39 +++++++++++ 16 files changed, 219 insertions(+), 6 deletions(-) create mode 100644 changelog/added/decoding-cloakroom-ticket.md diff --git a/changelog/added/decoding-cloakroom-ticket.md b/changelog/added/decoding-cloakroom-ticket.md new file mode 100644 index 00000000..20aca331 --- /dev/null +++ b/changelog/added/decoding-cloakroom-ticket.md @@ -0,0 +1 @@ +Added experimental support for reading external storage reference payloads that are encoded with the configured payload codec and marked with `__temporal_external_storage_reference` metadata. This release does not write them yet. A later release will, once workers have had time to upgrade. diff --git a/temporalio/lib/temporalio/converters/data_converter.rb b/temporalio/lib/temporalio/converters/data_converter.rb index e3600ba0..f152d367 100644 --- a/temporalio/lib/temporalio/converters/data_converter.rb +++ b/temporalio/lib/temporalio/converters/data_converter.rb @@ -89,6 +89,9 @@ def to_payloads(values, hints: nil) # @param hint [Object, nil] Hint, if any, to assist conversion. # @return [Object] Decoded and converted Ruby value. def from_payload(payload, hint: nil) + if external_storage + payload = Internal::ExternalStorageReferences.decode_references([payload], payload_codec:).first + end payload = @external_storage_runner.retrieve([payload]).first payload = payload_codec.decode([payload]).first if payload_codec payload_converter.from_payload(payload, hint:) @@ -105,7 +108,9 @@ def from_payload(payload, hint: nil) def from_payloads(payloads, hints: nil) return [] unless payloads && !payloads.payloads.empty? - payloads = Api::Common::V1::Payloads.new(payloads: @external_storage_runner.retrieve(payloads.payloads.to_a)) + payloads = payloads.payloads.to_a + payloads = Internal::ExternalStorageReferences.decode_references(payloads, payload_codec:) if external_storage + payloads = Api::Common::V1::Payloads.new(payloads: @external_storage_runner.retrieve(payloads)) if payload_codec && !payloads.payloads.empty? payloads = Api::Common::V1::Payloads.new(payloads: payload_codec.decode(payloads.payloads)) end diff --git a/temporalio/lib/temporalio/error.rb b/temporalio/lib/temporalio/error.rb index e1d4c171..14d72932 100644 --- a/temporalio/lib/temporalio/error.rb +++ b/temporalio/lib/temporalio/error.rb @@ -133,6 +133,22 @@ def initialize( end end + # Error that occurs when a payload marked as an encoded external storage reference does not decode to a reference. + # This usually means the payload codec configured to read it is not the one that wrote it. + # + # @note WARNING: This API is experimental and may change in the future. + # + # @!visibility private + class ExternalStorageReferenceDecodeError < Error + # @!visibility private + def initialize( + message = '[TMPRL1106] Encountered an encoded external storage reference that could not be decoded. ' \ + 'Check that the payload codec used to write it is configured.' + ) + super + end + end + # Error raised by a client for a general RPC failure. class RPCError < Error # @return [Code] Status code for the error. diff --git a/temporalio/lib/temporalio/internal/external_storage_references.rb b/temporalio/lib/temporalio/internal/external_storage_references.rb index 15502b22..16d17351 100644 --- a/temporalio/lib/temporalio/internal/external_storage_references.rb +++ b/temporalio/lib/temporalio/internal/external_storage_references.rb @@ -2,6 +2,7 @@ require 'temporalio/api' require 'temporalio/api/sdk/v1/external_storage' +require 'temporalio/error' module Temporalio module Internal @@ -14,6 +15,7 @@ module Internal module ExternalStorageReferences ENCODING = 'json/protobuf' MESSAGE_TYPE = 'temporal.api.sdk.v1.ExternalStorageReference' + MARKER_KEY = '__temporal_external_storage_reference' class << self # @param payload [Api::Common::V1::Payload] Payload to check. @@ -38,6 +40,34 @@ def parse_reference(payload) ) end + # @param payload [Api::Common::V1::Payload] Payload to check. + # @return [Boolean] Whether the payload is marked as a reference that may have been encoded by a payload codec. + def marked_reference?(payload) + payload.metadata[MARKER_KEY] == 'true' + end + + # Replace each marked reference with the plain reference it encodes, so it can be retrieved. + # + # @param payloads [Array] Payloads that may contain marked references. Not mutated. + # @param payload_codec [Converters::PayloadCodec, nil] Codec that encoded the references. + # @return [Array] Payloads with every marked reference decoded. + # @raise [Error::ExternalStorageReferenceDecodeError] If a marked reference does not decode to a reference. + def decode_references(payloads, payload_codec:) + payloads.map do |payload| + next payload unless marked_reference?(payload) + + # The payload is decoded as it appears in history, marker included, since that is what a codec server + # receives too. + reference = payload_codec ? payload_codec.decode([payload]).first : payload + raise Error::ExternalStorageReferenceDecodeError unless reference && reference?(reference) + + if reference.external_payloads.empty? + reference.external_payloads.push(*payload.external_payloads.map(&:dup)) + end + reference + end + end + # @param driver_name [String] Name of the driver that stored the payload. # @param claim_data [Hash] Driver data identifying the stored payload. # @param original_size_bytes [Integer] Encoded size of the payload that was offloaded. diff --git a/temporalio/lib/temporalio/internal/external_storage_runner.rb b/temporalio/lib/temporalio/internal/external_storage_runner.rb index e25ed3a5..1497223b 100644 --- a/temporalio/lib/temporalio/internal/external_storage_runner.rb +++ b/temporalio/lib/temporalio/internal/external_storage_runner.rb @@ -91,8 +91,10 @@ def retrieve(payloads) claims_by_driver = Hash.new { |hash, driver| hash[driver] = [] } payloads.each_with_index do |payload, index| reference = ExternalStorageReferences.parse_reference(payload) - next unless reference + next unless reference || ExternalStorageReferences.marked_reference?(payload) raise Error::ExternalStorageNotConfiguredError unless storage + # With storage configured, callers decode marked references before retrieving them + raise Error::ExternalStorageReferenceDecodeError unless reference driver = storage.driver(reference.driver_name) raise Error, "No external storage driver registered with name '#{reference.driver_name}'" unless driver diff --git a/temporalio/lib/temporalio/internal/worker/activity_worker.rb b/temporalio/lib/temporalio/internal/worker/activity_worker.rb index 716c0e19..0d290072 100644 --- a/temporalio/lib/temporalio/internal/worker/activity_worker.rb +++ b/temporalio/lib/temporalio/internal/worker/activity_worker.rb @@ -5,6 +5,7 @@ require 'temporalio/cancellation' require 'temporalio/converters/raw_value' require 'temporalio/internal/bridge/api' +require 'temporalio/internal/external_storage_references' require 'temporalio/internal/external_storage_runner' require 'temporalio/internal/proto_utils' require 'temporalio/scoped_logger' @@ -193,8 +194,11 @@ def execute_activity(task_token, defn, start) raw_heartbeat_details: begin payloads = start.heartbeat_details.to_ary data_converter = @worker.options.client.data_converter - payloads = ExternalStorageRunner.new(data_converter.external_storage, namespace: nil).retrieve(payloads) codec = data_converter.payload_codec + if data_converter.external_storage + payloads = ExternalStorageReferences.decode_references(payloads, payload_codec: codec) + end + payloads = ExternalStorageRunner.new(data_converter.external_storage, namespace: nil).retrieve(payloads) payloads = codec.decode(payloads) if codec payloads.map { |p| Temporalio::Converters::RawValue.new(p) } end, @@ -218,9 +222,12 @@ def execute_activity(task_token, defn, start) args: if defn.raw_args payloads = start.input.to_ary data_converter = @worker.options.client.data_converter + codec = data_converter.payload_codec + if data_converter.external_storage + payloads = ExternalStorageReferences.decode_references(payloads, payload_codec: codec) + end payloads = ExternalStorageRunner.new(data_converter.external_storage, namespace: nil) .retrieve(payloads) - codec = data_converter.payload_codec payloads = codec.decode(payloads) if codec payloads.map { |p| Temporalio::Converters::RawValue.new(p) } else diff --git a/temporalio/lib/temporalio/internal/worker/workflow_worker.rb b/temporalio/lib/temporalio/internal/worker/workflow_worker.rb index 50ccce83..221bd552 100644 --- a/temporalio/lib/temporalio/internal/worker/workflow_worker.rb +++ b/temporalio/lib/temporalio/internal/worker/workflow_worker.rb @@ -3,6 +3,7 @@ require 'temporalio/api/payload_visitor' require 'temporalio/error' require 'temporalio/internal/bridge/api' +require 'temporalio/internal/external_storage_references' require 'temporalio/internal/external_storage_runner' require 'temporalio/internal/worker/workflow_instance' require 'temporalio/scoped_logger' @@ -105,7 +106,9 @@ def initialize( end @payload_decoding_visitor = Api::PayloadVisitor.new(skip_search_attributes: true) do |payload_or_payloads| replace_payloads_on_visit(payload_or_payloads) do |payloads| - payloads = storage_runner.retrieve(payloads.to_a) + payloads = payloads.to_a + payloads = ExternalStorageReferences.decode_references(payloads, payload_codec:) if external_storage + payloads = storage_runner.retrieve(payloads) payloads = payload_codec.decode(payloads) if payload_codec payloads end diff --git a/temporalio/rbi/temporalio/error.rbi b/temporalio/rbi/temporalio/error.rbi index 145f3033..f2468171 100644 --- a/temporalio/rbi/temporalio/error.rbi +++ b/temporalio/rbi/temporalio/error.rbi @@ -298,6 +298,13 @@ class Temporalio::Error::ExternalStorageNotConfiguredError < ::Temporalio::Error def initialize(message = T.unsafe(nil)); end end +class Temporalio::Error::ExternalStorageReferenceDecodeError < ::Temporalio::Error + extend T::Sig + + sig { params(message: String).void } + def initialize(message = T.unsafe(nil)); end +end + class Temporalio::Error::RPCError < ::Temporalio::Error sig { params(message: String, code: Integer, raw_grpc_status: T.nilable(Object)).void } def initialize(message, code:, raw_grpc_status:); end diff --git a/temporalio/rbi/temporalio/internal/external_storage_references.rbi b/temporalio/rbi/temporalio/internal/external_storage_references.rbi index dc9905dc..7eb1dd71 100644 --- a/temporalio/rbi/temporalio/internal/external_storage_references.rbi +++ b/temporalio/rbi/temporalio/internal/external_storage_references.rbi @@ -5,6 +5,7 @@ module Temporalio::Internal::ExternalStorageReferences ENCODING = T.let(T.unsafe(nil), String) MESSAGE_TYPE = T.let(T.unsafe(nil), String) + MARKER_KEY = T.let(T.unsafe(nil), String) sig { params(payload: Temporalio::Api::Common::V1::Payload).returns(T::Boolean) } def self.reference?(payload); end @@ -15,6 +16,17 @@ module Temporalio::Internal::ExternalStorageReferences end def self.parse_reference(payload); end + sig { params(payload: Temporalio::Api::Common::V1::Payload).returns(T::Boolean) } + def self.marked_reference?(payload); end + + sig do + params( + payloads: T::Array[Temporalio::Api::Common::V1::Payload], + payload_codec: T.nilable(Temporalio::Converters::PayloadCodec) + ).returns(T::Array[Temporalio::Api::Common::V1::Payload]) + end + def self.decode_references(payloads, payload_codec:); end + sig do params( driver_name: String, diff --git a/temporalio/sig/temporalio/error.rbs b/temporalio/sig/temporalio/error.rbs index 1cd4771b..48445538 100644 --- a/temporalio/sig/temporalio/error.rbs +++ b/temporalio/sig/temporalio/error.rbs @@ -53,6 +53,10 @@ module Temporalio def initialize: (?String message) -> void end + class ExternalStorageReferenceDecodeError < Error + def initialize: (?String message) -> void + end + class RPCError < Error attr_reader code: Code::enum diff --git a/temporalio/sig/temporalio/internal/external_storage_references.rbs b/temporalio/sig/temporalio/internal/external_storage_references.rbs index b4cf9312..a19de254 100644 --- a/temporalio/sig/temporalio/internal/external_storage_references.rbs +++ b/temporalio/sig/temporalio/internal/external_storage_references.rbs @@ -3,8 +3,14 @@ module Temporalio module ExternalStorageReferences ENCODING: String MESSAGE_TYPE: String + MARKER_KEY: String def self.reference?: (Api::Common::V1::Payload payload) -> bool + def self.marked_reference?: (Api::Common::V1::Payload payload) -> bool + def self.decode_references: ( + Array[Api::Common::V1::Payload] payloads, + payload_codec: Converters::PayloadCodec? + ) -> Array[Api::Common::V1::Payload] def self.parse_reference: ( Api::Common::V1::Payload payload ) -> Api::Sdk::V1::ExternalStorageReference? diff --git a/temporalio/test/external_storage_runner_test.rb b/temporalio/test/external_storage_runner_test.rb index 3e9d56a8..ea36a4d2 100644 --- a/temporalio/test/external_storage_runner_test.rb +++ b/temporalio/test/external_storage_runner_test.rb @@ -129,6 +129,15 @@ def test_without_storage_retrieve_raises_on_reference assert_raises(Temporalio::Error::ExternalStorageNotConfiguredError) { Runner.new(nil, namespace: nil).retrieve([reference]) } end + def test_without_storage_retrieve_raises_on_marked_reference + # Opaque to the runner, as a codec-encoded reference is + marked = Temporalio::Api::Common::V1::Payload.new( + metadata: { 'encoding' => 'binary/encrypted', References::MARKER_KEY => 'true' }, data: 'encrypted' + ) + + assert_raises(Temporalio::Error::ExternalStorageNotConfiguredError) { Runner.new(nil, namespace: nil).retrieve([marked]) } + end + private def storage(driver, payload_size_threshold: 0) diff --git a/temporalio/test/external_storage_test.rb b/temporalio/test/external_storage_test.rb index 862b211e..438ce883 100644 --- a/temporalio/test/external_storage_test.rb +++ b/temporalio/test/external_storage_test.rb @@ -1,10 +1,12 @@ # frozen_string_literal: true require 'base64' +require 'base64_codec' require 'in_memory_storage_driver' require 'recording_storage_driver_limiter' require 'securerandom' require 'temporalio/cancellation' +require 'temporalio/converters/data_converter' require 'temporalio/converters/external_storage' require 'temporalio/converters/storage_driver_activity_info' require 'temporalio/converters/storage_driver_claim' @@ -14,6 +16,7 @@ require 'temporalio/converters/storage_driver_workflow_info' require 'temporalio/error' require 'temporalio/internal/external_storage_references' +require 'temporalio/internal/external_storage_runner' require 'test' class ExternalStorageTest < Test @@ -285,8 +288,72 @@ def test_not_configured_error_names_its_code assert_includes err.message, 'TMPRL1105' end + def test_decode_references_decodes_marked_reference_and_keeps_its_size + reference = References.create_reference_payload( + driver_name: 'mem', claim_data: { 'key' => 'k' }, original_size_bytes: 385 + ) + ordinary = payload('"ordinary"') + + decoded = References.decode_references( + [encoded_reference(reference), ordinary], payload_codec: Base64Codec.new + ) + + assert_equal reference, decoded[0] + assert_same ordinary, decoded[1] + end + + def test_decode_references_raises_when_marked_payload_does_not_decode_to_a_reference + reference = References.create_reference_payload(driver_name: 'mem', claim_data: {}, original_size_bytes: 1) + + # Read without the codec that wrote it + err = assert_raises(Temporalio::Error::ExternalStorageReferenceDecodeError) do + References.decode_references([encoded_reference(reference)], payload_codec: nil) + end + assert_includes err.message, 'TMPRL1106' + + # Decodes, but not to a reference + assert_raises(Temporalio::Error::ExternalStorageReferenceDecodeError) do + References.decode_references( + [encoded_reference(payload('"not a reference"'))], payload_codec: Base64Codec.new + ) + end + end + + def test_decode_references_accepts_marked_reference_that_was_not_encoded + reference = References.create_reference_payload(driver_name: 'mem', claim_data: {}, original_size_bytes: 1) + reference.metadata[References::MARKER_KEY] = 'true' + + assert_same reference, References.decode_references( + [reference], payload_codec: nil + ).first + end + + def test_data_converter_reads_encoded_reference + driver = InMemoryStorageDriver.new + storage = Temporalio::Converters::ExternalStorage.new(drivers: [driver], payload_size_threshold: 0) + codec = Base64Codec.new + stored = Temporalio::Converters::DataConverter.new(payload_codec: codec).to_payload('stored-value') + reference = Temporalio::Internal::ExternalStorageRunner.new(storage, namespace: nil).store([stored]).first + converter = Temporalio::Converters::DataConverter.new(payload_codec: codec, external_storage: storage) + + assert_equal 'stored-value', converter.from_payload(encoded_reference(reference)) + assert_equal ['stored-value'], converter.from_payloads( + Temporalio::Api::Common::V1::Payloads.new(payloads: [encoded_reference(reference)]) + ) + end + private + # Encodes the payload without its size and marks it, so decoding must restore the size from the outer payload + def encoded_reference(reference) + without_size = Temporalio::Api::Common::V1::Payload.decode(reference.to_proto) + without_size.external_payloads.clear + encoded = Base64Codec.new.encode([without_size]).first + encoded.metadata[References::MARKER_KEY] = 'true' + encoded.external_payloads.push(*reference.external_payloads.map(&:dup)) + encoded + end + def cancellation Temporalio::Cancellation.new end diff --git a/temporalio/test/sig/external_storage_test.rbs b/temporalio/test/sig/external_storage_test.rbs index d25ce55f..8c47a39d 100644 --- a/temporalio/test/sig/external_storage_test.rbs +++ b/temporalio/test/sig/external_storage_test.rbs @@ -1,4 +1,5 @@ class ExternalStorageTest < Test + def encoded_reference: (Temporalio::Api::Common::V1::Payload reference) -> Temporalio::Api::Common::V1::Payload def cancellation: -> Temporalio::Cancellation def limiter: -> Temporalio::Converters::StorageDriverLimiter def select_context: -> Temporalio::Converters::StorageDriverSelectContext diff --git a/temporalio/test/sig/worker_external_storage_test.rbs b/temporalio/test/sig/worker_external_storage_test.rbs index a089d6a1..0cf3ec71 100644 --- a/temporalio/test/sig/worker_external_storage_test.rbs +++ b/temporalio/test/sig/worker_external_storage_test.rbs @@ -85,6 +85,10 @@ class WorkerExternalStorageTest < Test Temporalio::Converters::StorageDriver driver, ?payload_codec: Temporalio::Converters::PayloadCodec? ) -> Temporalio::Client - def first_attrs: (Enumerable[untyped] events, Symbol attrs_method) -> untyped + def encoded_reference: ( + Temporalio::Converters::StorageDriver driver, + String value + ) -> Temporalio::Api::Common::V1::Payload + def first_attrs:(Enumerable[untyped] events, Symbol attrs_method) -> untyped def assert_reference: (Temporalio::Api::Common::V1::Payload payload) -> void end diff --git a/temporalio/test/worker_external_storage_test.rb b/temporalio/test/worker_external_storage_test.rb index 94ad1e90..580ae281 100644 --- a/temporalio/test/worker_external_storage_test.rb +++ b/temporalio/test/worker_external_storage_test.rb @@ -7,6 +7,7 @@ require 'temporalio/converters/external_storage' require 'temporalio/error' require 'temporalio/internal/external_storage_references' +require 'temporalio/internal/external_storage_runner' require 'temporalio/worker' require 'temporalio/workflow' require 'test' @@ -223,6 +224,32 @@ def test_worker_without_storage_fails_the_task_on_a_reference end end + def test_worker_reads_encoded_reference + driver = InMemoryStorageDriver.new + client = client_with_storage(driver, payload_codec: Base64Codec.new) + # Ruby does not write encoded references yet, so the input is written as another SDK would + execute_workflow( + EchoWorkflow, Temporalio::Converters::RawValue.new(encoded_reference(driver, 'start-input')), + client:, + start_workflow_client: env.client, + workflow_payload_codec_thread_pool: Temporalio::Worker::ThreadPool.default + ) do |handle| + assert_equal 'start-input done', client.workflow_handle(handle.id).result + end + end + + def test_worker_without_the_writing_codec_fails_the_task_on_an_encoded_reference + driver = InMemoryStorageDriver.new + execute_workflow( + EchoWorkflow, Temporalio::Converters::RawValue.new(encoded_reference(driver, 'start-input')), + client: client_with_storage(driver), + start_workflow_client: env.client, + workflow_payload_codec_thread_pool: Temporalio::Worker::ThreadPool.default + ) do |handle| + assert_eventually_task_fail(handle:, message_contains: 'TMPRL1106') + end + end + class AsyncCompletionActivity < Temporalio::Activity::Definition def initialize @task_token = Queue.new @@ -478,6 +505,18 @@ def client_with_storage(driver, payload_codec: nil) Temporalio::Client.new(**env.client.options.with(data_converter:).to_h) # steep:ignore InsufficientKeywordArguments end + # Stores the value encoded with Base64Codec, then encodes and marks its reference + def encoded_reference(driver, value) + codec = Base64Codec.new + storage = Temporalio::Converters::ExternalStorage.new(drivers: [driver], payload_size_threshold: 0) + stored = Temporalio::Converters::DataConverter.new(payload_codec: codec).to_payload(value) + reference = Temporalio::Internal::ExternalStorageRunner.new(storage, namespace: nil).store([stored]).first + encoded = codec.encode([reference]).first + encoded.metadata[References::MARKER_KEY] = 'true' + encoded.external_payloads.push(*reference.external_payloads.map(&:dup)) + encoded + end + def first_attrs(events, attrs_method) events.filter_map { |event| event.public_send(attrs_method) }.first || flunk("No event with #{attrs_method}") end From a4fe49ca28b46d5c65de51b8709fdfddace34198 Mon Sep 17 00:00:00 2001 From: Chris Constable Date: Wed, 18 Nov 2026 14:23:24 -0700 Subject: [PATCH 2/3] feedback: shortcircuit logic for decoding payloads, update tests, whitespace fix. --- .../internal/external_storage_references.rb | 7 ++- .../internal/external_storage_runner.rb | 1 - temporalio/test/base64_codec.rb | 2 + .../test/external_storage_runner_test.rb | 12 ++++ temporalio/test/external_storage_test.rb | 25 ++++---- .../test/sig/worker_external_storage_test.rbs | 10 +++- .../test/worker_external_storage_test.rb | 58 +++++++++++++++++++ 7 files changed, 98 insertions(+), 17 deletions(-) diff --git a/temporalio/lib/temporalio/internal/external_storage_references.rb b/temporalio/lib/temporalio/internal/external_storage_references.rb index 16d17351..c5be9890 100644 --- a/temporalio/lib/temporalio/internal/external_storage_references.rb +++ b/temporalio/lib/temporalio/internal/external_storage_references.rb @@ -49,16 +49,19 @@ def marked_reference?(payload) # Replace each marked reference with the plain reference it encodes, so it can be retrieved. # # @param payloads [Array] Payloads that may contain marked references. Not mutated. - # @param payload_codec [Converters::PayloadCodec, nil] Codec that encoded the references. + # @param payload_codec [Converters::PayloadCodec, nil] Codec that encoded the references. Without one, payloads + # are returned as is and the storage runner rejects a marked payload that is not a plain reference. # @return [Array] Payloads with every marked reference decoded. # @raise [Error::ExternalStorageReferenceDecodeError] If a marked reference does not decode to a reference. def decode_references(payloads, payload_codec:) + return payloads unless payload_codec + payloads.map do |payload| next payload unless marked_reference?(payload) # The payload is decoded as it appears in history, marker included, since that is what a codec server # receives too. - reference = payload_codec ? payload_codec.decode([payload]).first : payload + reference = payload_codec.decode([payload]).first raise Error::ExternalStorageReferenceDecodeError unless reference && reference?(reference) if reference.external_payloads.empty? diff --git a/temporalio/lib/temporalio/internal/external_storage_runner.rb b/temporalio/lib/temporalio/internal/external_storage_runner.rb index 1497223b..e8edea4f 100644 --- a/temporalio/lib/temporalio/internal/external_storage_runner.rb +++ b/temporalio/lib/temporalio/internal/external_storage_runner.rb @@ -93,7 +93,6 @@ def retrieve(payloads) reference = ExternalStorageReferences.parse_reference(payload) next unless reference || ExternalStorageReferences.marked_reference?(payload) raise Error::ExternalStorageNotConfiguredError unless storage - # With storage configured, callers decode marked references before retrieving them raise Error::ExternalStorageReferenceDecodeError unless reference driver = storage.driver(reference.driver_name) diff --git a/temporalio/test/base64_codec.rb b/temporalio/test/base64_codec.rb index 17306bd6..ea907084 100644 --- a/temporalio/test/base64_codec.rb +++ b/temporalio/test/base64_codec.rb @@ -15,6 +15,8 @@ def encode(payloads) def decode(payloads) payloads.map do |p| + next p unless p.metadata['encoding'] == 'test/base64' + Temporalio::Api::Common::V1::Payload.decode( Base64.strict_decode64(p.data) ) diff --git a/temporalio/test/external_storage_runner_test.rb b/temporalio/test/external_storage_runner_test.rb index ea36a4d2..c05b3a0a 100644 --- a/temporalio/test/external_storage_runner_test.rb +++ b/temporalio/test/external_storage_runner_test.rb @@ -138,6 +138,18 @@ def test_without_storage_retrieve_raises_on_marked_reference assert_raises(Temporalio::Error::ExternalStorageNotConfiguredError) { Runner.new(nil, namespace: nil).retrieve([marked]) } end + def test_retrieve_raises_on_marked_payload_that_is_not_a_reference + # A reference encoded by a codec this side does not have + marked = Temporalio::Api::Common::V1::Payload.new( + metadata: { 'encoding' => 'binary/encrypted', References::MARKER_KEY => 'true' }, data: 'encrypted' + ) + + err = assert_raises(Temporalio::Error::ExternalStorageReferenceDecodeError) do + Runner.new(storage(InMemoryStorageDriver.new), namespace: nil).retrieve([marked]) + end + assert_includes err.message, 'TMPRL1106' + end + private def storage(driver, payload_size_threshold: 0) diff --git a/temporalio/test/external_storage_test.rb b/temporalio/test/external_storage_test.rb index 438ce883..fb955454 100644 --- a/temporalio/test/external_storage_test.rb +++ b/temporalio/test/external_storage_test.rb @@ -302,16 +302,7 @@ def test_decode_references_decodes_marked_reference_and_keeps_its_size assert_same ordinary, decoded[1] end - def test_decode_references_raises_when_marked_payload_does_not_decode_to_a_reference - reference = References.create_reference_payload(driver_name: 'mem', claim_data: {}, original_size_bytes: 1) - - # Read without the codec that wrote it - err = assert_raises(Temporalio::Error::ExternalStorageReferenceDecodeError) do - References.decode_references([encoded_reference(reference)], payload_codec: nil) - end - assert_includes err.message, 'TMPRL1106' - - # Decodes, but not to a reference + def test_decode_references_raises_when_marked_payload_decodes_to_something_else assert_raises(Temporalio::Error::ExternalStorageReferenceDecodeError) do References.decode_references( [encoded_reference(payload('"not a reference"'))], payload_codec: Base64Codec.new @@ -319,15 +310,23 @@ def test_decode_references_raises_when_marked_payload_does_not_decode_to_a_refer end end - def test_decode_references_accepts_marked_reference_that_was_not_encoded + def test_decode_references_accepts_marked_reference_the_codec_passes_through reference = References.create_reference_payload(driver_name: 'mem', claim_data: {}, original_size_bytes: 1) reference.metadata[References::MARKER_KEY] = 'true' - assert_same reference, References.decode_references( - [reference], payload_codec: nil + assert_equal reference, References.decode_references( + [reference], payload_codec: Base64Codec.new ).first end + def test_decode_references_without_codec_returns_payloads_unchanged + encoded = encoded_reference( + References.create_reference_payload(driver_name: 'mem', claim_data: {}, original_size_bytes: 1) + ) + + assert_same encoded, References.decode_references([encoded], payload_codec: nil).first + end + def test_data_converter_reads_encoded_reference driver = InMemoryStorageDriver.new storage = Temporalio::Converters::ExternalStorage.new(drivers: [driver], payload_size_threshold: 0) diff --git a/temporalio/test/sig/worker_external_storage_test.rbs b/temporalio/test/sig/worker_external_storage_test.rbs index 0cf3ec71..f90353d5 100644 --- a/temporalio/test/sig/worker_external_storage_test.rbs +++ b/temporalio/test/sig/worker_external_storage_test.rbs @@ -32,6 +32,14 @@ class WorkerExternalStorageTest < Test def execute: -> String end + class EncodedHeartbeatActivity < Temporalio::Activity::Definition + @plain_client: Temporalio::Client + @encoded_detail: Temporalio::Api::Common::V1::Payload + + def initialize: (Temporalio::Client plain_client, Temporalio::Api::Common::V1::Payload encoded_detail) -> void + def execute: () -> untyped + end + class AsyncCompletionActivity < Temporalio::Activity::Definition @task_token: Queue @@ -89,6 +97,6 @@ class WorkerExternalStorageTest < Test Temporalio::Converters::StorageDriver driver, String value ) -> Temporalio::Api::Common::V1::Payload - def first_attrs:(Enumerable[untyped] events, Symbol attrs_method) -> untyped + def first_attrs: (Enumerable[untyped] events, Symbol attrs_method) -> untyped def assert_reference: (Temporalio::Api::Common::V1::Payload payload) -> void end diff --git a/temporalio/test/worker_external_storage_test.rb b/temporalio/test/worker_external_storage_test.rb index 580ae281..a7e0b9bd 100644 --- a/temporalio/test/worker_external_storage_test.rb +++ b/temporalio/test/worker_external_storage_test.rb @@ -250,6 +250,64 @@ def test_worker_without_the_writing_codec_fails_the_task_on_an_encoded_reference end end + def test_worker_without_storage_or_codec_fails_the_task_on_an_encoded_reference + execute_workflow( + EchoWorkflow, Temporalio::Converters::RawValue.new(encoded_reference(InMemoryStorageDriver.new, 'start-input')) + ) do |handle| + assert_eventually_task_fail(handle:, message_contains: 'TMPRL1105') + end + end + + def test_activity_reads_encoded_reference_input + driver = InMemoryStorageDriver.new + client = client_with_storage(driver, payload_codec: Base64Codec.new) + worker = Temporalio::Worker.new( + client:, task_queue: "tq-#{SecureRandom.uuid}", activities: [HeartbeatRetryActivity] + ) + worker.run do + # Started with a plain client so the raw input reaches history as another SDK would write it + handle = env.client.start_activity( + HeartbeatRetryActivity, Temporalio::Converters::RawValue.new(encoded_reference(driver, 'activity-input')), + id: "act-#{SecureRandom.uuid}", task_queue: worker.task_queue, start_to_close_timeout: 10, + retry_policy: Temporalio::RetryPolicy.new(max_attempts: 2, initial_interval: 0.1) + ) + assert_equal 'activity-input heartbeat-detail', client.activity_handle(handle.id).result + end + end + + # Heartbeats through a client without codec or storage, so the details reach the server as written + class EncodedHeartbeatActivity < Temporalio::Activity::Definition + def initialize(plain_client, encoded_detail) + @plain_client = plain_client + @encoded_detail = encoded_detail + end + + def execute + info = Temporalio::Activity::Context.current.info + if info.attempt == 1 + @plain_client.async_activity_handle(info.task_token) + .heartbeat(Temporalio::Converters::RawValue.new(@encoded_detail)) + raise 'Intentional error' + end + info.heartbeat_details.first + end + end + + def test_activity_reads_encoded_reference_heartbeat_details + driver = InMemoryStorageDriver.new + client = client_with_storage(driver, payload_codec: Base64Codec.new) + activity = EncodedHeartbeatActivity.new(env.client, encoded_reference(driver, 'heartbeat-detail')) + worker = Temporalio::Worker.new(client:, task_queue: "tq-#{SecureRandom.uuid}", activities: [activity]) + worker.run do + handle = client.start_activity( + EncodedHeartbeatActivity, + id: "act-#{SecureRandom.uuid}", task_queue: worker.task_queue, start_to_close_timeout: 10, + retry_policy: Temporalio::RetryPolicy.new(max_attempts: 2, initial_interval: 0.1) + ) + assert_equal 'heartbeat-detail', handle.result + end + end + class AsyncCompletionActivity < Temporalio::Activity::Definition def initialize @task_token = Queue.new From 32f21366d2e4ec829e76686e24443338d4bf2f0f Mon Sep 17 00:00:00 2001 From: Chris Constable Date: Wed, 18 Nov 2026 14:31:08 -0700 Subject: [PATCH 3/3] rename test --- temporalio/test/external_storage_test.rb | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/temporalio/test/external_storage_test.rb b/temporalio/test/external_storage_test.rb index fb955454..1b411858 100644 --- a/temporalio/test/external_storage_test.rb +++ b/temporalio/test/external_storage_test.rb @@ -310,13 +310,19 @@ def test_decode_references_raises_when_marked_payload_decodes_to_something_else end end - def test_decode_references_accepts_marked_reference_the_codec_passes_through - reference = References.create_reference_payload(driver_name: 'mem', claim_data: {}, original_size_bytes: 1) + def test_decode_references_keeps_marked_reference_the_codec_passes_through + reference = References.create_reference_payload( + driver_name: 'mem', claim_data: { 'key' => 'k' }, original_size_bytes: 385 + ) reference.metadata[References::MARKER_KEY] = 'true' + ordinary = payload('"ordinary"') - assert_equal reference, References.decode_references( - [reference], payload_codec: Base64Codec.new - ).first + decoded = References.decode_references( + [reference, ordinary], payload_codec: Base64Codec.new + ) + + assert_equal reference, decoded[0] + assert_same ordinary, decoded[1] end def test_decode_references_without_codec_returns_payloads_unchanged