diff --git a/packages/libs/src/pwa/constants.ts b/packages/libs/src/pwa/constants.ts index d61efc2..e29488f 100644 --- a/packages/libs/src/pwa/constants.ts +++ b/packages/libs/src/pwa/constants.ts @@ -1,16 +1,26 @@ import type { InstallState, ServiceWorkerConfig } from './types'; +/** Fixed: browsers check this URL for updates, so it is never renamed or removed. */ export const SERVICE_WORKER_URL = '/sw.js'; + +/** + * Both apps serve one origin (0001), so they share this registration and one cache: they ship the + * same worker and the same `NEXT_PUBLIC_SERVICE_WORKER_ENABLED` (0053). + */ export const SERVICE_WORKER_SCOPE = '/'; export const CACHE_NAME_PREFIX = 'pwa-'; export const SERVICE_WORKER_CONFIG: ServiceWorkerConfig = { - // The default; only the developer switches an app to 'cache-first'. + // Fonts and the sprite only: /_next/static/ is always cache first (0051). Only the developer + // switches an app to 'cache-first'. strategy: 'stale-while-revalidate', // Raise v1 when the worker changes what it stores or how it keys it. cacheName: `${CACHE_NAME_PREFIX}assets-v1`, cachePrefix: CACHE_NAME_PREFIX, + // One deploy of both apps, and the least recently used go first (0052), so a device that uses + // one app keeps all of that app's files. maxEntries: 200, + storeConcurrency: 4, cacheLoadedMessage: 'pwa.cache-loaded', paths: { static: '/_next/static/', diff --git a/packages/libs/src/pwa/service-worker.ts b/packages/libs/src/pwa/service-worker.ts index 50af960..a7bf01b 100644 --- a/packages/libs/src/pwa/service-worker.ts +++ b/packages/libs/src/pwa/service-worker.ts @@ -1,12 +1,23 @@ -// A classic script: no import or export, so writeServiceWorker can emit it as one file. -// writeServiceWorker writes SERVICE_WORKER_CONFIG above it. Type-checked by tsconfig.worker.json -// (the WebWorker lib); the lib's main tsconfig leaves it out. +// The worker: a classic script with no import or export, so writeServiceWorker can emit it as one +// file. writeServiceWorker writes SERVICE_WORKER_CONFIG above it; the worker reads nothing else. +// It stores only JS and CSS from /_next/static/, fonts from /fonts/, and the icon sprite. Every +// other request, pages and data included, reaches the network untouched, and so do these when +// Cache Storage fails. Chromium sends the others past the worker (install); other browsers wake +// the worker for them, and it lets them through. Type-checked by tsconfig.worker.json (the +// WebWorker lib); the lib's main tsconfig leaves it out. declare const SERVICE_WORKER_CONFIG: import('./types').ServiceWorkerConfig; +/** A Static Routing API condition, with the parts this worker uses (Chromium 123 and later). */ +type RouterCondition = + | { requestMode: RequestMode } + | { urlPattern: URLPattern } + | { or: RouterCondition[] }; + +/** The Static Routing API: the first rule whose condition matches picks the source. */ type InstallEventWithRoutes = ExtendableEvent & { addRoutes?: ( - rules: { condition: { requestMode: RequestMode }; source: 'network' }[], + rules: { condition: RouterCondition; source: 'network' | 'fetch-event' }[], ) => Promise; }; @@ -16,11 +27,11 @@ const { cacheName, cachePrefix, maxEntries, + storeConcurrency, cacheLoadedMessage, paths, } = SERVICE_WORKER_CONFIG; -/** JS and CSS from /_next/static/, fonts from /fonts/, and the icon sprite: nothing else. */ function isStoredKind(url: URL): boolean { if (url.origin !== worker.location.origin) return false; const { pathname } = url; @@ -37,26 +48,104 @@ function isStorable(response: Response): boolean { ); } +/** The URL an entry is keyed by: Cache Storage ignores the fragment. */ +function entryUrl(url: string): string { + const parsed = new URL(url); + parsed.hash = ''; + return parsed.href; +} + +/** The stored copy, or `undefined` when there is none or Cache Storage fails, so the network answers. */ +async function lookup( + request: Request | string, +): Promise { + try { + return await caches.match(request, { cacheName, ignoreVary: true }); + } catch { + return undefined; + } +} + +// The stored URLs, least recently used first (0052). Read once per worker start and kept in step with +// every put and delete, so storing never lists the cache again. A put moves its entry to the end of +// keys(), so a restarted worker reads the same order back. +let order: Promise | undefined; + +function storedOrder(cache: Cache): Promise { + order ??= cache.keys().then( + (keys) => keys.map((key) => entryUrl(key.url)), + (error: unknown) => { + order = undefined; + throw error; + }, + ); + return order; +} + +/** + * The cache, or `undefined` once something else deleted it: the kill switch in another tab, or the + * visitor clearing site data. Only activation creates it, so a worker that outlives its + * registration never leaves an orphan cache behind; it forgets the order of the deleted one and + * stores nothing until the next activation. + */ +async function openCache(): Promise { + if (await caches.has(cacheName)) return caches.open(cacheName); + order = undefined; + return undefined; +} + async function store(request: Request, response: Response): Promise { try { - const cache = await caches.open(cacheName); - if (new URL(request.url).pathname === paths.sprite) { - // One sprite: a new ?v= replaces the older ones. - const versions = await cache.keys(request, { ignoreSearch: true }); - await Promise.all(versions.map((version) => cache.delete(version))); - } + const cache = await openCache(); + if (!cache) return; + const urls = await storedOrder(cache); await cache.put(request, response); - const keys = await cache.keys(); + const url = entryUrl(request.url); + // One sprite: a new ?v= replaces the older ones. + const replaced = + new URL(url).pathname === paths.sprite + ? urls.filter( + (other) => + other !== url && new URL(other).pathname === paths.sprite, + ) + : []; + // The entry moves to the most recently used end. No await until the order is updated, so + // concurrent stores never see half of it. + const kept = urls.filter( + (other) => other !== url && !replaced.includes(other), + ); + kept.push(url); + const evicted = kept.splice(0, Math.max(0, kept.length - maxEntries)); + urls.splice(0, urls.length, ...kept); await Promise.all( - keys - .slice(0, Math.max(0, keys.length - maxEntries)) - .map((key) => cache.delete(key)), + [...replaced, ...evicted].map((other) => + cache.delete(other, { ignoreVary: true }), + ), ); } catch { // A full or blocked cache costs one network request next time, nothing more. } } +/** + * Stores a hit again when it nears the eviction end, which moves it to the most recently used end, + * so the files every page uses outlive the dead chunks of older deploys. A file is rewritten at + * most once per half a cache of new entries. + */ +async function touch(request: Request): Promise { + try { + const cache = await openCache(); + if (!cache) return; + const urls = await storedOrder(cache); + const index = urls.indexOf(entryUrl(request.url)); + if (index === -1 || index >= urls.length - maxEntries / 2) return; + const stored = await cache.match(request, { ignoreVary: true }); + if (stored) await store(request, stored); + } catch { + // The entry keeps its place; at worst it's evicted and downloaded again. + } +} + // Matching validators mean the same file. A response without one counts as changed. function isSameFile(stored: Response, fresh: Response): boolean { const validator = (response: Response) => @@ -65,28 +154,25 @@ function isSameFile(stored: Response, fresh: Response): boolean { return freshValidator !== null && freshValidator === validator(stored); } -async function fromNetwork( - event: FetchEvent, - stored?: Response, -): Promise { +// waitUntil after an await is allowed here, because the respondWith promise is still pending. +async function fromNetwork(event: FetchEvent): Promise { const response = await fetch(event.request); - if (isStorable(response) && !(stored && isSameFile(stored, response))) { + if (isStorable(response)) event.waitUntil(store(event.request, response.clone())); - } return response; } async function staleWhileRevalidate(event: FetchEvent): Promise { - const stored = await caches.match(event.request, { - cacheName, - ignoreVary: true, - }); - const fresh = fromNetwork(event, stored); - if (!stored) return fresh; - // The check finishes after the response; when it fails, the stored copy stays. + const stored = await lookup(event.request); + if (!stored) return fromNetwork(event); + // The check finishes after the response: a changed file replaces the copy, an unchanged one + // counts as used, and a failed check keeps the copy. event.waitUntil( - fresh.then( - () => undefined, + fetch(event.request).then( + (fresh) => + isStorable(fresh) && !isSameFile(stored, fresh) + ? store(event.request, fresh) + : touch(event.request), () => undefined, ), ); @@ -94,53 +180,76 @@ async function staleWhileRevalidate(event: FetchEvent): Promise { } async function cacheFirst(event: FetchEvent): Promise { - const stored = await caches.match(event.request, { - cacheName, - ignoreVary: true, - }); - return stored ?? fromNetwork(event); + const stored = await lookup(event.request); + if (!stored) return fromNetwork(event); + event.waitUntil(touch(event.request)); + return stored; } -const respond = strategy === 'cache-first' ? cacheFirst : staleWhileRevalidate; +// Next.js names every /_next/static/ file after its content, so a stored copy is never outdated +// and needs no check (0051). Fonts and the sprite follow the configured strategy. +function respond(event: FetchEvent, url: URL): Promise { + const checked = + strategy === 'stale-while-revalidate' && + !url.pathname.startsWith(paths.static); + return checked ? staleWhileRevalidate(event) : cacheFirst(event); +} -function toStoredKindUrl(value: unknown): URL | null { +function toStoredKindHref(value: unknown): string | null { if (typeof value !== 'string') return null; try { const url = new URL(value); - return isStoredKind(url) ? url : null; + return isStoredKind(url) ? entryUrl(url.href) : null; } catch { return null; } } async function storeLoaded(urls: unknown[]): Promise { + // The message comes from a page, so every URL is checked again. const wanted = urls - .map(toStoredKindUrl) - .filter((url): url is URL => url !== null); - await Promise.all( - wanted.slice(0, maxEntries).map(async (url) => { - if (await caches.match(url.href, { cacheName, ignoreVary: true })) return; + .map(toStoredKindHref) + .filter((href): href is string => href !== null); + const queue = [...new Set(wanted)].slice(0, maxEntries); + // A few at a time, so the worker never floods the disk while the page is in use. + const drain = async (): Promise => { + for (let href = queue.shift(); href; href = queue.shift()) { + if (await lookup(href)) continue; // The page loaded it a moment ago, so the HTTP cache answers. - const response = await fetch(url.href).catch(() => null); - if (response && isStorable(response)) { - await store(new Request(url.href), response); - } - }), - ); + const response = await fetch(href).catch(() => null); + if (response && isStorable(response)) + await store(new Request(href), response); + } + }; + await Promise.all(Array.from({ length: storeConcurrency }, drain)); } worker.addEventListener('install', (event) => { void worker.skipWaiting(); - // Chromium sends navigations straight to the network, so the worker never starts only to let a - // page through. Other browsers use navigation preload (activate). + // Chromium sends every request the worker doesn't store straight to the network, so the worker + // never starts only to let a page, an RSC payload, or an API call through. The patterns are only + // a first cut: the fetch listener still checks the origin and the file type. Other browsers use + // navigation preload for pages (activate) and wake the worker for the rest. const routable = event as InstallEventWithRoutes; if (!routable.addRoutes) return; + const addRoutes = routable.addRoutes.bind(routable); + const stored = [ + `${paths.static}*.js`, + `${paths.static}*.css`, + `${paths.fonts}*.woff2`, + paths.sprite, + ].map((pathname) => ({ urlPattern: new URLPattern({ pathname }) })); + // Rules append in order. Two calls, so a Chromium that rejects the second still keeps the first. event.waitUntil( - routable - .addRoutes([ + (async () => { + await addRoutes([ { condition: { requestMode: 'navigate' }, source: 'network' }, - ]) - .catch(() => undefined), + ]).catch(() => undefined); + await addRoutes([ + { condition: { or: stored }, source: 'fetch-event' }, + { condition: { urlPattern: new URLPattern({}) }, source: 'network' }, + ]).catch(() => undefined); + })(), ); }); @@ -150,6 +259,8 @@ worker.addEventListener('activate', (event) => { await worker.registration.navigationPreload ?.enable() .catch(() => undefined); + // The only place the cache is created (openCache). + await caches.open(cacheName).catch(() => undefined); const names = await caches.keys(); await Promise.all( names @@ -173,15 +284,14 @@ worker.addEventListener('fetch', (event) => { ); return; } - // DevTools sends these; fetch rejects them. - if (request.cache === 'only-if-cached' && request.mode !== 'same-origin') { + // DevTools sends these, and fetch rejects them. + if (request.cache === 'only-if-cached' && request.mode !== 'same-origin') return; - } - if (isStoredKind(new URL(request.url))) event.respondWith(respond(event)); + const url = new URL(request.url); + if (isStoredKind(url)) event.respondWith(respond(event, url)); }); worker.addEventListener('message', (event) => { - // The worker trusts no message: storeLoaded checks every URL again. const message = event.data as Partial< import('./types').CacheLoadedMessage > | null; diff --git a/packages/libs/src/pwa/types.ts b/packages/libs/src/pwa/types.ts index cc7e7b2..f2e9370 100644 --- a/packages/libs/src/pwa/types.ts +++ b/packages/libs/src/pwa/types.ts @@ -4,18 +4,24 @@ export type ServiceWorkerOptions = { enabled: boolean; }; +/** + * How the worker serves fonts and the icon sprite: 'stale-while-revalidate' unless the developer + * explicitly chose 'cache-first'. `/_next/static/` is always cache first (0051). + */ export type CacheStrategy = 'stale-while-revalidate' | 'cache-first'; /** The worker's settings. writeServiceWorker writes them into public/sw.js; the worker reads nothing else. */ export type ServiceWorkerConfig = { - /** 'stale-while-revalidate' unless the developer explicitly chose 'cache-first'. */ + /** For fonts and the sprite; 'stale-while-revalidate' unless the developer chose 'cache-first'. */ strategy: CacheStrategy; /** The one cache, such as 'pwa-assets-v1'. */ cacheName: string; /** Every cache this lib owns starts with it. */ cachePrefix: string; - /** Above it, the oldest entries go first. */ + /** Above it, the least recently used entries go first (0052). */ maxEntries: number; + /** How many files the worker stores at once from the page's list of what it loaded. */ + storeConcurrency: number; /** The type of the message that lists what the page already loaded. */ cacheLoadedMessage: string; paths: {