@pylonsync/functions 0.3.248 → 0.3.249

package/package.json

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

package/src/runtime.ts

@@ -236,6 +236,24 @@ function dispatch(line: string): void {
             String(err),
         });
       });
+  } else if (msg.type === "handle_form") {
+    // route.ts form/method handler (#276) — lazy-imported like SSR so
+    // projects without route handlers pay nothing on startup.
+    import("./ssr-form-runtime")
+      .then((mod) =>
+        mod.handleForm(
+          msg as unknown as Parameters<typeof mod.handleForm>[0],
+          send,
+        ),
+      )
+      .catch((err) => {
+        send({
+          type: "error",
+          call_id: (msg as unknown as { call_id: string }).call_id,
+          code: "SSR_FORM_RUNTIME_CRASH",
+          message: err?.message || String(err),
+        });
+      });
   } else if (msg.type === "bundle_client") {
     // Hydration — build the client-side bundle once and report
     // the path back. Lazy-imported for the same reason as SSR.
@@ -426,7 +444,7 @@ export function buildDbReader(callId: string, unsafeOp = false): DbReader {
   return reader;
 }
 
-function buildDbWriter(callId: string, unsafeOp = false): DbWriter {
+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

package/src/ssr-client-bundler.ts

@@ -510,6 +510,52 @@ function installNavHandlers() {
   window.addEventListener("popstate", () => {
     navigate(location.pathname + location.search, { push: false });
   });
+  // Progressive-enhancement form submit (#276): intercept <form data-pylon-form>
+  // so the page doesn't full-reload. fetch the same route.ts endpoint, follow
+  // the handler's redirect, and swap the destination in via navigate(). Without
+  // JS this listener never runs and the browser submits natively (POST →
+  // handler → 303 → GET) — identical result, just a full navigation.
+  document.addEventListener("submit", (e) => {
+    if (e.defaultPrevented) return;
+    const form = e.target;
+    if (!form || form.tagName !== "FORM") return;
+    if (!form.hasAttribute("data-pylon-form")) return;
+    const action = form.getAttribute("action");
+    if (!action) return;
+    // Off-origin actions / new-tab targets → let the browser submit.
+    if (action.startsWith("http://") || action.startsWith("https://") || action.startsWith("//")) return;
+    const tgt = form.getAttribute("target");
+    if (tgt && tgt !== "" && tgt !== "_self") return;
+    const method = (form.getAttribute("method") || "post").toUpperCase();
+    e.preventDefault();
+    // urlencoded body (matches the server's parser; files use the native path).
+    const body = new URLSearchParams();
+    const fd = new FormData(form);
+    fd.forEach((v, k) => {
+      if (typeof v === "string") body.append(k, v);
+    });
+    fetch(action, {
+      method,
+      body,
+      credentials: "same-origin",
+      headers: { Accept: "text/html" },
+    })
+      .then((res) => {
+        // fetch followed the handler's 303 → res.url is the destination page.
+        // Drive a client navigation to it (re-renders without a full reload).
+        const dest = new URL(res.url || action, location.href);
+        if (dest.origin === location.origin) {
+          navigate(dest.pathname + dest.search);
+        } else {
+          window.location.href = dest.href;
+        }
+      })
+      .catch(() => {
+        // Network/abort — fall back to a native submit so the user isn't stuck.
+        form.removeAttribute("data-pylon-form");
+        form.submit();
+      });
+  });
 }
 
 // Expose for <Link> component prefetch.

package/src/ssr-form-runtime.ts

@@ -0,0 +1,188 @@
+// route.ts form/method handler runtime (#276). Invoked by runtime.ts when the
+// host sends a "handle_form" message. Imports the route.ts module, picks the
+// handler by HTTP method, runs it with the parsed form + a read/write `db` +
+// the SsrResponse controller, and replies over the SAME response_start /
+// render_done protocol a render uses. A handler's common job is
+// POST-redirect-GET: write something, then `response.redirect("/x?ok=1")`
+// (303 by default here) so the no-JS browser follows with a GET.
+import {
+  makeResponseController,
+  PylonRouteControl,
+  finalizeHeaders,
+  importModule,
+  type ResponseState,
+} from "./ssr-runtime";
+import { buildDbWriter } from "./runtime";
+
+/** Matches HandleFormMessage in crates/functions/src/protocol.rs. */
+export interface HandleFormMessage {
+  type: "handle_form";
+  call_id: string;
+  component: string;
+  route_path: string;
+  method: string;
+  url: string;
+  params: Record<string, string>;
+  search_params: Record<string, string>;
+  form: Record<string, string | string[]>;
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  auth: {
+    user_id: string | null;
+    is_admin: boolean;
+    tenant_id: string | null;
+    roles: string[];
+  };
+}
+
+type Send = (msg: Record<string, unknown>) => void;
+
+/** Parsed form fields. Mirrors URLSearchParams get/getAll/has semantics. */
+export interface FormFields {
+  /** First value for `name`, or null. */
+  get(name: string): string | null;
+  /** All values for `name` (empty array if none). */
+  getAll(name: string): string[];
+  has(name: string): boolean;
+  /** Raw map: name → value | values. */
+  readonly fields: Record<string, string | string[]>;
+}
+
+function makeFormFields(raw: Record<string, string | string[]>): FormFields {
+  return {
+    get(name) {
+      const v = raw[name];
+      if (v == null) return null;
+      return Array.isArray(v) ? (v.length > 0 ? v[0] : null) : v;
+    },
+    getAll(name) {
+      const v = raw[name];
+      if (v == null) return [];
+      return Array.isArray(v) ? v : [v];
+    },
+    has(name) {
+      return Object.prototype.hasOwnProperty.call(raw, name);
+    },
+    fields: raw,
+  };
+}
+
+const HANDLER_METHODS = ["POST", "PUT", "PATCH", "DELETE"] as const;
+const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64");
+const isDev = () =>
+  process.env.PYLON_DEV_MODE === "1" || process.env.PYLON_DEV_MODE === "true";
+
+export async function handleForm(
+  msg: HandleFormMessage,
+  send: Send,
+): Promise<void> {
+  const cwd = process.cwd();
+  // Default 303 See Other — the correct POST-redirect-GET status for a form
+  // (307 would re-issue the POST to the redirect target).
+  const responseState: ResponseState = { status: 303, headers: {}, cookies: [] };
+  const response = makeResponseController(responseState, 303);
+  const req = {
+    form: makeFormFields(msg.form ?? {}),
+    params: msg.params,
+    searchParams: msg.search_params,
+    auth: msg.auth,
+    cookies: msg.cookies,
+    headers: msg.headers,
+    // Read+write DB handle (mutation-shaped; the host answers writes against a
+    // broadcast-capable store). serverData (read-only) isn't given — a handler
+    // writes via `db` and the developer enforces trust with `req.auth`.
+    db: buildDbWriter(msg.call_id),
+    response,
+  };
+
+  let mod: any;
+  try {
+    mod = await importModule(cwd, msg.component);
+  } catch (e: any) {
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: "SSR_FORM_IMPORT_FAILED",
+      message: isDev() && e?.stack ? String(e.stack) : e?.message ?? String(e),
+    });
+    return;
+  }
+
+  const method = (msg.method || "POST").toUpperCase();
+  const handler = mod[method];
+  if (typeof handler !== "function") {
+    // 405 — advertise the methods this route.ts actually exports.
+    const allow = HANDLER_METHODS.filter(
+      (m) => typeof mod[m] === "function",
+    ).join(", ");
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status: 405,
+      headers: {
+        "content-type": "text/plain; charset=utf-8",
+        ...(allow ? { allow } : {}),
+      },
+    });
+    send({
+      type: "render_chunk",
+      call_id: msg.call_id,
+      data: b64(`Method ${method} not allowed`),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+    return;
+  }
+
+  try {
+    await handler(req);
+    // No redirect()/notFound() thrown → commit the handler's response: its
+    // status (default 303) + headers + cookies. A 303 with no explicit
+    // Location redirects back to the route path (POST-redirect-GET).
+    const extra: Record<string, string> = {};
+    if (responseState.status === 303 && !responseState.headers["location"]) {
+      extra["location"] = msg.route_path || "/";
+    }
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status: responseState.status,
+      headers: finalizeHeaders(responseState, extra),
+    });
+    send({ type: "render_done", call_id: msg.call_id });
+  } catch (err: any) {
+    // response.redirect()/notFound() throw PylonRouteControl — turn into a
+    // 3xx + Location / 404, carrying any cookies the handler set first.
+    if (err instanceof PylonRouteControl) {
+      if (err.kind === "redirect") {
+        send({
+          type: "response_start",
+          call_id: msg.call_id,
+          status: err.redirectStatus ?? 303,
+          headers: finalizeHeaders(responseState, { location: err.url ?? "/" }),
+        });
+        send({ type: "render_done", call_id: msg.call_id });
+        return;
+      }
+      send({
+        type: "response_start",
+        call_id: msg.call_id,
+        status: 404,
+        headers: finalizeHeaders(responseState),
+      });
+      send({
+        type: "render_chunk",
+        call_id: msg.call_id,
+        data: b64("Not found"),
+      });
+      send({ type: "render_done", call_id: msg.call_id });
+      return;
+    }
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: err?.code ?? "SSR_FORM_FAILED",
+      message:
+        isDev() && err?.stack ? String(err.stack) : err?.message ?? String(err),
+    });
+  }
+}

package/src/ssr-runtime.ts

@@ -75,7 +75,7 @@ type Send = (msg: Record<string, unknown>) => void;
  * it's thrown during the shell render. (Throw it OUTSIDE an error
  * boundary — an enclosing boundary would swallow the signal.)
  */
-class PylonRouteControl extends Error {
+export class PylonRouteControl extends Error {
   kind: "redirect" | "notFound";
   url?: string;
   redirectStatus?: number;
@@ -146,7 +146,7 @@ function serializeCookie(
   return c;
 }
 
-interface ResponseState {
+export interface ResponseState {
   status: number;
   headers: Record<string, string>;
   cookies: string[];
@@ -184,7 +184,14 @@ export interface SsrResponse {
   notFound(): never;
 }
 
-function makeResponseController(state: ResponseState): SsrResponse {
+// `defaultRedirectStatus` is the status `response.redirect(url)` uses when the
+// caller doesn't pass one: 307 for a page render (preserve the method on the
+// rare redirecting GET), 303 for a route.ts form handler (POST-redirect-GET —
+// the browser must follow with a GET, not re-POST).
+export function makeResponseController(
+  state: ResponseState,
+  defaultRedirectStatus = 307,
+): SsrResponse {
   return {
     setStatus(code) {
       if (!Number.isInteger(code) || code < 100 || code > 599) {
@@ -204,7 +211,7 @@ function makeResponseController(state: ResponseState): SsrResponse {
     setCookie(name, value, opts) {
       state.cookies.push(serializeCookie(name, value, opts));
     },
-    redirect(url, status = 307): never {
+    redirect(url, status = defaultRedirectStatus): never {
       assertNoControlChars(url, "redirect url");
       if (!Number.isInteger(status) || status < 300 || status > 399) {
         throw new Error(`pylon ssr: redirect() status must be 3xx, got ${status}`);
@@ -226,7 +233,7 @@ function makeResponseController(state: ResponseState): SsrResponse {
  * into one `Set-Cookie` header each (newline is forbidden inside a
  * cookie, so it can't be turned into header injection).
  */
-function finalizeHeaders(
+export function finalizeHeaders(
   state: ResponseState,
   extra?: Record<string, string>,
 ): Record<string, string> {
@@ -373,7 +380,7 @@ export function renderMetadata(React: any, m: SsrMetadata | undefined): any {
 const MODULE_EXTS = [".tsx", ".ts", ".jsx", ".js"];
 
 /** Import a project-relative module, trying each common extension. */
-async function importModule(cwd: string, relPath: string): Promise<any> {
+export async function importModule(cwd: string, relPath: string): Promise<any> {
   const base = `${cwd}/${relPath}`;
   let lastErr: unknown = null;
   for (const ext of MODULE_EXTS) {
@@ -1221,13 +1228,28 @@ export async function handleRenderRoute(
       ssrValueCache,
     );
 
+    // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
+    // if its output is auth-INDEPENDENT — so wrap props.auth in a Proxy that
+    // flips `authTouched` the moment a page/layout reads it. Reading auth at
+    // all (even for an anonymous request) opts the render OUT of caching,
+    // because the output could differ by identity. The raw auth is restored
+    // before serialization (so the hydration blob carries real values, and so
+    // JSON.stringify doesn't trip the Proxy itself).
+    let authTouched = false;
+    const authProxy = new Proxy(msg.auth as Record<string, unknown>, {
+      get(target, prop, receiver) {
+        authTouched = true;
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
     props = {
       url: msg.url,
       params: msg.params,
       searchParams: msg.search_params,
       headers: msg.headers,
       cookies: msg.cookies,
-      auth: msg.auth,
+      auth: authProxy,
       // Response controller — a page/layout calls response.setStatus /
       // setHeader / setCookie / redirect / notFound to shape the reply.
       response,
@@ -1338,11 +1360,45 @@ export async function handleRenderRoute(
     // The shell rendered without a redirect()/notFound() throw, so the
     // page's chosen status (default 200) + headers + cookies go out now,
     // before the first body byte.
+    //
+    // #277 cache verdict (Stage 1, buffered path only — a streaming render
+    // commits its head before the body resolves, so `authTouched` isn't final
+    // yet). A render is shareable (CDN-cacheable via `public, s-maxage`) ONLY
+    // when ALL hold: it opted in (`export const revalidate` / `dynamic:
+    // "force-static"`), never read props.auth (authTouched), set no cookie,
+    // isn't `force-dynamic`, and per-caller strict policies are OFF — in strict
+    // mode serverData reads are auth-filtered, so the output isn't shareable.
+    // We emit an INTERNAL `x-pylon-cacheable` header the host turns into a
+    // public Cache-Control and STRIPS; its ABSENCE is the fail-closed default
+    // (the host keeps no-cache / no-store). The 200-only guard avoids caching
+    // an error/redirect.
+    const revalidateSecs =
+      typeof (mod as any).revalidate === "number" && (mod as any).revalidate > 0
+        ? Math.floor((mod as any).revalidate)
+        : (mod as any).dynamic === "force-static"
+          ? 31536000 // a year — only a deploy invalidates a force-static page
+          : null;
+    const forceDynamic = (mod as any).dynamic === "force-dynamic";
+    const strictPolicies = process.env.PYLON_STRICT_FN_POLICIES === "1";
+    const cacheable =
+      revalidateSecs != null &&
+      !forceDynamic &&
+      !authTouched &&
+      responseState.cookies.length === 0 &&
+      !strictPolicies &&
+      !Loading &&
+      responseState.status === 200;
+    // Restore the raw auth before any serialization below (the Proxy was only
+    // for the render-time auth-touch probe).
+    if (props) props.auth = msg.auth;
     send({
       type: "response_start",
       call_id: msg.call_id,
       status: responseState.status,
-      headers: finalizeHeaders(responseState),
+      headers: finalizeHeaders(
+        responseState,
+        cacheable ? { "x-pylon-cacheable": String(revalidateSecs) } : {},
+      ),
     });
 
     // Pre-load the manifest BEFORE the React stream starts emitting