@pylonsync/functions 0.22.50 → 0.22.59

package/src/ssr-offline.ts

@@ -3,12 +3,13 @@
 //   - `readManifestOffline`: the `offline` block of pylon.manifest.json.
 //   - `buildOfflineWorker`: computes the service worker config for one client
 //     build (the precache list comes from `routeAssetUrls`, the same list the
-//     SSR render emits tags for) and writes `pylon-sw.js` into the build.
+//     SSR render emits tags for) and writes `pylon-sw.js` into the build,
+//     with `pylon-version.json` beside it (served at `/_pylon/version`).
 //   - `offlineHeadTags`: the install tags every page's `<head>` gets.
 //
 // The worker itself is offline-sw.ts. The Rust host serves
-// `/manifest.webmanifest` and `/pylon-sw.js` (crates/runtime/src/frontend/
-// offline.rs).
+// `/manifest.webmanifest`, `/pylon-sw.js` and `/_pylon/version`
+// (crates/runtime/src/frontend/offline.rs).
 
 import { renderServiceWorker, type ServiceWorkerConfig } from "./offline-sw";
 import { matchRoute } from "./ssr-route-match";
@@ -37,8 +38,24 @@ export interface BundleOffline {
   routes: string[];
   /** The service worker's version (its cache names carry it). */
   version: string;
+  /** When this build was made (ISO 8601). Not part of `version`: two
+   *  machines that build the same app get the same version. */
+  builtAt: string;
 }
 
+/** `pylon-version.json` in the client build, served at `/_pylon/version`.
+ *  `useAppUpdate` in @pylonsync/react polls it. */
+export interface BuildVersionFile {
+  version: string;
+  builtAt: string;
+  /** Hash of what a home-screen app reads only when it is added (see
+   *  `installIdentity`). */
+  install: string;
+}
+
+/** The file the runtime serves at `/_pylon/version`. */
+export const VERSION_FILE = "pylon-version.json";
+
 /** How long a navigation to an offline route waits for the network before
  *  the worker shows the kept page. Long enough for a slow but working
  *  connection to win; short enough that a dead one does not leave a blank
@@ -98,10 +115,88 @@ export function isDynamicPattern(pattern: string): boolean {
   return /\[[^\]]+\]/.test(pattern);
 }
 
-/** The service worker config for this build. */
+/**
+ * Hash of what iOS reads from the web app manifest and the head tags only
+ * when the app is added to the home screen: the name, the short name, the
+ * display mode, the start URL and the icons (with the bytes of each icon
+ * file in `public/`). When it changes, an installed app keeps the old
+ * values until it is removed and added again.
+ *
+ * The manifest is the one the runtime serves: `public/manifest.webmanifest`,
+ * then `<appDir>/manifest.webmanifest`, else the `offline` config (see
+ * `web_manifest_source` in crates/runtime/src/frontend/offline.rs).
+ */
+export async function installIdentity(
+  fs: any,
+  path: any,
+  cwd: string,
+  appDirRel: string,
+  offline: ManifestOfflineInput,
+): Promise<string> {
+  let served: any = null;
+  for (const candidate of [
+    path.join(cwd, "public", "manifest.webmanifest"),
+    path.join(cwd, appDirRel, "manifest.webmanifest"),
+  ]) {
+    if (!fs.existsSync(candidate)) continue;
+    try {
+      served = JSON.parse(fs.readFileSync(candidate, "utf8"));
+    } catch {
+      served = { unreadable: fs.readFileSync(candidate, "utf8") };
+    }
+    break;
+  }
+  const { createHash } = await import("node:crypto");
+  const iconContent = (src: unknown): string | null => {
+    if (typeof src !== "string" || !src.startsWith("/") || src.startsWith("//")) return null;
+    const file = path.join(cwd, "public", src.split(/[?#]/)[0]);
+    if (!fs.existsSync(file)) return null;
+    return createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+  };
+  const icons = (list: unknown) =>
+    (Array.isArray(list) ? list : []).map((icon: any) => ({
+      src: icon?.src ?? null,
+      sizes: icon?.sizes ?? null,
+      purpose: icon?.purpose ?? null,
+      content: iconContent(icon?.src),
+    }));
+  const identity = served
+    ? {
+        name: served.name ?? null,
+        shortName: served.short_name ?? null,
+        display: served.display ?? null,
+        startUrl: served.start_url ?? null,
+        icons: icons(served.icons),
+        unreadable: served.unreadable ?? null,
+      }
+    : {
+        name: offline.name,
+        shortName: offline.shortName ?? offline.name,
+        display: offline.display,
+        startUrl: offline.startUrl,
+        icons: icons(offline.icons),
+      };
+  // The head tags come from the `offline` config even when the app ships its
+  // own manifest file.
+  const touch = touchIcon(offline.icons);
+  const head = {
+    title: offline.shortName ?? offline.name,
+    touchIcon: touch,
+    touchIconContent: iconContent(touch),
+  };
+  return createHash("sha256")
+    .update(JSON.stringify({ identity, head }))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+/** The service worker config for this build. `install` is
+ *  `installIdentity`; it is part of the version, so a manifest change
+ *  installs a new worker (which precaches the new manifest). */
 export async function offlineWorkerConfig(
   manifest: RouteAssetManifest,
   offline: ManifestOfflineInput,
+  install: string = "",
 ): Promise<{ config: ServiceWorkerConfig; unknownRoutes: string[] }> {
   const prefix = manifest.public_prefix || "/_pylon/build/";
   const { matched, unknown } = resolveOfflineRoutes(manifest, offline.routes);
@@ -132,22 +227,26 @@ export async function offlineWorkerConfig(
   // changed per boot would reinstall the worker on every deploy machine.
   const { createHash } = await import("node:crypto");
   const version = createHash("sha256")
-    .update(JSON.stringify(base))
+    .update(JSON.stringify({ ...base, install }))
     .digest("hex")
     .slice(0, 16);
   return { config: { version, ...base }, unknownRoutes: unknown };
 }
 
-/** Write `pylon-sw.js` into `outdir` and return the bundle manifest's
- *  `offline` block. */
+/** Write `pylon-sw.js` and `pylon-version.json` into `outdir` and return
+ *  the bundle manifest's `offline` block. `cwd` and `appDirRel` locate the
+ *  app's own manifest file and its icons. */
 export async function buildOfflineWorker(
   fs: any,
   path: any,
   outdir: string,
   manifest: RouteAssetManifest,
   offline: ManifestOfflineInput,
+  cwd: string,
+  appDirRel: string,
 ): Promise<BundleOffline> {
-  const { config, unknownRoutes } = await offlineWorkerConfig(manifest, offline);
+  const install = await installIdentity(fs, path, cwd, appDirRel, offline);
+  const { config, unknownRoutes } = await offlineWorkerConfig(manifest, offline, install);
   if (unknownRoutes.length > 0) {
     // eslint-disable-next-line no-console
     console.warn(
@@ -156,6 +255,12 @@ export async function buildOfflineWorker(
     );
   }
   fs.writeFileSync(path.join(outdir, "pylon-sw.js"), renderServiceWorker(config), "utf8");
+  const versionFile: BuildVersionFile = {
+    version: config.version,
+    builtAt: new Date().toISOString(),
+    install,
+  };
+  fs.writeFileSync(path.join(outdir, VERSION_FILE), JSON.stringify(versionFile), "utf8");
   return {
     name: offline.name,
     ...(offline.shortName ? { shortName: offline.shortName } : {}),
@@ -164,6 +269,7 @@ export async function buildOfflineWorker(
     startUrl: offline.startUrl,
     routes: offline.routes,
     version: config.version,
+    builtAt: versionFile.builtAt,
   };
 }
 

package/src/ssr-precompress.test.ts

@@ -0,0 +1,49 @@
+// Build-time brotli and gzip copies of the client build's text files.
+
+import { afterEach, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { MIN_COMPRESS_BYTES, precompressBuild } from "./ssr-precompress";
+
+let dir = "";
+afterEach(() => {
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  dir = "";
+});
+
+const js = "export const rows = [" + Array.from({ length: 400 }, (_, i) => `{id:${i},name:"row ${i}"}`).join(",") + "];\n";
+
+test("writes .br and .gz copies that decompress to the file", () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-precompress-"));
+  fs.mkdirSync(path.join(dir, "chunks"));
+  fs.writeFileSync(path.join(dir, "chunks", "chunk-abcd1234.js"), js);
+  fs.writeFileSync(path.join(dir, "styles-abcd1234.css"), "a{color:red}".repeat(200));
+
+  const result = precompressBuild(fs, path, zlib, dir);
+  expect(result.files).toBe(2);
+  expect(result.brotliBytes).toBeLessThan(result.bytes);
+
+  const file = path.join(dir, "chunks", "chunk-abcd1234.js");
+  expect(zlib.brotliDecompressSync(fs.readFileSync(file + ".br")).toString()).toBe(js);
+  expect(zlib.gunzipSync(fs.readFileSync(file + ".gz")).toString()).toBe(js);
+  expect(fs.statSync(file + ".br").size).toBeLessThan(js.length / 4);
+});
+
+test("skips small files, binary formats and copies that would not be smaller", () => {
+  dir = fs.mkdtempSync(path.join(os.tmpdir(), "pylon-precompress-"));
+  fs.writeFileSync(path.join(dir, "tiny-abcd1234.js"), "x".repeat(MIN_COMPRESS_BYTES - 1));
+  fs.writeFileSync(path.join(dir, "font-abcd1234.woff2"), js);
+  // Random bytes do not compress.
+  const noise = Buffer.from(Array.from({ length: 4096 }, () => Math.floor(Math.random() * 256)));
+  fs.writeFileSync(path.join(dir, "noise-abcd1234.js"), noise);
+
+  const result = precompressBuild(fs, path, zlib, dir);
+  expect(result.files).toBe(0);
+  expect(fs.readdirSync(dir).sort()).toEqual([
+    "font-abcd1234.woff2",
+    "noise-abcd1234.js",
+    "tiny-abcd1234.js",
+  ]);
+});

package/src/ssr-precompress.ts

@@ -0,0 +1,67 @@
+// Brotli and gzip copies of the client build's text files, written at build
+// time. The runtime sends `<file>.br` or `<file>.gz` with Content-Encoding
+// when the browser accepts it (serve_pylon_client_bundle in
+// crates/runtime/src/frontend.rs), so no request pays to compress.
+
+/** Extensions worth compressing. Images and fonts are compressed already. */
+const COMPRESSIBLE = new Set([".js", ".mjs", ".css", ".json", ".map", ".svg", ".wasm", ".txt", ".html"]);
+
+/** Smaller files gain less than the bytes of the encoding headers. */
+export const MIN_COMPRESS_BYTES = 1024;
+
+export interface PrecompressResult {
+  /** Files that got at least one compressed copy. */
+  files: number;
+  /** Total bytes of those files, and of their brotli copies. */
+  bytes: number;
+  brotliBytes: number;
+}
+
+/**
+ * Write `<file>.br` (brotli, quality 11) and `<file>.gz` (gzip, level 9)
+ * next to every compressible file in `outdir` of at least
+ * `MIN_COMPRESS_BYTES`. A copy that is not smaller than the file is not
+ * written. Copies left by an earlier build are replaced.
+ */
+export function precompressBuild(fs: any, path: any, zlib: any, outdir: string): PrecompressResult {
+  const result: PrecompressResult = { files: 0, bytes: 0, brotliBytes: 0 };
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!entry.isFile() || !COMPRESSIBLE.has(path.extname(entry.name))) continue;
+      const data: Uint8Array = fs.readFileSync(full);
+      if (data.length < MIN_COMPRESS_BYTES) continue;
+      const br: Uint8Array = zlib.brotliCompressSync(data, {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
+          [zlib.constants.BROTLI_PARAM_SIZE_HINT]: data.length,
+        },
+      });
+      const gz: Uint8Array = zlib.gzipSync(data, { level: 9 });
+      let wrote = false;
+      for (const [ext, copy] of [
+        [".br", br],
+        [".gz", gz],
+      ] as const) {
+        const target = full + ext;
+        if (copy.length < data.length) {
+          fs.writeFileSync(target, copy);
+          wrote = true;
+        } else if (fs.existsSync(target)) {
+          fs.unlinkSync(target);
+        }
+      }
+      if (wrote) {
+        result.files++;
+        result.bytes += data.length;
+        result.brotliBytes += Math.min(br.length, data.length);
+      }
+    }
+  };
+  walk(outdir);
+  return result;
+}

package/src/ssr-runtime.ts

@@ -2222,8 +2222,9 @@ export function buildHydrationTail(args: {
   // raw `auth` is replaced AFTER the live-handle strip below.
   bucketAuth?: { signedIn: boolean };
   /** The app opted into `buildManifest({ offline })`: the client registers
-   *  the service worker (production only). */
-  offline?: boolean;
+   *  the service worker (production only), and `useAppUpdate` compares this
+   *  build's version with `/_pylon/version`. */
+  offline?: { version: string; builtAt?: string };
   /** Client-side NAVIGATION payload: emit the `__PYLON_DATA__` blob and
    *  nothing else. The client already has the runtime and resolves the route
    *  entry from the build manifest, so the entry `<script>`, the preload tags
@@ -2289,7 +2290,13 @@ export function buildHydrationTail(args: {
     typeof process !== "undefined" ? process.env.PYLON_APP_NAME : undefined;
   if (appName) hydrationPayload.app = appName;
   // App-global, identity-free: safe in a shared or offline tail.
-  if (args.offline) hydrationPayload.offline = { dev: isDevMode() };
+  if (args.offline) {
+    hydrationPayload.offline = {
+      dev: isDevMode(),
+      version: args.offline.version,
+      builtAt: args.offline.builtAt ?? null,
+    };
+  }
   if (args.kind) hydrationPayload.kind = args.kind;
   const json = escapeScriptJson(JSON.stringify(hydrationPayload));
   let tail = `<script id="__PYLON_DATA__" type="application/json">${json}</script>`;
@@ -2675,20 +2682,23 @@ export function makeServerData(
   // 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,
+  // Fired on every call whose result can depend on the caller: serverData.fn
+  // (the fn may read ctx.auth) and every policy-filtered read (the host applies
+  // the caller's read policies to `ssrRead` reads). The render vetoes shared
+  // caching when it carried a real identity. `serverData.unsafe.*` skips
+  // policies, so its rows are the same for every caller and it does not fire.
+  onIdentityRead?: () => void,
   // Fired on every serverData read (fn calls included), so an offline-shell
   // render can refuse a page that needs the server to render.
   onRead?: () => void,
 ): any {
   const promiseCache = new Map<string, Promise<any>>();
-  const wrap = (r: any, prefix: string): any => {
+  const wrap = (r: any, prefix: string, callerFiltered: boolean): any => {
     const out: any = {};
     for (const m of SERVER_DATA_METHODS) {
       out[m] = (...args: any[]) => {
         onRead?.();
+        if (callerFiltered) onIdentityRead?.();
         const key = prefix + m + ":" + stableStringify(args);
         let p = promiseCache.get(key);
         if (!p) {
@@ -2703,8 +2713,8 @@ export function makeServerData(
     }
     return out;
   };
-  const sd = wrap(reader, "");
-  if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:");
+  const sd = wrap(reader, "", true);
+  if (reader.unsafe) sd.unsafe = wrap(reader.unsafe, "u:", false);
   if (callFn) {
     sd.fn = (name: string, args?: Record<string, unknown>) => {
       onRead?.();
@@ -2713,7 +2723,7 @@ export function makeServerData(
       const key = "fn:" + name + ":" + stableStringify(args ?? {});
       let p = promiseCache.get(key);
       if (!p) {
-        onFnCall?.();
+        onIdentityRead?.();
         p = callFn(name, args).then((value: any) => {
           valueCache[key] = value;
           return value;
@@ -2805,11 +2815,11 @@ export function computeCacheVerdict(args: {
  *    `authTouched` proves a bucketable body depends on nothing but the binary
  *    session bit.
  *  - `dynamicTouched` — reading request headers/cookies makes it request-specific.
- *  - `strictPolicies` — in strict mode serverData reads are auth-FILTERED, so the
- *    body/ssrData would vary by identity even without the page reading auth. In
- *    the default (non-strict) mode serverData reads bypass the policy gate and
- *    return identity-independent rows, so the cached body is safe to share within
- *    the bucket. Strict mode therefore must NOT bucket.
+ *  - `strictPolicies` — kept as a veto. Safe serverData reads are filtered by
+ *    the caller's read policies in EVERY mode (not only strict), so an
+ *    identity-carrying render that reads serverData sets `authTouched` itself
+ *    (makeServerData's onIdentityRead); that, not this flag, is what keeps a
+ *    signed-in render with policy-filtered rows out of the bucket.
  *  - cookieCount / forceDynamic / wantsStream / non-200 — same reasons as the
  *    anon verdict (a Set-Cookie, a streaming head, or an error/redirect can't be
  *    safely shared).
@@ -2874,8 +2884,11 @@ export function computeOfflineShellVerdict(args: {
   status: number;
 }): { ok: true } | { ok: false; reason: string } {
   if (args.status !== 200) return { ok: false, reason: `status ${args.status}` };
-  if (args.authTouched) return { ok: false, reason: "the page read props.auth" };
+  // serverData before auth: a signed-in serverData read also sets authTouched
+  // (it returns the caller's rows), and "read serverData" is the actionable
+  // reason.
   if (args.serverDataTouched) return { ok: false, reason: "the page read serverData" };
+  if (args.authTouched) return { ok: false, reason: "the page read props.auth" };
   if (args.dynamicTouched) {
     return { ok: false, reason: "the page read request headers or cookies" };
   }
@@ -3446,12 +3459,13 @@ export async function handleRenderRoute(
       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.
+      // A query function may read ctx.auth, and a safe read returns only the
+      // rows the caller's read policies allow: identity-specific output the
+      // read-tracking proxies can't see. An identity-carrying render that
+      // called serverData.fn or made a safe read 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)) {
@@ -3918,8 +3932,8 @@ export async function handleRenderRoute(
     let preloadPolyfills: string | undefined;
     // The same file list the offline service worker precaches for this route.
     let preloadAssets: RouteAssetFiles | null = null;
-    // Whether the app opted into `buildManifest({ offline })`.
-    let offlineApp = false;
+    // The build's version when the app opted into `buildManifest({ offline })`.
+    let offlineApp: { version: string; builtAt?: string } | undefined;
     try {
       const { getManifest } = await import("./ssr-client-bundler");
       const manifest = await getManifest();
@@ -3927,7 +3941,12 @@ export async function handleRenderRoute(
       preloadManifestRoute = manifest.routes[msg.component] ?? null;
       preloadPolyfills = manifest.polyfills;
       preloadAssets = routeAssetFiles(manifest, msg.component);
-      offlineApp = !!manifest.offline;
+      if (manifest.offline) {
+        offlineApp = {
+          version: manifest.offline.version,
+          builtAt: manifest.offline.builtAt,
+        };
+      }
       if (!preloadManifestRoute) {
         preloadManifestErr = `manifest has no entry for "${msg.component}"`;
       }

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

@@ -8,7 +8,7 @@
  *  - 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
+ *  - the onIdentityRead notification that lets the render veto shared caching for
  *    identity-carrying requests;
  *  - the client runtime template carrying the matching `fn` shim.
  */
@@ -47,7 +47,7 @@ describe("makeServerData.fn", () => {
     ]);
   });
 
-  test("onFnCall fires once per unique call (the cache-veto hook)", async () => {
+  test("onIdentityRead fires once per unique fn call (the cache-veto hook)", async () => {
     let touches = 0;
     const sd = makeServerData(
       noopReader,

package/src/types.ts

@@ -832,7 +832,21 @@ export type LlmContentBlock =
       tool_use_id: string;
       content: string;
       is_error?: boolean;
-    };
+    }
+  /** An image the model reads: png, jpeg, gif or webp, as base64. */
+  | { type: "image"; source: LlmMediaSource }
+  /**
+   * A document the model reads: a PDF or plain text, as base64. Anthropic
+   * only: the OpenAI provider refuses it (LLM_UNSUPPORTED_CONTENT).
+   */
+  | { type: "document"; source: LlmMediaSource; title?: string };
+
+/** The bytes of an image or document block. */
+export interface LlmMediaSource {
+  type: "base64";
+  media_type: string;
+  data: string;
+}
 
 export interface LlmTool {
   name: string;
@@ -1075,6 +1089,35 @@ export interface Files {
    * so keep lifetimes short.
    */
   signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
+  /**
+   * What the host knows of a stored file, in any function. On a backend
+   * that tracks owners (local disk, a private S3 bucket) `ownerId` is who
+   * uploaded or stored it, and a file that does not exist is null. A
+   * backend that does not (`ownerTracked: false`, the Stack0 CDN) knows no
+   * owner: there a file id is a capability, so check who may use it
+   * yourself, for example by recording uploads in your own rows.
+   */
+  info(fileId: string): Promise<FileInfo | null>;
+}
+
+/** {@link Files.info}. */
+export interface FileInfo {
+  id: string;
+  /** Recorded at upload, when the backend keeps it. */
+  contentType: string | null;
+  /** The uploader, or null when the backend does not track it or the system stored it. */
+  ownerId: string | null;
+  public: boolean;
+  /** The backend records owners, so `ownerId` and a null answer can be trusted. */
+  ownerTracked: boolean;
+}
+
+/** {@link ActionFiles.read}. */
+export interface ReadFile {
+  id: string;
+  contentType: string | null;
+  size: number;
+  data: Uint8Array;
 }
 
 /** Options for {@link ActionFiles.store}. */
@@ -1117,6 +1160,12 @@ export interface ActionFiles extends Files {
   ): Promise<StoredFile>;
   /** Delete a stored file. `deleted` is false when it did not exist. */
   delete(fileId: string): Promise<{ deleted: boolean }>;
+  /**
+   * A stored file's bytes, with server trust: the function decides who may
+   * read it. At most the host's upload limit (25 MiB, or
+   * `PYLON_MAX_UPLOAD_BYTES`).
+   */
+  read(fileId: string): Promise<ReadFile>;
 }
 
 /**