A cacheable raw Response is shaped by a request header nothing keys on

[frenzzy]

Describe the bug

A GET-declared function that answers with a raw Response and a public cache policy sends two different bodies at the same url, chosen by a request header no cache keys on and no Vary names.

The runtime shapes that response by whether the caller is scripted (packages/web/server-functions/src/server.ts):

// raw responses pass through untouched
if (result.headers && result.headers.has("X-Content-Raw")) return result;
if (instance) {
 // forward headers, forward non-redirect statuses, decode the body
}

With an instance header the body is re-encoded for the transport; without one the Response is handed back verbatim. Both keep the cache-control the function set. A shared cache stores whichever arrives first and serves it to the other caller — and GET-declared reads skip the origin gate, so the unscripted variant is reachable from a prefetch, a crawler, or a plain navigation.

What the wrong entry does downstream: a scripted caller receiving the raw HTML sees no body format on a 2xx, decodes nothing, and resolves the call to undefined (#3087's rule deliberately does not judge a 2xx). A navigation receiving the encoded variant renders codec frames.

This is the shape #3070 was about — a request header deciding a cacheable response — in a place that fix did not reach.

Steps to reproduce

mkdir sf-vary && cd sf-vary && npm init -y
npm i @solidjs/web@2.0.0-rc.4
node repro.mjs

repro.mjs:

import { AsyncLocalStorage } from "node:async_hooks";
globalThis[Symbol.for("solid.RequestContext")] = new AsyncLocalStorage();
const {
 GET, createServerReference, handleServerFunctionRequest, registerServerReference
} = await import("@solidjs/web/server-functions/server");

GET(
 createServerReference(
 registerServerReference("feed", async () =>
 new Response("<p>hi</p>", {
 headers: { "content-type": "text/html", "cache-control": "public, max-age=60" }
 })
 )
 )
);

const call = scripted =>
 handleServerFunctionRequest(
 new Request("http://localhost/_server/feed", {
 headers: {
 "Sec-Fetch-Site": "same-origin",
 ...(scripted ? { "X-Server-Function-Instance": "server-function:1" } : {})
 }
 })
 );

for (const scripted of [true, false]) {
 const response = await call(scripted);
 console.log(
 (scripted ? "scripted " : "unscripted"),
 response.status,
 "| cache-control:", response.headers.get("cache-control"),
 "| vary:", response.headers.get("vary") ?? "(none)",
 "| body:", JSON.stringify((await response.text()).slice(0, 24))
 );
}

Output on 2.0.0-rc.4:

scripted 200 | cache-control: public, max-age=60 | vary: (none) | body: ";0x00000271;{\"t\":25,\"i\":"
unscripted 200 | cache-control: public, max-age=60 | vary: (none) | body: "<p>hi</p>"

No Vary at all: a declared read skips the origin gate, so nothing keys the difference. On rc.3 the responses did carry Vary: Sec-Fetch-Site, Origin, Referer, which names the CSRF trio and still not the header that decides the body.

Expected behavior

One url, one answer — or an answer that cannot be cached.

Options

1. Give the two answers two urls. The scripted transport dispatches to its own address: <endpoint>/<id> stays the plain-HTTP answer a form post, a crawler or curl gets, and a scripted call goes somewhere adjacent (<endpoint>/<id>.data, <endpoint>/data/<id> — pick a spelling). The instance header goes back to being what it is for, correlating a call, and stops deciding what the body is.

   Every cache keys on the url, so the two variants can no longer collide: no Vary, no header forwarding to configure, no cooperation from the CDN at all. The discriminator is one bit, so it costs one more cache entry per function instead of fragmenting the key. Addressing is already path-based since feat(web): address server function calls by path #3076, so this is serverFunctionAddress() on the client and one more thing for parseServerFunctionAddress to strip on the server.

   It is a wire change — client, server, and anything writing an address by hand. Forms keep posting to the bare address, so progressive enhancement is untouched, and arguably clearer: the address a human writes by hand is the one that answers in JSON. One thing worth knowing before picking a spelling — React Router serves data requests from .data urls, and iOS content blockers block those for looking like tracking endpoints (iOS content blockers block .data single fetch URLs, breaking client-side navigation remix-run/react-router#14834). The suffix wants to be boring.

2. Refuse to cache what the caller shaped. The runtime knows which branch it took, so the raw-Response branch could force no-store and override the function's policy. Surgical, keeps both behaviours, and the thing it takes away — caching a raw Response at the edge — is the thing that is unsafe today. Overriding an explicit policy is the part worth arguing about.

3. Converge the two callers: hand a returned Response back verbatim to a scripted caller too, the way X-Content-Raw already does for both. One url, one answer, cacheable. But it changes what a scripted call receives today (a decoded body, with headers and status forwarded), so it is a protocol change rather than a fix.

4. Vary: X-Server-Function-Instance on the divergent branch. Correct per HTTP and the weakest of these in practice — below.

5. Document it: a raw Response must not carry a public cache policy. Cheapest, and the failure stays silent for anyone who does not read that line.

(2) is the small fix that could land now; (1) is the one that makes the bug unreachable rather than unreached. They compose — no-store today does not block splitting the addresses later.

Why Vary is the weak option

Not theory — this exact shape has been paid for elsewhere. Next.js shapes a response by the rsc request header and drew CVE-2025-49005 for omitting the header that keys it: "a cache poisoning issue in Next.js App Router >=15.3.0 < 15.3.3 may have allowed RSC payloads to be cached and served in place of HTML" (advisory).

Their own CDN guide then says why the header was never enough on its own — "Many CDNs don't support Vary without additional configuration" — which is why they added the _rsc search parameter as a cache-key discriminator that works "even on CDNs that ignore Vary". And the direction they document now is url-shaped: move the cache-affecting inputs into the pathname (/my/page.rsc), "eliminating the need for Vary on custom headers", so that "No Vary support needed" from the CDN.

There is a second reason it does not apply here: X-Server-Function-Instance is unique per call, so varying on it is a guaranteed miss — option (2) with extra steps and a worse name.

Worth noting the seams do not let userland solve this: prepareRequest and fetch (#3080) can move the request's url, but the branch is server-side on the header, so both answers still meet at whichever url the client picked.

A neighbour, not the same bug

throw respond(x, { status: 400, headers: { "cache-control": "public, max-age=60" } }) caches an error response. Both callers get the same bytes there, so nothing is poisonable — but the no-store default stepping aside for a thrown envelope is worth a line in the docs.

Environment

@solidjs/web	2.0.0-rc.4 (published), and next
Node	v24.19.0
OS	macOS (darwin 25.6.0)

[ryansolid]

Fixed on next in 9522945. Scripted calls now have their own address — <endpoint>/data/<id> — leaving the bare <endpoint>/<id> to plain HTTP (a reference's .url, rendered form actions, direct callers). The answer's shape is a function of the URL alone, so a shared cache can never replay one caller kind's answer to the other; the RSS-feed shape and the codec shape each live at their own path with the author's cache policy intact. Transitional: the instance header still summons the scripted shape at the bare address (already-loaded tabs survive a deploy), with those answers forced no-store so the divergent shape can never enter a cache. Downstream drafts: solidjs/solid-vite-plugin#335, solidjs/solid-router#591, solidjs/templates#288.

[frenzzy]

Verified on cc2fb53e by re-running the repro above against a build from source.

reference .url = /_server/redir <- plain HTTP (form actions, curl, crawlers)
client fetched = /_server/data/redir <- scripted calls

/_server/feed | 200 | public, max-age=60 | "<p>hi</p>"
/_server/data/feed | 200 | public, max-age=60 | ";0x00000271;{\"t\":25…"

Two shapes, two urls, both cacheable and unable to collide — with no Vary and nothing asked of the CDN, which was the part I cared about most. The transitional bare-address-plus-instance-header path answers no-store, so the divergent shape cannot enter a cache during a deploy either.

Worth noting this is the direction Next.js documents as where they are heading after paying for the header approach with CVE-2025-49005 — "moving all cache-affecting inputs into the URL pathname, eliminating the need for Vary on custom headers". Nice to see it land here as the first answer rather than the second.