@pylonsync/functions 0.22.46 → 0.22.50

package/src/offline-sw.ts

@@ -0,0 +1,330 @@
+// The offline service worker, served at `/pylon-sw.js` for apps that set
+// `buildManifest({ offline })`.
+//
+// The client bundler writes the worker into the client build with this
+// build's config inlined (`renderServiceWorker`). The worker body is the
+// source of `pylonServiceWorker` itself, serialized with `toString()`, so
+// the tests in offline-sw.test.ts run the same code the browser runs. That
+// imposes one rule on this file: `pylonServiceWorker` and `classifyRequest`
+// may not reference anything outside their own bodies (no imports, no
+// module-level helpers).
+//
+// What it does:
+//   - install: precache the build's client files for the offline routes,
+//     the web app manifest and the icons, then fetch each static offline
+//     route's HTML ("shell") with `X-Pylon-Offline-Shell: 1` and keep it when
+//     the runtime answers `Pylon-Offline-Shell: 1` (the HTML is the same for
+//     every signed-in user).
+//   - navigations: network first. When the network fails (or, for an offline
+//     route, takes longer than `navigationTimeoutMs`), answer with the
+//     route's shell, else the start URL's shell. The client runtime renders
+//     the real URL from the local replica.
+//   - build files: cache first. They are content-hashed, so a cached copy
+//     is always correct.
+//   - everything else (API, auth, sync, dev endpoints): not intercepted, never
+//     cached. Data comes from the sync engine, not the HTTP cache.
+//   - activate: delete caches from other builds. A new deploy installs a new
+//     worker, which waits until every tab of the app is closed (the next
+//     launch) before it takes over. No `skipWaiting`.
+
+/** The build-specific values inlined into `/pylon-sw.js`. */
+export interface ServiceWorkerConfig {
+  /** Hash of everything below. Cache names carry it. */
+  version: string;
+  /** The client build's public prefix (`/_pylon/build/`, or a CDN URL). */
+  buildPrefix: string;
+  /** URLs to keep at install: the offline routes' build files, the web app
+   *  manifest, the icons. */
+  precache: string[];
+  /** Offline routes without dynamic segments: their HTML is kept at install. */
+  shells: string[];
+  /** Every offline route pattern (`/leads/[id]` included). */
+  routes: string[];
+  /** Path of the start URL; its shell answers any navigation with no
+   *  better match. */
+  startPath: string;
+  /** How long a navigation to an offline route waits for the network before
+   *  the worker answers with the shell. */
+  navigationTimeoutMs: number;
+}
+
+/** What the worker does with one request. */
+export type RequestKind =
+  /** A page load: network first, shell when offline. */
+  | "navigate"
+  /** A file of the client build: cache first. */
+  | "build"
+  /** The web app manifest or an icon: cache first. */
+  | "precached"
+  /** Not intercepted, never cached. */
+  | "network";
+
+/**
+ * Classify one request. Pure; `self.location.origin` is passed in.
+ */
+export function classifyRequest(
+  request: { url: string; method: string; mode: string },
+  config: ServiceWorkerConfig,
+  origin: string,
+): RequestKind {
+  if (request.method !== "GET") return "network";
+  let url: URL;
+  try {
+    url = new URL(request.url);
+  } catch {
+    return "network";
+  }
+  const sameOrigin = url.origin === origin;
+  if (sameOrigin) {
+    const path = url.pathname;
+    // Data and control endpoints. Data reaches the page through the sync
+    // engine; a cached API answer would be a stale copy of the replica, and
+    // a cached auth answer could sign in the wrong person.
+    const neverCached = [
+      "/api/",
+      "/auth/",
+      "/_pylon/dev/",
+      "/studio",
+      "/events",
+      "/health",
+      "/metrics",
+      "/.well-known/",
+    ];
+    for (const prefix of neverCached) {
+      if (path === prefix.replace(/\/$/, "") || path.startsWith(prefix)) return "network";
+    }
+    if (path === "/pylon-sw.js") return "network";
+    if (request.mode === "navigate") return "navigate";
+    if (path.startsWith("/_pylon/build/")) return "build";
+  }
+  if (!sameOrigin && config.buildPrefix && url.href.startsWith(config.buildPrefix)) {
+    return "build";
+  }
+  if (sameOrigin && config.precache.indexOf(url.pathname) !== -1) return "precached";
+  return "network";
+}
+
+/**
+ * The worker. `sw` is the ServiceWorkerGlobalScope (`self`); passing it in
+ * keeps the body free of globals so tests can supply their own. `classify`
+ * is `classifyRequest`, passed in for the same reason.
+ */
+export function pylonServiceWorker(
+  sw: any,
+  config: ServiceWorkerConfig,
+  classify: typeof classifyRequest,
+): void {
+  const ASSETS = "pylon-" + config.version + "-assets";
+  const SHELLS = "pylon-" + config.version + "-shells";
+  const STATE_KEY = "/__pylon_sw_state";
+  const SHELL_REQUEST_HEADER = "X-Pylon-Offline-Shell";
+  const SHELL_RESPONSE_HEADER = "Pylon-Offline-Shell";
+
+  function warn(message: string): void {
+    try {
+      sw.console.warn("[pylon offline] " + message);
+    } catch {
+      // No console in this scope.
+    }
+  }
+
+  function splitPath(p: string): string[] {
+    const trimmed = p.replace(/\/+$/, "");
+    return trimmed === "" ? [] : trimmed.slice(1).split("/");
+  }
+
+  // Does `pathname` match a route pattern (`/leads/[id]`, `/docs/[...slug]`)?
+  function matchesPattern(pattern: string, pathname: string): boolean {
+    const pat = splitPath(pattern);
+    const target = splitPath(pathname);
+    for (let i = 0; i < pat.length; i++) {
+      const seg = pat[i];
+      if (seg.startsWith("[...") && seg.endsWith("]")) return target.length > i;
+      if (seg.startsWith("[[...") && seg.endsWith("]]")) return true;
+      if (i >= target.length) return false;
+      if (seg.startsWith("[") && seg.endsWith("]")) continue;
+      if (seg !== target[i]) return false;
+    }
+    return pat.length === target.length;
+  }
+
+  function isOfflineRoute(pathname: string): boolean {
+    for (const route of config.routes) {
+      if (matchesPattern(route, pathname)) return true;
+    }
+    return false;
+  }
+
+  function normalizePath(pathname: string): string {
+    return pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
+  }
+
+  // Fetch each static offline route's HTML and keep the ones the runtime
+  // marks as identical for every signed-in user. Returns false when the
+  // network failed, so the caller does not record the refresh as done.
+  async function refreshShells(): Promise<boolean> {
+    const cache = await sw.caches.open(SHELLS);
+    let reached = false;
+    for (const path of config.shells) {
+      let res: any;
+      try {
+        res = await sw.fetch(path, {
+          headers: { [SHELL_REQUEST_HEADER]: "1" },
+          credentials: "same-origin",
+          cache: "no-store",
+        });
+      } catch {
+        continue;
+      }
+      reached = true;
+      const verdict = res.headers.get(SHELL_RESPONSE_HEADER);
+      if (res.ok && !res.redirected && verdict === "1") {
+        await cache.put(path, res);
+      } else if (res.redirected || (verdict && verdict !== "1") || res.status === 404) {
+        // A definite answer that this page is not a shell for the current
+        // session (a redirect to sign-in, a page that reads the user): drop
+        // the old copy so it is not shown to the wrong session. A server
+        // error keeps the old copy.
+        await cache.delete(path);
+        warn(
+          path +
+            " is not kept for offline use: " +
+            (verdict || (res.redirected ? "redirected to " + res.url : "status " + res.status)),
+        );
+      } else {
+        warn(path + " is not kept for offline use: status " + res.status);
+      }
+    }
+    return reached;
+  }
+
+  // The client posts its signed-in state after every page load. The shells
+  // carry that one bit, so refetch them when it changed.
+  async function syncSession(signedIn: boolean): Promise<void> {
+    const cache = await sw.caches.open(SHELLS);
+    const stored = await cache.match(STATE_KEY);
+    if (stored) {
+      const state = await stored.json();
+      if (state && state.signedIn === signedIn) return;
+    }
+    if (await refreshShells()) {
+      await cache.put(
+        STATE_KEY,
+        new sw.Response(JSON.stringify({ signedIn }), {
+          headers: { "Content-Type": "application/json" },
+        }),
+      );
+    }
+  }
+
+  async function shellFor(pathname: string): Promise<any> {
+    const cache = await sw.caches.open(SHELLS);
+    const exact = await cache.match(normalizePath(pathname));
+    if (exact) return exact;
+    return cache.match(config.startPath);
+  }
+
+  function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+    return new Promise((resolve, reject) => {
+      const timer = sw.setTimeout(() => reject(new Error("timeout")), ms);
+      promise.then(
+        (v) => {
+          sw.clearTimeout(timer);
+          resolve(v);
+        },
+        (e) => {
+          sw.clearTimeout(timer);
+          reject(e);
+        },
+      );
+    });
+  }
+
+  async function handleNavigation(request: any): Promise<any> {
+    const pathname = new URL(request.url).pathname;
+    const offlineRoute = isOfflineRoute(pathname);
+    const network = sw.fetch(request);
+    try {
+      // Only an offline route has a page to show instead, so only an
+      // offline route stops waiting for a slow network.
+      return await (offlineRoute
+        ? withTimeout(network, config.navigationTimeoutMs)
+        : network);
+    } catch (err) {
+      const shell = await shellFor(pathname);
+      if (shell) return shell;
+      // Nothing kept: wait for the network after all (a slow answer beats
+      // the browser's offline page), and let a real failure through.
+      return network;
+    }
+  }
+
+  async function cacheFirst(request: any): Promise<any> {
+    const cache = await sw.caches.open(ASSETS);
+    const hit = await cache.match(request);
+    if (hit) return hit;
+    const res = await sw.fetch(request);
+    // Keep build files the page loads lazily (a dynamic import, an image
+    // the page imports), so they work offline after their first use.
+    if (res && res.ok) await cache.put(request, res.clone());
+    return res;
+  }
+
+  sw.addEventListener("install", (event: any) => {
+    event.waitUntil(
+      (async () => {
+        const cache = await sw.caches.open(ASSETS);
+        // All-or-nothing: a build file that fails to download fails the
+        // install, and the previous worker keeps serving the previous build.
+        await cache.addAll(config.precache);
+        await refreshShells();
+      })(),
+    );
+  });
+
+  sw.addEventListener("activate", (event: any) => {
+    event.waitUntil(
+      (async () => {
+        const names: string[] = await sw.caches.keys();
+        await Promise.all(
+          names
+            .filter(
+              (n) => n.indexOf("pylon-") === 0 && n !== ASSETS && n !== SHELLS,
+            )
+            .map((n) => sw.caches.delete(n)),
+        );
+        // Control the tab that installed the first worker, so the app works
+        // offline after one visit. With an older worker this runs only after
+        // every tab closed, so it never swaps a build mid-session.
+        await sw.clients.claim();
+      })(),
+    );
+  });
+
+  sw.addEventListener("fetch", (event: any) => {
+    const request = event.request;
+    const kind = classify(request, config, sw.location.origin);
+    if (kind === "navigate") event.respondWith(handleNavigation(request));
+    else if (kind === "build" || kind === "precached") event.respondWith(cacheFirst(request));
+  });
+
+  sw.addEventListener("message", (event: any) => {
+    const data = event.data;
+    if (data && data.type === "pylon:session" && typeof data.signedIn === "boolean") {
+      event.waitUntil(syncSession(data.signedIn));
+    }
+  });
+}
+
+/** The `/pylon-sw.js` source for one build. */
+export function renderServiceWorker(config: ServiceWorkerConfig): string {
+  return (
+    "// Generated by Pylon for this build. Do not edit.\n(" +
+    pylonServiceWorker.toString() +
+    ")(self, " +
+    JSON.stringify(config) +
+    ", " +
+    classifyRequest.toString() +
+    ");\n"
+  );
+}

package/src/ssr-client-bundler.test.ts

@@ -909,3 +909,66 @@ describe("client router popstate", () => {
     expect(src.match(/renderedPath = location\.pathname \+ location\.search;/g)?.length).toBeGreaterThanOrEqual(3);
   });
 });
+
+describe("offline service worker (buildManifest({ offline }))", () => {
+  test("an offline app's build writes pylon-sw.js with each offline route's files", async () => {
+    tempDir = makeFixture(
+      {
+        "page.tsx": PAGE_BODY("Home"),
+        "leads/page.tsx": PAGE_BODY("Leads"),
+        "leads/[id]/page.tsx": PAGE_BODY("Lead"),
+        "settings/page.tsx": PAGE_BODY("Settings"),
+      },
+      { "layout.tsx": LAYOUT_BODY },
+    );
+    fs.writeFileSync(
+      path.join(tempDir, "pylon.manifest.json"),
+      JSON.stringify({
+        offline: {
+          name: "Field Sales",
+          icons: [{ src: "/icons/192.png", sizes: "192x192" }],
+          startUrl: "/leads",
+          display: "standalone",
+          routes: ["/leads", "/leads/[id]"],
+        },
+      }),
+    );
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+
+    const { manifestPath, outdir } = await buildClientBundle();
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as PylonBundleManifest;
+    expect(manifest.offline?.routes).toEqual(["/leads", "/leads/[id]"]);
+    expect(manifest.offline?.version).toMatch(/^[0-9a-f]{16}$/);
+
+    const sw = fs.readFileSync(path.join(outdir, "pylon-sw.js"), "utf8");
+    // Valid script (compiled, not run).
+    const { Script } = await import("node:vm");
+    expect(() => new Script(sw)).not.toThrow();
+    const config = JSON.parse(sw.slice(sw.indexOf(")(self, ") + 8, sw.lastIndexOf(", function")));
+    expect(config.version).toBe(manifest.offline!.version);
+    expect(config.shells).toEqual(["/leads"]);
+    const prefix = manifest.public_prefix;
+    for (const component of ["app/leads/page", "app/leads/[id]/page"]) {
+      expect(config.precache).toContain(prefix + manifest.routes[component].file);
+    }
+    // Not an offline route: its entry is not precached.
+    expect(config.precache).not.toContain(prefix + manifest.routes["app/settings/page"].file);
+    expect(config.precache).toContain("/icons/192.png");
+
+    // The same build gives the same version: no reinstall per boot.
+    const again = await buildClientBundle();
+    const second = JSON.parse(fs.readFileSync(again.manifestPath, "utf8")) as PylonBundleManifest;
+    expect(second.offline?.version).toBe(manifest.offline!.version);
+  });
+
+  test("an app without offline gets no worker", async () => {
+    tempDir = makeFixture({ "page.tsx": PAGE_BODY("Home") }, { "layout.tsx": LAYOUT_BODY });
+    originalCwd = process.cwd();
+    process.chdir(tempDir);
+    const { manifestPath, outdir } = await buildClientBundle();
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as PylonBundleManifest;
+    expect(manifest.offline).toBeUndefined();
+    expect(fs.existsSync(path.join(outdir, "pylon-sw.js"))).toBe(false);
+  });
+});

package/src/ssr-client-bundler.ts

@@ -42,6 +42,7 @@ import {
   type ManifestBuildConfig,
 } from "./build-compat";
 import { serverBundle } from "./server-bundle";
+import { buildOfflineWorker, readManifestOffline, type BundleOffline } from "./ssr-offline";
 
 type Send = (msg: Record<string, unknown>) => void;
 
@@ -357,7 +358,7 @@ const CLIENT_RUNTIME_SOURCE = `// Generated by Pylon SSR (Phase 2 client runtime
 
 import { createElement, Fragment, Suspense } from "react";
 import { hydrateRoot } from "react-dom/client";
-import { configureClient } from "@pylonsync/react";
+import { configureClient, registerOfflineWorker } from "@pylonsync/react";
 import { createPylonBoundary, nearestBoundaryComponent } from "./client-boundary";
 import { LOADING_MODULES } from "./loading-registry";
 import { createNavPayloadCache } from "./nav-cache";
@@ -771,6 +772,25 @@ export function hydrate(component, Page, Layouts) {
       },
     });
     installNavHandlers();
+    // Registers the offline service worker for an app that opted in, and
+    // removes one left on this origin by an earlier build otherwise.
+    registerOfflineWorker({
+      optedIn: !!data.offline,
+      production: !(data.offline && data.offline.dev),
+      signedIn: !!(data.props && data.props.session && data.props.session.exists),
+    });
+    if (data.offline) {
+      // The service worker answered this load with the page it kept for
+      // another URL: a dynamic offline route, or no network. The page on
+      // screen is that URL's; render the address bar's URL from the replica.
+      const shellPath = data.props && data.props.pathname;
+      if (typeof shellPath === "string" && shellPath !== location.pathname) {
+        navigate(location.pathname + location.search + location.hash, {
+          replace: true,
+          shellPath,
+        });
+      }
+    }
     return;
   }
   // Subsequent hydrate calls fire from dynamic-loaded entries
@@ -959,6 +979,24 @@ async function navigate(href, opts) {
       html = await res.text();
     }
   } catch {
+    // No network. An offline route renders from the replica; anything else
+    // needs the server.
+    if (myEpoch !== navEpoch) return;
+    if (await renderOffline(url, myEpoch, opts, push)) {
+      navState.settled = true;
+      if (placeholderTimer) clearTimeout(placeholderTimer);
+      return;
+    }
+    if (opts && opts.shellPath) {
+      // This load already came from a kept page and the URL cannot open
+      // offline. Reloading would get the same kept page again; show its URL.
+      navState.settled = true;
+      if (placeholderTimer) clearTimeout(placeholderTimer);
+      history.replaceState({ component: currentComponent }, "", opts.shellPath);
+      renderedPath = location.pathname + location.search;
+      window.dispatchEvent(new Event("pylon:navigation"));
+      return;
+    }
     fullLoad();
     return;
   }
@@ -1038,6 +1076,67 @@ async function navigate(href, opts) {
   }
 }
 
+// Render an offline route with no server: the page reads its data from the
+// local replica (db.useQuery), so it needs only its code, its params and the
+// identity-free props the last page had. Returns false when the URL is not an
+// offline route, or its code is not on the device.
+async function renderOffline(url, myEpoch, opts, push) {
+  const manifest = await loadManifest();
+  if (!manifest || !manifest.offline || !activeRoot) return false;
+  const offlineRoutes = {};
+  for (const r of manifest.offline.routes || []) offlineRoutes[r] = { path: r };
+  if (!matchRoute({ routes: offlineRoutes }, url.pathname)) return false;
+  const matched = matchRoute(manifest, url.pathname);
+  if (!matched) return false;
+  let route;
+  try {
+    route = await loadRouteEntry(matched.component);
+  } catch (e) {
+    return false;
+  }
+  if (myEpoch !== navEpoch) return true;
+  const prev = currentPageProps || {};
+  const searchParams = {};
+  url.searchParams.forEach((v, k) => {
+    searchParams[k] = v;
+  });
+  const data = {
+    component: matched.component,
+    props: {
+      pathname: url.pathname,
+      url: url.pathname,
+      host: prev.host || "",
+      params: matched.params,
+      searchParams,
+      auth: prev.auth,
+      session: prev.session,
+      headers: {},
+      cookies: {},
+    },
+    ssrData: {},
+  };
+  setNavParams(data);
+  currentPageProps = withClientProps(data);
+  const tree = withBoundary(
+    buildTree(route.Page, route.Layouts, currentPageProps),
+    data.component,
+    myEpoch,
+  );
+  currentComponent = data.component;
+  navPayloads.clear();
+  activeRoot.render(tree);
+  const target = url.pathname + url.search + url.hash;
+  if (opts && opts.replace) {
+    history.replaceState({ component: data.component }, "", target);
+  } else if (push) {
+    history.pushState({ component: data.component }, "", target);
+  }
+  window.dispatchEvent(new Event("pylon:navigation"));
+  renderedPath = location.pathname + location.search;
+  window.scrollTo(0, 0);
+  return true;
+}
+
 function installNavHandlers() {
   document.addEventListener("click", (e) => {
     if (e.defaultPrevented) return;
@@ -1225,6 +1324,11 @@ export interface PylonBundleManifest {
    *  independent); rendered into every SSR `<head>` against `public_prefix`.
    *  Absent when the app declares no `font({...})`. */
   fonts?: ManifestFonts;
+  /** `buildManifest({ offline })`: the install tags for every page's head,
+   *  the routes the client may render with no network, and the service
+   *  worker version. The worker is `pylon-sw.js` in the outdir. Absent when
+   *  the app did not opt in. */
+  offline?: BundleOffline;
   /** Set when the Tailwind compile failed for this build: the pages are
    *  serving WITHOUT styles. Dev surfaces it as an on-page banner (see
    *  pylonDevHud) — a silent unstyled page reads as a CSS bug, not a
@@ -1955,6 +2059,21 @@ export async function _doBuildInner(
       console.warn(`[pylon ssr] font build failed: ${fErr?.message ?? fErr}`);
     }
 
+    // Offline service worker (`buildManifest({ offline })`). After the CSS
+    // and fonts, because the precache list is every file the offline routes'
+    // pages load. A failure never kills the build: the app still works
+    // online, and the runtime answers 404 for `/pylon-sw.js`.
+    try {
+      const offline = readManifestOffline(fs, path, cwd, manifestFile);
+      if (offline) {
+        manifest.offline = await buildOfflineWorker(fs, path, outdir, manifest, offline);
+      }
+    } catch (oErr: any) {
+      if (opts.strict) throw new Error(`offline worker build failed: ${oErr?.message ?? oErr}`);
+      // eslint-disable-next-line no-console
+      console.warn(`[pylon offline] service worker build failed: ${oErr?.message ?? oErr}`);
+    }
+
     // App-overridable rate-limit page. The rate limiter short-circuits in the
     // Rust layer BEFORE SSR, so it can't render a route per (shed) request —
     // instead pre-render `app/rate-limit.tsx` ONCE here to a self-contained