@pylonsync/functions 0.3.384 → 0.4.0

package/dist/auth.d.ts

@@ -0,0 +1,4 @@
+import type { AuthInfo } from "./types";
+export type AuthClaims = Omit<AuthInfo, "elevate">;
+/** Normalize the Rust wire envelope into the public function auth shape. */
+export declare function normalizeAuthClaims(raw: Record<string, unknown>): AuthClaims;

package/dist/runtime.d.ts

@@ -16,6 +16,15 @@
  */
 import type { DbReader, DbWriter, Llm, Rooms } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
+/**
+ * Query-function caller for SSR `serverData.fn(name, args)`. Sends the same
+ * `run_fn` frame `ctx.runQuery` uses, on the render's call_id — the host's
+ * render loop executes the query with the PAGE's auth context (anonymous on
+ * public pages) and rejects anything that isn't a query. Legacy rpc() (no
+ * op_id) is correct here: concurrent calls queue settle-chained on the one
+ * call_id, matching how ctx.runQuery behaves inside a function.
+ */
+export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
 /**
  * Build the LLM client that round-trips through the host runtime.

package/dist/ssr-runtime.d.ts

@@ -394,6 +394,16 @@ export declare function buildHydrationTail(args: {
  * carrying any stack content. FNV-1a over message+stack, 8 hex chars.
  */
 export declare function errorDigest(err: any): string;
+/**
+ * Wrap a DbReader so each `serverData.x(...)` call returns a PROMISE CACHED
+ * by (method, args) — required for React 19 `use()`, which re-invokes the
+ * call on the post-suspense re-render and must get the same (now-resolved)
+ * promise instead of a fresh pending one (else it suspends forever). Each
+ * resolved value is also recorded into `valueCache` keyed identically, so it
+ * can be serialized into `__PYLON_DATA__.ssrData` and replayed on the client
+ * — keeping hydration free of mismatches.
+ */
+export declare function makeServerData(reader: any, valueCache: Record<string, any>, callFn?: (name: string, args?: Record<string, unknown>) => Promise<unknown>, onFnCall?: () => void): any;
 /**
  * #278: does this route STREAM (vs buffer the whole document)? Streaming is
  * opt-in: a `loading.tsx` (route-level Suspense) or `export const streaming =

package/dist/types.d.ts

@@ -40,6 +40,10 @@ export interface AuthInfo<R extends AuthRequirement = "optional"> {
     /** Active tenant id (selected organization) for multi-tenant apps.
      *  Null when the session hasn't selected one. */
     tenantId: string | null;
+    /** Exact role slugs for the active organization/session. Custom roles do
+     *  not imply `member` or `admin`; compare explicitly or use
+     *  `ctx.requireMember` for an authoritative membership lookup. */
+    roles: string[];
     /**
      * Promote the call's auth context after the handler has done its
      * own authentication check (HMAC signature verification on a

package/package.json

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

package/src/auth.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { normalizeAuthClaims } from "./auth";
+
+describe("function auth normalization", () => {
+  test("preserves custom roles from the Rust wire envelope", () => {
+    expect(
+      normalizeAuthClaims({
+        user_id: "u1",
+        is_admin: false,
+        tenant_id: "org_1",
+        roles: ["reviewer"],
+      }),
+    ).toEqual({
+      userId: "u1",
+      isAdmin: false,
+      tenantId: "org_1",
+      roles: ["reviewer"],
+    });
+  });
+
+  test("defaults missing roles to an empty array and drops non-strings", () => {
+    expect(normalizeAuthClaims({}).roles).toEqual([]);
+    expect(normalizeAuthClaims({ roles: ["billing", 42, null] }).roles).toEqual([
+      "billing",
+    ]);
+  });
+});

package/src/auth.ts

@@ -0,0 +1,19 @@
+import type { AuthInfo } from "./types";
+
+export type AuthClaims = Omit<AuthInfo, "elevate">;
+
+/** Normalize the Rust wire envelope into the public function auth shape. */
+export function normalizeAuthClaims(
+  raw: Record<string, unknown>,
+): AuthClaims {
+  return {
+    userId:
+      ((raw.userId ?? raw.user_id) as string | null | undefined) ?? null,
+    isAdmin: Boolean(raw.isAdmin ?? raw.is_admin),
+    tenantId:
+      ((raw.tenantId ?? raw.tenant_id) as string | null | undefined) ?? null,
+    roles: Array.isArray(raw.roles)
+      ? raw.roles.filter((role): role is string => typeof role === "string")
+      : [],
+  };
+}

package/src/member.test.ts

@@ -65,6 +65,20 @@ describe("ctx.requireMember", () => {
     ).toBe("FORBIDDEN");
   });
 
+  test("custom roles are exact-match and inherit no built-in role", async () => {
+    const reviewer = { id: "m1", role: "reviewer" };
+    const requireMember = makeRequireMember("u1", spyRead([reviewer]).read);
+
+    expect(
+      await codeOf(() =>
+        requireMember("org_1", { role: ["owner", "admin", "member"] }),
+      ),
+    ).toBe("FORBIDDEN");
+    expect(await requireMember("org_1", { role: ["reviewer"] })).toEqual(
+      reviewer,
+    );
+  });
+
   test("role gate: passes when the member's role IS allowed (string or array)", async () => {
     const owner = { id: "m1", role: "owner" };
     expect(

package/src/runtime.ts

@@ -35,6 +35,7 @@ import type {
   FnDefinition,
   AuthInfo,
 } from "./types";
+import { normalizeAuthClaims } from "./auth";
 import { makeRequireMember } from "./member";
 import { isDevMode } from "./ssr-runtime";
 import { validateArgs } from "./validators";
@@ -509,6 +510,26 @@ export function buildDbReader(callId: string, ssrRead = false): DbReader {
   };
 }
 
+/**
+ * Query-function caller for SSR `serverData.fn(name, args)`. Sends the same
+ * `run_fn` frame `ctx.runQuery` uses, on the render's call_id — the host's
+ * render loop executes the query with the PAGE's auth context (anonymous on
+ * public pages) and rejects anything that isn't a query. Legacy rpc() (no
+ * op_id) is correct here: concurrent calls queue settle-chained on the one
+ * call_id, matching how ctx.runQuery behaves inside a function.
+ */
+export function buildSsrFnCaller(
+  callId: string,
+): (name: string, args?: Record<string, unknown>) => Promise<unknown> {
+  return (name, args) =>
+    rpc(callId, {
+      type: "run_fn",
+      fn_name: name,
+      fn_type: "query",
+      args: args ?? {},
+    });
+}
+
 function buildReaderOps(
   callId: string,
   unsafeOp: boolean,
@@ -1062,11 +1083,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
   // already got camelCase don't regress.
   const rawAuth = msg.auth as unknown as Record<string, unknown>;
   const auth: AuthInfo = {
-    userId: ((rawAuth.userId ?? rawAuth.user_id) as string | null | undefined) ?? null,
-    isAdmin: Boolean(rawAuth.isAdmin ?? rawAuth.is_admin),
-    tenantId:
-      ((rawAuth.tenantId ?? rawAuth.tenant_id) as string | null | undefined) ??
-      null,
+    ...normalizeAuthClaims(rawAuth),
     // `elevate` round-trips through the host runtime which mutates
     // the per-call caller_is_admin flag — that's what subsequent
     // scheduler.runAfter() reads. We also mutate the local

package/src/ssr-client-bundler.ts

@@ -385,6 +385,14 @@ function makeClientServerData(ssrData) {
   };
   const sd = wrap("");
   sd.unsafe = wrap("u:");
+  // serverData.fn(name, args) — key MUST match the server's makeServerData
+  // ("fn:" + name + ":" + stableStringify(args ?? {})) so hydration replays
+  // the query function's SSR'd result without a mismatch.
+  sd.fn = (name, args) => {
+    const key = "fn:" + name + ":" + stableStringify(args ?? {});
+    if (!pc.has(key)) pc.set(key, fulfilledThenable(cache[key]));
+    return pc.get(key);
+  };
   return sd;
 }
 
@@ -411,6 +419,11 @@ function makePendingServerData() {
   };
   const sd = wrap("");
   sd.unsafe = wrap("u:");
+  sd.fn = (name, args) => {
+    const key = "fn:" + name + ":" + stableStringify(args ?? {});
+    if (!pc.has(key)) pc.set(key, pending());
+    return pc.get(key);
+  };
   return sd;
 }
 

package/src/ssr-runtime.ts

@@ -2193,7 +2193,19 @@ const SERVER_DATA_METHODS = [
  * can be serialized into `__PYLON_DATA__.ssrData` and replayed on the client
  * — keeping hydration free of mismatches.
  */
-function makeServerData(reader: any, valueCache: Record<string, any>): any {
+export function makeServerData(
+  reader: any,
+  valueCache: Record<string, any>,
+  // `serverData.fn(name, args)` — runs a registered QUERY function with the
+  // page's own auth context (the host's render loop enforces query-only and
+  // executes it exactly like ctx.runQuery). Lets a page SSR data whose safe
+  // public projection lives in a gated query instead of open row policies.
+  callFn?: (name: string, args?: Record<string, unknown>) => Promise<unknown>,
+  // Fired on every serverData.fn call so the render can veto shared caching
+  // when the call carried a real identity (the fn may read ctx.auth, making
+  // its output identity-specific without the page ever touching props.auth).
+  onFnCall?: () => void,
+): any {
   const promiseCache = new Map<string, Promise<any>>();
   const wrap = (r: any, prefix: string): any => {
     const out: any = {};
@@ -2215,6 +2227,23 @@ function makeServerData(reader: any, valueCache: Record<string, any>): any {
   };
   const sd = wrap(reader, "");
   if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:");
+  if (callFn) {
+    sd.fn = (name: string, args?: Record<string, unknown>) => {
+      // Key MUST match the client shim's `fn` key so hydration replays
+      // the value from ssrData without a mismatch.
+      const key = "fn:" + name + ":" + stableStringify(args ?? {});
+      let p = promiseCache.get(key);
+      if (!p) {
+        onFnCall?.();
+        p = callFn(name, args).then((value: any) => {
+          valueCache[key] = value;
+          return value;
+        });
+        promiseCache.set(key, p);
+      }
+      return p;
+    };
+  }
   return sd;
 }
 
@@ -2794,7 +2823,11 @@ export async function handleRenderRoute(
     // gate as a query function's ctx.db, and rejects any write. Promise-
     // cached so `use()` doesn't re-suspend forever; resolved values land in
     // `ssrValueCache` for hydration replay.
-    const { buildDbReader } = await import("./runtime");
+    const { buildDbReader, buildSsrFnCaller } = await import("./runtime");
+    // Reading auth at all (even for an anon request) opts the render OUT of
+    // caching, because the output could differ by identity. Declared before
+    // serverData so `serverData.fn` can flip it too (below).
+    let authTouched = false;
     // `ssrRead: true` — serverData results are serialized into the
     // client-visible `__PYLON_DATA__` blob, so the host applies the same
     // per-row policy filter + `server_only`/`passwordHash` projection the
@@ -2802,6 +2835,19 @@ export async function handleRenderRoute(
     const serverData = makeServerData(
       buildDbReader(msg.call_id, true),
       ssrValueCache,
+      buildSsrFnCaller(msg.call_id),
+      // A query function runs with the page's auth and may read ctx.auth
+      // internally — identity-specific output the read-tracking proxies
+      // can't see. An identity-carrying render that called serverData.fn
+      // must therefore veto shared caches exactly as if it read props.auth.
+      // Anonymous renders stay cacheable: the anonymous result is uniform
+      // across every anonymous visitor.
+      () => {
+        const a = msg.auth as Record<string, unknown> | undefined;
+        if (a && (a.user_id || a.is_admin || a.tenant_id)) {
+          authTouched = true;
+        }
+      },
     );
 
     // #277 cache-safety proof. A render is shareable (CDN/disk cacheable) ONLY
@@ -2820,9 +2866,6 @@ export async function handleRenderRoute(
       return proxy;
     };
 
-    // Reading auth at all (even for an anon request) opts the render OUT of
-    // caching, because the output could differ by identity.
-    let authTouched = false;
     const authProxy = track(
       msg.auth as Record<string, unknown> | undefined,
       () => {

package/src/ssr-serverdata-fn.test.ts

@@ -0,0 +1,83 @@
+/**
+ * `serverData.fn(name, args)` — SSR pages calling query functions with the
+ * page's auth context. Pins the pieces that must not drift:
+ *
+ *  - the cache key shape ("fn:" + name + ":" + stableStringify(args ?? {})),
+ *    which the client hydration shim replays from ssrData — a mismatch means
+ *    hydration re-suspends forever;
+ *  - promise caching per (name, args) so React 19 `use()` gets the SAME
+ *    promise on the post-suspense re-render;
+ *  - resolved values recorded into the valueCache (the ssrData blob);
+ *  - the onFnCall notification that lets the render veto shared caching for
+ *    identity-carrying requests;
+ *  - the client runtime template carrying the matching `fn` shim.
+ */
+import { describe, expect, test } from "bun:test";
+import { makeServerData } from "./ssr-runtime";
+
+const noopReader = {};
+
+describe("makeServerData.fn", () => {
+  test("caches per (name, args) and records into valueCache with the wire key", async () => {
+    const valueCache: Record<string, any> = {};
+    const calls: Array<[string, any]> = [];
+    const sd = makeServerData(noopReader, valueCache, async (name, args) => {
+      calls.push([name, args]);
+      return { rows: [name, args?.x ?? null] };
+    });
+
+    const p1 = sd.fn("getPublicSchedule", { x: 1 });
+    const p2 = sd.fn("getPublicSchedule", { x: 1 });
+    expect(p1).toBe(p2); // use() re-render must see the SAME promise
+
+    const v = await p1;
+    expect(v).toEqual({ rows: ["getPublicSchedule", 1] });
+    expect(calls.length).toBe(1); // deduped
+
+    // Distinct args → distinct call, distinct cache entry.
+    await sd.fn("getPublicSchedule", { x: 2 });
+    expect(calls.length).toBe(2);
+
+    // No args normalizes to {} in the key.
+    await sd.fn("getSpeakers");
+    expect(Object.keys(valueCache).sort()).toEqual([
+      'fn:getPublicSchedule:{"x":1}',
+      'fn:getPublicSchedule:{"x":2}',
+      "fn:getSpeakers:{}",
+    ]);
+  });
+
+  test("onFnCall fires once per unique call (the cache-veto hook)", async () => {
+    let touches = 0;
+    const sd = makeServerData(
+      noopReader,
+      {},
+      async () => null,
+      () => {
+        touches++;
+      },
+    );
+    sd.fn("a");
+    sd.fn("a"); // cached — no second touch
+    sd.fn("b");
+    expect(touches).toBe(2);
+  });
+
+  test("no callFn → no fn method (older host pairing)", () => {
+    const sd = makeServerData(noopReader, {});
+    expect(sd.fn).toBeUndefined();
+  });
+});
+
+describe("client runtime shim parity", () => {
+  test("CLIENT_RUNTIME_SOURCE replays fn results with the identical key", async () => {
+    const src = await Bun.file(
+      new URL("./ssr-client-bundler.ts", import.meta.url).pathname,
+    ).text();
+    // Both client stand-ins (hydration replay + optimistic-nav pending) must
+    // build the exact server-side key. String-level guard against drift.
+    const keyExpr = '"fn:" + name + ":" + stableStringify(args ?? {})';
+    const count = src.split(keyExpr).length - 1;
+    expect(count).toBeGreaterThanOrEqual(2);
+  });
+});

package/src/types.ts

@@ -47,6 +47,10 @@ export interface AuthInfo<R extends AuthRequirement = "optional"> {
   /** Active tenant id (selected organization) for multi-tenant apps.
    *  Null when the session hasn't selected one. */
   tenantId: string | null;
+  /** Exact role slugs for the active organization/session. Custom roles do
+   *  not imply `member` or `admin`; compare explicitly or use
+   *  `ctx.requireMember` for an authoritative membership lookup. */
+  roles: string[];
   /**
    * Promote the call's auth context after the handler has done its
    * own authentication check (HMAC signature verification on a