@pylonsync/functions 0.3.218 → 0.3.222

package/package.json

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

package/src/runtime.ts

@@ -210,6 +210,26 @@ function dispatch(line: string): void {
         message: err?.message || String(err),
       });
     });
+  } else if (msg.type === "render_route") {
+    // SSR dispatch — file-based page render. Lazy-imported so
+    // projects without SSR routes don't pay the react-dom cost on
+    // startup. handleRenderRoute manages its own error frames; we
+    // still catch here so a bare throw can't kill the runtime.
+    import("./ssr-runtime")
+      .then((mod) =>
+        mod.handleRenderRoute(
+          msg as unknown as Parameters<typeof mod.handleRenderRoute>[0],
+          send,
+        ),
+      )
+      .catch((err) => {
+        send({
+          type: "error",
+          call_id: (msg as unknown as { call_id: string }).call_id,
+          code: "SSR_RUNTIME_CRASH",
+          message: err?.message || String(err),
+        });
+      });
   } else if (msg.type === "result") {
     const res = msg as unknown as ResultMessage & { op_id?: string };
     // Prefer op_id when the host sent it. Fall back to call_id for replies

package/src/ssr-runtime.ts

@@ -0,0 +1,184 @@
+// SSR handler — invoked by runtime.ts when the host sends a
+// "render_route" message. Dynamically imports the page module, calls
+// react-dom/server.renderToReadableStream, base64-encodes chunks back
+// over the NDJSON pipe.
+//
+// The whole module is loaded lazily (handleRenderRoute is awaited from
+// the dispatch arm) so projects without SSR routes pay nothing — no
+// react-dom dependency requirement, no startup cost.
+
+/**
+ * The message payload the host sends. Matches RenderRouteMessage in
+ * crates/functions/src/protocol.rs.
+ */
+export interface RenderRouteMessage {
+  type: "render_route";
+  call_id: string;
+  /**
+   * Project-relative module path (e.g. "app/hello/page"). The
+   * adapter joins cwd + this + the right extension (.tsx → .ts).
+   */
+  component: string;
+  /** The matched route pattern (e.g. `/blog/:slug`). */
+  route_path: string;
+  /** The incoming URL path (e.g. `/blog/hello-world`). */
+  url: string;
+  /** Dynamic-segment matches keyed by name (e.g. `{slug: "hello-world"}`). */
+  params: Record<string, string>;
+  /** Parsed query string. */
+  search_params: Record<string, string>;
+  /** Lowercased header names → values. */
+  headers: Record<string, string>;
+  /** Parsed cookies. */
+  cookies: Record<string, string>;
+  /** Pylon auth context. */
+  auth: {
+    user_id: string | null;
+    is_admin: boolean;
+    tenant_id: string | null;
+    roles: string[];
+  };
+}
+
+type Send = (msg: Record<string, unknown>) => void;
+
+/**
+ * Phase 1 SSR handler. Resolves the component, renders it via
+ * react-dom/server.renderToReadableStream, pumps chunks back to the
+ * host as base64-encoded NDJSON.
+ *
+ * Errors fall back to a type:"error" frame so the host can return a
+ * 500 with the error body. Mid-stream errors (after the first chunk
+ * has flushed) are uncatchable here — React's `onError` would have
+ * to feed into a separate signal, deferred to Phase 1.5.
+ */
+export async function handleRenderRoute(
+  msg: RenderRouteMessage,
+  send: Send,
+): Promise<void> {
+  try {
+    // react + react-dom are USER deps. ssr-runtime.ts lives in
+    // packages/functions/src/, but the user's react install is under
+    // their project cwd. `import("react-dom/server")` in this file
+    // would resolve against pylon's own node_modules (which doesn't
+    // declare react), so we route through a Bun-resolveSync against
+    // the user's cwd.
+    const cwd = process.cwd();
+    const resolveFromUser = (spec: string): string =>
+      (Bun as any).resolveSync
+        ? (Bun as any).resolveSync(spec, cwd)
+        : spec;
+    // `renderToReadableStream` is only exported from
+    // `react-dom/server.browser` (WHATWG streams), not the plain
+    // `react-dom/server` (which is Node-stream-style). Try browser
+    // first, fall back to the default entry for environments that
+    // re-route it (Next runs a custom dist).
+    let reactDomServerImport: any;
+    try {
+      // @ts-ignore — user-dep, resolved at runtime
+      reactDomServerImport = await import(
+        /* @vite-ignore */ resolveFromUser("react-dom/server.browser")
+      );
+    } catch {
+      // @ts-ignore — user-dep, resolved at runtime
+      reactDomServerImport = await import(
+        /* @vite-ignore */ resolveFromUser("react-dom/server")
+      );
+    }
+    // @ts-ignore — user-dep, resolved at runtime
+    const reactImport = await import(
+      /* @vite-ignore */ resolveFromUser("react")
+    );
+    const React = reactImport.default ?? reactImport;
+    const renderToReadableStream =
+      reactDomServerImport.renderToReadableStream ??
+      reactDomServerImport.default?.renderToReadableStream;
+    if (typeof renderToReadableStream !== "function") {
+      throw new Error(
+        "react-dom/server.browser does not export renderToReadableStream — install react@>=18 + react-dom@>=18",
+      );
+    }
+
+    // Resolve the page module. The component string is project-
+    // relative without extension; try .tsx → .ts → .jsx → .js so
+    // any of the common page-file shapes work. cwd was captured
+    // above for the react resolver.
+    const baseName = `${cwd}/${msg.component}`;
+    let mod: any = null;
+    let lastErr: unknown = null;
+    for (const ext of [".tsx", ".ts", ".jsx", ".js"]) {
+      try {
+        mod = await import(`${baseName}${ext}`);
+        break;
+      } catch (e) {
+        lastErr = e;
+      }
+    }
+    if (!mod) {
+      throw lastErr ?? new Error(`could not import component "${msg.component}"`);
+    }
+    const Component = mod.default ?? mod.Page ?? mod.page;
+    if (typeof Component !== "function") {
+      throw new Error(
+        `component "${msg.component}" has no default export (or named export "Page")`,
+      );
+    }
+
+    const props = {
+      url: msg.url,
+      params: msg.params,
+      searchParams: msg.search_params,
+      headers: msg.headers,
+      cookies: msg.cookies,
+      auth: msg.auth,
+    };
+
+    const element = React.createElement(Component, props);
+    const stream: ReadableStream<Uint8Array> = await renderToReadableStream(
+      element,
+      {
+        onError(err: unknown) {
+          // React captures render errors during the streaming render
+          // and feeds them here. Phase 1 logs to stderr; Phase 1.5
+          // sends a structured signal so the host can truncate the
+          // body + emit a debug overlay.
+          // eslint-disable-next-line no-console
+          console.error("[ssr] renderToReadableStream onError:", err);
+        },
+      },
+    );
+
+    // Headers go out before the first chunk so the host can write the
+    // response head.
+    send({
+      type: "response_start",
+      call_id: msg.call_id,
+      status: 200,
+      headers: { "content-type": "text/html; charset=utf-8" },
+    });
+
+    const reader = stream.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (!value || value.byteLength === 0) continue;
+      // base64 in pure JS via Buffer (Bun ships it). For large
+      // pages this is O(n) per chunk; fine for Phase 1.
+      const b64 = Buffer.from(value).toString("base64");
+      send({
+        type: "render_chunk",
+        call_id: msg.call_id,
+        data: b64,
+      });
+    }
+    send({ type: "render_done", call_id: msg.call_id });
+  } catch (err: any) {
+    // Pre-first-chunk error → host returns 500.
+    send({
+      type: "error",
+      call_id: msg.call_id,
+      code: err?.code ?? "SSR_RENDER_FAILED",
+      message: err?.message ?? String(err),
+    });
+  }
+}