@pwa-platform/engine-workbox 0.1.0-beta.0 → 0.1.0-beta.2

package/dist/worker/index.d.ts

@@ -1,4 +1,6 @@
 export { createPrecacheEngine } from "./engine.js";
 export type { PwaPrecacheActivateResult, PwaPrecacheEngine, PwaPrecacheInstallResult } from "./engine.js";
 export type { PwaPrecacheEngineOptions, PwaPrecacheManifestEntry } from "./options.js";
+export { createRuntimeCacheEngine } from "./runtime.js";
+export type { PwaRuntimeCacheEngine, PwaRuntimeCacheEngineOptions, PwaRuntimeCacheHit, PwaRuntimeCacheResult } from "./runtime.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/worker/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC"}

package/dist/worker/index.js

@@ -1,4 +1,5 @@
 // Worker entry (`@pwa-platform/engine-workbox/worker`): runs in a service worker after bundling and depends only
-// on workbox-precaching and workbox-core, never on Node modules.
+// on workbox-precaching, workbox-strategies, workbox-expiration and workbox-core, never on Node modules.
 export { createPrecacheEngine } from "./engine.js";
+export { createRuntimeCacheEngine } from "./runtime.js";
 //# sourceMappingURL=index.js.map

package/dist/worker/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,iEAAiE;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,yGAAyG;AACzG,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/worker/runtime.d.ts

@@ -0,0 +1,36 @@
+export type PwaRuntimeCacheEngineOptions = {
+    readonly cacheName: string;
+    readonly strategy: "network-first" | "stale-while-revalidate";
+    readonly maxEntries: number;
+    readonly maxAgeSeconds: number;
+    /** Platform admission check; the engine writes to the cache only when it resolves true. */
+    readonly admit: (response: Response) => Promise<boolean>;
+    /**
+     * 1-30 integer seconds. Only meaningful for strategy "network-first": passed straight through to Workbox's
+     * `NetworkFirst` so a cache hit is served once the timeout elapses, even while the network request is still
+     * pending. Ignored for "stale-while-revalidate", which never waits on the network before serving a cache hit.
+     * Omitted entirely (not `undefined`) when unset, so an engine built without it constructs `NetworkFirst`
+     * exactly as before this option existed.
+     */
+    readonly networkTimeoutSeconds?: number;
+};
+export type PwaRuntimeCacheHit = {
+    readonly cachedAt: number;
+    readonly reason: "network-failed" | "network-timeout" | "stale-while-revalidate";
+};
+export type PwaRuntimeCacheResult = {
+    readonly response: Response;
+    readonly servedFromCache: PwaRuntimeCacheHit | null;
+};
+/** Runtime-cache port used by the platform worker (sw-runtime); it only acts when `handle` is called. */
+export type PwaRuntimeCacheEngine = {
+    /** Handles one fetch event; registers its own background work with event.waitUntil. */
+    handle(event: FetchEvent): Promise<PwaRuntimeCacheResult>;
+};
+/**
+ * Creates the runtime-cache port for one plan entry. Write-time admission and the read-time expiry stamp are the
+ * platform's own; `ExpirationPlugin` only enforces `maxEntries` (LRU) and `purgeOnQuotaError`, never `maxAgeSeconds`
+ * (see below).
+ */
+export declare function createRuntimeCacheEngine(options: PwaRuntimeCacheEngineOptions): PwaRuntimeCacheEngine;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/worker/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/worker/runtime.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,wBAAwB,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CACzC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,wBAAwB,CAAC;CAClF,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,kBAAkB,GAAG,IAAI,CAAA;CAAE,CAAC;AAEzH,yGAAyG;AACzG,MAAM,MAAM,qBAAqB,GAAG;IAClC,uFAAuF;IACvF,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CAC3D,CAAC;AAOF;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,4BAA4B,GAAG,qBAAqB,CAyGrG"}

package/dist/worker/runtime.js

@@ -0,0 +1,107 @@
+import { ExpirationPlugin } from "workbox-expiration";
+import { NetworkFirst, StaleWhileRevalidate } from "workbox-strategies";
+/** Internal header on the cached copy only; stripped before the response reaches the page. Never a public API. */
+const STAMP_HEADER = "x-pwa-platform-cached-at";
+/** Clones `response`'s status, statusText and body with `headers` in place of its own. */
+function withHeaders(response, headers) {
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}
+/**
+ * Creates the runtime-cache port for one plan entry. Write-time admission and the read-time expiry stamp are the
+ * platform's own; `ExpirationPlugin` only enforces `maxEntries` (LRU) and `purgeOnQuotaError`, never `maxAgeSeconds`
+ * (see below).
+ */
+export function createRuntimeCacheEngine(options) {
+    const { cacheName, strategy, maxEntries, maxAgeSeconds, admit, networkTimeoutSeconds } = options;
+    // Per-request correlation for servedFromCache: a module- or closure-level "last hit" variable would leak between
+    // concurrent fetch events on the same engine instance, so hits are keyed by the FetchEvent of the call that
+    // produced them and read back once, in `handle`.
+    const hits = new WeakMap();
+    // Marks the moment a network-first request's own network fetch fails. Workbox's `fetchDidFail` plugin hook fires
+    // synchronously, inside `fetch()`'s catch block, only when `fetch()` itself throws (a real network failure) --
+    // never for a 4xx/5xx response, and never for the timeout path. NetworkFirst reaches a cache hit through exactly
+    // one of two routes (see workbox-strategies@7.4.1 NetworkFirst.js `_handle`): the network-failure catch in
+    // `_getNetworkPromise` (which always runs `fetchDidFail` before calling `handler.cacheMatch`), or the timeout
+    // callback in `_getTimeoutPromise` (which calls `handler.cacheMatch` directly and never touches `fetchDidFail`).
+    // So when `cachedResponseWillBeUsed` fires, checking whether this event's fetch already failed distinguishes the
+    // two reliably: it reads a flag set synchronously by Workbox's own callback ordering, rather than racing a
+    // second timer of our own against Workbox's `networkTimeoutSeconds` timer.
+    const networkFailed = new WeakMap();
+    // fetchDidFail is only meaningful when a timeout is in play (see the reason ternary in cachedResponseWillBeUsed
+    // below: without a timeout the reason always falls back to "network-failed" regardless of this flag), so it is
+    // included in the plugin object only for strategy "network-first" with a timeout configured. An engine built
+    // without a timeout is therefore constructed with exactly the plugin list this module had before this option
+    // existed (no fetchDidFail key on platformPlugin at all).
+    const trackNetworkFailure = strategy === "network-first" && networkTimeoutSeconds !== undefined;
+    const platformPlugin = {
+        ...(trackNetworkFailure
+            ? {
+                async fetchDidFail({ event }) {
+                    if (event instanceof FetchEvent)
+                        networkFailed.set(event, true);
+                },
+            }
+            : {}),
+        // Registering this hook is also what stops Workbox from prepending its own default cacheOkAndOpaque plugin
+        // (workbox-strategies only does that when no plugin already defines cacheWillUpdate) — admission here is the
+        // only gate, private/opaque/non-200 responses are never written unless `admit` itself accepts them.
+        async cacheWillUpdate({ response }) {
+            if (!(await admit(response)))
+                return null;
+            const headers = new Headers(response.headers);
+            headers.set(STAMP_HEADER, String(Date.now()));
+            return withHeaders(response, headers);
+        },
+        async cachedResponseWillBeUsed({ request, cachedResponse, event, }) {
+            if (cachedResponse === undefined)
+                return cachedResponse;
+            const stampValue = cachedResponse.headers.get(STAMP_HEADER);
+            const stamp = stampValue === null ? Number.NaN : Number(stampValue);
+            // Expiry is decided solely by this stamp, never by ExpirationPlugin's own Date-header check: that check
+            // vetoes entries at read time using the server's Date header, which would reject a freshly written copy of a
+            // CDN-cached (and therefore already-old) response. ExpirationPlugin is configured below without
+            // maxAgeSeconds so its own freshness check never runs.
+            if (!Number.isFinite(stamp) || Date.now() - stamp > maxAgeSeconds * 1000) {
+                const cache = await self.caches.open(cacheName);
+                await cache.delete(request);
+                return undefined;
+            }
+            if (event instanceof FetchEvent) {
+                const reason = strategy !== "network-first"
+                    ? "stale-while-revalidate"
+                    : networkFailed.get(event) === true
+                        ? "network-failed"
+                        : networkTimeoutSeconds !== undefined
+                            ? "network-timeout"
+                            : "network-failed";
+                hits.set(event, { cachedAt: stamp, reason });
+            }
+            const headers = new Headers(cachedResponse.headers);
+            headers.delete(STAMP_HEADER);
+            return withHeaders(cachedResponse, headers);
+        },
+    };
+    // maxAgeSeconds intentionally omitted: see the comment in cachedResponseWillBeUsed above.
+    const expirationPlugin = new ExpirationPlugin({ maxEntries, purgeOnQuotaError: true });
+    // The platform plugin must run before ExpirationPlugin so a request expired by our stamp is deleted (and its
+    // cachedResponse turned into undefined) before ExpirationPlugin's own cachedResponseWillBeUsed sees it.
+    const plugins = [platformPlugin, expirationPlugin];
+    const strategyInstance = strategy === "network-first"
+        ? new NetworkFirst(networkTimeoutSeconds === undefined ? { cacheName, plugins } : { cacheName, plugins, networkTimeoutSeconds })
+        : new StaleWhileRevalidate({ cacheName, plugins });
+    return {
+        async handle(event) {
+            const [responseDone, handlerDone] = strategyInstance.handleAll({ event, request: event.request });
+            // A write failure (including QuotaExceededError, which purgeOnQuotaError above reacts to globally) must
+            // never surface as an unhandled rejection or affect the response already given to the page; handlerDone only
+            // covers Workbox's own background work (cache writes), which is otherwise unobserved once ignored here.
+            event.waitUntil(handlerDone.catch(() => undefined));
+            const response = await responseDone;
+            const servedFromCache = hits.get(event) ?? null;
+            hits.delete(event);
+            networkFailed.delete(event);
+            return { response, servedFromCache };
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/worker/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/worker/runtime.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pwa-platform/engine-workbox",
-  "version": "0.1.0-beta.0",
-  "description": "Internal Workbox precache engine for PWA Platform.",
+  "version": "0.1.0-beta.2",
+  "description": "Internal Workbox precache and runtime-cache engine for PWA Platform.",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -19,8 +19,10 @@
   ],
   "dependencies": {
     "workbox-core": "7.4.1",
+    "workbox-expiration": "7.4.1",
     "workbox-precaching": "7.4.1",
-    "@pwa-platform/contracts": "0.1.0-beta.0"
+    "workbox-strategies": "7.4.1",
+    "@pwa-platform/contracts": "0.1.0-beta.2"
   },
   "devDependencies": {
     "@playwright/test": "1.63.0",