Skip to content

Commit c66130d

Browse files
ryansolidclaudecursoragent
authored
feat(web): remove the X-Server-Function-Instance header from the wire protocol (#3421)
Since #3094 the header decided nothing: the answer shape is the address (/data/ for the scripted transport, bare for plain HTTP), no-JS gating is the address plus a form post, and #3416 had already dropped it from GET reads so a <link rel="preload"> could match them. What remained was a per-call id the handler copied into `context.instance` for the transformResult / transformFlightResult hooks, which no consumer reads — not the router (@solidjs/router@next), not frames, not the invocation or trace channels. Cross-wire correlation is the trace context's job (#3402). The header is gone from shared.ts, no longer sent by the client or read by the server, and no longer exported from either entry; `context.instance` leaves the hook contexts. The prepareRequest validation (#3174) uses the transport's method as its sentinel on every call shape — the one field every call carries — so a hook returning a fresh `{ headers }` is still refused before dispatch. Client-side call observers keep their local `instance` id. Tests: 29 spec files stop emulating the header in hand-built requests. The #3094 pins that sent the header to prove it was inert go with it — the code path they pinned left in #3102, and there is nothing left to be inert to; "shape by url alone" keeps its data-vs-bare comparison. The #3406 addressing test asserts the full header set per call shape. Co-authored-by: Claude <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent 76230f9 commit c66130d

36 files changed

Lines changed: 113 additions & 237 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/web": patch
3+
---
4+
5+
Remove the `X-Server-Function-Instance` header from the server-function wire protocol. Since #3094 it decided nothing: the answer shape is the address (`/data/` for the scripted transport, bare for plain HTTP), no-JS gating is the address plus a form post, and #3416 had already dropped it from GET reads so preloads could match. What remained was a per-call id the handler copied into `context.instance` for `transformResult` / `transformFlightResult`, which nothing consumed; cross-wire correlation is the trace context's job (`traceparent`, #3402). Breaking, nominally: `context.instance` is gone from the hook contexts, and `INSTANCE_HEADER` is no longer exported from `@solidjs/web/server-functions/{client,server}`. A legacy header on an incoming request is ignored, as it already was. The `prepareRequest` validation (#3174) now uses the transport's method as its sentinel on every call shape, so a hook returning a fresh `{ headers }` instead of spreading is still refused before dispatch. Client-side `observeServerFunctionCalls` events keep their local `instance` id for pairing a request with its response.

‎documentation/solid-2.0/10-server-functions.md‎

Lines changed: 22 additions & 22 deletions
Large diffs are not rendered by default.

‎packages/web/server-functions/src/client.ts‎

Lines changed: 18 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ import {
1212
BODY_FORMAT_HEADER,
1313
BodyFormat,
1414
ERROR_HEADER,
15-
INSTANCE_HEADER,
1615
LIVE_SOURCE,
1716
REDIRECT_HEADER,
1817
SERVER_FUNCTION_INVOKE,
@@ -49,7 +48,6 @@ export {
4948
ChunkReader,
5049
ERROR_HEADER,
5150
FLASH_COOKIE,
52-
INSTANCE_HEADER,
5351
REDIRECT_HEADER,
5452
SERVER_FUNCTION_INVOKE,
5553
SINGLE_FLIGHT_HEADER,
@@ -464,13 +462,12 @@ async function createRequest(base, id, instance, options, meta) {
464462
const headers = { ...options.headers };
465463
// A GET-encoded call's identity is its url, and nothing else: caches key
466464
// on it, and a `<link rel="preload" as="fetch">` is reused only by a
467-
// fetch matching it exactly, headers included. A per-call header makes
468-
// every read unique to the preload matcher, so the browser fetches twice
469-
// (#3406). The instance id therefore rides only the POST transport; a
470-
// read stays as plain as the url it is addressed by. (Its role as the
471-
// scripted-caller signal ended with #3094 — the data address is that.)
465+
// fetch matching it exactly, headers included, so a read carries no
466+
// header of the transport's own (#3406). The per-call `instance` id is
467+
// client-side bookkeeping for the call observers below; it never goes on
468+
// the wire (the scripted-caller signal is the data address, #3094, and
469+
// cross-wire correlation is the trace context's job).
472470
const read = options.method && options.method.toUpperCase() === "GET";
473-
if (!read) headers[INSTANCE_HEADER] = instance;
474471
// Subscribing to flight data IS the single-flight opt-in: with consumers
475472
// registered the transport asks the server for collection on every
476473
// mutation call; a consumer-less app never asks the server to do
@@ -501,13 +498,12 @@ async function createRequest(base, id, instance, options, meta) {
501498
// spreading — used to silently drop the argument payload, the abort
502499
// signal and every protocol header, and the call still dispatched (as
503500
// a bare GET the handler answers 405, with nothing naming the cause).
504-
// The transport's own init is the sentinel: the instance header rides
505-
// every POST-shaped call, so a returned init that lost it did not carry
506-
// the original forward; a GET-encoded call is header-free by design
507-
// (see above), so there the method the transport set stands in — a
508-
// fresh `{ headers }` carries none. Everything else stays the hook's to
509-
// change — a deliberate body/signal replacement is in contract
510-
// (streaming uploads), dropping the protocol is not.
501+
// The method the transport set is the sentinel: it is the one field
502+
// every call carries (a read has no body and no header of its own), and
503+
// a fresh `{ headers }` has none — `fetch` would default it to GET and
504+
// a POST call would dispatch without its payload. Everything else stays
505+
// the hook's to change — a deliberate body/signal replacement is in
506+
// contract (streaming uploads), dropping the protocol is not.
511507
if (prepared && prepared !== init) {
512508
if (typeof prepared !== "object") {
513509
throw new Error(
@@ -516,15 +512,14 @@ async function createRequest(base, id, instance, options, meta) {
516512
"init => ({ ...init, headers: { ...init.headers, ... } })"
517513
);
518514
}
519-
const kept = read
520-
? typeof prepared.method === "string" && prepared.method.toUpperCase() === "GET"
521-
: new Headers(prepared.headers).has(INSTANCE_HEADER);
522-
if (!kept) {
515+
if (
516+
typeof prepared.method !== "string" ||
517+
prepared.method.toUpperCase() !== init.method.toUpperCase()
518+
) {
523519
throw new Error(
524-
"prepareRequest returned an init without the transport's own settings " +
525-
`(${read ? "the GET method" : `the ${INSTANCE_HEADER} header`}), which would ` +
526-
"send the call without its payload or protocol. Spread the init it received: " +
527-
"init => ({ ...init, headers: { ...init.headers, ... } })"
520+
`prepareRequest returned an init without the transport's ${init.method} method, ` +
521+
"which would send the call without its payload or protocol. Spread the init it " +
522+
"received: init => ({ ...init, headers: { ...init.headers, ... } })"
528523
);
529524
}
530525
}

‎packages/web/server-functions/src/server.ts‎

Lines changed: 14 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,6 @@ import {
2727
BODY_FORMAT_HEADER,
2828
BodyFormat,
2929
ERROR_HEADER,
30-
INSTANCE_HEADER,
3130
LIVE_SOURCE,
3231
REDIRECT_HEADER,
3332
SERVER_FUNCTION_INVOKE,
@@ -56,7 +55,6 @@ import {
5655
export {
5756
ERROR_HEADER,
5857
FLASH_COOKIE,
59-
INSTANCE_HEADER,
6058
REDIRECT_HEADER,
6159
SERVER_FUNCTION_INVOKE,
6260
SINGLE_FLIGHT_HEADER,
@@ -294,7 +292,6 @@ export interface ServerFunctionsServerConfig {
294292
context: {
295293
id: string;
296294
args: unknown[];
297-
instance: string | null;
298295
request: Request;
299296
thrown?: boolean;
300297
}
@@ -311,7 +308,7 @@ export interface ServerFunctionsServerConfig {
311308
transformFlightResult?(
312309
event: ServerFunctionEvent,
313310
outcome: { value: unknown; data: unknown },
314-
context: { id: string; args: unknown[]; instance: string | null; request: Request }
311+
context: { id: string; args: unknown[]; request: Request }
315312
): Response | undefined | Promise<Response | undefined>;
316313
/**
317314
* The in-process mirror of `transformResult` for direct (same-server)
@@ -495,13 +492,12 @@ export interface HandleServerFunctionOptions {
495492
* Observes or replaces the function's result before encoding — the
496493
* extension point for response metadata policies (headers, statuses,
497494
* substituted results). Runs for returned and thrown results alike
498-
* (`context.thrown` distinguishes); `context.instance` is null for calls
499-
* that carry no instance header — no-JS form posts, direct HTTP, and the
500-
* transport's own GET-encoded reads, which stay header-free so caches
501-
* and preloads can match them (#3406). The context carries the call's identity — the function `id` and
502-
* the parsed `args` the implementation was invoked with — matching the
503-
* direct-call mirror (`transformDirectResult`), so a policy keying state
504-
* by the call works over either dispatch path. Return the result
495+
* (`context.thrown` distinguishes). The context carries the call's
496+
* identity — the function `id` and the parsed `args` the implementation
497+
* was invoked with — matching the direct-call mirror
498+
* (`transformDirectResult`), so a policy keying state by the call works
499+
* over either dispatch path; `context.request` tells a scripted call (the
500+
* `/data/` address) from a bare-address one. Return the result
505501
* unchanged to pass through, or a `ResponseEnvelope` (exposed through
506502
* the core entry) to send HTTP metadata plus a structured payload. Runs
507503
* before `collectFlightData`, so the flight hook sees the transformed
@@ -514,7 +510,6 @@ export interface HandleServerFunctionOptions {
514510
context: {
515511
id: string;
516512
args: unknown[];
517-
instance: string | null;
518513
request: Request;
519514
thrown?: boolean;
520515
}
@@ -532,7 +527,7 @@ export interface HandleServerFunctionOptions {
532527
transformFlightResult?(
533528
event: ServerFunctionEvent,
534529
outcome: { value: unknown; data: unknown },
535-
context: { id: string; args: unknown[]; instance: string | null; request: Request }
530+
context: { id: string; args: unknown[]; request: Request }
536531
): Response | undefined | Promise<Response | undefined>;
537532
/**
538533
* Builds the response for calls made without the client runtime (at
@@ -3306,10 +3301,10 @@ export function handleServerFunctionRequest(
33063301
* (call headers and cookies copied on), returning undefined keeps the
33073302
* plain serialized envelope.
33083303
* - `handleNoJS(result, request, args)`: response for calls made without
3309-
* the client runtime (no instance header) — the override for the no-JS
3304+
* the client runtime (at the bare address) — the override for the no-JS
33103305
* form convention. Falls back to the configured hook, then to
33113306
* `createNoJSHandler()` for browser form posts (redirect back with the
3312-
* outcome in a flash cookie); other no-instance callers, such as direct
3307+
* outcome in a flash cookie); other bare-address callers, such as direct
33133308
* HTTP requests, get the normal serialized response.
33143309
* - `csrf`: configures same-origin request validation, or disables it with
33153310
* `false`. Enabled by default.
@@ -3383,8 +3378,6 @@ export async function handleServerFunctionRequest(request, options = {}) {
33833378
if (protectsRequest && !(await allowsServerFunctionRequest(request, csrf === true ? {} : csrf))) {
33843379
return finalizeTransportResponse(forbiddenResponse(), method);
33853380
}
3386-
const instance = request.headers.get(INSTANCE_HEADER);
3387-
33883381
if (!functionId) {
33893382
const response = new Response(DEV ? "Server function not found" : null, { status: 404 });
33903383
return finalizeTransportResponse(protectsRequest ? withCSRFVary(response) : response, method);
@@ -3395,10 +3388,10 @@ export async function handleServerFunctionRequest(request, options = {}) {
33953388
// ADDRESS: the data address IS the scripted protocol, the bare address is
33963389
// plain HTTP. On the url, not a header, because shared caches key on the
33973390
// url and store one answer per key — a header-driven shape means one
3398-
// caller kind's cached answer can be replayed to the other (#3094). The
3399-
// instance header does not shape the answer; it only identifies a POST
3400-
// transport call to the hooks (`context.instance`) — reads carry none,
3401-
// so caches and preloads can match them (#3406).
3391+
// caller kind's cached answer can be replayed to the other (#3094). No
3392+
// header identifies the caller either: a GET-encoded read carries none
3393+
// of the transport's own, so to caches and preloads it is exactly its
3394+
// url (#3406).
34023395
const scripted = address.data;
34033396

34043397
// Method allowlist: POST always dispatches (the default transport);
@@ -3650,7 +3643,6 @@ export async function handleServerFunctionRequest(request, options = {}) {
36503643
const flightContext = {
36513644
id: functionId,
36523645
args: parsed,
3653-
instance,
36543646
request,
36553647
collectsFlight,
36563648
codec,

‎packages/web/server-functions/src/shared.ts‎

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -603,18 +603,6 @@ export function decodeErrorHeaderValue(value) {
603603
}
604604
}
605605

606-
/**
607-
* Header carrying a per-call instance id, on the POST transport only. It
608-
* reaches the handler's hooks as `context.instance` (null without it) and
609-
* matches what the client's call observers report, so a call can be
610-
* followed across the wire. GET-encoded reads never carry it: their
611-
* identity is the url, which caches and `<link rel="preload">` key on, and
612-
* a per-call header would make each read unmatchable (#3406). It no longer
613-
* decides anything about the answer — the data address is the scripted
614-
* signal (#3094).
615-
*/
616-
export const INSTANCE_HEADER = "X-Server-Function-Instance";
617-
618606
/** Header carrying the body format tag (a `BodyFormat` value). */
619607
export const BODY_FORMAT_HEADER = "X-Server-Function-Format";
620608

‎packages/web/test/runtime/cookies.spec.js‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -314,15 +314,11 @@ describe("createSSRResponse carries multiple Set-Cookie values", () => {
314314
});
315315

316316
describe("handleServerFunctionRequest folds the event response stub", () => {
317-
const INSTANCE_HEADERS = {
318-
"X-Server-Function-Instance": "server-function:test"
319-
};
320-
321317
function dispatch(id, event, extraHeaders = {}, options = {}) {
322318
return handleServerFunctionRequest(
323319
new Request(`http://localhost/_server/${encodeURIComponent(id)}`, {
324320
method: "POST",
325-
headers: { ...INSTANCE_HEADERS, ...extraHeaders }
321+
headers: extraHeaders
326322
}),
327323
{ createEvent: () => event, csrf: false, ...options }
328324
);

‎packages/web/test/server/frame-hn.spec.tsx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@ globalThis.document = new JSDOM("<body></body>").window.document;
2020
import { frameTransformResult } from "../../frames/src/frame-sink.js";
2121
import { applyFrameResponse, isFrameStreamResponse } from "../../frames/src/frame-transport.js";
2222
import {
23-
INSTANCE_HEADER,
2423
handleServerFunctionRequest,
2524
registerServerFunction
2625
} from "../../server-functions/src/server.js";
@@ -86,7 +85,6 @@ function fetchStory(storyId: string) {
8685
method: "POST",
8786
headers: {
8887
"Sec-Fetch-Site": "same-origin",
89-
[INSTANCE_HEADER]: "1",
9088
"Content-Type": "text/plain",
9189
"X-Server-Function-Format": "1"
9290
},

‎packages/web/test/server/response-invariants.spec.tsx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,6 @@ describe("error sanitization passes thrown Responses through (production bundle)
9292
method: "POST",
9393
headers: {
9494
"Sec-Fetch-Site": "same-origin",
95-
"X-Server-Function-Instance": "server-function:test",
9695
"content-type": "application/json",
9796
"X-Server-Function-Format": "1"
9897
},

‎packages/web/test/server/server-functions-abort-conforming-length.spec.tsx‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,6 @@ async function abortMidUpload(declaration: string | null) {
108108
});
109109
const headers: Record<string, string> = {
110110
"Sec-Fetch-Site": "same-origin",
111-
"X-Server-Function-Instance": "server-function:test",
112111
[BODY_FORMAT_HEADER]: JSON_FORMAT
113112
};
114113
// A conforming declaration is the ONLY difference between the two rows.

‎packages/web/test/server/server-functions-addressing.spec.tsx‎

Lines changed: 18 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ function connectTransport(seen: Request[]) {
6464
};
6565
}
6666

67-
/** A call made without the client runtime: no instance header. */
67+
/** A call made without the client runtime: at the bare address, no transport headers. */
6868
function unscripted(url: string, init: RequestInit = {}) {
6969
return handleServerFunctionRequest(
7070
new Request(`http://localhost${url}`, {
@@ -99,8 +99,9 @@ describe("server-function addressing (#3070, built bundles)", () => {
9999
// A `<link rel="preload" as="fetch">` is reused only by a fetch that
100100
// matches it exactly, headers included, so a per-call header on the
101101
// cacheable transport made the browser fetch every preloaded read
102-
// twice. The url is the whole identity of a read; the instance id stays
103-
// on the POST transport, where it still names the call to the hooks.
102+
// twice. The url is the whole identity of a read. No call carries a
103+
// per-call id any more: the scripted-caller signal is the address
104+
// (#3094) and the id was client-side bookkeeping for call observers.
104105
serverGET(
105106
createServerSideReference(
106107
registerServerReference("addr-preload-0", async (n?: number) =>
@@ -119,15 +120,15 @@ describe("server-function addressing (#3070, built bundles)", () => {
119120
restore();
120121
}
121122
const [read, argless, write] = seen;
123+
// (the harness stamps Sec-Fetch-Site on the way in; the browser's is not a header the transport sets)
124+
const sent = (request: Request) =>
125+
[...request.headers.keys()].filter(name => name !== "sec-fetch-site").sort();
122126
expect(read.method).toBe("GET");
123-
expect(read.headers.get("X-Server-Function-Instance")).toBeNull();
124-
expect([...read.headers.keys()].filter(name => name.startsWith("x-server-function"))).toEqual(
125-
[]
126-
);
127-
expect(argless.headers.get("X-Server-Function-Instance")).toBeNull();
128-
// the POST transport keeps its per-call id
127+
expect(sent(read)).toEqual([]);
128+
expect(sent(argless)).toEqual([]);
129+
// the POST transport's headers describe the body, never the call
129130
expect(write.method).toBe("POST");
130-
expect(write.headers.get("X-Server-Function-Instance")).toMatch(/^server-function:/);
131+
expect(sent(write)).toEqual(["content-type", "x-server-function-format"]);
131132
});
132133

133134
it("addresses a POST call by path, with nothing in the query", async () => {
@@ -272,30 +273,12 @@ describe("server-function addressing (#3070, built bundles)", () => {
272273
expect(await response.text()).toBe("ok");
273274
});
274275

275-
it("answers the same url the same way, scripted or not", async () => {
276-
// The reading is decided by the url alone: a cache keys on the url, so a
277-
// request header must never change what a call means.
278-
serverGET(
279-
createServerSideReference(
280-
registerServerReference("addr-invariant-0", async (value: unknown) =>
281-
value instanceof URLSearchParams ? `params:${value.get("q")}` : `other:${typeof value}`
282-
)
283-
)
284-
);
285-
const scripted = await unscripted("/_server/addr-invariant-0?q=solid", {
286-
headers: { "X-Server-Function-Instance": "server-function:test" }
287-
});
288-
const plain = await unscripted("/_server/addr-invariant-0?q=solid");
289-
expect(await scripted.text()).toBe("params:solid");
290-
expect(await plain.text()).toBe("params:solid");
291-
});
292-
293276
it("shapes the answer by the url alone (#3094)", async () => {
294277
// The two caller kinds get differently shaped answers — the codec's at
295278
// the data address, plain HTTP at the bare one — and a shared cache
296-
// stores one answer per url. So the shape must be a function of the url,
297-
// never of a request header: at either address, the same url answers
298-
// with the same shape whether or not the instance header rides along.
279+
// stores one answer per url. So the shape must be a function of the url
280+
// and nothing else: a direct caller at the data address gets the codec
281+
// shape, and the same function at the bare address answers verbatim.
299282
serverGET(
300283
createServerSideReference(
301284
registerServerReference(
@@ -308,13 +291,9 @@ describe("server-function addressing (#3070, built bundles)", () => {
308291
)
309292
);
310293

311-
// data address: the codec shape, header or no header
312-
const dataTagged = await unscripted("/_server/data/addr-shape-0", {
313-
headers: { "X-Server-Function-Instance": "server-function:test" }
314-
});
315-
const dataPlain = await unscripted("/_server/data/addr-shape-0");
316-
expect(dataTagged.headers.has("X-Server-Function-Format")).toBe(true);
317-
expect(dataPlain.headers.has("X-Server-Function-Format")).toBe(true);
294+
// data address: the codec shape
295+
const data = await unscripted("/_server/data/addr-shape-0");
296+
expect(data.headers.has("X-Server-Function-Format")).toBe(true);
318297

319298
// bare address: the raw Response verbatim
320299
const bare = await unscripted("/_server/addr-shape-0");
@@ -333,10 +312,6 @@ describe("server-function addressing (#3070, built bundles)", () => {
333312
const response = await unscripted(`/_server/addr-broken-0?${query}`);
334313
expect([query, response.status]).toEqual([query, 400]);
335314
}
336-
const scripted = await unscripted("/_server/addr-broken-0?args=hello", {
337-
headers: { "X-Server-Function-Instance": "server-function:test" }
338-
});
339-
expect(scripted.status).toBe(400);
340315
});
341316

342317
it("ignores the id header and the query parameter that used to address a call", async () => {
@@ -390,10 +365,7 @@ describe("server-function addressing (#3070, built bundles)", () => {
390365
registerServerFunction("data", async () => "the id named data");
391366
const bare = await unscripted("/_server/data", { method: "POST" });
392367
expect(await bare.text()).toBe("the id named data");
393-
const scripted = await unscripted("/_server/data/data", {
394-
method: "POST",
395-
headers: { "X-Server-Function-Instance": "server-function:test" }
396-
});
368+
const scripted = await unscripted("/_server/data/data", { method: "POST" });
397369
expect(scripted.status).toBe(200);
398370
});
399371

0 commit comments

Comments
 (0)