@pylonsync/functions 0.3.259 → 0.3.262

package/package.json

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

package/src/runtime-db.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Regression tests for the ctx.db builder surfaces (runtime.ts).
+ *
+ * Guards the contract the types now promise (types.ts made `unsafe`
+ * REQUIRED on the top-level db and absent on the unsafe surface):
+ *
+ *   1. `db.unsafe` always exists, with the full op surface.
+ *   2. `db.unsafe.unsafe` does NOT exist (no chaining — it would be a
+ *      runtime undefined that the old optional type silently allowed).
+ *   3. Plain ops emit `unsafe_op: false`; `unsafe.*` ops emit
+ *      `unsafe_op: true` — the flag the Rust policy gate keys on.
+ *
+ * runtime.ts runs main() on import (it IS the bun runner entrypoint),
+ * so the builders are exercised in a child process: we feed it a
+ * script over a kept-open stdin pipe and read the NDJSON protocol
+ * frames it writes to stdout.
+ */
+import { expect, test } from "bun:test";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+const SCRIPT = `
+import { buildDbReader, buildDbWriter } from ${JSON.stringify(RUNTIME)};
+
+const reader = buildDbReader("c_r");
+const writer = buildDbWriter("c_w");
+
+// Structural facts ride stderr (fenceStdout reserves stdout for frames).
+console.error("STRUCT " + JSON.stringify({
+  readerUnsafe: typeof reader.unsafe.get === "function",
+  writerUnsafeWrites: typeof (writer.unsafe as any).update === "function",
+  noReaderChain: (reader.unsafe as any).unsafe === undefined,
+  noWriterChain: (writer.unsafe as any).unsafe === undefined,
+}));
+
+// Fire one op per surface — no host replies, so don't await; the
+// emitted frames on stdout are the assertion target.
+reader.get("Todo", "r1").catch(() => {});
+reader.unsafe.get("Todo", "r2").catch(() => {});
+writer.update("Todo", "w1", { a: 1 }).catch(() => {});
+writer.unsafe.update("Todo", "w2", { a: 2 }).catch(() => {});
+
+setTimeout(() => process.exit(0), 300);
+`;
+
+test("db builders: required unsafe surface, no chaining, unsafe_op flag routing", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-db-"));
+  const scriptPath = join(dir, "probe.ts");
+  writeFileSync(scriptPath, SCRIPT);
+
+  const proc = Bun.spawn(["bun", scriptPath], {
+    stdin: "pipe", // keep main()'s readerLoop alive until the probe exits itself
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  // 1+2: structure as reported from inside the child.
+  const structLine = stderr.split("\n").find((l) => l.includes("STRUCT "));
+  expect(structLine).toBeDefined();
+  const struct = JSON.parse(structLine!.slice(structLine!.indexOf("STRUCT ") + 7));
+  expect(struct.readerUnsafe).toBe(true);
+  expect(struct.writerUnsafeWrites).toBe(true);
+  expect(struct.noReaderChain).toBe(true);
+  expect(struct.noWriterChain).toBe(true);
+
+  // 3: every emitted db frame carries the right unsafe_op flag.
+  const frames = stdout
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>)
+    .filter((f) => f.type === "db");
+  const byId = (id: string) => frames.find((f) => f.id === id);
+
+  expect(byId("r1")).toMatchObject({ op: "get", unsafe_op: false });
+  expect(byId("r2")).toMatchObject({ op: "get", unsafe_op: true });
+  expect(byId("w1")).toMatchObject({ op: "update", unsafe_op: false });
+  expect(byId("w2")).toMatchObject({ op: "update", unsafe_op: true });
+});

package/src/runtime.ts

@@ -357,7 +357,11 @@ function rpc(callId: string, msg: Record<string, unknown>): Promise<unknown> {
 // `serverData` read handle that reuses this module's `send` + `pendingRpcs`
 // + reader loop. The render call_id ("r_<n>") correlates DB replies back
 // through the shared pendingRpcs map.
-export function buildDbReader(callId: string, unsafeOp = false): DbReader {
+export function buildDbReader(callId: string): DbReader {
+  return { ...buildReaderOps(callId, false), unsafe: buildReaderOps(callId, true) };
+}
+
+function buildReaderOps(callId: string, unsafeOp: boolean): Omit<DbReader, "unsafe"> {
   // All DB ops use rpcDb so Promise.all over ctx.db reads can run in
   // parallel without colliding on the outer call_id key.
   //
@@ -366,7 +370,7 @@ export function buildDbReader(callId: string, unsafeOp = false): DbReader {
   // caller-aware policy gate (in Phase 2 — see
   // pylon-functions/protocol.rs). Plain ctx.db.* leaves the flag
   // off (the safe default); ctx.db.unsafe.* sets it.
-  const reader: DbReader = {
+  return {
     async get(entity, id) {
       return (await rpcDb(callId, {
         type: "db",
@@ -435,23 +439,26 @@ export function buildDbReader(callId: string, unsafeOp = false): DbReader {
       })) as any;
     },
   };
-  if (!unsafeOp) {
-    (reader as DbReader & { unsafe: DbReader }).unsafe = buildDbReader(
-      callId,
-      true,
-    );
-  }
-  return reader;
 }
 
-export function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
-  // Drop the reader's `unsafe` shortcut before spreading — the
-  // writer needs its own (which we attach below). Without this
-  // strip, `writer.unsafe` would be a DbReader and the type
-  // narrows incorrectly.
-  const { unsafe: _ignored, ...readerOps } = buildDbReader(callId, unsafeOp);
-  const writer: DbWriter = {
-    ...readerOps,
+export function buildDbWriter(callId: string): DbWriter {
+  // Top-level `ctx.db` is the safe path. `ctx.db.unsafe` is the
+  // escape hatch — same surface, every emitted op carries
+  // `unsafe_op: true` so the future caller-aware policy gate
+  // (PYLON_STRICT_FN_POLICIES) skips enforcement. Use sparingly,
+  // with a justifying comment, ideally in code that runs only
+  // from server-internal callers (webhooks, cron sweeps, admin
+  // tools).
+  //
+  // The unsafe surface carries no `.unsafe` of its own — chaining
+  // is a compile error AND a self-reference would loop on JSON
+  // serialization.
+  return { ...buildWriterOps(callId, false), unsafe: buildWriterOps(callId, true) };
+}
+
+function buildWriterOps(callId: string, unsafeOp: boolean): Omit<DbWriter, "unsafe"> {
+  return {
+    ...buildReaderOps(callId, unsafeOp),
     async insert(entity, data) {
       const r = (await rpcDb(callId, {
         type: "db",
@@ -518,23 +525,6 @@ export function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
       });
     },
   };
-  // Top-level `ctx.db` is the safe path. `ctx.db.unsafe` is the
-  // escape hatch — same surface, every emitted op carries
-  // `unsafe_op: true` so the future caller-aware policy gate
-  // (PYLON_STRICT_FN_POLICIES) skips enforcement. Use sparingly,
-  // with a justifying comment, ideally in code that runs only
-  // from server-internal callers (webhooks, cron sweeps, admin
-  // tools).
-  //
-  // Self-reference would create an infinite loop on JSON
-  // serialization; only assign on the writer's `.unsafe` once.
-  if (!unsafeOp) {
-    (writer as DbWriter & { unsafe: DbWriter }).unsafe = buildDbWriter(
-      callId,
-      true,
-    );
-  }
-  return writer;
 }
 
 function buildStream(callId: string): Stream {
@@ -942,12 +932,12 @@ async function main() {
       (f) => f.endsWith(".ts") || f.endsWith(".js")
     );
   } catch {
-    send({
-      type: "ready",
-      functions: [],
-      error: `Cannot read functions directory: ${fnDir}`,
-    });
-    return;
+    // No `functions/` directory. Legitimate for a pure-SSR app (file-based
+    // `app/**/page.tsx` routes + entity CRUD, no server functions) — the host
+    // still spawns this runner to execute SSR renders. Load zero functions and
+    // fall through so we send `ready` AND start the reader loop; returning here
+    // would leave the runner unable to serve renders (silent 404s).
+    files = [];
   }
 
   for (const file of files) {
@@ -989,7 +979,23 @@ async function main() {
   }));
   send({ type: "ready", functions });
 
+  // Belt-and-suspenders against orphaning: if the host dies in a way that
+  // somehow leaves our stdin open, we'll have been reparented to init
+  // (ppid === 1). Notice and exit. Unref'd so it never keeps us alive on its
+  // own.
+  const orphanWatch = setInterval(() => {
+    if (process.ppid === 1) process.exit(0);
+  }, 2000);
+  if (typeof orphanWatch.unref === "function") orphanWatch.unref();
+
   await readerLoop();
+
+  // readerLoop only returns when stdin hits EOF — i.e. the host (the pylon
+  // process that spawned us) is gone. Force-exit. We must NOT rely on the
+  // event loop draining on its own: the stdout writer, keep-alive sockets
+  // from `fetch`, and Bun's own handles keep the process alive, so every
+  // killed `pylon dev` would otherwise orphan its whole bun runner pool.
+  process.exit(0);
 }
 
 main().catch((err) => {

package/src/ssr-client-bundler.ts

@@ -290,6 +290,15 @@ function makeNoopResponse() {
 // For a hydrated error boundary (#279), synthesize the reset() the server
 // rendered as a no-op: re-fetch + re-render the current URL (a transient
 // error clears to the page; a deterministic one re-shows the boundary).
+// The current route's dynamic params (e.g. { projectId: "p_1" }). Lives here,
+// not in the DOM __PYLON_DATA__ (which navigate() never rewrites), so useParams()
+// in a deep client child has a reactive source. A fresh object per nav → stable
+// reference between navs (useSyncExternalStore needs that).
+let currentParams = {};
+function setNavParams(data) {
+  currentParams = (data && data.props && data.props.params) || {};
+}
+
 function withClientProps(data) {
   const props = { ...(data.props || {}) };
   props.serverData = makeClientServerData(data.ssrData);
@@ -396,6 +405,7 @@ export function hydrate(component, Page, Layouts) {
       );
       return;
     }
+    setNavParams(data);
     const tree = buildTree(Page, Layouts, withClientProps(data));
     activeRoot = hydrateRoot(document, tree);
     installNavHandlers();
@@ -472,6 +482,7 @@ async function navigate(href, opts) {
   }
   document.title = doc.title || document.title;
   syncHeadMeta(doc);
+  setNavParams(data);
   const tree = buildTree(route.Page, route.Layouts, withClientProps(data));
   activeRoot.render(tree);
   const target = url.pathname + url.search;
@@ -559,7 +570,14 @@ function installNavHandlers() {
 }
 
 // Expose for <Link> component prefetch.
-const pylonGlobal = { prefetch, navigate };
+const pylonGlobal = {
+  prefetch,
+  navigate,
+  // Read by useParams(); a getter so it always reflects the latest nav.
+  get params() {
+    return currentParams;
+  },
+};
 if (typeof window !== "undefined") {
   window.__pylon = pylonGlobal;
 }

package/src/ssr-runtime.test.ts

@@ -11,6 +11,8 @@ import {
   buildHydrationTail,
   errorDigest,
   resolveOrigin,
+  asRouteControl,
+  PylonRouteControl,
 } from "./ssr-runtime";
 
 describe("resolveOrigin — Host-header allowlist (cache-poisoning fence)", () => {
@@ -391,3 +393,41 @@ describe("buildHydrationTail — boundary hydration (#279) + strip (#270)", () =
     expect(errorDigest(new Error("other"))).not.toBe(d1);
   });
 });
+
+describe("asRouteControl — route-control normalization (redirect/notFound)", () => {
+  test("passes the framework's own PylonRouteControl straight through", () => {
+    const redirect = new PylonRouteControl("redirect");
+    redirect.url = "/login";
+    redirect.redirectStatus = 302;
+    expect(asRouteControl(redirect)).toBe(redirect);
+
+    const nf = new PylonRouteControl("notFound");
+    expect(asRouteControl(nf)).toBe(nf);
+  });
+
+  test("recognizes @pylonsync/react's branded notFound() error by digest", () => {
+    // The cross-package contract: `notFound()` from @pylonsync/react throws an
+    // error stamped `digest === "PYLON_NOT_FOUND"`. The runtime duck-types on
+    // that brand (no import of the React class) and turns it into a notFound
+    // control → a real 404 + nearest not-found.tsx. If this regresses, a
+    // server page calling notFound() would 500 instead of 404.
+    const reactNotFound = Object.assign(new Error("PYLON_NOT_FOUND"), {
+      digest: "PYLON_NOT_FOUND",
+    });
+    const ctrl = asRouteControl(reactNotFound);
+    expect(ctrl).not.toBeNull();
+    expect(ctrl?.kind).toBe("notFound");
+  });
+
+  test("does NOT swallow ordinary errors as a 404 (fails open is forbidden)", () => {
+    // The critical safety property: a real render error must fall through to
+    // the error.tsx / 500 path, never be silently masked as a not-found.
+    expect(asRouteControl(new Error("boom"))).toBeNull();
+    expect(asRouteControl(new TypeError("nope"))).toBeNull();
+    expect(asRouteControl({ digest: "SOME_OTHER_DIGEST" })).toBeNull();
+    expect(asRouteControl({ digest: 42 })).toBeNull();
+    expect(asRouteControl(null)).toBeNull();
+    expect(asRouteControl(undefined)).toBeNull();
+    expect(asRouteControl("PYLON_NOT_FOUND")).toBeNull(); // a bare string, not an error
+  });
+});

package/src/ssr-runtime.ts

@@ -99,6 +99,34 @@ export class PylonRouteControl extends Error {
   }
 }
 
+/**
+ * Digest brand that `@pylonsync/react`'s `notFound()` stamps on the error it
+ * throws. We recognize it here by string instead of importing the class so the
+ * runtime stays decoupled from the React package (which doesn't depend on
+ * functions). Keep in sync with `NotFoundError.digest` in
+ * `packages/react/src/useRouter.ts`.
+ */
+const REACT_NOT_FOUND_DIGEST = "PYLON_NOT_FOUND";
+
+/**
+ * Normalize a thrown value into a route-control signal: either the framework's
+ * own `PylonRouteControl` (`response.redirect()` / `response.notFound()`) or a
+ * branded `NotFoundError` thrown by `@pylonsync/react`'s `notFound()` from a
+ * page/layout render. Returns `null` for an ordinary error so the caller falls
+ * through to its real error-handling path.
+ */
+export function asRouteControl(err: unknown): PylonRouteControl | null {
+  if (err instanceof PylonRouteControl) return err;
+  if (
+    err != null &&
+    typeof err === "object" &&
+    (err as { digest?: unknown }).digest === REACT_NOT_FOUND_DIGEST
+  ) {
+    return new PylonRouteControl("notFound");
+  }
+  return null;
+}
+
 export interface SsrCookieOptions {
   path?: string;
   domain?: string;
@@ -1481,7 +1509,8 @@ export async function handleRenderRoute(
           // (partial HTML); the dev overlay (#275) only covers failures BEFORE
           // response_start (host-side err channel). Buffered renders surface
           // their error through the catch/boundary path below.
-          if (err instanceof PylonRouteControl) {
+          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
@@ -1489,9 +1518,10 @@ export async function handleRenderRoute(
             // synchronous shell). Surface it loudly instead of silently losing.
             // eslint-disable-next-line no-console
             console.error(
-              `[ssr] response.${err.kind}() called below a <Suspense> boundary was ignored — ` +
-                `the HTTP head was already sent. Call response.redirect()/notFound() in the ` +
-                `synchronous shell render, before any await/<Suspense>.`,
+              `[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;
           }
@@ -1736,16 +1766,20 @@ export async function handleRenderRoute(
 
     send({ type: "render_done", call_id: msg.call_id });
   } catch (err: any) {
-    // A page/layout called response.redirect() or response.notFound()
-    // during render → short-circuit to a 3xx + Location or a 404 instead
-    // of a body. Page-set cookies/headers still ride along.
-    if (err instanceof PylonRouteControl) {
-      if (err.kind === "redirect") {
+    // A page/layout called response.redirect()/response.notFound(), or
+    // `notFound()` from @pylonsync/react, during render → short-circuit to a
+    // 3xx + Location or a 404 instead of a body. Page-set cookies/headers
+    // still ride along.
+    const ctrl = asRouteControl(err);
+    if (ctrl) {
+      if (ctrl.kind === "redirect") {
         send({
           type: "response_start",
           call_id: msg.call_id,
-          status: err.redirectStatus ?? 307,
-          headers: finalizeHeaders(responseState, { location: err.url ?? "/" }),
+          status: ctrl.redirectStatus ?? 307,
+          headers: finalizeHeaders(responseState, {
+            location: ctrl.url ?? "/",
+          }),
         });
         send({ type: "render_done", call_id: msg.call_id });
         return;

package/src/types.ts

@@ -99,10 +99,11 @@ export interface DbReader {
    * convention. A future `pylon lint` rule will flag bare
    * `ctx.db.unsafe.*` without a comment immediately above.
    *
-   * Optional on the type because old Pylon runtimes don't ship
-   * it; new code that targets v0.3.161+ can rely on the field.
+   * Required on the type (every runtime since v0.3.161 ships it) —
+   * but absent on the unsafe surface itself, so `ctx.db.unsafe.unsafe`
+   * is a compile error rather than a runtime undefined.
    */
-  unsafe?: DbReader;
+  unsafe: Omit<DbReader, "unsafe">;
 
   /** Get a single row by ID. Returns null if not found. */
   get(entity: string, id: string): Promise<Record<string, unknown> | null>;
@@ -201,7 +202,7 @@ export interface DbWriter extends DbReader {
    * write surface (insert/update/delete/link/unlink/advisoryLock).
    * Overrides the inherited read-only `unsafe` from DbReader.
    */
-  unsafe?: DbWriter;
+  unsafe: Omit<DbWriter, "unsafe">;
 
   /** Insert a new row. Returns the generated ID. */
   insert(entity: string, data: Record<string, unknown>): Promise<string>;