Files
tech-log-frontend/src/contracts/service-worker.ts
T

153 lines
4.9 KiB
TypeScript

/**
* §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-<first 16 lower-hex of staticAssetSetDigest>`. */
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<ServiceWorkerStartOutcome>;
requestActivation(): Promise<ServiceWorkerActivationOutcome>;
resetOwnedCaches(): Promise<ServiceWorkerResetOutcome>;
stop(): Promise<void>;
}