Expose transport metadata and raw transport in clients

[hardbyte]

The generated clients have very limited access to the underlying transport layer (i.e., HTTP). This restricts developers from implementing common and important client-side logic - accessing timing info, headers (eg, X-Rate-Limit-Remaining, ETag).

[avkonst]

I am not convinced this is aligned with the idea of the simple client. Why does a client need to access something what is not in the signature?

…

On Fri, 25 Jul 2025, 02:07 Andy Yu, ***@***.***> wrote: *andyyu2004* left a comment (thepartly/reflectapi#88) <#88 (comment)> Can this not be done at the axum layer with middleware, what's an example usecase? — Reply to this email directly, view it on GitHub <#88 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AA6JSVIVLKAJFFLGWFTH5DT3KFRKNAVCNFSM6AAAAACCJ3BI3WVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTCMJVGI2TSNRXGU> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[hardbyte]

Why does a client need to access something what is not in the signature?

To make the client easier to test and troubleshoot.

I am not convinced this is aligned with the idea of the simple client.

I agree that the primary goal is to provide a "simple client" where the developer doesn't have to think about the underlying transport. For the 80% use case, the interaction should feel like a simple function call, not an HTTP request. My proposed design in #89 is trying to preserve this simplicity for the common path while also adding an opt-in mechanism.

My motivation for this proposal came from writing tests for a TypeScript client. I wanted to assert that a specific API call returned the correct HTTP status code. This felt like a very reasonable and basic requirement for testing an API client. This information was completely hidden by the abstraction, same with other information such as headers.

Of course we could have exposed the status code similar to Rust to solve that immediate problem. It seemed the right time to propose a standard way to access the transport-level data consistently.

[avkonst]

For the 80% use case

The goal is to make the client applicable in 100% and we achieved it so far.

To make the client easier to test and troubleshoot.

The proposed changes make it easier to bind to internals for the business logic. If a client does so and we do a change on internals, we might break the business logic. I fundamentally disagree with exposing internals (it is similar to exposing what blob was sent to the storage driver, when a libc client called fopen). Below I outlined how to deal with your specific need in tests and the general design principles for more generic needs.

assert that a specific API call returned the correct HTTP status code.

In your particular case, if you did true blackbox testing, you would only care about error handling the reflectapi provides. And it does differentiate between

• success result as per the result signature (200 always, but a user does not need to know about the exact status),
• structured application error as per the error type (most 4XX codes except a few but a user does not need to know the exact status code),
• other error (network error, protocol error, like bad request, or an internal error 5XX - I believe the error context includes the underlying cause in the error for very much complete troubleshooting).
  So it is very complete error handling and troubleshooting mechanism enabling a client to verify all of the business logic. The variance between 4XX code simply does not matter from the application point view, it does (should) not change any business logic.

If you would like to test the status code in the white box method, you can achieve it by exposing playwright fixture like theLastResponseStatusCode, instrumenting the existing playwright implementation of the reflectapi client, and assert on that. That would be only available in tests and will enable you to do what you want. It adds tiny value as you are only additionally testing what number is logged in a browser or server logs. There is nothing else what is bound to the status code what can not be tested with pure error handling mechanism the existing client provides. So, I would question how much worth the effort it is, but that is possible, if you want.

The general design principles:

• everything a user needs to be done per call should be on the API call function signature.
  • As I explained above, status code is not one of the things a client needs to know.
  • few things we came across in the past which might require function call signature change (new optional parameter): retry policy, logging policy, timeout policy, etc. We did not look into this yet but that would be clean way to alter the behaviour of the client per call, without exposing its internals.
  • there might be other needs which might drive the change to the function signature but I can not imagine what it could be, so I will wait for the particular use case requirements and would not add anything generic here
• everything else is done per client, and there is very powerful mechanism for this already: a user can provide the complete implementation of a client, like we do already for our core-server or for testing.
  • things you mentioned in the pull request like performance, logging are per client. And there is existing powerful mechanism to influence this.

[hardbyte]

The key point is that transport metadata is not (always) an internal implementation detail; it is part of the public contract of the HTTP protocol itself. By hiding it, we are withholding information that the server or some intermediate proxy intentionally sent to the client.

[avkonst]

The key point is that transport metadata is not (always) an internal implementation detail;

from the user of the generated client point of view it is internal. If something a user need to know (have public) should be on the signature

it is part of the public contract of the HTTP protocol itself.

It is public to the generated client, not to the user of the generated client. Same way HTTP does not expose raw TCP packages to it's user, we do not expose raw HTTP data to the user of the generated client

By hiding it, we are withholding information that the server or some intermediate proxy intentionally sent to the client.

Once again, there should not be any such information which would influence business logic of user of the generated client per call.

[hardbyte]

The fundamental disagreement is whether transport-level metadata (status codes, headers) is an "internal implementation detail" or part of the public API contract.

@avkonst and I had a discussion in person today and walked away both considering a middle ground alternative with declarative server side annotation. Important metadata is "promoted" into the actual response schema via an annotation on the server.

Alternative 1: The Annotation-Based Approach

How it could work

1. Server-Side (Rust): The API author annotates the function.

#[reflectapi(
    // The schema would encode that the 'ETag' header should be exposed.
    expose_header(name = "ETag", field = "etag")
)]
pub async fn list(&self, /*...*/) -> Paginated<Pet> { /*...*/ }

2. Codegen: The code generator picks this up and adds an etag field to the generated Response. Here for example the a Paginated<Pet> list response model in TS might include:

  export interface Paginated<T> {
    items: Array<T>;
    cursor?: string | null;
    etag?: string; // Automatically added
  }

Similar for Rust:

// generated.rs
#[derive(Debug, serde::Deserialize)]
pub struct Paginated<T> {
    pub items: std::vec::Vec<T>,
    pub cursor: std::option::Option<std::string::String>,
    #[serde(alias = "ETag")] // Populated from the ETag header
    pub etag: std::option::Option<std::string::String>,
}

3. Client-Side: The user accesses it like any other data field.

const response = await client.pets.list_pets({}, {});
if (response.is_ok()) {
  const etag = response.unwrap_ok().etag; // Type-safe and discoverable
}

Pros & Cons of Annotation Approach

Pros:

• Architecturally Pure: The transport layer remains completely hidden. The ETag is now officially part of the application-level data model.
• Type-Safe and Explicit: The contract is clear, discoverable, and statically typed.
• Server Authoritative: The Rust server author is in full control of what is exposed via the generated client.
• Elegant for Stable Metadata: For headers that are a core, stable part of an API's contract (like ETag), this is a really nice solution.

Cons:

• Inflexible & brittle: Only works for headers that were declared by the server at compile time. Standard but un-annotated headers doesn't work. It feels un-ergonomic to force a server author to manually annotate for standard HTTP headers like Cache-Control or Retry-After.
• Poor debugging (can't easily inspect diagnostic headers like request correlation headers CF-Ray, X-Request-ID)

Hybrid Solution

My take is that the annotation based approach is excellent for exposing specific well known headers but is insufficient on its own. Perhaps the ideal solution is a hybrid that provides the best of both.

• Implement the annotation approach as the primary, recommended way to handle contractual metadata.
• Also provide a strictly opt-in "escape hatch" for advanced use cases, like the originally proposed TransportMetadata object. This could be disabled by default and only enabled via an explicit client configuration flag, signaling to the user that they are touching a lower-level API. expose_transport_metadata=True?

[avkonst]

your summary was written by AI right :) ? clear not spot on.

So we do not want this:

#[reflectapi(
    // The schema would encode that the 'ETag' header should be exposed.
    expose_header(name = "ETag", field = "etag")
)]
pub async fn list(&self, /*...*/) -> Paginated<Pet> { /*...*/ }

Instead, we want this:

// need to ensure lower case for names as headers are case sensitive
#[reflectapi(expose_header(name = "cloudflare-retry-timeout", field = "retry_allowed_in", type = Duration)]
struct SomeReturnType {}

or a bit easier:

struct SomeReturnType {
    #reflectapi(expose_header) // < that is all we need to know
    #[serde(rename = "cloudflare-retry-timeout")] // need to ensure lower case as headers are case sensitive
    retry_allowed_in: Duration
}

but it has got the disadvantage if a type is reused by multiple endpoints where one does not inject the field. Also a field would need to be initialized to default by the server with skipping serialization if default value

Even easier, possibly more correct, approach would be to add it to an endpoint builder, for example:

with_header("cloudflare-retry-timeout", "retry_allowed_in", String::reflect_output())

In the generated code, the access to the extracted header would look like (in all languages):

response: Result<SomeReturnType> = ....;
response = respose.unwrap();
response.retry_allowed_in(); // <-- notice function, but not field.

[avkonst]

Also provide a strictly opt-in "escape hatch" for advanced use cases, like the originally proposed TransportMetadata object. This could be disabled by default and only enabled via an explicit client configuration flag, signaling to the user that they are touching a lower-level API. expose_transport_metadata=True?

I would not add it until really requested by someone.

[avkonst]

Inflexible & brittle: Only works for headers that were declared by the server at compile time. Standard but un-annotated headers doesn't work. It feels un-ergonomic to force a server author to manually annotate for standard HTTP headers like Cache-Control or Retry-After.

but also very explicit for the server side and the client side. it might be slightly unergonomic for the server (although very explicit about the supported features) but very explicit and very ergonomic for a client (see example in my comment above)

[avkonst]

Poor debugging (can't easily inspect diagnostic headers like request correlation headers CF-Ray, X-Request-ID)

Not sure I agree with it. Display / Debug (rust) and toString (typescript) can make all headers printed, although I think it is very much big waste of resources to carry around all of the headers but not only those which are declared. Debugger still can see raw responses on breakpoints in the right places.