@pylonsync/functions 0.3.328 → 0.3.330

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.328",
+  "version": "0.3.330",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/ssr-runtime.ts

@@ -2864,6 +2864,15 @@ export async function handleRenderRoute(
       : pageLeaf;
     tree = await buildLayoutTree(cwd, tree, msg.layouts, props, React);
     const element = tree;
+    // Tracks whether the HTTP head (response_start) has actually gone out. A
+    // redirect()/notFound() from a suspended subtree is only genuinely IGNORED
+    // once the head is committed. Before that — every buffered render, and a
+    // streaming render up until response_start — the control signal rejects the
+    // render and the outer catch below emits the real 3xx/404, so the redirect
+    // IS honored. Gating the onError warning on this stops a false "head already
+    // sent" error from firing on every correct synchronous-shell auth-guard
+    // redirect (the buffered path is the overwhelmingly common case).
+    let headCommitted = false;
     const stream: ReadableStream<Uint8Array> = await renderToReadableStream(
       element,
       {
@@ -2877,18 +2886,24 @@ export async function handleRenderRoute(
           // their error through the catch/boundary path below.
           const ctrl = asRouteControl(err);
           if (ctrl) {
-            // A redirect()/notFound() thrown from BELOW a <Suspense> boundary:
-            // the shell already committed the head, so React swallowed it and
-            // it can't change the response. This is a known limitation on BOTH
-            // the buffered and streamed paths (response.* must fire in the
-            // synchronous shell). Surface it loudly instead of silently losing.
-            // eslint-disable-next-line no-console
-            console.error(
-              `[ssr] ${ctrl.kind}() called below a <Suspense> boundary was ignored — ` +
-                `the HTTP head was already sent. Call response.redirect()/notFound() (or ` +
-                `notFound() from @pylonsync/react) in the synchronous shell render, before ` +
-                `any await/<Suspense>.`,
-            );
+            // A redirect()/notFound() control signal surfaced during render. It
+            // was only truly ignored if the head is already committed: past
+            // response_start on a STREAMING render, a signal from a suspended
+            // subtree can't change the already-sent response — surface it
+            // loudly. Otherwise (every buffered render, and a streaming render
+            // pre-commit) the signal rejects the render and the outer catch
+            // turns it into the real 3xx/404, so the redirect is honored and
+            // nothing was lost — warning there would fire on every correct
+            // auth-guard redirect.
+            if (headCommitted) {
+              // eslint-disable-next-line no-console
+              console.error(
+                `[ssr] ${ctrl.kind}() called below a <Suspense> boundary was ignored — ` +
+                  `the HTTP head was already sent. Call response.redirect()/notFound() (or ` +
+                  `notFound() from @pylonsync/react) in the synchronous shell render, before ` +
+                  `any await/<Suspense>.`,
+              );
+            }
             return;
           }
           // eslint-disable-next-line no-console
@@ -3067,6 +3082,10 @@ export async function handleRenderRoute(
           : {}),
       }),
     });
+    // The head is on the wire now — from here a redirect()/notFound() thrown by
+    // a suspended subtree (streaming render) is genuinely too late to change the
+    // response, so onError above will (correctly) warn.
+    headCommitted = true;
 
     // Pre-load the manifest BEFORE the React stream starts emitting
     // so we know which `<link rel="stylesheet">` and

package/src/ssr-streaming.test.ts

@@ -17,6 +17,7 @@ import { describe, expect, test } from "bun:test";
 import React, { Suspense, use } from "react";
 import { renderToReadableStream } from "react-dom/server.browser";
 import {
+  asRouteControl,
   buildHydrationTail,
   computeBucketVerdict,
   computeCacheVerdict,
@@ -25,6 +26,7 @@ import {
   describeCacheVerdict,
   diffCommittedResponse,
   isDevMode,
+  PylonRouteControl,
 } from "./ssr-runtime";
 
 // ---------------------------------------------------------------------------
@@ -405,6 +407,106 @@ describe("react streaming mechanism", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// onError gating: a redirect()/notFound() is only "ignored" once the HTTP head
+// is committed. The runtime tracks a `headCommitted` flag and only logs the
+// scary "[ssr] … was ignored — head already sent" warning when it's true.
+// Before that (every BUFFERED render, and a streaming render pre-commit) the
+// control signal rejects the render and the outer catch turns it into the real
+// 3xx/404 — so warning there would fire on every CORRECT synchronous-shell
+// auth-guard redirect. These tests lock the React behavior that makes the gate
+// correct, using the real PylonRouteControl + asRouteControl classifier.
+// ---------------------------------------------------------------------------
+
+function makeRedirect(url: string): PylonRouteControl {
+  const e = new PylonRouteControl("redirect");
+  e.url = url;
+  e.redirectStatus = 307;
+  return e;
+}
+
+describe("SSR onError gating (redirect only 'ignored' after head commit)", () => {
+  test("BUFFERED shell redirect: render REJECTS (→ outer catch emits 307); no warning fires pre-commit", async () => {
+    // The auth-guard shape: response.redirect() throws a PylonRouteControl in
+    // the synchronous shell, before any await/<Suspense>.
+    function GuardedPage(): any {
+      throw makeRedirect("/login");
+    }
+    let headCommitted = false;
+    const warnings: string[] = [];
+    let rejectedWith: PylonRouteControl | null = null;
+    try {
+      const stream = await renderToReadableStream(
+        React.createElement(GuardedPage, {}),
+        {
+          onError(err: unknown) {
+            const ctrl = asRouteControl(err);
+            // Mirror the runtime's gate exactly: only warn once head is out.
+            if (ctrl && headCommitted) warnings.push(ctrl.kind);
+          },
+        },
+      );
+      // Buffered path: the runtime awaits allReady, THEN sends response_start
+      // (commits the head). A shell throw never gets here.
+      await (stream as any).allReady;
+      headCommitted = true;
+    } catch (err) {
+      // This is the runtime's outer catch — where the real 307 is emitted.
+      rejectedWith = asRouteControl(err);
+    }
+    expect(rejectedWith?.kind).toBe("redirect"); // honored, not lost
+    expect(rejectedWith?.url).toBe("/login");
+    expect(headCommitted).toBe(false); // head never committed → NOT ignored
+    expect(warnings).toEqual([]); // ← the fix: no false warning on a correct redirect
+  });
+
+  test("STREAMING below-<Suspense> redirect: onError fires AFTER head commit → warns", async () => {
+    const d = makeDeferred<string[]>();
+    // Throws a redirect from BELOW the boundary, only once its data resolves —
+    // i.e. after the shell (and head) have already been flushed.
+    function LateRedirect({ p }: { p: Promise<string[]> }): any {
+      use(p);
+      throw makeRedirect("/login");
+    }
+    function StreamPage({ p }: { p: Promise<string[]> }) {
+      return React.createElement(
+        "div",
+        null,
+        React.createElement("h1", null, "Shell"),
+        React.createElement(
+          Suspense,
+          { fallback: React.createElement("p", null, "L") },
+          React.createElement(LateRedirect, { p }),
+        ),
+      );
+    }
+    let headCommitted = false;
+    const warnings: string[] = [];
+    const stream = await renderToReadableStream(
+      React.createElement(StreamPage, { p: d.promise }),
+      {
+        onError(err: unknown) {
+          const ctrl = asRouteControl(err);
+          if (ctrl && headCommitted) warnings.push(ctrl.kind);
+        },
+      },
+    );
+    const reader = stream.getReader();
+    await reader.read(); // first flush = shell + fallback → head is on the wire
+    headCommitted = true; // runtime sends response_start at this point
+    d.resolve(["x"]); // resolve → LateRedirect throws below the committed boundary
+    try {
+      for (;;) {
+        const { done } = await reader.read();
+        if (done) break;
+      }
+    } catch {
+      /* the stream may error after the late throw; irrelevant here */
+    }
+    expect(warnings).toEqual(["redirect"]); // genuinely ignored → correctly warned
+  });
+});
+
 describe("hydration tail ordering (#278: data blob before entry script)", () => {
   test("__PYLON_DATA__ carries ssrData and the entry <script type=module> is LAST", () => {
     const ssrData = { 'list:["Note"]': [{ id: "1", body: "hi" }] };