@ultimat3/pwa 1.0.0

package/src/strategies.ts

@@ -0,0 +1,207 @@
+/**
+ * The four caching strategies as named functions, plus the render-mode → strategy table.
+ * You never choose a strategy by hand: the route's render mode already encodes how fresh
+ * its bytes have to be, so the mapping is derived and the override is the exception.
+ */
+
+import { PwaStrategyExhaustedError } from './errors';
+
+export type StrategyName =
+  | 'cache-first'
+  | 'network-first'
+  | 'stale-while-revalidate'
+  | 'network-only';
+
+export const STRATEGY_NAMES: readonly StrategyName[] = [
+  'cache-first',
+  'network-first',
+  'stale-while-revalidate',
+  'network-only',
+];
+
+export type PwaRenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
+export type PwaOfflineStrategy = 'precache' | 'runtime' | 'network-only';
+
+/**
+ * Structural view of `@ultimat3/render`'s `RouteDescriptor`. Tier-4 packages must not
+ * import each other, so route data arrives as data and this is the shape it must have.
+ */
+export interface PwaRoute {
+  readonly path: string;
+  readonly surface: 'site' | 'app' | 'api';
+  readonly mode: PwaRenderMode;
+  readonly offline: PwaOfflineStrategy;
+  readonly dynamic?: boolean;
+  /** Explicit per-route override; wins over the derived strategy. */
+  readonly strategy?: StrategyName;
+  /** Content hash of the built HTML — the precache revision. */
+  readonly revision?: string;
+  readonly bytes?: number;
+  /** Companion data endpoint precached alongside the HTML. */
+  readonly dataUrl?: string;
+}
+
+/** Render mode → runtime strategy. The whole reason `sw.js` is generated, not written. */
+export const MODE_STRATEGY: Readonly<Record<PwaRenderMode, StrategyName>> = Object.freeze({
+  static: 'cache-first',
+  isr: 'stale-while-revalidate',
+  ssr: 'network-first',
+  stream: 'stale-while-revalidate',
+  spa: 'cache-first',
+});
+
+export function strategyFor(route: PwaRoute): StrategyName {
+  if (route.strategy !== undefined) return route.strategy;
+  // `network-only` is a declaration that this URL must never be answered from a cache.
+  if (route.offline === 'network-only') return 'network-only';
+  return MODE_STRATEGY[route.mode];
+}
+
+export interface StrategyEnv {
+  /** The named cache this strategy reads and writes. */
+  open(cacheName: string): Promise<StrategyCache>;
+  fetch(request: Request): Promise<Response>;
+}
+
+export interface StrategyCache {
+  match(request: Request): Promise<Response | undefined>;
+  put(request: Request, response: Response): Promise<void>;
+}
+
+export interface StrategyOptions {
+  readonly cacheName: string;
+  /** Served when the network fails and the cache is empty. */
+  readonly fallback?: () => Promise<Response>;
+}
+
+export async function cacheFirst(
+  request: Request,
+  env: StrategyEnv,
+  options: StrategyOptions,
+): Promise<Response> {
+  const cache = await env.open(options.cacheName);
+  const hit = await cache.match(request);
+  if (hit !== undefined) return hit;
+  return fetchAndStore(request, env, cache, options);
+}
+
+export async function networkFirst(
+  request: Request,
+  env: StrategyEnv,
+  options: StrategyOptions,
+): Promise<Response> {
+  const cache = await env.open(options.cacheName);
+  try {
+    const response = await env.fetch(request);
+    if (response.ok) await cache.put(request, response.clone());
+    return response;
+  } catch (error) {
+    const hit = await cache.match(request);
+    if (hit !== undefined) return hit;
+    if (options.fallback !== undefined) return options.fallback();
+    throw error;
+  }
+}
+
+/** Answer from the cache immediately, refresh behind the response. */
+export async function staleWhileRevalidate(
+  request: Request,
+  env: StrategyEnv,
+  options: StrategyOptions,
+): Promise<Response> {
+  const cache = await env.open(options.cacheName);
+  const hit = await cache.match(request);
+  const refresh = env
+    .fetch(request)
+    .then(async (response) => {
+      if (response.ok) await cache.put(request, response.clone());
+      return response;
+    })
+    .catch(async () => (hit !== undefined ? hit : fallbackOrThrow(options)));
+
+  if (hit !== undefined) {
+    void refresh.catch(() => undefined);
+    return hit;
+  }
+  return refresh;
+}
+
+export async function networkOnly(
+  request: Request,
+  env: StrategyEnv,
+  options: StrategyOptions,
+): Promise<Response> {
+  try {
+    return await env.fetch(request);
+  } catch (error) {
+    if (options.fallback !== undefined) return options.fallback();
+    throw error;
+  }
+}
+
+export const STRATEGY_FNS: Readonly<
+  Record<
+    StrategyName,
+    (request: Request, env: StrategyEnv, options: StrategyOptions) => Promise<Response>
+  >
+> = Object.freeze({
+  'cache-first': cacheFirst,
+  'network-first': networkFirst,
+  'stale-while-revalidate': staleWhileRevalidate,
+  'network-only': networkOnly,
+});
+
+async function fetchAndStore(
+  request: Request,
+  env: StrategyEnv,
+  cache: StrategyCache,
+  options: StrategyOptions,
+): Promise<Response> {
+  try {
+    const response = await env.fetch(request);
+    if (response.ok) await cache.put(request, response.clone());
+    return response;
+  } catch (error) {
+    if (options.fallback !== undefined) return options.fallback();
+    throw error;
+  }
+}
+
+async function fallbackOrThrow(options: StrategyOptions): Promise<Response> {
+  if (options.fallback !== undefined) return options.fallback();
+  throw new PwaStrategyExhaustedError({ cacheName: options.cacheName });
+}
+
+/**
+ * The emitted counterpart of the functions above. Kept as source strings because the
+ * service worker is a generated artifact with no bundler in the loop — the shapes are
+ * identical on purpose and `strategies.test.ts` asserts both halves stay in step.
+ */
+export const STRATEGY_SOURCE: Readonly<Record<StrategyName, string>> = Object.freeze({
+  'cache-first': `async function cacheFirst(req,cn,fb){
+  const c=await caches.open(cn);const hit=await c.match(req);if(hit)return hit;
+  try{const r=await fetch(req);if(r.ok)await c.put(req,r.clone());return r}catch(e){if(fb)return fb();throw e}
+}`,
+  'network-first': `async function networkFirst(req,cn,fb){
+  const c=await caches.open(cn);
+  try{const r=await fetch(req);if(r.ok)await c.put(req,r.clone());return r}
+  catch(e){const hit=await c.match(req);if(hit)return hit;if(fb)return fb();throw e}
+}`,
+  'stale-while-revalidate': `async function staleWhileRevalidate(req,cn,fb){
+  const c=await caches.open(cn);const hit=await c.match(req);
+  const refresh=fetch(req).then(async(r)=>{if(r.ok)await c.put(req,r.clone());return r})
+    .catch(()=>hit||(fb?fb():Response.error()));
+  if(hit){refresh.catch(()=>{});return hit}
+  return refresh
+}`,
+  'network-only': `async function networkOnly(req,cn,fb){
+  try{return await fetch(req)}catch(e){if(fb)return fb();throw e}
+}`,
+});
+
+export const STRATEGY_FN_NAMES: Readonly<Record<StrategyName, string>> = Object.freeze({
+  'cache-first': 'cacheFirst',
+  'network-first': 'networkFirst',
+  'stale-while-revalidate': 'staleWhileRevalidate',
+  'network-only': 'networkOnly',
+});

package/src/version-skew.ts

@@ -0,0 +1,187 @@
+/**
+ * Version skew — what actually breaks PWAs. A client that loaded build A keeps running
+ * for hours; build B deletes A's chunks; the next lazy import 404s and the app dies with
+ * a blank screen. Nothing here is optional:
+ *
+ *   immutable build id per deploy → the client sends it on every request →
+ *   old builds' assets are retained for N deploys → a stale client gets
+ *   `AppUpdateAvailable`, never a 404 → forced reload only after a grace period.
+ */
+
+import { BuildIdMissingError } from './errors';
+
+export const BUILD_ID_HEADER = 'x-ultimate-build';
+export const BUILD_ID_META = 'x-ultimate-build';
+
+export type DeployChannel = 'production' | 'preview' | 'branch';
+
+export interface BuildIdInput {
+  /** Preferred source: the commit is the deploy's real identity. */
+  readonly gitSha?: string;
+  /** Milliseconds; only used when there is no sha. */
+  readonly timestamp?: number;
+  readonly channel?: DeployChannel;
+  /** Branch or PR slug; keeps preview ids from ever colliding with production. */
+  readonly ref?: string;
+}
+
+/**
+ * Deterministic for a given input — two builds of the same commit on the same channel
+ * produce the same id, so a rebuild does not needlessly evict every client's cache.
+ */
+export function buildId(input: BuildIdInput = {}): string {
+  const channel = input.channel ?? 'production';
+  const base = input.gitSha ?? String(input.timestamp ?? 0);
+  if (base === '' || base === '0') {
+    throw new BuildIdMissingError(
+      'cannot derive a build id: no gitSha and no timestamp',
+      'set GIT_SHA in the build environment (docker build --build-arg GIT_SHA=$(git rev-parse HEAD))',
+    );
+  }
+  const short = base.slice(0, 12);
+  const ref = input.ref === undefined ? '' : `-${slug(input.ref)}`;
+  return channel === 'production' ? short : `${channel}${ref}-${short}`;
+}
+
+function slug(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 24);
+}
+
+export function assertBuildId(value: string | undefined | null): asserts value is string {
+  if (value === undefined || value === null || value.trim() === '') {
+    throw new BuildIdMissingError(
+      'the build id is empty, so caches cannot be keyed and skew cannot be detected',
+      'set GIT_SHA in the build environment and pass it to generateServiceWorker(routes, config, buildId)',
+    );
+  }
+}
+
+/**
+ * Every cache name carries the build id, so a preview deploy physically cannot write into
+ * the production cache even on the same origin — the classic way a branch deploy poisons
+ * production for everyone who visited it once.
+ */
+export function cacheNamespace(id: string, kind: 'precache' | 'runtime' | 'pages'): string {
+  assertBuildId(id);
+  return `x-${kind}-${id}`;
+}
+
+export interface Deploy {
+  readonly buildId: string;
+  /** Epoch milliseconds. */
+  readonly deployedAt: number;
+  readonly channel?: DeployChannel;
+}
+
+export interface RetentionPlan {
+  readonly retain: readonly string[];
+  readonly evict: readonly string[];
+  readonly caches: readonly string[];
+}
+
+/**
+ * Keep the last N builds' assets alive. N is how many deploys a tab may sit open across
+ * before it is allowed to break; 3 is the sane default for a daily-deploy team.
+ */
+export function retentionPlan(deploys: readonly Deploy[], keep = 3): RetentionPlan {
+  const ordered = [...deploys].sort((a, b) => b.deployedAt - a.deployedAt);
+  const retained = ordered.slice(0, Math.max(1, keep));
+  const evicted = ordered.slice(Math.max(1, keep));
+  return {
+    retain: retained.map((d) => d.buildId),
+    evict: evicted.map((d) => d.buildId),
+    caches: retained.flatMap((d) => [
+      cacheNamespace(d.buildId, 'precache'),
+      cacheNamespace(d.buildId, 'runtime'),
+      cacheNamespace(d.buildId, 'pages'),
+    ]),
+  };
+}
+
+export type SkewState = 'current' | 'stale' | 'unknown';
+
+/** `unknown` means "no id sent" — a first load, a crawler, or a cache-busted client. */
+export function detectSkew(
+  clientBuildId: string | null | undefined,
+  serverBuildId: string,
+): SkewState {
+  if (clientBuildId === null || clientBuildId === undefined || clientBuildId.trim() === '') {
+    return 'unknown';
+  }
+  return clientBuildId === serverBuildId ? 'current' : 'stale';
+}
+
+export type ForceReason = 'security' | 'breaking-protocol' | 'never';
+
+export interface UpdatePolicyInput {
+  /** How long a stale client may keep running before the reload is forced. */
+  readonly graceMs?: number;
+  readonly forceOn?: readonly ForceReason[];
+}
+
+export interface UpdatePolicy {
+  readonly graceMs: number;
+  readonly forceOn: readonly ForceReason[];
+  shouldForce(reason: ForceReason, staleForMs: number): boolean;
+}
+
+export const DEFAULT_GRACE_MS = 6 * 60 * 60 * 1000;
+
+export function updatePolicy(input: UpdatePolicyInput = {}): UpdatePolicy {
+  const graceMs = input.graceMs ?? DEFAULT_GRACE_MS;
+  const forceOn = input.forceOn ?? ['security'];
+  return {
+    graceMs,
+    forceOn,
+    // A security patch still respects the grace window; it just does not wait forever.
+    shouldForce: (reason, staleForMs) => forceOn.includes(reason) && staleForMs >= graceMs,
+  };
+}
+
+/**
+ * The client-side contract. The SW posts this to every controlled page; the app shows an
+ * unobtrusive "refresh to update" affordance and reloads on the user's terms — unless
+ * `forced`, in which case it reloads at `deadlineAt`.
+ */
+export interface AppUpdateAvailable {
+  readonly type: 'AppUpdateAvailable';
+  readonly from: string;
+  readonly to: string;
+  readonly forced: boolean;
+  /** Epoch milliseconds after which the client reloads itself. Null when not forced. */
+  readonly deadlineAt: number | null;
+}
+
+export const APP_UPDATE_AVAILABLE = 'AppUpdateAvailable' as const;
+
+export interface UpdateSignalInput {
+  readonly clientBuildId: string | null | undefined;
+  readonly serverBuildId: string;
+  readonly policy: UpdatePolicy;
+  readonly reason?: ForceReason;
+  readonly staleForMs?: number;
+  readonly now?: number;
+}
+
+/** Null when the client is current or unknown — no signal, no nag. */
+export function updateSignal(input: UpdateSignalInput): AppUpdateAvailable | null {
+  const state = detectSkew(input.clientBuildId, input.serverBuildId);
+  if (state !== 'stale') return null;
+
+  const reason = input.reason ?? 'never';
+  const staleForMs = input.staleForMs ?? 0;
+  const forced = input.policy.shouldForce(reason, staleForMs);
+  const now = input.now ?? Date.now();
+
+  return {
+    type: APP_UPDATE_AVAILABLE,
+    from: String(input.clientBuildId),
+    to: input.serverBuildId,
+    forced,
+    deadlineAt: forced ? now : null,
+  };
+}