Skip to content

Commit 9e6c867

Browse files
docs(web): rule the createEvent request contract — standards-shaped only
event.request is a standards-shaped Request (url, method, headers, signal, readable body) and nothing more. Any body-size enforcement on a Fetch body puts the runtime between the host's stream and the decoder and forces a rebuilt Request, so host-specific fields on the inbound object (request.cf, srvx runtime/ip/waitUntil) are not carried — and never were on the default bodySizeLimit path. Hosts have their own request in closure when they call the handler and surface platform handles on the event (locals). Settles #3315: #3312's rebuild-from-parts is the final shape, not a stopgap. Co-authored-by: Cursor <[email protected]>
1 parent a71e42e commit 9e6c867

3 files changed

Lines changed: 19 additions & 1 deletion

File tree

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+
Document the `createEvent(request)` contract: the request is a standards-shaped `Request` and nothing more. Body-size enforcement may hand a rebuilt `Request`, so host-specific fields on the inbound object are not carried; hosts surface platform handles on the event from their own request.

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ if (url.pathname.startsWith("/_server")) {
6060

6161
The handler resolves the function id, decodes arguments, runs the function under a request-event scope, and encodes the result (forwarding redirect/revalidation metadata through headers). All framework policy layers on through its options — each optional, the bare handler works alone:
6262

63-
- **`createEvent(request)`** — build the request event a call runs under; integrations supply their richer event (cookies, response helpers, platform handles).
63+
- **`createEvent(request)`** — build the request event a call runs under; integrations supply their richer event (cookies, response helpers, platform handles). The `request` handed here is a **standards-shaped `Request` and nothing more** — url, method, headers, signal, readable body. Enforcing `bodySizeLimit` puts the runtime between the host's stream and the decoder, so this may be a `Request` the runtime rebuilt, and host-specific fields on the inbound object (`request.cf`, srvx's `runtime`/`ip`/`waitUntil`) are not carried. This is a ruling, not a gap: any body-size enforcement on a Fetch body forces a rebuild, and `event.request` follows Solid's standards-only stance everywhere else. The host has its own request in closure when it calls the handler — read platform handles there and put them on the event (`locals`), which is where integrations should surface them regardless.
6464
- **`provideEvent(event, fn)`** — establish the event scope; defaults to the AsyncLocalStorage instance that `@solidjs/web/storage`’s `provideRequestEvent` parks on the global.
6565
- **`wrapInvocation(run, context)`** — wrap the function execution itself; the per-invocation seam for framework policy that must surround the call (auth guards, logging, error mapping, per-function middleware built in userland). Called inside the event scope with the invocation identity already established — `getServerFunctionInvocation()` answers before, during, and after `run()` — with `context` carrying `{ id, args, event, request?, direct }`. Must return `run()`’s result (replacing it replaces the result; throwing routes through normal error encoding). The **configured** hook also wraps direct SSR calls (`direct: true`, no `request`), so a policy can’t be bypassed by calling the function during a render; the per-request option applies to HTTP dispatch only. One hook, not a chain — composition stays userland, per the symmetry note under `prepareRequest`.
6666
- **`transformResult(event, result, context)`** — observe or replace the result before encoding; the extension point for response-metadata policy. Runs for returned and thrown results alike. Also configurable **server-wide** via `configureServerFunctionsServer` (the per-request option overrides, following the `collectFlightData` fallback pattern), so generic dispatchers that call `handleServerFunctionRequest(request)` with no options still apply it — this is how server components install `frameTransformResult` once. Its in-process mirror for direct SSR calls is `transformDirectResult(value, { id })` (config-only; direct calls never pass through the HTTP handler).

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -448,6 +448,15 @@ export interface HandleServerFunctionOptions {
448448
* Builds the request event a call runs under (default: bare
449449
* `{ request, locals: {} }`). Integrations supply their richer event
450450
* (cookies, response helpers, platform handles).
451+
*
452+
* `request` is a standards-shaped `Request` — url, method, headers,
453+
* signal, readable body — and nothing more. Enforcing `bodySizeLimit`
454+
* puts the runtime between the host's stream and the decoder, so the
455+
* object handed here may be one the runtime rebuilt; host-specific
456+
* fields on the inbound object (`request.cf`, srvx's `runtime`, `ip`,
457+
* `waitUntil`) are not carried. The host has its own request in closure
458+
* when it calls the handler: read platform handles there and put them on
459+
* the event (`locals`) rather than through `request`.
451460
*/
452461
createEvent?(request: Request): ServerFunctionEvent;
453462
/**
@@ -3214,6 +3223,10 @@ export function handleServerFunctionRequest(
32143223
* Options:
32153224
* - `createEvent(request)`: builds the request event (default: bare
32163225
* `{ request, locals: {} }`). Integrations supply their richer event.
3226+
* `request` is standards-shaped only — it may be a rebuilt `Request`
3227+
* (body-size enforcement), so host-specific fields on the inbound object
3228+
* are not carried; hosts read those from their own request and put them
3229+
* on the event.
32173230
* - `provideEvent(event, fn)`: overrides the configured provider per call.
32183231
* - `wrapInvocation(run, context)`: wraps the function execution itself —
32193232
* the per-invocation seam for framework policies (per-function

0 commit comments

Comments
 (0)