fix(0.1.1102): re-land the 13 dropped v0.1.1101 fixes + fix the cold-cache redis SSR regression, optional-catch-all root, and client-side barrel leak

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.1102",
+  "version": "0.1.1103",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "minimumDependencyAge": {

docs/api-reference/veryfront/index.md

@@ -79,11 +79,11 @@ export function getServerData(ctx: DataContext) {
 | `mergeConfigs` | Merge multiple partial Veryfront configuration objects into one config object. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/config/define-config.ts#L19) |
 | `mergeConfigs` |  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/config/define-config.ts#L20) |
 | `mergeConfigs` |  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/config/define-config.ts#L21) |
-| `notFound` | Return a 404 result from a data loader. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/data/helpers.ts#L9) |
+| `notFound` | Render the 404 page from a data loader. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/data/helpers.ts#L45) |
 | `parseFormData` | Parse and validate multipart or URL-encoded form data. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/input-validation/parsers.ts#L48) |
 | `parseJsonBody` | Parse and validate a JSON request body. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/input-validation/parsers.ts#L12) |
 | `parseQueryParams` | Parse and validate query parameters from a request URL. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/input-validation/parsers.ts#L81) |
-| `redirect` | Return a redirect result from a data loader. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/data/helpers.ts#L4) |
+| `redirect` | Redirect the request from a data loader. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/data/helpers.ts#L34) |
 | `sanitizeData` | Sanitize data to prevent XSS and prototype pollution attacks. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/security/input-validation/sanitizers.ts#L2) |
 | `serverError` | Create a 500 Internal Server Error response. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/platform/compat/http/responses.ts#L134) |
 | `startServer` | Start a Veryfront server in development or production mode. | [source](https://github.com/veryfront/veryfront-code/blob/main/src/server/index.ts#L331) |

docs/guides/api-routes.md

@@ -25,9 +25,7 @@ export function GET() {
 }
 ```
 
-Use `pages/api/**` in the pages router. Export named HTTP method handlers or a `default` fallback handler. Each handler receives an `APIContext` as `ctx`; use `ctx.request` for the raw request, `ctx.params` for route params, and `ctx.query` for query parameters.
-
-The `ctx.json` helper is intentionally overloaded by arity: `ctx.json()` reads the request body as JSON, while `ctx.json(data, init?)` returns a JSON `Response`. Use `ctx.request` directly when you need lower-level request APIs such as streaming, form data, or text parsing.
+Use `pages/api/**` in the pages router. Export named HTTP method handlers or a `default` fallback handler. Each handler receives an `APIContext` as `ctx`; use `ctx.request` for the raw request, `ctx.params` for route params, `ctx.query` for query parameters, and `ctx.json(data)` or `Response.json(data)` to return JSON. To read a posted JSON body, use `ctx.body()`, which parses it once and answers a 400 if it is malformed.
 
 ```ts
 // pages/api/hello.ts
@@ -36,6 +34,11 @@ import type { APIContext } from "veryfront";
 export function GET(ctx: APIContext) {
   return ctx.json({ message: "Hello, world!" });
 }
+
+export async function POST(ctx: APIContext) {
+  const { name } = await ctx.body<{ name: string }>();
+  return ctx.json({ message: `Hello, ${name}!` });
+}
 ```
 
 ## Basic route
@@ -99,13 +102,13 @@ export async function GET(ctx: APIContext) {
 }
 
 export async function POST(ctx: APIContext) {
-  const body = await ctx.json();
+  const body = await ctx.body<Record<string, unknown>>();
   const user = { id: "user_456", ...body };
   return ctx.json(user, { status: 201 });
 }
 
 export async function DELETE(ctx: APIContext) {
-  const { id } = await ctx.json() as { id?: string };
+  const { id } = await ctx.body<{ id?: string }>();
   if (!id) return ctx.json({ error: "Missing id" }, { status: 400 });
   return new Response(null, { status: 204 });
 }

docs/guides/data-fetching.md

@@ -93,6 +93,27 @@ export async function getServerData({ params }: DataContext) {
 redirect("/new-url", true); // 301 permanent redirect
 ```
 
+Throwing works the same way. `throw notFound()` and `throw redirect(...)` behave exactly like returning them, which is useful inside a helper that has no clean way to return to the data function:
+
+```tsx
+import { type DataContext, notFound } from "veryfront";
+
+const posts = [{ slug: "hello", title: "Hello" }];
+
+function requirePost(slug: string) {
+  const post = posts.find((item) => item.slug === slug);
+  if (!post) throw notFound();
+
+  return post;
+}
+
+export function getServerData({ params }: DataContext) {
+  return { props: { post: requirePost(String(params.slug)) } };
+}
+```
+
+Only the objects `notFound()` and `redirect()` produce are read as control flow. Every other thrown value is an error, including an object that happens to carry a `notFound` property, such as a parsed error body from an upstream API.
+
 ## Client-side fetching
 
 For data that loads after the page renders, fetch in a client component:

src/data/helpers.test.ts

@@ -116,5 +116,49 @@ describe("helpers.ts", () => {
     it("rejects notFound: false", () => {
       assertEquals(isDataControlResult({ notFound: false }), false);
     });
+
+    // A loader that does `throw await res.json()` against an upstream returning
+    // `{ notFound: true, message: "record locked" }` must reach the error
+    // handler. Reading it as a 404 renders the wrong page, records a circuit
+    // breaker success, skips the log, and caches the bogus 404.
+    it("rejects an unbranded object that only looks like notFound()", () => {
+      assertEquals(isDataControlResult({ notFound: true }), false);
+      assertEquals(
+        isDataControlResult({ notFound: true, message: "record locked", requestId: "abc" }),
+        false,
+      );
+    });
+
+    it("rejects an unbranded object that only looks like redirect()", () => {
+      assertEquals(isDataControlResult({ redirect: { destination: "/login" } }), false);
+      assertEquals(
+        isDataControlResult({ redirect: { destination: "/login", permanent: true } }),
+        false,
+      );
+    });
+
+    it("recognises a control result rebuilt from the same public brand", () => {
+      // Project code runs against its own copy of the helpers. The brand is a
+      // registered symbol so it matches across module instances and realms.
+      const rebuilt = { notFound: true };
+      Object.defineProperty(rebuilt, Symbol.for("veryfront.dataControlResult"), { value: true });
+
+      assertEquals(isDataControlResult(rebuilt), true);
+    });
+  });
+
+  describe("returned-result contract", () => {
+    it("keeps the brand off the serialized shape", () => {
+      assertEquals(JSON.stringify(notFound()), '{"notFound":true}');
+      assertEquals(
+        JSON.stringify(redirect("/login")),
+        '{"redirect":{"destination":"/login","permanent":false}}',
+      );
+    });
+
+    it("keeps the brand off enumerable keys", () => {
+      assertEquals(Object.keys(notFound()), ["notFound"]);
+      assertEquals(Object.keys(redirect("/login")), ["redirect"]);
+    });
   });
 });

src/data/helpers.ts

@@ -1,13 +1,49 @@
 import type { DataResult } from "./types.ts";
 
-/** Return a redirect result from a data loader. */
+/**
+ * Brand marking an object as produced by {@link notFound} or {@link redirect}.
+ *
+ * A registered symbol, so a result built by one copy of this module is
+ * recognised by another. Project code and the framework do not always share a
+ * module instance, and isolated data fetching crosses a realm boundary.
+ *
+ * Symbols are dropped by `structuredClone`, so the brand does not survive
+ * `postMessage`. Worker-side code normalises a thrown control result before it
+ * is posted back, while the object is still in-realm.
+ */
+const DATA_CONTROL_RESULT = Symbol.for("veryfront.dataControlResult");
+
+/**
+ * Mark a result as framework-produced control flow.
+ *
+ * The brand is non-enumerable, so it stays out of `Object.keys`,
+ * `JSON.stringify`, and the `DataResult` schema. A returned control result
+ * behaves exactly as it did before the brand existed.
+ */
+function brandDataControlResult(result: DataResult): DataResult {
+  Object.defineProperty(result, DATA_CONTROL_RESULT, { value: true });
+  return result;
+}
+
+/**
+ * Redirect the request from a data loader.
+ *
+ * Return it or throw it. `throw redirect("/login")` behaves exactly like
+ * `return redirect("/login")`.
+ */
 export function redirect(destination: string, permanent = false): DataResult {
-  return { redirect: { destination, permanent } };
+  return brandDataControlResult({ redirect: { destination, permanent } });
 }
 
-/** Return a 404 result from a data loader. */
+/**
+ * Render the 404 page from a data loader.
+ *
+ * Return it or throw it. `throw notFound()` behaves exactly like
+ * `return notFound()`, which is useful deep inside a helper that has no clean
+ * way to return to the loader.
+ */
 export function notFound(): DataResult {
-  return { notFound: true };
+  return brandDataControlResult({ notFound: true });
 }
 
 /**
@@ -18,19 +54,19 @@ export function notFound(): DataResult {
  * naturally and is what people coming from other frameworks reach for. Thrown,
  * the plain object is not an `Error`, so the SSR error handler stringified it
  * to `[object Object]` and returned a 500 instead of the intended 404 or
- * redirect. Recognising the shape lets a thrown result behave like a returned
+ * redirect. Recognising the brand lets a thrown result behave like a returned
  * one.
+ *
+ * The check is on the brand, never on the shape. A loader that does
+ * `throw await response.json()` against an upstream answering
+ * `{ notFound: true, message: "record locked" }` is reporting a failure, and
+ * reading that as a 404 would render the wrong page, log nothing, and cache a
+ * 404 the site never asked for.
  */
 export function isDataControlResult(value: unknown): value is DataResult {
   if (value === null || typeof value !== "object") return false;
-  if (value instanceof Error) return false;
-
-  const candidate = value as { notFound?: unknown; redirect?: unknown };
-
-  if (candidate.notFound === true) return true;
 
-  const destination = (candidate.redirect as { destination?: unknown } | undefined)?.destination;
-  return typeof destination === "string";
+  return (value as Record<symbol, unknown>)[DATA_CONTROL_RESULT] === true;
 }
 
 /**

src/data/server-data-fetcher.test.ts

@@ -2,9 +2,11 @@ import "#veryfront/schemas/_test-setup.ts";
 import { assertEquals, assertExists, assertRejects } from "#veryfront/testing/assert.ts";
 import { afterEach, describe, it } from "#veryfront/testing/bdd.ts";
 import { ServerDataFetcher } from "./server-data-fetcher.ts";
-import type { DataContext, PageWithData } from "./types.ts";
+import type { DataContext, DataResult, PageWithData } from "./types.ts";
 import { notFound, redirect } from "./helpers.ts";
 import { __resetPoolForTests } from "#veryfront/security/sandbox/worker-pool.ts";
+import { runWithExactSourceIntegrationPolicy } from "#veryfront/integrations/source-policy-context.ts";
+import { join } from "node:path";
 
 describe("ServerDataFetcher", () => {
   function createContext(overrides: Partial<DataContext> = {}): DataContext {
@@ -445,6 +447,120 @@ describe("ServerDataFetcher", () => {
       }
     });
 
+    // Worker isolation is the configuration operators are told to use for
+    // untrusted project code, so the in-process path alone is not enough. A
+    // control result thrown inside the worker is a plain object, and the worker
+    // error path serialized it with String(), producing "[object Object]" and a
+    // 500 on the host.
+    describe("under worker isolation", () => {
+      let projectDir: string | null = null;
+
+      afterEach(async () => {
+        try {
+          Deno.env.delete("WORKER_ISOLATION_ENABLED");
+        } catch { /* ok */ }
+        try {
+          Deno.env.delete("WORKER_ISOLATION_DATA");
+        } catch { /* ok */ }
+        __resetPoolForTests();
+
+        if (projectDir) {
+          await Deno.remove(projectDir, { recursive: true }).catch(() => {});
+          projectDir = null;
+        }
+      });
+
+      async function writeIsolatedPage(source: string): Promise<
+        { modulePath: string; projectDir: string }
+      > {
+        const dir = await Deno.realPath(await Deno.makeTempDir({ prefix: "vf-isolated-data-" }));
+        projectDir = dir;
+        const modulePath = join(dir, "page.ts");
+        await Deno.writeTextFile(modulePath, source);
+
+        Deno.env.set("WORKER_ISOLATION_ENABLED", "1");
+        Deno.env.set("WORKER_ISOLATION_DATA", "1");
+        __resetPoolForTests();
+
+        return { modulePath, projectDir: dir };
+      }
+
+      // The worker cannot import the framework helpers: its read permission is
+      // scoped to the project directory. `notFound()` brands its result with a
+      // registered symbol precisely so a result built anywhere is recognised
+      // everywhere, so the fixture rebuilds the same public brand.
+      const BRAND_SOURCE =
+        `Object.defineProperty(result, Symbol.for("veryfront.dataControlResult"), { value: true });`;
+
+      function isolatedFetch(
+        modulePath: string,
+        dir: string,
+      ): Promise<DataResult> {
+        const fetcher = new ServerDataFetcher();
+        const pageModule: PageWithData = {
+          default: () => null,
+          getServerData: () => ({ props: {} }),
+        };
+
+        return runWithExactSourceIntegrationPolicy(
+          { schemaVersion: 1, mode: "unrestricted" },
+          () =>
+            fetcher.fetch(pageModule, createContext(), {
+              modulePath,
+              projectDir: dir,
+            }),
+        );
+      }
+
+      it("treats a thrown notFound() as a 404 result", async () => {
+        const { modulePath, projectDir: dir } = await writeIsolatedPage(
+          `export function getServerData() {
+             const result = { notFound: true };
+             ${BRAND_SOURCE}
+             throw result;
+           }
+           export default function Page() { return null; }`,
+        );
+
+        const result = await isolatedFetch(modulePath, dir);
+
+        assertEquals(result.notFound, true);
+        assertEquals(result.redirect, undefined);
+      });
+
+      it("treats a thrown redirect() as a redirect result", async () => {
+        const { modulePath, projectDir: dir } = await writeIsolatedPage(
+          `export function getServerData() {
+             const result = { redirect: { destination: "/login", permanent: true } };
+             ${BRAND_SOURCE}
+             throw result;
+           }
+           export default function Page() { return null; }`,
+        );
+
+        const result = await isolatedFetch(modulePath, dir);
+
+        assertEquals(result.redirect?.destination, "/login");
+        assertEquals(result.redirect?.permanent, true);
+        assertEquals(result.notFound, undefined);
+      });
+
+      it("still propagates a genuine Error thrown in the worker", async () => {
+        const { modulePath, projectDir: dir } = await writeIsolatedPage(
+          `export function getServerData() {
+             throw new Error("intentional test error from isolated getServerData");
+           }
+           export default function Page() { return null; }`,
+        );
+
+        await assertRejects(
+          () => isolatedFetch(modulePath, dir),
+          Error,
+          "intentional test error from isolated getServerData",
+        );
+      });
+    });
+
     it("still opens the circuit breaker on repeated genuine errors", async () => {
       const fetcher = new ServerDataFetcher();
       const context = createContext({