Add path-based asset backend proxy routing#668
Add path-based asset backend proxy routing#668ChristianPavilonis wants to merge 3 commits intomainfrom
Conversation
aram356
left a comment
aram356
left a comment
There was a problem hiding this comment.
Summary
Path-based asset proxy routing closely follows the spec, with a clean separation from the publisher pipeline and a conservative forwarded-header set. Concerns are concentrated around (1) origin_url validation that lets path/query through silently, (2) missing test coverage for spec-stated invariants — most importantly that asset failures must not silently fall back to publisher.origin_url, and (3) one CLAUDE.md doc-comment compliance gap.
Blocking
🔧 wrench
- Missing doc comments on
ProxyAssetRoute(crates/trusted-server-core/src/settings.rs:336-339) origin_urlvalidation accepts URLs with path/query that are silently dropped at runtime (crates/trusted-server-core/src/settings.rs:740-766)- No test that asset-origin failures stop at 502 without falling back to
publisher.origin_url(crates/trusted-server-adapter-fastly/src/route_tests.rs, around theasset_routes_*tests) — spec §9 forbids the fallback; the impl is correct but unpinned by tests.
Non-blocking
🤔 thinking
Strict-Transport-Securityfrom asset origin forwarded unchanged (crates/trusted-server-core/src/proxy.rs:657-663) — same class of risk as upstreamSet-Cookie, which is correctly stripped. Either strip HSTS too or document explicitly.- Spec-listed test gaps: HEAD passthrough, non-GET/HEAD bypass, redirect pass-through, query-string-ignored-for-matching. All small additions given existing helpers.
- String-prefix matching can match non-segment boundaries (
prefix = "/static"matches/staticfile.js). Spec is explicit, but every example uses a trailing/. Worth a sentence in the toml comment and field doc.
♻️ refactor
- Idiomatic method-set check in
route_request(crates/trusted-server-adapter-fastly/src/main.rs:153-156) — replace thematch &method { &Method::GET | &Method::HEAD => ... }withmatches!(...).then(...).flatten(). - Test-stub duplication:
StaticResponseHttpClientcould move intoplatform::test_supportby extendingStubHttpClientwithpush_response_with_headers. - Validation split between
Proxy::normalizeandProxy::prepare_runtimeis inconsistent with the rest ofSettings, which uses#[validate]attributes. Either consolidate or comment the rationale.
🌱 seedling
- WASM heap pressure for large asset bodies (
crates/trusted-server-adapter-fastly/src/platform.rs:223-237→fastly_response_to_platformcallstake_body_bytes();crates/trusted-server-core/src/proxy.rs:657re-buffers viaset_body(Vec<u8>)). Same asPublisherResponse::PassThrough, so not a regression — but this PR is specifically targeting asset traffic, where bodies are routinely larger than HTML. Track as a streaming pass-through follow-up mirroringPublisherResponse::Stream. (Anchored in the body sinceplatform.rsis unchanged in this PR.)
⛏ nitpick
- Validation error wording (
crates/trusted-server-core/src/settings.rs:716,validate_no_trailing_slash): the spec says "must not include a trailing slash"; the error message says "origin_url must not end with '/'". Aligning the wording reads slightly better in operator-facing errors. The function itself is unchanged in this PR but is reached via the newvalidate_proxy_origin_url. (Anchored in the body since the line is outside the diff.) - Redundant
to_ascii_lowercase()ontarget_url.scheme()— already lowercase from URL parsing. See inline comment. Set-Cookiestrip test only verifies a single header is removed; should test multiple. See inline comment.
CI Status
- fmt: PASS
- clippy: PASS
- rust tests: PASS (858 tests, 0 failures locally; CI green)
- vitest: PASS
- format-typescript: PASS
- format-docs: PASS
- browser & integration tests: PASS
- CodeQL / Analyze: PASS
| #[derive(Debug, Default, Clone, Deserialize, Serialize)] | ||
| pub struct ProxyAssetRoute { | ||
| pub prefix: String, | ||
| pub origin_url: String, |
There was a problem hiding this comment.
🔧 wrench — ProxyAssetRoute and its pub fields lack doc comments. CLAUDE.md is explicit: "Each public item must have a doc comment." The sibling Proxy fields are documented; this new struct should match. Add a struct-level summary plus per-field docs that also call out the runtime-replacement behavior of origin_url (see the validation finding on line 766).
/// A path-prefix asset route that proxies matched first-party requests to an alternate origin.
#[derive(Debug, Default, Clone, Deserialize, Serialize)]
pub struct ProxyAssetRoute {
/// Path prefix matched against the incoming request path. Must start with `/`.
pub prefix: String,
/// Absolute http/https origin used for upstream requests. Only the scheme/host/port are
/// used; any path or query on this URL is replaced by the incoming request's path/query.
pub origin_url: String,
}| } | ||
|
|
||
| Ok(()) | ||
| } |
There was a problem hiding this comment.
🔧 wrench — validate_proxy_origin_url rejects a trailing / but accepts URLs with a non-empty path or a query string, which are then silently dropped at runtime by target_url.set_path(req_path) / set_query(req_query) in handle_asset_proxy_request.
For example, origin_url = "https://cdn.example.com/api?token=abc" passes validation, but at request time the upstream becomes https://cdn.example.com/<incoming-path>?<incoming-query> — the configured /api and ?token=abc vanish without warning. This is the same misconfiguration class the trailing-slash check is meant to catch.
Fix: also reject origin_url whose parsed path() is non-empty/non-/, and whose query() is Some(_):
if !matches!(parsed.path(), "" | "/") {
let mut err = ValidationError::new("origin_url_has_path");
err.add_param("value".into(), &value);
err.message = Some("origin_url must not include a path; only scheme/host/port are used".into());
return Err(err);
}
if parsed.query().is_some() {
let mut err = ValidationError::new("origin_url_has_query");
err.add_param("value".into(), &value);
err.message = Some("origin_url must not include a query string".into());
return Err(err);
}| StatusCode::BAD_GATEWAY, | ||
| "should bypass publisher consent dependencies and fail only on the missing upstream client" | ||
| ); | ||
| } |
There was a problem hiding this comment.
🔧 wrench — The spec (§9 / §"Failure Semantics") explicitly forbids silent fallback to publisher.origin_url when an asset origin fails. The current implementation does the right thing, but no test pins that behavior — a future refactor could regress it without anyone noticing.
asset_routes_bypass_publisher_consent_dependencies shows that asset routes don't run the consent path, but it doesn't prove the failure path stops at 502 instead of attempting publisher.origin_url. Please add a focused test that asserts:
- an asset-route request whose backend
ensure()(or upstreamsend()) fails returns 502, and - the publisher origin's
send()is never invoked for that request (e.g., via a stubPlatformHttpClientthat records call counts and asserts zero calls to the publisher origin).
| // publisher domain through this proxy path. | ||
| response.remove_header(header::SET_COOKIE); | ||
|
|
||
| Ok(response) |
There was a problem hiding this comment.
🤔 thinking — Stripping Set-Cookie is great, but Strict-Transport-Security from the asset origin is forwarded unchanged. Because the asset proxy serves on the publisher's first-party domain, the browser will treat any HSTS header from the asset CDN as the publisher's policy — especially dangerous with includeSubDomains; preload, which would lock down the entire site based on what the asset CDN sends.
This is the same class of "asset CDN influencing publisher security state" risk that motivated stripping Set-Cookie. Either:
- strip
strict-transport-securityfrom asset responses by default (cheapest, mirrors the Set-Cookie pattern), or - document this explicitly in the spec security section and require operators to confirm their asset origins don't send hostile HSTS.
If option 1, one extra line next to the existing remove_header(SET_COOKIE):
response.remove_header(header::STRICT_TRANSPORT_SECURITY);| "// Script overridden by Trusted Server\n", | ||
| "should serve the integration response instead of proxying to the asset origin" | ||
| ); | ||
| } |
There was a problem hiding this comment.
🤔 thinking — The spec's "Recommended Tests" section calls out several invariants that aren't covered yet. All are a few lines given existing helpers (StubHttpClient, StaticResponseHttpClient):
- HEAD passthrough (spec §12 / §"Method forwarding"): only GET is exercised in
handle_asset_proxy_request_forwards_asset_headers_and_host. - Non-GET/HEAD bypass (spec §6): no test that
POST /.images/fooskips asset matching and falls through to publisher. - Redirect pass-through (spec §11): no test that a 301/302 from upstream is returned to the client unchanged.
- Query string ignored for matching (spec §"Matching algorithm"): not pinned in
proxy_asset_route_for_path_*tests.
These keep the spec and tests in lockstep so behavior shifts surface as failing tests.
| let matched_asset_route = match &method { | ||
| &Method::GET | &Method::HEAD => settings.asset_route_for_path(&path), | ||
| _ => None, | ||
| }; |
There was a problem hiding this comment.
♻️ refactor — match &method { &Method::GET | &Method::HEAD => ..., _ => None } is awkward; the &pat borrow dance only exists to avoid moving method before the outer match consumes it. Cleaner:
let matched_asset_route = matches!(method, Method::GET | Method::HEAD)
.then(|| settings.asset_route_for_path(&path))
.flatten();| Err(Report::new(PlatformError::Unsupported)) | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
♻️ refactor — StaticResponseHttpClient exists only because StubHttpClient::push_response(status, body) doesn't accept response headers. Extending StubHttpClient (e.g., push_response_with_headers) would let both the SET_COOKIE strip test and the forwarded-headers test share infrastructure with the rest of the proxy test suite, and keep test stubs centralized in platform::test_support.
| for route in &self.asset_routes { | ||
| route.prepare_runtime()?; | ||
| } | ||
|
|
There was a problem hiding this comment.
♻️ refactor — Asset-route validation is split across Proxy::normalize (trim + duplicate warn) and Proxy::prepare_runtime (prefix/origin_url validation). Other settings fields validate via #[validate(...)] attributes. Either:
- fold prefix/origin_url validation into the standard
#[validate]pipeline so asset routes are validated alongside the rest ofSettings, or - add a brief code comment explaining why these specifically need deferred validation in
prepare_runtimerather than at deserialization time.
| req.get_path(), | ||
| req.get_query_str().unwrap_or(""), | ||
| )?; | ||
| let scheme = target_url.scheme().to_ascii_lowercase(); |
There was a problem hiding this comment.
⛏ nitpick — target_url.scheme() is already lowercase per the URL parsing rules — to_ascii_lowercase() here (and at line 533 in build_asset_proxy_target_url, line 559 in asset_origin_host_header) is dead work and slightly misleads the reader into thinking mixed-case schemes are possible at this point.
| "should preserve safe cache validator headers on asset responses" | ||
| ); | ||
| } | ||
|
|
There was a problem hiding this comment.
⛏ nitpick — The Set-Cookie strip test only asserts a single Set-Cookie is removed. Fastly's Response::remove_header does strip all entries with that name (per the SDK 0.11.12 source), but the test should pin that contract by including two distinct Set-Cookie values and asserting both are gone after the strip.
2 participants
Summary
[[proxy.asset_routes]]path-prefix routing so selected first-party asset paths can proxy to a different backend origin thanpublisher.origin_url.GET/HEAD, uses longest-prefix-wins, and preserves the full incoming path/query while swapping only the origin.Changes
docs/superpowers/specs/2026-04-28-multi-backend-asset-proxy-design.mdcrates/trusted-server-core/src/settings.rsProxyAssetRoute,proxy.asset_routesconfig support, asset-route normalization/validation, duplicate-prefix warnings, and longest-prefix matching helpers.crates/trusted-server-core/src/proxy.rscrates/trusted-server-adapter-fastly/src/main.rscrates/trusted-server-adapter-fastly/src/route_tests.rstrusted-server.toml[[proxy.asset_routes]]configuration shape with a commented example.Closes
Closes #663
Test plan
cargo test --workspacecargo clippy --workspace --all-targets --all-features -- -D warningscargo fmt --all -- --checkcd crates/js/lib && npx vitest runcd crates/js/lib && npm run formatcd docs && npm run formatcargo build --package trusted-server-adapter-fastly --release --target wasm32-wasip1fastly compute serveChecklist
unwrap()in production code — useexpect("should ...")tracingmacros (notprintln!)