/** * §17–§18. Service Worker contract. * * One physical registration per scope covers PWA lifecycle, verified static * asset fetch, Web Push and the optional sync wake-up. A separate registration * for any of those is prohibited. */ export const SERVICE_WORKER_PROTOCOL_VERSION = 1 as const; export const SERVICE_WORKER_CACHE_SCHEMA_VERSION = 1 as const; export const SERVICE_WORKER_SCRIPT_PATH = "service-worker.js" as const; export const SERVICE_WORKER_BOUNDS = Object.freeze({ assets: 256, singleAssetBytes: 2 * 1024 * 1024, assetSetBytes: 5 * 1024 * 1024, fetchConcurrency: 4, installDeadlineMs: 60_000, clientDrainMs: 30_000, updateCheckIntervalMs: 6 * 60 * 60 * 1_000, retainedPreviousCaches: 1, reloadGuardBytes: 512, reloadGuardTtlMs: 10 * 60 * 1_000, }); export type ServiceWorkerHandlerId = | "WEB_PUSH" | "PWA_STATIC_ASSETS" | "OFFLINE_SYNC_WAKEUP"; /** * §17.3. Removal is staged. `ACTIVE` never transitions directly to `null`: * a registration that already exists in a browser must first be unregistered, * then have its owned resources purged, before the source may disappear. */ export type InstalledServiceWorkerSelection = | Readonly<{ mode: "ACTIVE"; scriptPath: typeof SERVICE_WORKER_SCRIPT_PATH; handlers: readonly ServiceWorkerHandlerId[]; }> | Readonly<{ mode: "REMOVE_REGISTRATION"; scriptPath: typeof SERVICE_WORKER_SCRIPT_PATH; }> | Readonly<{ mode: "PURGE_OWNED_RESOURCES"; scriptPath: typeof SERVICE_WORKER_SCRIPT_PATH; }>; /** §17.7. Page and worker read the same compile-time identity tuple. */ export type ServiceWorkerProtocolIdentity = Readonly<{ serviceWorkerProtocolVersion: typeof SERVICE_WORKER_PROTOCOL_VERSION; cacheSchemaVersion: typeof SERVICE_WORKER_CACHE_SCHEMA_VERSION; buildId: string; releaseId: string; contractSetDigest: string; staticAssetSetDigest: string; }>; export type ServiceWorkerMessageKind = | "PAGE_HELLO" | "WORKER_HELLO_ACK" | "UPDATE_READY" | "ACTIVATE_REQUEST" | "ACTIVATE_ACCEPTED" | "ACTIVATE_REJECTED" | "CLIENT_DRAIN_REQUEST" | "CLIENT_DRAINED" | "ACTIVATED_RELOAD_REQUIRED" | "CACHE_RESET_REQUEST" | "CACHE_RESET_RESULT" | "SYNC_WAKE_OBSERVED"; export type ServiceWorkerMessage = Readonly<{ protocolVersion: typeof SERVICE_WORKER_PROTOCOL_VERSION; kind: ServiceWorkerMessageKind; messageId: string; sourceBuildId: string; targetBuildId?: string; nonce?: string; /** Present only on a successful CACHE_RESET_RESULT. */ cachesDeleted?: number; }>; /** §18.3. Compile-time asset manifest; the worker never fetches one. */ export interface StaticAssetManifestV1 { readonly schemaVersion: 1; readonly buildId: string; readonly releaseId: string; readonly setDigest: `sha256:${string}`; readonly assets: readonly Readonly<{ url: string; sha256: `sha256:${string}`; bytes: number; contentType: string; }>[]; } /** §18.2. `ca-static-v1-`. */ export const STATIC_CACHE_PREFIX = "ca-static-v1-" as const; export function staticCacheName(setDigest: string): string { const hex = setDigest.replace(/^sha256:/, "").slice(0, 16); if (!/^[0-9a-f]{16}$/.test(hex)) { throw new TypeError("Static asset set digest is invalid."); } return `${STATIC_CACHE_PREFIX}${hex}`; } export function isOwnedStaticCacheName(name: string): boolean { return ( name.startsWith(STATIC_CACHE_PREFIX) && /^[0-9a-f]{16}$/.test(name.slice(STATIC_CACHE_PREFIX.length)) ); } export type ServiceWorkerStartOutcome = | Readonly<{ kind: "ACTIVE"; buildId: string }> | Readonly<{ kind: "RELOAD_TO_ENABLE" }> | Readonly<{ kind: "UPDATE_WAITING" }> | Readonly<{ kind: "DISABLED" }> | Readonly<{ kind: "INCOMPATIBLE" }> | Readonly<{ kind: "FAILED"; code: string }>; export type ServiceWorkerActivationOutcome = | Readonly<{ kind: "ACTIVATED_RELOAD_REQUIRED" }> | Readonly<{ kind: "BLOCKED_DIRTY_CLIENT" }> | Readonly<{ kind: "CLIENT_DRAIN_TIMEOUT" }> | Readonly<{ kind: "NO_WAITING_WORKER" }> | Readonly<{ kind: "PROTOCOL_MISMATCH" }> | Readonly<{ kind: "FAILED"; code: string }>; export type ServiceWorkerResetOutcome = | Readonly<{ kind: "RESET"; cachesDeleted: number }> | Readonly<{ kind: "NOT_CONTROLLED" }> | Readonly<{ kind: "PROTOCOL_MISMATCH" }> | Readonly<{ kind: "FAILED"; code: string }>; export type ServiceWorkerRemovalOutcome = | Readonly<{ kind: "ABSENT" }> | Readonly<{ kind: "UNREGISTERED" }> | Readonly<{ kind: "PURGED"; cachesDeleted: number; metadataDeleted: number }> | Readonly<{ kind: "OWNERSHIP_MISMATCH" }> | Readonly<{ kind: "FAILED"; operation: "LOOKUP" | "UNREGISTER" | "PURGE" }>; export interface ServiceWorkerRuntimeHost { start(): Promise; requestActivation(): Promise; resetOwnedCaches(): Promise; stop(): Promise; }