@pylonsync/functions 0.11.6 → 0.13.0

package/src/runtime-shard-ticket.test.ts

@@ -0,0 +1,137 @@
+/**
+ * `ctx.shards` — the frames the runtime sends to the host (`ticket`,
+ * `create`, `stop`, `get`, `list`) and the values it returns. The host signs (it holds the secret); this
+ * checks the TS half. Same child-process NDJSON harness as
+ * runtime-email.test.ts.
+ */
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const RUNTIME = join(import.meta.dir, "runtime.ts");
+
+function parseFrames(text: string): Record<string, unknown>[] {
+  return text
+    .split("\n")
+    .filter((l) => l.trim().startsWith("{"))
+    .map((l) => JSON.parse(l) as Record<string, unknown>);
+}
+
+/** Run one function in a real runtime child; `host` answers its frames. */
+async function runFunction(
+  source: string,
+  host: (frame: Record<string, unknown>) => unknown,
+  hostFrameTypes: string[],
+  fnType: "mutation" | "action" = "mutation",
+): Promise<{ value: unknown; hostFrames: Record<string, unknown>[] }> {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-fn-shards-"));
+  mkdirSync(join(dir, "functions"));
+  writeFileSync(join(dir, "functions", "run.ts"), source);
+  const proc = Bun.spawn([process.execPath, RUNTIME, "./functions"], {
+    cwd: dir,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+  const decoder = new TextDecoder();
+  let buffered = "";
+  let consumed = 0;
+  const next = async (): Promise<Record<string, unknown>> => {
+    for (;;) {
+      const frames = parseFrames(buffered);
+      if (frames.length > consumed) return frames[consumed++];
+      const { done, value } = await reader.read();
+      if (done) throw new Error("runtime exited");
+      buffered += decoder.decode(value, { stream: true });
+    }
+  };
+  const send = (msg: Record<string, unknown>) =>
+    (proc.stdin as import("bun").FileSink).write(JSON.stringify(msg) + "\n");
+
+  while ((await next()).type !== "ready");
+  send({
+    type: "call",
+    call_id: "c_1",
+    fn_name: "run",
+    fn_type: fnType,
+    args: {},
+    auth: { user_id: "u1", is_admin: false, tenant_id: null },
+  });
+  const hostFrames: Record<string, unknown>[] = [];
+  try {
+    for (;;) {
+      const frame = await next();
+      if (frame.type === "return") return { value: frame.value, hostFrames };
+      if (frame.type === "error") throw new Error(JSON.stringify(frame));
+      if (hostFrameTypes.includes(frame.type as string)) {
+        hostFrames.push(frame);
+        send({ type: "result", call_id: "c_1", data: host(frame) });
+      }
+    }
+  } finally {
+    proc.kill();
+  }
+}
+
+test("ctx.shards.ticket sends sign_shard_ticket and returns the host's ticket", async () => {
+  const { value, hostFrames } = await runFunction(
+    `export default {
+  type: "mutation",
+  handler: async (ctx) => {
+    const ticket = await ctx.shards.ticket("zone-3", {
+      subscriberId: "char_12",
+      claims: { realm: "north" },
+      ttlSecs: 30,
+    });
+    return { ticket };
+  },
+};
+`,
+    () => "v1.payload.sig",
+    ["sign_shard_ticket"],
+  );
+  expect(hostFrames[0]).toMatchObject({
+    call_id: "c_1",
+    shard: "zone-3",
+    subscriber_id: "char_12",
+    claims: { realm: "north" },
+    ttl_secs: 30,
+  });
+  expect(value).toEqual({ ticket: "v1.payload.sig" });
+});
+
+test("ctx.shards.create/get/list/stop in an action send shard_op frames", async () => {
+  const info = { id: "m1", kind: "arena", tick: 0, subscribers: 0, running: true };
+  const { value, hostFrames } = await runFunction(
+    `export default {
+  type: "action",
+  handler: async (ctx) => {
+    const created = await ctx.shards.create("arena", "m1", { fog: true });
+    const got = await ctx.shards.get("m1");
+    const all = await ctx.shards.list();
+    const stopped = await ctx.shards.stop("m1");
+    return { created, got, all, stopped };
+  },
+};
+`,
+    (frame) => {
+      switch (frame.op) {
+        case "create":
+        case "get":
+          return info;
+        case "list":
+          return [info];
+        default:
+          return true;
+      }
+    },
+    ["shard_op"],
+    "action",
+  );
+  expect(hostFrames.map((f) => f.op)).toEqual(["create", "get", "list", "stop"]);
+  expect(hostFrames[0]).toMatchObject({ kind: "arena", id: "m1", params: { fog: true } });
+  expect(hostFrames[3]).toMatchObject({ id: "m1" });
+  expect(value).toEqual({ created: info, got: info, all: [info], stopped: true });
+});

package/src/runtime.ts

@@ -22,6 +22,8 @@ import type {
   EmailOptions,
   EmailSender,
   Files,
+  Shards,
+  ShardInfo,
   Stream,
   Scheduler,
   Llm,
@@ -46,6 +48,8 @@ import { normalizeAuthClaims } from "./auth";
 import { makeRequireMember } from "./member";
 import { isDevMode } from "./ssr-runtime";
 import { validateArgs } from "./validators";
+import { serverBundle } from "./server-bundle";
+import { fenceStdout } from "./stdout-fence";
 import { readdirSync } from "fs";
 import { join, basename } from "path";
 
@@ -111,61 +115,6 @@ function send(msg: Record<string, unknown>): void {
   }
 }
 
-/**
- * Redirect console.* from user code to stderr so handlers can't accidentally
- * emit a line that looks like a protocol frame and confuse the Rust reader.
- *
- * Before this guard, a handler calling `console.log('{"type":"return",...}')`
- * — either intentionally or by logging an object shaped that way — would be
- * parsed by the host as a real protocol message. Moving all console output
- * to stderr keeps stdout reserved for NDJSON protocol frames only.
- *
- * The original console methods are saved on the console object as
- * `__stdoutLog` etc. in case the runtime itself needs to write diagnostics
- * to stdout for some reason (it currently doesn't).
- */
-function fenceStdout(): void {
-  const toStderr = (prefix: string) => (...args: unknown[]) => {
-    const line = args
-      .map((a) => {
-        if (typeof a === "string") return a;
-        // Error: JSON.stringify yields `{}` because message/stack are
-        // non-enumerable. That made `console.error("x:", err)` log as `x: {}`,
-        // hiding the real failure from operators. Unwrap by hand.
-        if (a instanceof Error) {
-          const parts = [a.stack || `${a.name}: ${a.message}`];
-          const code = (a as { code?: unknown }).code;
-          if (code !== undefined) parts.push(`code=${String(code)}`);
-          const cause = (a as { cause?: unknown }).cause;
-          if (cause !== undefined) {
-            try {
-              parts.push(`cause=${cause instanceof Error ? cause.stack || cause.message : JSON.stringify(cause)}`);
-            } catch {
-              parts.push(`cause=${String(cause)}`);
-            }
-          }
-          return parts.join(" ");
-        }
-        try {
-          return JSON.stringify(a);
-        } catch {
-          return String(a);
-        }
-      })
-      .join(" ");
-    Bun.write(Bun.stderr, `${prefix}${line}\n`);
-  };
-  // Intentional: we want console.* for user handlers to go to stderr.
-  // Overwrite the globals before any user code is loaded.
-  const c = globalThis.console as unknown as Record<string, unknown>;
-  c.__stdoutLog = c.log;
-  c.log = toStderr("");
-  c.info = toStderr("");
-  c.warn = toStderr("[warn] ");
-  c.error = toStderr("[error] ");
-  c.debug = toStderr("[debug] ");
-}
-
 // ---------------------------------------------------------------------------
 // Single reader + dispatcher
 // ---------------------------------------------------------------------------
@@ -575,6 +524,39 @@ export function buildDbReader(callId: string, ssrRead = false): DbReader {
  * op_id) is correct here: concurrent calls queue settle-chained on the one
  * call_id, matching how ctx.runQuery behaves inside a function.
  */
+/** `ctx.shards` — shard tickets, signed host-side. */
+function buildShards(callId: string): Shards {
+  return {
+    async ticket(shardId, opts) {
+      return rpc(callId, {
+        type: "sign_shard_ticket",
+        shard: shardId,
+        subscriber_id: opts?.subscriberId,
+        claims: opts?.claims ?? {},
+        ttl_secs: opts?.ttlSecs,
+      }) as Promise<string>;
+    },
+    async create(kind, shardId, params) {
+      return rpc(callId, {
+        type: "shard_op",
+        op: "create",
+        kind,
+        id: shardId,
+        params: params ?? {},
+      }) as Promise<ShardInfo>;
+    },
+    async stop(shardId) {
+      return rpc(callId, { type: "shard_op", op: "stop", id: shardId }) as Promise<boolean>;
+    },
+    async get(shardId) {
+      return rpc(callId, { type: "shard_op", op: "get", id: shardId }) as Promise<ShardInfo | null>;
+    },
+    async list() {
+      return rpc(callId, { type: "shard_op", op: "list" }) as Promise<ShardInfo[]>;
+    },
+  };
+}
+
 /** `ctx.files` — signed download URLs, minted host-side. */
 function buildFiles(callId: string): Files {
   return {
@@ -1192,6 +1174,7 @@ function buildActionCtx(
       return err;
     },
     files: buildFiles(callId),
+    shards: buildShards(callId),
     // Actions have no ctx.db; read membership via the built-in internal query.
     requireMember: makeRequireMember(auth.userId, (entity, filter) =>
       rpc(callId, {
@@ -1344,6 +1327,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
           reader.query(entity, { ...filter, $limit: 1 }),
         ),
         files: buildFiles(msg.call_id),
+        shards: buildShards(msg.call_id),
       };
       break;
     }
@@ -1368,6 +1352,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
           writer.query(entity, { ...filter, $limit: 1 }),
         ),
         files: buildFiles(msg.call_id),
+        shards: buildShards(msg.call_id),
       };
       break;
     }
@@ -1474,6 +1459,30 @@ function firstStackFrame(err: unknown): string {
 // Startup: scan functions dir, send ready, then start reader loop
 // ---------------------------------------------------------------------------
 
+/**
+ * The `.ts` / `.js` modules directly inside `dir`, each with its name (file
+ * name without extension) and a loader. A missing directory yields none: a
+ * pure-SSR app has no `functions/`, and most apps have no `workflows/`. The
+ * runner must still send `ready` and serve renders in that case.
+ */
+function listModuleFiles(
+  dir: string,
+): Array<{ name: string; file: string; load: () => Promise<any> }> {
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter(
+      (f) => f.endsWith(".ts") || f.endsWith(".js"),
+    );
+  } catch {
+    return [];
+  }
+  return files.map((file) => ({
+    name: basename(file, file.endsWith(".ts") ? ".ts" : ".js"),
+    file,
+    load: () => import(join(dir, file)),
+  }));
+}
+
 async function main() {
   // Fence user `console.*` away from stdout BEFORE any user code is
   // imported — the import side-effects alone could print a stray line
@@ -1481,27 +1490,21 @@ async function main() {
   fenceStdout();
 
   const fnDir = process.argv[2] || "./functions";
+  const bundle = serverBundle();
 
-  let files: string[];
-  try {
-    files = readdirSync(fnDir).filter(
-      (f) => f.endsWith(".ts") || f.endsWith(".js")
-    );
-  } catch {
-    // 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 = [];
-  }
+  const fnSources = bundle
+    ? Object.keys(bundle.functions).map((name) => ({
+        name,
+        file: `${name} (bundled)`,
+        load: bundle.functions[name],
+      }))
+    : listModuleFiles(join(process.cwd(), fnDir));
 
   const { isAgentDefinition, AGENT_MARKER } = await import("./agent");
   let agentsPresent = false;
-  for (const file of files) {
-    const name = basename(file, file.endsWith(".ts") ? ".ts" : ".js");
+  for (const { name, file, load } of fnSources) {
     try {
-      const mod = await import(join(process.cwd(), fnDir, file));
+      const mod = await load();
       const def = mod.default as FnDefinition | undefined;
       // Runtime shape check — a misnamed/malformed export should
       // log + skip, not crash the loader. TS narrows `def.handler`
@@ -1547,18 +1550,16 @@ async function main() {
   );
   type WorkflowDefinition = import("./workflows").WorkflowDefinition;
   const workflowRegistry = new Map<string, WorkflowDefinition>();
-  const wfDir = join(process.cwd(), "workflows");
-  let wfFiles: string[] = [];
-  try {
-    wfFiles = readdirSync(wfDir).filter(
-      (f) => f.endsWith(".ts") || f.endsWith(".js"),
-    );
-  } catch {
-    // No workflows/ directory — the common case; declare nothing.
-  }
-  for (const file of wfFiles) {
+  const wfSources = bundle
+    ? Object.keys(bundle.workflows).map((name) => ({
+        name,
+        file: `${name} (bundled)`,
+        load: bundle.workflows[name],
+      }))
+    : listModuleFiles(join(process.cwd(), "workflows"));
+  for (const { file, load } of wfSources) {
     try {
-      const mod = await import(join(wfDir, file));
+      const mod = await load();
       const def = mod.default;
       if (isWorkflowDefinition(def)) {
         if (workflowRegistry.has(def.name)) {

package/src/server-bundle.test.ts

@@ -0,0 +1,89 @@
+// SSR module lookups in a production server bundle.
+//
+// An artifact has no app/ source files, so every lookup that checks the disk
+// in source mode (boundary walk, route-group dirs, layout chain, module
+// import) must answer from the bundle's module registry instead. These run
+// the lookups with a registry set and a cwd that holds no files, and expect
+// the same answers the source-mode tests get from a real tree.
+
+import { afterAll, afterEach, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { moduleKey, setServerBundle, type PylonServerBundle } from "./server-bundle";
+import { findBoundaryIn, importModule, moduleExistsIn } from "./ssr-runtime";
+
+const EMPTY_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-bundle-lookup-"));
+
+/** Set a registry with one loader per key. Returns the module namespaces the
+ *  loaders resolve to, and how many times each loader ran. */
+function withModules(keys: string[]): { ns: Record<string, any>; loads: Record<string, number> } {
+  const ns: Record<string, any> = {};
+  const loads: Record<string, number> = {};
+  const modules: PylonServerBundle["modules"] = {};
+  for (const k of keys) {
+    ns[k] = { default: () => k };
+    loads[k] = 0;
+    modules[k] = async () => {
+      loads[k] += 1;
+      return ns[k];
+    };
+  }
+  const bundle: PylonServerBundle = {
+    functions: {},
+    workflows: {},
+    modules,
+    react: null,
+    reactDomServer: null,
+    clientDir: "client",
+    ogAssets: { resvgWasm: "", interRegular: "", interSemiBold: "" },
+  };
+  setServerBundle(bundle);
+  return { ns, loads };
+}
+
+afterEach(() => {
+  delete (globalThis as any).__PYLON_SERVER_BUNDLE__;
+});
+afterAll(() => fs.rmSync(EMPTY_DIR, { recursive: true, force: true }));
+
+test("moduleKey normalizes separators, a leading ./, and extensions", () => {
+  expect(moduleKey(".\\app\\blog\\page.tsx")).toBe("app/blog/page");
+  expect(moduleKey("app/page")).toBe("app/page");
+});
+
+test("moduleExistsIn answers from the registry, not the disk", () => {
+  withModules(["app/layout", "app/blog/page"]);
+  expect(moduleExistsIn(fs, path, EMPTY_DIR, "app", "layout")).toBe(true);
+  expect(moduleExistsIn(fs, path, EMPTY_DIR, "app/blog", "page")).toBe(true);
+  expect(moduleExistsIn(fs, path, EMPTY_DIR, "app/blog", "layout")).toBe(false);
+});
+
+test("the boundary walk finds the nearest boundary, through route groups", () => {
+  withModules([
+    "app/not-found",
+    "app/(shop)/cart/not-found",
+    "app/(shop)/cart/items/page",
+    "app/(marketing)/error",
+    "app/blog/page",
+  ]);
+  expect(findBoundaryIn(fs, path, EMPTY_DIR, "app/(shop)/cart/items/page", "not-found")).toBe(
+    "app/(shop)/cart/not-found",
+  );
+  expect(findBoundaryIn(fs, path, EMPTY_DIR, "app/blog/page", "not-found")).toBe("app/not-found");
+  // A group directly under app/ answers for "/" too.
+  expect(findBoundaryIn(fs, path, EMPTY_DIR, "app/blog/page", "error")).toBe(
+    "app/(marketing)/error",
+  );
+  expect(findBoundaryIn(fs, path, EMPTY_DIR, "app/blog/page", "loading")).toBeNull();
+});
+
+test("importModule loads the bundled module on demand and names a missing one", async () => {
+  const { ns, loads } = withModules(["app/page", "app/layout"]);
+  expect(await importModule(EMPTY_DIR, "app/page")).toBe(ns["app/page"]);
+  // Lookups by key never evaluate a module; only an import does.
+  expect(moduleExistsIn(fs, path, EMPTY_DIR, "app", "layout")).toBe(true);
+  expect(loads).toEqual({ "app/page": 1, "app/layout": 0 });
+  await expect(importModule(EMPTY_DIR, "app/missing")).rejects.toThrow("not in the server bundle");
+});

package/src/server-bundle.ts

@@ -0,0 +1,63 @@
+// The module registry of a production server bundle (`pylon build`).
+//
+// In source mode the runner imports app code by path at run time: function
+// files from `functions/`, workflows from `workflows/`, and page / layout /
+// boundary modules from `app/`. It also resolves `react` from the app's
+// `node_modules`. A production bundle has none of those files. Its generated
+// entry puts a loader for every module in this registry and then starts the
+// runtime. Every loader in this package asks the registry first.
+//
+// The registry holds loaders, not modules, so each module is evaluated when
+// it is first needed, as in source mode: the runtime loads each function
+// with its own try/catch at boot, and a page loads on its first render. A
+// module that throws at the top level fails alone.
+//
+// The entry sets the registry before it imports the runtime, whose top-level
+// `main()` reads it.
+
+/** Loads one bundled module and returns its namespace. */
+export type ModuleLoader = () => Promise<any>;
+
+export interface PylonServerBundle {
+  /** Function name (file name without extension) → module loader. */
+  functions: Record<string, ModuleLoader>;
+  /** Workflow file name (without extension) → module loader. */
+  workflows: Record<string, ModuleLoader>;
+  /** Project-relative, extension-less, "/"-separated module path
+   *  (`app/blog/page`) → module loader. Holds every module under the app
+   *  dir that the SSR runtime can import: pages, layouts, boundaries,
+   *  loading states, route handlers, OG image modules, metadata routes. */
+  modules: Record<string, ModuleLoader>;
+  /** The app's React and React DOM server, as bundled with the pages, so SSR
+   *  renders with the same React instance the page modules import. */
+  react: any;
+  reactDomServer: any;
+  /** Client bundle directory, relative to the artifact root. */
+  clientDir: string;
+  /** Absolute paths of the files the OG image renderer reads at run time.
+   *  In source mode it finds them next to its own source file and in
+   *  `node_modules`; the bundle copies them next to the server output. */
+  ogAssets: {
+    resvgWasm: string;
+    interRegular: string;
+    interSemiBold: string;
+  };
+}
+
+const KEY = "__PYLON_SERVER_BUNDLE__";
+
+export function serverBundle(): PylonServerBundle | null {
+  return ((globalThis as any)[KEY] as PylonServerBundle | undefined) ?? null;
+}
+
+export function setServerBundle(bundle: PylonServerBundle): void {
+  (globalThis as any)[KEY] = bundle;
+}
+
+/** Normalize a module path to the registry key form. */
+export function moduleKey(relPath: string): string {
+  return relPath
+    .replace(/\\/g, "/")
+    .replace(/^\.\//, "")
+    .replace(/\.(tsx?|jsx?)$/, "");
+}