@pylonsync/functions 0.22.47 → 0.22.50

package/src/ssr-offline-shell.test.ts

@@ -0,0 +1,248 @@
+// Offline apps (`buildManifest({ offline })`), render side:
+//
+//   - A render the service worker asked for (`x-pylon-offline-shell: 1`) is
+//     marked keepable only when its HTML is the same for every signed-in
+//     user, and then its hydration data carries the signed-in bit and no
+//     identity. A page that reads props.auth, serverData, headers or cookies
+//     is refused.
+//   - Every page of an offline app gets the install tags and tells the
+//     client to register the worker.
+//   - The files the worker precaches for a route are exactly the files the
+//     route's HTML loads (Plan 012 step 2).
+//
+// ssr-runtime.ts pulls in runtime.ts (the bun runner entrypoint, which runs
+// main() on import), so each render runs in a child process, like
+// ssr-page-host.test.ts.
+
+import { expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { offlineWorkerConfig } from "./ssr-offline";
+import { routeAssetUrls } from "./ssr-route-assets";
+
+const SSR_RUNTIME = join(import.meta.dir, "ssr-runtime.ts");
+const PKG_NODE_MODULES = join(import.meta.dir, "..", "node_modules");
+
+interface Frame {
+  type: string;
+  headers?: Record<string, string>;
+  data?: string;
+}
+
+const BUNDLE_MANIFEST = {
+  build_id: "b1",
+  outdir: ".pylon/client-build",
+  public_prefix: "/_pylon/build/",
+  polyfills: "polyfills-aaaa1111.js",
+  routes: {
+    "app/page": {
+      file: "client-entry-app__page-bbbb2222.js",
+      imports: ["chunks/chunk-cccc3333.js", "chunks/chunk-dddd4444.js"],
+      css: ["styles-eeee5555.css"],
+      path: "/",
+    },
+  },
+  fonts: {
+    faces: [],
+    variables: [],
+    preload: ["fonts/inter-ffff6666.woff2"],
+  },
+  offline: {
+    name: "Field Sales",
+    shortName: "Sales",
+    themeColor: "#0b2545",
+    icons: [
+      { src: "/icons/192.png", sizes: "192x192", type: "image/png" },
+      { src: "/icons/512.png", sizes: "512x512", type: "image/png" },
+    ],
+    startUrl: "/",
+    routes: ["/"],
+    version: "v1",
+  },
+};
+
+function makeApp(pageBody: string, manifest: object = BUNDLE_MANIFEST): string {
+  const dir = mkdtempSync(join(tmpdir(), "pylon-offline-shell-"));
+  mkdirSync(join(dir, "app"), { recursive: true });
+  mkdirSync(join(dir, ".pylon", "client-build"), { recursive: true });
+  symlinkSync(PKG_NODE_MODULES, join(dir, "node_modules"), "dir");
+  writeFileSync(
+    join(dir, "app", "layout.tsx"),
+    `export default function Layout({ children }: any) {
+  return <html><head><title>t</title></head><body>{children}</body></html>;
+}
+`,
+  );
+  writeFileSync(
+    join(dir, "app", "page.tsx"),
+    `export default function Page(props: any) {
+${pageBody}
+}
+`,
+  );
+  writeFileSync(join(dir, ".pylon", "client-build", "styles-eeee5555.css"), "p{color:red}");
+  writeFileSync(
+    join(dir, ".pylon", "client-build", "manifest.json"),
+    JSON.stringify(manifest),
+  );
+  return dir;
+}
+
+const SIGNED_IN = {
+  user_id: "u_ana",
+  is_admin: false,
+  tenant_id: "t_veritas",
+  roles: ["rep"],
+};
+
+async function render(
+  dir: string,
+  opts: { shell?: boolean; auth?: object; env?: Record<string, string> } = {},
+): Promise<{ start: Frame | undefined; html: string; data: any }> {
+  const headers: Record<string, string> = { host: "app.example" };
+  if (opts.shell) headers["x-pylon-offline-shell"] = "1";
+  const auth = opts.auth ?? SIGNED_IN;
+  const msg = {
+    type: "render_route",
+    call_id: "c1",
+    component: "app/page",
+    layouts: ["app/layout"],
+    route_path: "/",
+    url: "/",
+    host: "app.example",
+    params: {},
+    search_params: {},
+    headers,
+    cookies: { sid: "secret-session" },
+    auth,
+    session_present: !!(auth as any).user_id,
+  };
+  const probe = `
+import { handleRenderRoute } from ${JSON.stringify(SSR_RUNTIME)};
+const frames = [];
+await handleRenderRoute(${JSON.stringify(msg)}, (m) => frames.push(m));
+console.error("FRAMES " + JSON.stringify(frames));
+setTimeout(() => process.exit(0), 50);
+`;
+  const probePath = join(dir, `probe-${Math.random().toString(36).slice(2)}.ts`);
+  writeFileSync(probePath, probe);
+  const proc = Bun.spawn(["bun", "run", probePath], {
+    cwd: dir,
+    env: { ...process.env, PYLON_DEV_MODE: "0", ...(opts.env ?? {}) },
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const code = await proc.exited;
+  const line = err.split("\n").find((l) => l.includes("FRAMES "));
+  if (code !== 0 || !line) {
+    throw new Error(`probe failed (exit ${code})\nstdout: ${out}\nstderr: ${err}`);
+  }
+  const frames = JSON.parse(line.slice(line.indexOf("FRAMES ") + 7)) as Frame[];
+  const html = frames
+    .filter((f) => f.type === "render_chunk")
+    .map((f) => Buffer.from(f.data!, "base64").toString("utf8"))
+    .join("");
+  const match = html.match(/<script id="__PYLON_DATA__"[^>]*>([\s\S]*?)<\/script>/);
+  return {
+    start: frames.find((f) => f.type === "response_start"),
+    html,
+    data: match ? JSON.parse(match[1]) : null,
+  };
+}
+
+const SESSION_ONLY_PAGE = `return <p>{props.session.exists ? "signed in" : "signed out"}</p>;`;
+
+test("a shell request for a page that reads only the signed-in bit is kept, without identity", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { start, html, data } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe("1");
+  expect(html).toContain("signed in");
+  expect(data.props.auth).toEqual({ signedIn: true });
+  expect(data.props.session).toEqual({ exists: true });
+  expect(html).not.toContain("u_ana");
+  expect(html).not.toContain("t_veritas");
+  expect(html).not.toContain("secret-session");
+});
+
+test("a page that reads props.auth is refused, with the reason", async () => {
+  const dir = makeApp(`return <p>{props.auth.userId ?? "anon"}</p>;`);
+  const { start } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe("refused; the page read props.auth");
+});
+
+test("a page that reads serverData is refused", async () => {
+  const dir = makeApp(`props.serverData.list("Lead"); return <p>x</p>;`);
+  const { start } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe("refused; the page read serverData");
+});
+
+test("a page that reads cookies is refused", async () => {
+  const dir = makeApp(`return <p>{String(props.cookies.theme)}</p>;`);
+  const { start } = await render(dir, { shell: true });
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBe(
+    "refused; the page read request headers or cookies",
+  );
+});
+
+test("an ordinary request carries no shell verdict and keeps its real auth", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { start, data } = await render(dir);
+  expect(start?.headers?.["x-pylon-offline-shell"]).toBeUndefined();
+  expect(data.props.auth.user_id).toBe("u_ana");
+});
+
+test("every page of an offline app gets the install tags and the register flag", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { html, data } = await render(dir);
+  expect(html).toContain('<link rel="manifest" href="/manifest.webmanifest">');
+  expect(html).toContain('<meta name="theme-color" content="#0b2545">');
+  expect(html).toContain('<meta name="apple-mobile-web-app-title" content="Sales">');
+  expect(html).toContain('<link rel="apple-touch-icon" href="/icons/512.png">');
+  expect(data.offline).toEqual({ dev: false });
+
+  const dev = await render(dir, { env: { PYLON_DEV_MODE: "1" } });
+  expect(dev.data.offline).toEqual({ dev: true });
+});
+
+test("an app without offline gets neither", async () => {
+  const { offline: _o, ...plain } = BUNDLE_MANIFEST;
+  const dir = makeApp(SESSION_ONLY_PAGE, plain);
+  const { html, data } = await render(dir);
+  expect(html).not.toContain('rel="manifest"');
+  expect(data.offline).toBeUndefined();
+});
+
+test("the worker precaches exactly the files the route's HTML loads", async () => {
+  const dir = makeApp(SESSION_ONLY_PAGE);
+  const { html } = await render(dir);
+  // Every build file the page references: stylesheets, modulepreloads,
+  // font preloads, module scripts.
+  const loaded = new Set<string>();
+  for (const m of html.matchAll(/<(?:link|script)\b[^>]*?(?:href|src)="(\/_pylon\/build\/[^"]+)"/g)) {
+    loaded.add(m[1]);
+  }
+  // The stylesheet is a link by default; record it whether linked or inlined.
+  for (const m of html.matchAll(/data-pylon-css="([^"]+)"/g)) loaded.add(`/_pylon/build/${m[1]}`);
+  const listed = routeAssetUrls(BUNDLE_MANIFEST, "app/page");
+  expect(new Set(listed)).toEqual(loaded);
+  expect(loaded.size).toBe(6);
+
+  const { config } = await offlineWorkerConfig(BUNDLE_MANIFEST, {
+    name: "Field Sales",
+    startUrl: "/",
+    display: "standalone",
+    routes: ["/"],
+    icons: BUNDLE_MANIFEST.offline.icons,
+  });
+  for (const url of loaded) expect(config.precache).toContain(url);
+  expect(config.precache).toContain("/_pylon/build/manifest.json");
+  expect(config.precache).toContain("/manifest.webmanifest");
+  expect(config.precache).toContain("/icons/512.png");
+  expect(config.shells).toEqual(["/"]);
+});

package/src/ssr-offline.ts

@@ -0,0 +1,205 @@
+// Build-time and render-time pieces of `buildManifest({ offline })`.
+//
+//   - `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.
+//   - `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).
+
+import { renderServiceWorker, type ServiceWorkerConfig } from "./offline-sw";
+import { matchRoute } from "./ssr-route-match";
+import { routeAssetUrls, type RouteAssetManifest } from "./ssr-route-assets";
+
+/** `buildManifest({ offline })` as the SDK writes it to pylon.manifest.json. */
+export interface ManifestOfflineInput {
+  name: string;
+  shortName?: string;
+  description?: string;
+  icons?: Array<{ src: string; sizes: string; type?: string; purpose?: string }>;
+  themeColor?: string;
+  backgroundColor?: string;
+  startUrl: string;
+  display: string;
+  routes: string[];
+}
+
+/** What the bundle manifest keeps for the render and the client runtime. */
+export interface BundleOffline {
+  name: string;
+  shortName?: string;
+  themeColor?: string;
+  icons?: Array<{ src: string; sizes: string; type?: string; purpose?: string }>;
+  startUrl: string;
+  routes: string[];
+  /** The service worker's version (its cache names carry it). */
+  version: string;
+}
+
+/** 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
+ *  screen. */
+export const NAVIGATION_TIMEOUT_MS = 3000;
+
+/** The `offline` block of `<cwd>/pylon.manifest.json`, or null. */
+export function readManifestOffline(
+  fs: any,
+  path: any,
+  cwd: string,
+  manifestPath: string = path.join(cwd, "pylon.manifest.json"),
+): ManifestOfflineInput | null {
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const o = m?.offline;
+    if (!o || typeof o.name !== "string") return null;
+    return {
+      ...o,
+      startUrl: typeof o.startUrl === "string" ? o.startUrl : "/",
+      display: typeof o.display === "string" ? o.display : "standalone",
+      routes: Array.isArray(o.routes) ? o.routes : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Every route pattern in `routes` that names a page in this build, with
+ *  the page's component. A pattern with no page is reported, not dropped
+ *  silently. */
+export function resolveOfflineRoutes(
+  manifest: RouteAssetManifest,
+  routes: string[],
+): { matched: Array<{ pattern: string; component: string }>; unknown: string[] } {
+  const matched: Array<{ pattern: string; component: string }> = [];
+  const unknown: string[] = [];
+  for (const pattern of routes) {
+    const component = Object.keys(manifest.routes).find(
+      (c) => manifest.routes[c]?.path === pattern,
+    );
+    if (component) {
+      matched.push({ pattern, component });
+      continue;
+    }
+    // A concrete path (`/leads/today`) served by a dynamic page.
+    const m = matchRoute(manifest as any, pattern);
+    if (m) matched.push({ pattern, component: m.component });
+    else unknown.push(pattern);
+  }
+  return { matched, unknown };
+}
+
+/** True for a pattern with a dynamic segment: one shell cannot serve it. */
+export function isDynamicPattern(pattern: string): boolean {
+  return /\[[^\]]+\]/.test(pattern);
+}
+
+/** The service worker config for this build. */
+export async function offlineWorkerConfig(
+  manifest: RouteAssetManifest,
+  offline: ManifestOfflineInput,
+): Promise<{ config: ServiceWorkerConfig; unknownRoutes: string[] }> {
+  const prefix = manifest.public_prefix || "/_pylon/build/";
+  const { matched, unknown } = resolveOfflineRoutes(manifest, offline.routes);
+  const precache = new Set<string>();
+  // The client runtime loads the bundle manifest before it can render a
+  // route; it is always same-origin.
+  precache.add("/_pylon/build/manifest.json");
+  for (const { component } of matched) {
+    for (const url of routeAssetUrls(manifest, component)) precache.add(url);
+  }
+  precache.add("/manifest.webmanifest");
+  for (const icon of offline.icons ?? []) precache.add(icon.src);
+  const startPath = offline.startUrl.split(/[?#]/)[0] || "/";
+  const shells = matched
+    .map((m) => m.pattern)
+    .filter((p) => !isDynamicPattern(p));
+  if (!shells.includes(startPath)) shells.unshift(startPath);
+  const base = {
+    buildPrefix: prefix,
+    precache: Array.from(precache).sort(),
+    shells,
+    routes: offline.routes,
+    startPath,
+    navigationTimeoutMs: NAVIGATION_TIMEOUT_MS,
+  };
+  // Content-derived: the build files are content-hashed, so the same build
+  // gives the same version on every machine and every boot. A version that
+  // 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))
+    .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. */
+export async function buildOfflineWorker(
+  fs: any,
+  path: any,
+  outdir: string,
+  manifest: RouteAssetManifest,
+  offline: ManifestOfflineInput,
+): Promise<BundleOffline> {
+  const { config, unknownRoutes } = await offlineWorkerConfig(manifest, offline);
+  if (unknownRoutes.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[pylon offline] offline.routes names no page for: ${unknownRoutes.join(", ")}. ` +
+        "Those paths will not open offline.",
+    );
+  }
+  fs.writeFileSync(path.join(outdir, "pylon-sw.js"), renderServiceWorker(config), "utf8");
+  return {
+    name: offline.name,
+    ...(offline.shortName ? { shortName: offline.shortName } : {}),
+    ...(offline.themeColor ? { themeColor: offline.themeColor } : {}),
+    ...(offline.icons && offline.icons.length > 0 ? { icons: offline.icons } : {}),
+    startUrl: offline.startUrl,
+    routes: offline.routes,
+    version: config.version,
+  };
+}
+
+function attr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/** The largest square icon, for `apple-touch-icon` (iOS does not read the
+ *  web app manifest's icons). */
+function touchIcon(icons: BundleOffline["icons"]): string | null {
+  let best: { src: string; size: number } | null = null;
+  for (const icon of icons ?? []) {
+    if (icon.purpose && !icon.purpose.split(" ").includes("any")) continue;
+    for (const s of icon.sizes.split(" ")) {
+      const m = s.match(/^(\d+)x(\d+)$/);
+      const size = m && m[1] === m[2] ? Number(m[1]) : 0;
+      if (size > 0 && (!best || size > best.size)) best = { src: icon.src, size };
+    }
+  }
+  return best ? best.src : null;
+}
+
+/** `<head>` tags that make the app installable. */
+export function offlineHeadTags(offline: BundleOffline): string {
+  let tags = `<link rel="manifest" href="/manifest.webmanifest">`;
+  if (offline.themeColor) {
+    tags += `<meta name="theme-color" content="${attr(offline.themeColor)}">`;
+  }
+  tags += `<meta name="mobile-web-app-capable" content="yes">`;
+  tags += `<meta name="apple-mobile-web-app-capable" content="yes">`;
+  tags += `<meta name="apple-mobile-web-app-title" content="${attr(offline.shortName ?? offline.name)}">`;
+  const icon = touchIcon(offline.icons);
+  if (icon) tags += `<link rel="apple-touch-icon" href="${attr(icon)}">`;
+  return tags;
+}

package/src/ssr-route-assets.ts

@@ -0,0 +1,68 @@
+// The client build files one page needs, from the bundle manifest.
+//
+// One list, two readers: the SSR render emits a tag for each file (stylesheet
+// links, modulepreloads, the polyfill and entry scripts, font preloads), and
+// the offline service worker precaches the same files for each offline route.
+// Computing them in one place keeps the two from drifting: a file the page
+// loads but the worker did not keep would break the page with no network.
+
+/** The bundle-manifest fields this module reads. */
+export interface RouteAssetManifest {
+  public_prefix?: string;
+  polyfills?: string;
+  routes: Record<
+    string,
+    { file: string; imports?: string[]; css?: string[]; path?: string } | undefined
+  >;
+  fonts?: { preload?: string[] } | null;
+}
+
+/** Outdir-relative files for one route, in the order the page loads them. */
+export interface RouteAssetFiles {
+  /** `<link rel="stylesheet">` (or inlined `<style>`) in the head. */
+  styles: string[];
+  /** `<link rel="modulepreload">` in the head. */
+  preloads: string[];
+  /** `<link rel="preload" as="font">` in the head. */
+  fonts: string[];
+  /** `<script type="module">` in the body tail: the polyfills, then the
+   *  route entry. */
+  scripts: string[];
+}
+
+/** The scripts the hydration tail loads for a route entry. */
+export function routeScriptFiles(
+  route: { file: string },
+  polyfills: string | undefined,
+): string[] {
+  return polyfills ? [polyfills, route.file] : [route.file];
+}
+
+/** Every client-build file the page for `component` loads, or null when the
+ *  build has no entry for it. */
+export function routeAssetFiles(
+  manifest: RouteAssetManifest,
+  component: string,
+): RouteAssetFiles | null {
+  const route = manifest.routes[component];
+  if (!route) return null;
+  return {
+    styles: route.css ?? [],
+    preloads: route.imports ?? [],
+    fonts: manifest.fonts?.preload ?? [],
+    scripts: routeScriptFiles(route, manifest.polyfills),
+  };
+}
+
+/** All of a route's files as URLs under the build's public prefix. */
+export function routeAssetUrls(
+  manifest: RouteAssetManifest,
+  component: string,
+): string[] {
+  const files = routeAssetFiles(manifest, component);
+  if (!files) return [];
+  const prefix = manifest.public_prefix || "/_pylon/build/";
+  return [...files.styles, ...files.preloads, ...files.fonts, ...files.scripts].map(
+    (f) => prefix + f,
+  );
+}