feat(libs): pwa worker serves /_next/static/ cache first, evicts least recently used, routes only stored kinds through the fetch event, stores loaded files a few at a time

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Amiram_se 2026-10-10 12:19:43 +04:00
parent c801ab6d8e
commit 3e0cf9628d
3 changed files with 189 additions and 63 deletions

View File

@ -1,16 +1,26 @@
import type { InstallState, ServiceWorkerConfig } from './types'; 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'; 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 SERVICE_WORKER_SCOPE = '/';
export const CACHE_NAME_PREFIX = 'pwa-'; export const CACHE_NAME_PREFIX = 'pwa-';
export const SERVICE_WORKER_CONFIG: ServiceWorkerConfig = { 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', strategy: 'stale-while-revalidate',
// Raise v1 when the worker changes what it stores or how it keys it. // Raise v1 when the worker changes what it stores or how it keys it.
cacheName: `${CACHE_NAME_PREFIX}assets-v1`, cacheName: `${CACHE_NAME_PREFIX}assets-v1`,
cachePrefix: CACHE_NAME_PREFIX, 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, maxEntries: 200,
storeConcurrency: 4,
cacheLoadedMessage: 'pwa.cache-loaded', cacheLoadedMessage: 'pwa.cache-loaded',
paths: { paths: {
static: '/_next/static/', static: '/_next/static/',

View File

@ -1,12 +1,23 @@
// A classic script: no import or export, so writeServiceWorker can emit it as one file. // The worker: a classic script with no import or export, so writeServiceWorker can emit it as one
// writeServiceWorker writes SERVICE_WORKER_CONFIG above it. Type-checked by tsconfig.worker.json // file. writeServiceWorker writes SERVICE_WORKER_CONFIG above it; the worker reads nothing else.
// (the WebWorker lib); the lib's main tsconfig leaves it out. // 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; 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 & { type InstallEventWithRoutes = ExtendableEvent & {
addRoutes?: ( addRoutes?: (
rules: { condition: { requestMode: RequestMode }; source: 'network' }[], rules: { condition: RouterCondition; source: 'network' | 'fetch-event' }[],
) => Promise<void>; ) => Promise<void>;
}; };
@ -16,11 +27,11 @@ const {
cacheName, cacheName,
cachePrefix, cachePrefix,
maxEntries, maxEntries,
storeConcurrency,
cacheLoadedMessage, cacheLoadedMessage,
paths, paths,
} = SERVICE_WORKER_CONFIG; } = SERVICE_WORKER_CONFIG;
/** JS and CSS from /_next/static/, fonts from /fonts/, and the icon sprite: nothing else. */
function isStoredKind(url: URL): boolean { function isStoredKind(url: URL): boolean {
if (url.origin !== worker.location.origin) return false; if (url.origin !== worker.location.origin) return false;
const { pathname } = url; 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<Response | undefined> {
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<string[]> | undefined;
function storedOrder(cache: Cache): Promise<string[]> {
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<Cache | undefined> {
if (await caches.has(cacheName)) return caches.open(cacheName);
order = undefined;
return undefined;
}
async function store(request: Request, response: Response): Promise<void> { async function store(request: Request, response: Response): Promise<void> {
try { try {
const cache = await caches.open(cacheName); const cache = await openCache();
if (new URL(request.url).pathname === paths.sprite) { if (!cache) return;
// One sprite: a new ?v= replaces the older ones. const urls = await storedOrder(cache);
const versions = await cache.keys(request, { ignoreSearch: true });
await Promise.all(versions.map((version) => cache.delete(version)));
}
await cache.put(request, response); 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( await Promise.all(
keys [...replaced, ...evicted].map((other) =>
.slice(0, Math.max(0, keys.length - maxEntries)) cache.delete(other, { ignoreVary: true }),
.map((key) => cache.delete(key)), ),
); );
} catch { } catch {
// A full or blocked cache costs one network request next time, nothing more. // 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<void> {
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. // Matching validators mean the same file. A response without one counts as changed.
function isSameFile(stored: Response, fresh: Response): boolean { function isSameFile(stored: Response, fresh: Response): boolean {
const validator = (response: Response) => const validator = (response: Response) =>
@ -65,28 +154,25 @@ function isSameFile(stored: Response, fresh: Response): boolean {
return freshValidator !== null && freshValidator === validator(stored); return freshValidator !== null && freshValidator === validator(stored);
} }
async function fromNetwork( // waitUntil after an await is allowed here, because the respondWith promise is still pending.
event: FetchEvent, async function fromNetwork(event: FetchEvent): Promise<Response> {
stored?: Response,
): Promise<Response> {
const response = await fetch(event.request); const response = await fetch(event.request);
if (isStorable(response) && !(stored && isSameFile(stored, response))) { if (isStorable(response))
event.waitUntil(store(event.request, response.clone())); event.waitUntil(store(event.request, response.clone()));
}
return response; return response;
} }
async function staleWhileRevalidate(event: FetchEvent): Promise<Response> { async function staleWhileRevalidate(event: FetchEvent): Promise<Response> {
const stored = await caches.match(event.request, { const stored = await lookup(event.request);
cacheName, if (!stored) return fromNetwork(event);
ignoreVary: true, // 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.
const fresh = fromNetwork(event, stored);
if (!stored) return fresh;
// The check finishes after the response; when it fails, the stored copy stays.
event.waitUntil( event.waitUntil(
fresh.then( fetch(event.request).then(
() => undefined, (fresh) =>
isStorable(fresh) && !isSameFile(stored, fresh)
? store(event.request, fresh)
: touch(event.request),
() => undefined, () => undefined,
), ),
); );
@ -94,53 +180,76 @@ async function staleWhileRevalidate(event: FetchEvent): Promise<Response> {
} }
async function cacheFirst(event: FetchEvent): Promise<Response> { async function cacheFirst(event: FetchEvent): Promise<Response> {
const stored = await caches.match(event.request, { const stored = await lookup(event.request);
cacheName, if (!stored) return fromNetwork(event);
ignoreVary: true, event.waitUntil(touch(event.request));
}); return stored;
return stored ?? fromNetwork(event);
} }
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<Response> {
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; if (typeof value !== 'string') return null;
try { try {
const url = new URL(value); const url = new URL(value);
return isStoredKind(url) ? url : null; return isStoredKind(url) ? entryUrl(url.href) : null;
} catch { } catch {
return null; return null;
} }
} }
async function storeLoaded(urls: unknown[]): Promise<void> { async function storeLoaded(urls: unknown[]): Promise<void> {
// The message comes from a page, so every URL is checked again.
const wanted = urls const wanted = urls
.map(toStoredKindUrl) .map(toStoredKindHref)
.filter((url): url is URL => url !== null); .filter((href): href is string => href !== null);
await Promise.all( const queue = [...new Set(wanted)].slice(0, maxEntries);
wanted.slice(0, maxEntries).map(async (url) => { // A few at a time, so the worker never floods the disk while the page is in use.
if (await caches.match(url.href, { cacheName, ignoreVary: true })) return; const drain = async (): Promise<void> => {
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. // The page loaded it a moment ago, so the HTTP cache answers.
const response = await fetch(url.href).catch(() => null); const response = await fetch(href).catch(() => null);
if (response && isStorable(response)) { if (response && isStorable(response))
await store(new Request(url.href), response); await store(new Request(href), response);
} }
}), };
); await Promise.all(Array.from({ length: storeConcurrency }, drain));
} }
worker.addEventListener('install', (event) => { worker.addEventListener('install', (event) => {
void worker.skipWaiting(); void worker.skipWaiting();
// Chromium sends navigations straight to the network, so the worker never starts only to let a // Chromium sends every request the worker doesn't store straight to the network, so the worker
// page through. Other browsers use navigation preload (activate). // 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; const routable = event as InstallEventWithRoutes;
if (!routable.addRoutes) return; 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( event.waitUntil(
routable (async () => {
.addRoutes([ await addRoutes([
{ condition: { requestMode: 'navigate' }, source: 'network' }, { 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 await worker.registration.navigationPreload
?.enable() ?.enable()
.catch(() => undefined); .catch(() => undefined);
// The only place the cache is created (openCache).
await caches.open(cacheName).catch(() => undefined);
const names = await caches.keys(); const names = await caches.keys();
await Promise.all( await Promise.all(
names names
@ -173,15 +284,14 @@ worker.addEventListener('fetch', (event) => {
); );
return; return;
} }
// DevTools sends these; fetch rejects them. // DevTools sends these, and fetch rejects them.
if (request.cache === 'only-if-cached' && request.mode !== 'same-origin') { if (request.cache === 'only-if-cached' && request.mode !== 'same-origin')
return; return;
} const url = new URL(request.url);
if (isStoredKind(new URL(request.url))) event.respondWith(respond(event)); if (isStoredKind(url)) event.respondWith(respond(event, url));
}); });
worker.addEventListener('message', (event) => { worker.addEventListener('message', (event) => {
// The worker trusts no message: storeLoaded checks every URL again.
const message = event.data as Partial< const message = event.data as Partial<
import('./types').CacheLoadedMessage import('./types').CacheLoadedMessage
> | null; > | null;

View File

@ -4,18 +4,24 @@ export type ServiceWorkerOptions = {
enabled: boolean; 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'; export type CacheStrategy = 'stale-while-revalidate' | 'cache-first';
/** The worker's settings. writeServiceWorker writes them into public/sw.js; the worker reads nothing else. */ /** The worker's settings. writeServiceWorker writes them into public/sw.js; the worker reads nothing else. */
export type ServiceWorkerConfig = { 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; strategy: CacheStrategy;
/** The one cache, such as 'pwa-assets-v1'. */ /** The one cache, such as 'pwa-assets-v1'. */
cacheName: string; cacheName: string;
/** Every cache this lib owns starts with it. */ /** Every cache this lib owns starts with it. */
cachePrefix: string; cachePrefix: string;
/** Above it, the oldest entries go first. */ /** Above it, the least recently used entries go first (0052). */
maxEntries: number; 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. */ /** The type of the message that lists what the page already loaded. */
cacheLoadedMessage: string; cacheLoadedMessage: string;
paths: { paths: {