feat: forward upstream response headers through protocol Response

[lmvdz]

Summary

The LLM client currently discards all upstream HTTP response headers before they reach the Switchyard response builder. Any headers set by the upstream backend (or a proxy in front of it) — such as routing decisions, request IDs, or observability metadata — are lost.

This PR adds an upstream_headers: http::HeaderMap field to protocol::Response and preserves upstream headers through the full client → protocol → server pipeline.

Changes

• protocol: Added upstream_headers: HeaderMap to Response struct
• libsy-llm-client: Captures headers in send_once() before the response body is consumed; passes through EncodedResponse → call_rewrite_model → protocol::Response
• switchyard-server: Forwards non-reserved upstream headers to the downstream client after Switchyard's own routing headers
• Updated all downstream Response constructors across libsy, switchyard-py, usage_metrics, and tests

Forwarding rules (in switchyard-server)

• Excluded: content-type, content-length, transfer-encoding, connection, date, server, x-request-id
• Excluded: x-switchyard-* headers (set by Switchyard itself)
• All other upstream response headers are passed through

Breaking changes

None. The new field defaults to HeaderMap::new() in all constructors.

[grahamking]

@lmvdz Yes, thanks for the issue. This needs doing. Are you able to work on it?

Why exclude x-request-id? I think typically it only goes agent -> server not the other way, so I guess it's academic.

Ensure that any headers Switchyard writes always override upstream ones.

If writing it with AI make sure to keep it very small and focused, with only minimal tests. Explicitly ask the model to simplify, and then ask it to merge overlapping tests.

[lmvdz]

hey @grahamking it's in my fork lmvdz#1

The reason for this was because there were some harness related headers that were getting lost when sending to switchyard. I'll go over the changes before opening the PR

[lmvdz]

We run Switchyard in front of our own auth gateway, with a deliberate split:

Switchyard owns policy while the gateway owns everything provider-specific: OAuth refresh tokens, subscription seat liveness, and credit/quota probing.

Switchyard therefore sees exactly two virtual targets ("cheap", "capable") and learns about quota exhaustion reactively, from failed requests; the gateway knows before dispatch whether the capable tier is actually available, and overflows to cheap instead of failing.

The only problem that arises from our setup is Switchyard routing log + OTel stats might think it routed to capable but the gateway overflowed to cheap.. out of scope for this Issue.

[grahamking]

Switchyard therefore sees exactly two virtual targets ("cheap", "capable") ..

That's a good way to do it. Switchyard gets to decide where the request should go in an ideal world. The messy realities of the network are handled elsewhere.

might think it routed to capable but the gateway overflowed to cheap

For the routing log / otel, could you record the model as selected instead of routed?

Later you'll want to compare what percentage of "selected" your gateway was able to deliver as "routed". Maybe you need to provision more "cheap" nodes because they are getting saturated and you're falling back to "capable", for example.

Switchyard routes in an idealized world of pure network and perfect uptime. The gateway / load balancer needs to deliver something as close to that as possible. The difference is a good metric to know about.

Submit your upstream response PR! (or let me know and we'll do it, but I don't want to take your contributions).

[lmvdz]

Submit your upstream response PR! (or let me know and we'll do it, but I don't want to take your contributions).

#571