turnkey: fold the response stub at the handler edge with commitEventResponse

A middleware that returns its own Response (an API handler that never calls
next()) bypasses createSSRResponse, so stub writes made inside the request
scope — cookies appended to event.response.headers, status — never reached
the wire. The generated handler now applies the runtime's
commitEventResponse(response, event) unconditionally at the handler edge,
strictly after the outermost middleware returns: headers stay mutable
through the whole unwind, committed page responses pass through untouched
(the fold is idempotent), and the per-path applyResponseStub folds (raw
entry.render Responses, server-function responses) collapse into the one
edge fold.

Resolved off a namespace import with a local fallback preserving the old
partial-fold semantics until the .40 repin ships the export in @solidjs/web
(TODO(.40-repin) in the codegen — a named import of a missing export is
fatal in ESM). Turnkey e2e: codegen string assertions (the fold resolves
off the runtime and runs after the unwind) pass against the pinned deps;
the new wire assertion — a /blocked early-return's stub cookie arrives
exactly once — verified 34/34 with the middleware mode against a local
post-repin @solidjs/web build (the mode as committed requires
> 2.0.0-beta.31 for composeMiddleware, per the previous changeset).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/handler-edge-commit-fold.md

@@ -0,0 +1,7 @@
+---
+'vite-plugin-solid': patch
+---
+
+Turnkey SSR closes the middleware early-return gap with the runtime's `commitEventResponse`: a middleware that answers without calling `next()` (an API handler) bypasses `createSSRResponse`, so its request-scope stub writes — cookies appended to `event.response.headers`, status — never reached the wire. The generated handler now applies `commitEventResponse(response, event)` unconditionally at the handler edge, strictly after the outermost middleware returns: headers stay mutable through the whole unwind, committed page responses pass through untouched (the fold is idempotent), and the inner per-path folds (`applyResponseStub` on raw `entry.render` Responses and server-function responses) collapse into the one edge fold.
+
+Until the next `@solidjs/web` repin ships `commitEventResponse` (TODO(.40-repin) in the codegen), the handler resolves it off a namespace import with a local fallback that preserves the previous partial fold semantics — a named import of a missing export would be fatal in ESM — so generated modules keep working against the current beta.31 line and upgrade to the runtime's fold (protocol-header denylist, committed-stub loudness) automatically at the repin.

examples/turnkey/src/middleware.ts

@@ -5,7 +5,9 @@
 // - runs inside the request-event scope: getRequestEvent() answers, locals
 //   decoration is visible to the page render and to server functions,
 // - composition order (first → second → dispatch, unwinding in reverse),
-// - short-circuiting (/blocked never reaches the render),
+// - short-circuiting (/blocked never reaches the render), with a stub
+//   cookie set inside the request scope that only the handler edge's
+//   commit fold can carry onto the early-return Response,
 // - error middleware (try/catch around next() turns a render throw into a
 //   controlled 500),
 // - the post-next() mutation window: headers set after `await next()` land
@@ -20,6 +22,11 @@ async function first(request: Request, next: Next): Promise<Response> {
   event.locals.order = ['first'];
   event.locals.user = 'mw-user';
   if (new URL(request.url).pathname === '/blocked') {
+    // Early return: this Response never goes through createSSRResponse, so
+    // the stub write below only reaches the wire through the handler
+    // edge's commitEventResponse fold after the chain unwinds — the e2e
+    // asserts the cookie arrives exactly once (fold ran, and only once).
+    event.response.headers.append('set-cookie', 'mw-blocked=1; Path=/');
     return new Response('blocked-by-middleware', { status: 403 });
   }
   try {

examples/turnkey/test/run.mjs

@@ -83,9 +83,13 @@
 //     emits the script-redirect fallback on the streamed 200,
 //   - `ssr.middleware` (SSR_MIDDLEWARE=1, src/middleware.ts): composition
 //     order, locals decoration visible to the page and to a server function
-//     over /_server (one request event fronts both), short-circuiting,
-//     error middleware catching a render throw, and the post-next()
+//     over /_server (one request event fronts both), short-circuiting —
+//     with the handler edge's commitEventResponse fold carrying an
+//     early-return's stub cookie onto the wire exactly once — error
+//     middleware catching a render throw, and the post-next()
 //     header-mutation window on a streamed response — in dev and prod,
+//     plus codegen string assertions that the generated handler resolves
+//     commitEventResponse from @solidjs/web and folds after the unwind,
 //   - `vite preview` serves the production artifact with no server file:
 //     dist/client statically, everything else (pages, /_server, middleware,
 //     the lifecycle) through the built handler.
@@ -1924,7 +1928,9 @@ async function runFramesMode() {
 //   hit the wire before the chain unwound,
 // - locals decoration visible to the page render (/whoami) and to a server
 //   function over /_server (the endpoint shares the chain's request event),
-// - short-circuit (/blocked never reaches the render),
+// - short-circuit (/blocked never reaches the render), and the handler
+//   edge's commit fold: the stub cookie the middleware appended inside the
+//   request scope arrives on the early-return Response exactly once,
 // - error middleware (/boom: a render throw becomes the middleware's 500).
 async function runMiddlewareChecksOverHttp(mode, origin, functionId) {
   const page = await fetchStreamed(origin + '/');
@@ -1964,6 +1970,20 @@ async function runMiddlewareChecksOverHttp(mode, origin, functionId) {
     blocked.status === 403 && blockedBody === 'blocked-by-middleware',
     `status ${blocked.status}, body ${JSON.stringify(blockedBody.slice(0, 60))}`,
   );
+  // The early return skipped createSSRResponse, so the stub cookie the
+  // middleware appended inside the request scope can only arrive through
+  // the handler edge's commitEventResponse fold — and exactly once (the
+  // fold is idempotent; nothing double-applies it).
+  const blockedCookies = (blocked.headers.getSetCookie ? blocked.headers.getSetCookie() : []).filter(
+    (cookie) => cookie.startsWith('mw-blocked='),
+  );
+  record(
+    mode,
+    'mw',
+    'early-return stub cookie arrives exactly once (edge commit fold)',
+    blockedCookies.length === 1 && blockedCookies[0].startsWith('mw-blocked=1'),
+    `set-cookie: ${JSON.stringify(blockedCookies)}`,
+  );
 
   const boom = await fetch(origin + '/boom', { headers: { accept: 'text/html' } });
   const boomBody = await boom.text();
@@ -2012,6 +2032,41 @@ async function runMiddlewareMode() {
   };
   let functionId = null;
   try {
+    // ---- Codegen: the generated handler folds at the edge ----------------
+    // String assertions on the handler module the plugin generates (no
+    // execution): every response leaves through commitEventResponse —
+    // resolved off the runtime with a local fallback until the .40 repin
+    // ships the export in @solidjs/web — strictly AFTER the middleware
+    // chain unwinds, so early-return Responses get their stub writes and
+    // post-next() header mutation stays possible through the whole unwind.
+    process.env.SSR_MIDDLEWARE = '1';
+    let probe;
+    try {
+      probe = await createServer({ root: exampleDir, server: { middlewareMode: true } });
+      const transformed = await probe.environments.ssr.transformRequest('virtual:solid-ssr-handler');
+      const code = transformed?.code || '';
+      const unwind = code.indexOf('runMiddleware(request');
+      const fold = code.indexOf('return commitEventResponse(response, event)');
+      record(
+        'mw-codegen',
+        'gen',
+        'handler resolves commitEventResponse from @solidjs/web (fallback until .40 repin)',
+        // `.commitEventResponse ??` survives the SSR transform (the
+        // namespace binding itself is rewritten to a vite import handle).
+        code.includes('.commitEventResponse ??'),
+      );
+      record(
+        'mw-codegen',
+        'gen',
+        'edge fold runs after the middleware chain unwinds',
+        unwind !== -1 && fold !== -1 && fold > unwind,
+        `runMiddleware @ ${unwind}, fold @ ${fold}`,
+      );
+    } finally {
+      await probe?.close();
+      delete process.env.SSR_MIDDLEWARE;
+    }
+
     // ---- Dev: the chain fronts the dev middlewares -----------------------
     const devOrigin = `http://localhost:${devPort}`;
     server = startProcess('pnpm', ['exec', 'vite', '--port', String(devPort), '--strictPort'], {

src/ssr/index.ts

@@ -381,10 +381,14 @@ export function ssrServe(
   // they differ in how the client entry URL is known (baked dev URL vs a
   // manifest scan) and what gets injected into <head> (Vite client + style
   // patch in dev). The response-head lifecycle is the runtime's
-  // (`createRequestEvent`/`createSSRResponse` from @solidjs/web): every
-  // request runs under a stub-backed event, `httpStatus`/`httpHeader`
-  // writes land on the wire at shell flush, a pre-flush redirect becomes a
-  // real 3xx and a post-flush one the script fallback. When
+  // (`createRequestEvent`/`createSSRResponse`/`commitEventResponse` from
+  // @solidjs/web): every request runs under a stub-backed event,
+  // `httpStatus`/`httpHeader` writes land on the wire at shell flush, a
+  // pre-flush redirect becomes a real 3xx and a post-flush one the script
+  // fallback, and a Response that skipped the render lifecycle (middleware
+  // early return, raw entry.render Response, server functions) has the
+  // stub folded on at the handler edge after the middleware chain fully
+  // unwinds. When
   // `serverFunctions` is enabled the endpoint is dispatched here on every
   // surface (the runnable-dev middleware routes through this module), so
   // user middleware and the shared request event front it identically.
@@ -394,6 +398,10 @@ export function ssrServe(
 
     const lines = [
       `import { createRequestEvent, createSSRResponse${middlewarePath ? ', composeMiddleware' : ''} } from '@solidjs/web';`,
+      // Namespace import so the handler also loads against runtimes that
+      // predate `commitEventResponse` (a named import of a missing export
+      // is fatal in ESM) — see the resolution + fallback below.
+      `import * as _webRuntime from '@solidjs/web';`,
       `import { provideRequestEvent } from ${JSON.stringify(STORAGE_SOURCE)};`,
       `import * as entry from ${JSON.stringify(entryServerSpec())};`,
       ...(middlewarePath
@@ -512,23 +520,38 @@ export function ssrServe(
 
     lines.push(
       ``,
-      // Responses that don't run the render lifecycle (raw Responses from
-      // entry.render, server-function responses) still honor stub header
-      // writes made before they were produced — matching what an
-      // h3/framework layer merging `event.response` would do. Status stays
-      // the response's own; `set-cookie` values append entry by entry.
-      `function applyResponseStub(response, stub) {`,
-      `  if (!stub || stub.committed) return response;`,
-      `  stub.committed = true;`,
-      `  try {`,
-      `    stub.headers.forEach((value, key) => {`,
-      `      if (key !== 'set-cookie' && !response.headers.has(key)) response.headers.set(key, value);`,
-      `    });`,
-      `    const cookies = stub.headers.getSetCookie ? stub.headers.getSetCookie() : [];`,
-      `    for (const cookie of cookies) response.headers.append('set-cookie', cookie);`,
-      `  } catch {}`,
-      `  return response;`,
-      `}`,
+      // The handler-edge commit fold — the runtime's `commitEventResponse`,
+      // the second of the response lifecycle's two exits: page results
+      // leave through `createSSRResponse`, any other Response (a middleware
+      // early return, a raw Response from entry.render, a server-function
+      // response) leaves through `commitEventResponse`, which folds the
+      // event's response stub onto it (cookies append entry-by-entry, other
+      // headers gap-fill, status stays the response's own) and commits the
+      // stub. Committed stubs pass through untouched, so the edge applies
+      // it unconditionally.
+      //
+      // TODO(.40-repin): collapse to the named import above and delete the
+      // fallback — `commitEventResponse` ships in @solidjs/web after the
+      // .40 repin. Until then the fallback preserves this handler's
+      // previous partial fold (no protocol denylist, no commit loudness) so
+      // the generated module keeps working against the published beta.31
+      // line, and middleware early returns get their stub writes onto the
+      // wire on both runtimes.
+      `const commitEventResponse =`,
+      `  _webRuntime.commitEventResponse ??`,
+      `  ((response, event) => {`,
+      `    const stub = event && event.response;`,
+      `    if (!stub || stub.committed) return response;`,
+      `    stub.committed = true;`,
+      `    try {`,
+      `      stub.headers.forEach((value, key) => {`,
+      `        if (key !== 'set-cookie' && !response.headers.has(key)) response.headers.set(key, value);`,
+      `      });`,
+      `      const cookies = stub.headers.getSetCookie ? stub.headers.getSetCookie() : [];`,
+      `      for (const cookie of cookies) response.headers.append('set-cookie', cookie);`,
+      `    } catch {}`,
+      `    return response;`,
+      `  });`,
       ``,
       `async function dispatchRequest(request, event, options) {`,
     );
@@ -537,11 +560,13 @@ export function ssrServe(
         `  if (new URL(request.url).pathname === endpoint) {`,
         // The call shares the middleware chain's event (locals decoration,
         // the response stub); an explicit host-provided createEvent wins.
-        `    const response = await handleServerFunctionRequest(request, {`,
+        // No fold here: the runtime's server-function handler runs the
+        // commit seam itself, and anything it left uncommitted is caught by
+        // the unconditional edge fold in handleRequest.
+        `    return handleServerFunctionRequest(request, {`,
         `      createEvent: () => event,`,
         `      ...options.serverFunctions,`,
         `    });`,
-        `    return applyResponseStub(response, event.response);`,
         `  }`,
       );
     }
@@ -556,7 +581,10 @@ export function ssrServe(
       `  if (result && typeof result.pipe !== 'function' && typeof result.then === 'function') {`,
       `    result = await result;`,
       `  }`,
-      `  if (result instanceof Response) return applyResponseStub(result, event.response);`,
+      // Raw Responses fold at the handler edge (handleRequest), after the
+      // middleware chain unwinds — not here, where middleware above this
+      // frame could still legitimately mutate headers.
+      `  if (result instanceof Response) return result;`,
       // The runtime's response-head lifecycle: commit at shell flush,
       // pre-flush Location as a real redirect, post-flush Location as the
       // script fallback; the transform injects the doctype/head pieces.
@@ -572,9 +600,16 @@ export function ssrServe(
       // Middleware runs inside the request scope, after event creation —
       // getRequestEvent() answers in middleware exactly as in app code, and
       // nothing reaches the wire until the outermost middleware returns.
-      `  return provideRequestEvent(event, () =>`,
+      `  const response = await provideRequestEvent(event, () =>`,
       `    runMiddleware(request, (req) => dispatchRequest(req || request, event, options)),`,
       `  );`,
+      // The fold runs strictly AFTER the outermost middleware returned:
+      // headers stay mutable through the whole unwind, and a middleware
+      // early return (an API handler that never called next()) gets its
+      // stub writes — cookies set inside the request scope, status — onto
+      // the wire. Unconditional: page responses come back from
+      // createSSRResponse committed and pass through untouched.
+      `  return commitEventResponse(response, event);`,
       `}`,
     );