[Storage] Custom Response Deserializer (response-level)

[vincenttran-msft]

Currently I am working on Arrow support for List Blobs: Azure/azure-sdk-for-rust#4796 where I have been making some hand-written edits to the generated code just to test the feasibility, and I believe I have hit the limits of current TypeSpec and Azure Core constructs.

Background

The feature being added is that we now will expose augmenting the Accept header, and passing: application/vnd.apache.arrow.stream,application/xml
should yield arrow (with XML as infallible fallback, if the server cannot for whatever reason return arrow).

The Rust emitter currently hardcodes how a response body is deserialized based on its content type (i.e. application/xml → XmlFormat). There is no way, from TypeSpec /client.tsp, to tell the emitter "for this operation, deserialize the response with my own handwritten function." This blocks any scenario where the client must decide the body format at runtime.

This is analogous to the existing field-level deserialize_with client option:

• (i.e.. @@clientOption(BlobItem.name, "deserialize_with", "crate::models::blob_name::option::deserialize", "rust")) - but that hook is a serde field attribute that runs inside an already-chosen format, so it can't switch between two different wire formats (Arrow vs XML). We need the equivalent hook at response-level.

Therefore, a single API call can therefore return either Arrow or XML on the wire, and the client chooses the right decoder per response.

Issues

Two things, both in the emitter's generated output:

1. No response-level format / deserializer override

The emitter picks the response Format from the content type and bakes it into the return type (e.g. Response<ListBlobsResponse, XmlFormat> / Pager<ListBlobsResponse, XmlFormat>). There is no client option to substitute a custom Format marker (e.g. crate::.../ArrowOrXmlFormat) or a custom response deserializer for a given operation that has the flexibility to determine what format and deserialization path to go down at runtime.

Sub-question: how does the custom deserializer know which format it received?

However this override is designed, the runtime deserializer needs a signal to tell Arrow from XML. There are two ways to provide that signal, and they have different implications:

Option A: Body sniffing (no signature change to DeserializeWith)

The current DeserializeWith::deserialize_with(body: ResponseBody) receives only the body, not the response headers. Since Apache Arrow IPC streams begin with the ARROW1 magic bytes and XML begins with <, the deserializer can inspect the leading bytes of the body and dispatch accordingly.

• ✅ Works with the trait exactly as it exists today - no core signature changes.
• ✅ Robust even if the service mislabels Content-Type; it keys off the actual payload.
• ✅ Keeps the format decision fully self-contained in the handwritten deserializer.
• ⚠️ Relies on a magic-byte heuristic rather than the declared content type; correct for Arrow/XML but not a general "any content type" mechanism.
• ⚠️ Requires the body to be buffered enough to peek at the header bytes (already the case here).

Option B: Pass response headers into the deserializer

Change the DeserializeWith / Format contract so the deserializer also receives the response headers (e.g. Content-Type), and dispatch on that.

• ✅ Uses the service's declared content type - the "correct" HTTP-native signal, and generalizes to any future format negotiation.
• ✅ No payload-shape assumptions.
• ⚠️ Requires a breaking change to a core trait (DeserializeWith / Format) in typespec_client_core, touching every existing Format implementation and consumer.
• ⚠️ Trusts the server's Content-Type; if it's ever wrong or missing, deserialization picks the wrong path (Arrow's fallback-to-XML makes this a real edge case to reason about).
• ⚠️ Larger blast radius and coordination cost across the SDK.

2. Pager continuation extraction is hardcoded to XML

For paged operations, the generated pager closure extracts the continuation token with a literal xml::from_xml(&body) to read NextMarker - outside the Format / DeserializeWith path (list_blobs example):

let (status, headers, body) = rsp.deconstruct();
let res: ...Page = xml::from_xml(&body)?;   // <-- hardcoded XML, not format-driven

On an Arrow body the continuation token lives in Arrow schema metadata, not XML, so this line fails regardless of any custom Format. Even if issue 1 is solved, paging still breaks.

Current Workarounds (Illegal Edits to Generated Code)

Today the only way to make this work is to hand-edit the generated client method to sniff the content type and decode Arrow, then re-encode it back to XML so the return type (Pager<..., XmlFormat>) is satisfied. This:

• edits files under generated/ (overwritten on the next regeneration), and
• does an Arrow → XML → Arrow round-trip that throws away the entire performance reason for supporting Arrow.

This also opens out the discussion of how we will handle the breaking nature of this change given that XmlFormat is currently baked into the response type unfortunately 😢

[heaths]

The feature being added is that we now will expose augmenting the Accept header, and passing: application/vnd.apache.arrow.stream,application/xml
should yield arrow (with XML as infallible fallback, if the server cannot for whatever reason return arrow).

Note: this behavior is not well-received by the REST API board nor SDK architects. None of the SDK languages like this for their customers, and it has a downstream impact on a lot of assumptions both in the SDK code and callers of said SDK code e.g., getting raw bytes and expecting XML before suddenly at some point with a newer api-version breaks because it's Arrow.

We believe the format should be dictated obviously and for those calls be invariant.

There is no client option to substitute a custom Format marker

That's not true. It is possible, but requires either separate methods or a separate client (the latter is probably better - perhaps as a subclient), but then customers have to explicitly reference the format. I already had a prototype for this I shared with your team: https://play.rust-lang.org/?version=stable&mode=release&edition=2021&gist=f28452f4dca6439feb172f8e7b9df49e

The problem is in the invoke_v2() call that requires customer explicitly specify the format e.g., invoke_v2::<ArrowFormat>(). Now, if you had a separate client for each of XML and Arrow, both would work. And this aligns with what the other language SDK architects are saying as well: automagically switching the format is not good.

Pager continuation extraction is hardcoded to XML

Because serde isn't a runtime deserializer like in some other languages. Your spec said it was XML, so we use XML because we have to know a format. Even if XmlFormat wasn't part of the API (which is required for Rust type parameters because, like C++ templates, type parameters are monomorphized at compile time), we still need to know the format to generate the compile-time deserialization.

Alternatives

You didn't list the other alternative besides separate subclients (ignoring for a second that this auto-switching has significant pushback from other languages) including writing your own XmlFormat under sdk/storage that keeps the API unbroken but actually could be used to bifurcate calls. You'd still need to generate clients for both XML and Arrow, but your convenience clients could just be lightweight wrappers using your own source-compatible XmlFormat.

That said, just like with other languages, there are going to be downstream issues. Part of the reason XmlFormat is part of the API contract is to support lazy deserialization for most models (basically everything but pageables and pollers): we have to know what the format is supposed to be so that calls like into_model() know, which means carrying around type information with the object to know how to deserialize later (rather, what API to call). In hindsight, maybe an enum would've been better but we already shipped. That would've been better to discover earlier.

Given the constraints and the pushback against "auto switching", I think your best bet are separate generated clients where you could have an "arrow" module (or whatever is appropriate - not sure if that name is TM) that has the same clients with a different format. Customers pick which format they want because, remember, most (all?) SDK languages also expose the raw response data including Rust so just giving them a stream of bytes and having them sniff it isn't a customer-friendly direction given our APIs to date.

[vincenttran-msft]

Noted. Thanks for your input here @heaths Heath. So instead, approaching it from as low-impact as possible, I've come up with the following:

• Generated list_blobs will now have a handwritten list_blobs implementation, and will and original generated will now be marked internal.
• In order to not be breaking, we will maintain the same return-type, but will require the following changes to Azure Core:
  • Add model field to Response which can hold the pre-deserialized model
  • A constructor to create a Response and provide a model to model
  • Update into_model() to return the cached model if present, otherwise deserialize as previously

This was mocked up in:
Azure/azure-sdk-for-rust#4818

Let me know your thoughts.

[heaths]

In order to not be breaking, we will maintain the same return-type, but will require the following changes to Azure Core:

That's not required at all. I told you internally you could have your own Format implementation that could handle the different cases and even call it XmlFormat, but it wouldn't be the same type. If people import XmlFormat from azure_core and not yours, it's still breaking.

You don't need to pre-deserialize the model if you have a format that supports the deserialization.