Files
clean-architecture-frontend…/src/adapters/cache-storage/public-response-cache-adapter.ts
T
DongHyeonka 7e7614fd48 fix(cache-storage): 손상 pointer에서도 inspect가 상태와 후보를 보여 준다
문제: inspect()는 active pointer 읽기가 실패하면 그 실패를 그대로
돌려준다. 손상 pointer(CORRUPT_DATA)는 조회·cleanup을 막고 다음
activation이 rollback 없이 덮어쓰는 상태인데, 그 상태를 진단할 유일한
관리 API도 같이 멈춘다. 운영자는 어떤 후보가 남았는지, 다음 activation이
무엇을 덮어쓰고 그 뒤 cleanup이 무엇을 지울지 모른 채 배포한다.
PublicCacheInspection에는 pointer 상태를 담을 칸이 없다.

고른 방법: PublicCacheInspection에 activePointer("NONE" | "READABLE" |
"UNREADABLE")를 둔다. pointer 읽기가 CORRUPT_DATA면 UNREADABLE로 적고
activeReleaseRegistryId는 null로 둔 채 후보 목록을 끝까지 채운다. 일시
오류(UNAVAILABLE 등)는 지금처럼 실패로 돌려준다. activation이 이미 쓰는
"CORRUPT_DATA만 손상으로 본다" 규칙과 같다. recipe fake도 같은 칸을
채운다. 리뷰가 함께 적은 inspect 전용 operation 이름은 공유 operation
union을 바꾸는 일이라 이번에 하지 않았다.

위험·한계: 공개 포트 타입에 필수 칸이 하나 는다. 결과를 읽는 쪽은
그대로지만 이 포트를 직접 구현한 쪽은 칸을 채워야 한다([계약]).
repo 안 소비자는 없다. inspect의 signal·판정 불가(0929/02-02)는
그대로다. service-worker-pwa 번들 9,733 → 9,758 / 10,100 gzip B.

검증:
- RED: public-response-cache-repair.test.ts 새 테스트가 activePointer
  없음으로 실패.
- GREEN: 같은 파일 11건 통과(손상 중 inspect ok, UNREADABLE, 후보
  r1·r2 verified, 일시 오류는 UNAVAILABLE). cache 단위 3파일 +
  tests/recipes 63건 통과. check:types, 바꾼 파일 eslint,
  check:optional-recipes:source PASS, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-05
2026-11-04 20:16:38 +09:00

1216 lines
40 KiB
TypeScript

import type {
CachedPublicResponse,
PublicCacheAsset,
PublicCacheCleanupReport,
PublicCacheInspection,
PublicCacheReleaseManifest,
PublicCacheReleaseSummary,
PublicResponseCache,
} from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type {
BrowserDataFailure,
BrowserDataOperation,
BrowserDataResult,
ByteSource,
} from "../../application/ports/browser-file-storage/shared.ts";
import {
abortedResult,
browserDataFailure,
browserDataSuccess,
} from "../browser-file-storage/result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
import {
cacheByteBucket,
cacheEntryBucket,
observePublicCacheSafely,
resolvePublicCachePolicy,
type PublicCacheRuntimePolicy,
type PublicCacheSafeObserver,
} from "./public-cache-policy.ts";
import {
CacheValidationFailure,
MAX_CONTROL_JSON_BYTES,
SHA256_HEX,
activePointerRequest,
asFailure,
assetKey,
canonicalManifest,
controlCacheName,
exceptionFailure,
isActivePointer,
isReleaseMarker,
jsonResponse,
markerRequest,
normalizeAndVerifyManifest,
normalizeAssets,
normalizeLookupRequest,
readBoundedJson,
releaseCacheName,
sha256Hex,
validationFailure,
type ActiveReleasePointer,
type BrowserFailureResult,
type NormalizedAsset,
type NormalizedReleaseManifest,
type PublicCacheCryptoFacade,
type ReleaseMarker,
} from "./public-cache-codec.ts";
import {
createNativeRequest,
readAndValidateResponse,
} from "./public-cache-response-validation.ts";
export interface PublicCacheMutationLock {
run<Value>(
signal: AbortSignal | undefined,
task: () => Promise<Value>,
): Promise<Value>;
}
export type PublicResponseCacheDependencies = Readonly<{
cacheStorage?: CacheStorage;
fetcher?: (request: Request) => Promise<Response>;
crypto: Crypto;
mutationLock?: PublicCacheMutationLock;
policy: PublicCacheRuntimePolicy;
now?: () => number;
observer?: PublicCacheSafeObserver;
}>;
type PublicCacheFacade = Readonly<{
match(request: Request): Promise<Response | undefined>;
put(request: Request, response: Response): Promise<void>;
}>;
type PublicCacheStorageFacade = Readonly<{
open(name: string): Promise<PublicCacheFacade>;
keys(): Promise<string[]>;
delete(name: string): Promise<boolean>;
}>;
type PublicResponseCacheDependencySnapshot = Readonly<{
cacheStorage?: PublicCacheStorageFacade;
fetcher?: (request: Request) => Promise<Response>;
crypto: PublicCacheCryptoFacade;
mutationLock?: PublicCacheMutationLock;
observer?: PublicCacheSafeObserver;
}>;
/**
* Q-6.2-6. A lookup-ready view of a verified marker. The cache name already
* encodes the manifest digest and the digest binds every asset field, so a
* marker verified once for a key stays valid for that key.
*/
type VerifiedLookupMarker = Readonly<{
key: string;
assetsByKey: ReadonlyMap<string, NormalizedAsset>;
}>;
type LockManagerLike = {
request<Value>(
name: string,
options: Readonly<{ mode: "exclusive"; signal?: AbortSignal }>,
callback: (lock: unknown) => Promise<Value>,
): Promise<Value>;
};
function snapshotPublicCacheDependencies(
dependencies: PublicResponseCacheDependencies,
): PublicResponseCacheDependencySnapshot {
const fetcher = dependencies.fetcher;
const observer = dependencies.observer;
if (
(fetcher !== undefined && typeof fetcher !== "function") ||
(observer !== undefined && typeof observer !== "function")
) {
throw new TypeError("Public cache runtime dependency is invalid.");
}
return Object.freeze({
cacheStorage: snapshotCacheStorage(dependencies.cacheStorage),
fetcher,
crypto: snapshotCacheCrypto(dependencies.crypto),
mutationLock: snapshotMutationLock(dependencies.mutationLock),
observer,
});
}
function snapshotCacheStorage(
cacheStorage: CacheStorage | undefined,
): PublicCacheStorageFacade | undefined {
if (!cacheStorage) return undefined;
const open = cacheStorage.open;
const keys = cacheStorage.keys;
const deleteCache = cacheStorage.delete;
if (
typeof open !== "function" ||
typeof keys !== "function" ||
typeof deleteCache !== "function"
) {
throw new TypeError("Public cache storage capability is invalid.");
}
return Object.freeze({
async open(name: string): Promise<PublicCacheFacade> {
const cache = await open.call(cacheStorage, name);
return snapshotCache(cache);
},
keys: keys.bind(cacheStorage),
delete: deleteCache.bind(cacheStorage),
});
}
function snapshotCache(cache: Cache): PublicCacheFacade {
const match = cache.match;
const put = cache.put;
if (typeof match !== "function" || typeof put !== "function") {
throw new TypeError("Public cache capability is invalid.");
}
return Object.freeze({
match: match.bind(cache),
put: put.bind(cache),
});
}
function snapshotCacheCrypto(crypto: Crypto): PublicCacheCryptoFacade {
const subtle = crypto?.subtle;
const digest = subtle?.digest;
if (typeof digest !== "function") {
throw new TypeError("Public cache crypto capability is invalid.");
}
return Object.freeze({
// WebCrypto copies its input when called (02-07), so no copy here.
async digestSha256(
bytes: Uint8Array<ArrayBuffer>,
): Promise<ArrayBuffer> {
return await digest.call(subtle, "SHA-256", bytes);
},
});
}
function snapshotMutationLock(
lock: PublicCacheMutationLock | undefined,
): PublicCacheMutationLock | undefined {
if (!lock) return undefined;
const run = lock.run;
if (typeof run !== "function") {
throw new TypeError("Public cache mutation lock is invalid.");
}
return Object.freeze({
async run<Value>(
signal: AbortSignal | undefined,
task: () => Promise<Value>,
): Promise<Value> {
return await (run.call(lock, signal, task) as Promise<Value>);
},
});
}
export function createPublicResponseCacheAdapter(
inputDependencies: PublicResponseCacheDependencies,
): PublicResponseCache {
const dependencies = snapshotPublicCacheDependencies(inputDependencies);
const policy = resolvePublicCachePolicy(inputDependencies.policy);
const now = inputDependencies.now ?? Date.now;
// ponytail: one slot for the active release only; a rollback re-verifies.
let verifiedLookupMarker: VerifiedLookupMarker | undefined;
const responses: PublicResponseCache["responses"] = Object.freeze({
async matchActiveExact(
request: Parameters<
PublicResponseCache["responses"]["matchActiveExact"]
>[0],
) {
const signal = request.signal;
const aborted = abortedResult(signal, "CACHE_LOOKUP");
if (aborted) return aborted;
if (!dependencies.cacheStorage) {
return unsupported("CACHE_LOOKUP", "RETRY");
}
let assetRequest: NormalizedAsset;
try {
assetRequest = normalizeLookupRequest(
request.absoluteUrl,
request.requestHeaders,
policy,
);
} catch (error) {
return validationFailure(error, "CACHE_LOOKUP");
}
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_LOOKUP",
outcome: "STARTED",
});
try {
// 02-07. One keys() per lookup, shared by the pointer read and the
// eviction check below.
let names = await dependencies.cacheStorage.keys();
const pointerResult = await readActivePointer(
dependencies.cacheStorage,
policy,
names,
);
if (!pointerResult.ok) {
return observeFailure(pointerResult, dependencies.observer);
}
if (!pointerResult.value) {
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_LOOKUP",
outcome: "SUCCEEDED",
});
return browserDataSuccess(null);
}
const pointer = pointerResult.value;
if (!names.includes(pointer.candidateCacheName)) {
// The name list predates the pointer read, which an activation may
// have moved to a newer cache; list again before reporting eviction.
names = await dependencies.cacheStorage.keys();
}
if (!names.includes(pointer.candidateCacheName)) {
return observeFailure(
browserDataFailure("STORAGE_EVICTED", "CACHE_LOOKUP", {
recovery: "REHYDRATE",
}),
dependencies.observer,
pointer.releaseRegistryId,
);
}
const cache = await dependencies.cacheStorage.open(
pointer.candidateCacheName,
);
const markerKey = `${pointer.candidateCacheName}\n${pointer.manifestDigestHex}`;
let verified =
verifiedLookupMarker?.key === markerKey
? verifiedLookupMarker
: undefined;
if (!verified) {
const markerResult = await readMarker(
cache,
policy,
dependencies.crypto,
);
if (!markerResult.ok) {
return observeFailure(
markerResult,
dependencies.observer,
pointer.releaseRegistryId,
);
}
const marker = markerResult.value;
if (
!marker ||
marker.releaseRegistryId !== pointer.releaseRegistryId ||
marker.manifestDigestHex !== pointer.manifestDigestHex
) {
return observeFailure(
browserDataFailure("INTEGRITY_FAILED", "CACHE_LOOKUP", {
recovery: "REHYDRATE",
}),
dependencies.observer,
pointer.releaseRegistryId,
);
}
verified = Object.freeze({
key: markerKey,
assetsByKey: new Map(
marker.assets.map((asset) => [assetKey(asset), asset]),
),
});
verifiedLookupMarker = verified;
}
const manifestAsset = verified.assetsByKey.get(
assetKey(assetRequest),
);
if (!manifestAsset) {
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_LOOKUP",
outcome: "SUCCEEDED",
releaseRegistryId: pointer.releaseRegistryId,
});
return browserDataSuccess(null);
}
const nativeRequest = createNativeRequest(manifestAsset);
// Exact Cache.match defaults are intentional. ignoreSearch,
// ignoreMethod and ignoreVary are never enabled.
const cached = await cache.match(nativeRequest);
if (!cached) {
return observeFailure(
browserDataFailure("STORAGE_EVICTED", "CACHE_LOOKUP", {
recovery: "REHYDRATE",
}),
dependencies.observer,
pointer.releaseRegistryId,
);
}
const read = await readAndValidateResponse(
cached,
manifestAsset,
policy,
dependencies.crypto,
signal,
);
if (!read.ok) {
return observeFailure(
rebaseFailure(read.error, "CACHE_LOOKUP"),
dependencies.observer,
pointer.releaseRegistryId,
manifestAsset.expectedByteLength,
);
}
const body = byteSourceFrom(read.value.bytes);
const response: CachedPublicResponse = Object.freeze({
status: 200,
headers: read.value.headers,
body,
integrity: Object.freeze({
algorithm: "SHA-256",
digestHex: manifestAsset.digestHex,
}),
});
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_LOOKUP",
outcome: "SUCCEEDED",
releaseRegistryId: pointer.releaseRegistryId,
byteBucket: cacheByteBucket(manifestAsset.expectedByteLength),
});
return browserDataSuccess(response);
} catch (error) {
return observeFailure(
exceptionFailure(error, "CACHE_LOOKUP"),
dependencies.observer,
);
}
},
});
const admin: PublicResponseCache["admin"] = Object.freeze({
async stageRelease(
manifest: PublicCacheReleaseManifest,
options: NonNullable<
Parameters<PublicResponseCache["admin"]["stageRelease"]>[1]
> = {},
) {
const signal = options.signal;
const aborted = abortedResult(signal, "CACHE_STAGE");
if (aborted) return aborted;
const availability = stageAvailability(dependencies);
if (availability) return availability;
let normalized: NormalizedReleaseManifest;
try {
normalized = await normalizeAndVerifyManifest(
manifest,
policy,
dependencies.crypto,
);
} catch (error) {
return validationFailure(error, "CACHE_STAGE");
}
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_STAGE",
outcome: "STARTED",
releaseRegistryId: normalized.releaseRegistryId,
entryBucket: cacheEntryBucket(normalized.assets.length),
});
// NS-08. One owner covers the whole staging body. Handing the signal to
// each `Request` only asked a cooperative fetch to stop: a stream or a
// digest that ignored it kept the mutation lock and, worse, could finish
// after the abort had already ended the operation and still write both the
// asset and the marker, publishing a release nobody was waiting for.
const owner = createAbortableOperation({ signal });
const ownedStep = async <Value>(
task: Promise<Value>,
compensate?: (value: Value) => void,
): Promise<Value> => {
const raced = await owner.race(task, compensate);
if (raced.kind === "REJECTED") throw raced.reason;
if (raced.kind !== "VALUE") {
throw new CacheValidationFailure("ABORTED");
}
return raced.value;
};
const assertOwned = (): void => {
if (owner.terminal() !== null) {
throw new CacheValidationFailure("ABORTED");
}
};
try {
const result = await dependencies.mutationLock!.run(
signal,
async () => {
assertOwned();
const cacheName = releaseCacheName(
policy,
normalized.releaseRegistryId,
normalized.manifestDigestHex,
);
const existingNames = await ownedStep(
Promise.resolve(dependencies.cacheStorage!.keys()),
);
// STO-RR-05. A candidate this call did not create may be the one
// currently serving traffic, so nothing about it is deleted before
// a replacement has been fetched and verified.
const preExistingCandidate = existingNames.includes(cacheName);
if (preExistingCandidate) {
const existing = await dependencies.cacheStorage!.open(cacheName);
const marker = await readMarker(
existing,
policy,
dependencies.crypto,
);
if (!marker.ok && marker.error.code !== "CORRUPT_DATA") {
// STO-RR-04. A marker that could not be read is unknown, not
// damaged. Treating a transient storage error as proof of
// corruption would delete a healthy active release.
return rebaseFailure(marker.error, "CACHE_STAGE");
}
if (
marker.ok &&
marker.value &&
marker.value.releaseRegistryId ===
normalized.releaseRegistryId &&
marker.value.manifestDigestHex ===
normalized.manifestDigestHex &&
marker.value.entryCount === normalized.assets.length
) {
// STO-04. The marker is a claim that staging completed, not
// evidence that every entry still exists and matches. Browser
// eviction, manual deletion and partial corruption all leave the
// marker intact, so the candidate is re-verified before reuse.
const verified = await verifyReleaseCandidate(
existing,
marker.value.assets,
policy,
dependencies.crypto,
signal,
);
if (verified.kind === "VERIFIED") {
return browserDataSuccess(summaryFromMarker(marker.value));
}
if (verified.kind === "UNKNOWN") {
// Abort or an unreadable candidate is never stage success and
// never silently deletes an owned candidate. 2026-11-01
// 02-03: the verdict is shared with activation, so the
// failure is re-labelled as this stage call's own.
return rebaseFailure(verified.failure.error, "CACHE_STAGE");
}
}
}
const cache = await ownedStep(
Promise.resolve(dependencies.cacheStorage!.open(cacheName)),
);
try {
let totalBytes = 0;
for (const asset of normalized.assets) {
assertOwned();
const cacheRequest = createNativeRequest(asset);
const networkRequest = createNativeRequest(
asset,
owner.signal,
);
const response = await ownedStep(
Promise.resolve(dependencies.fetcher!(networkRequest)),
// A response that arrives after the owner ended is released
// rather than read.
(late) => {
void late.body?.cancel().catch(() => undefined);
},
);
const read = await ownedStep(
readAndValidateResponse(
response,
asset,
policy,
dependencies.crypto,
owner.signal,
),
);
if (!read.ok) throw new CacheValidationFailure(read.error.code);
assertOwned();
totalBytes += read.value.bytes.byteLength;
if (totalBytes > policy.maxReleaseBytes) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
await ownedStep(
Promise.resolve(
cache.put(
cacheRequest,
new Response(Uint8Array.from(read.value.bytes), {
status: 200,
headers: read.value.headers.map(
([name, value]) => [name, value],
),
}),
),
),
);
}
assertOwned();
const marker: ReleaseMarker = Object.freeze({
schemaVersion: 1,
verified: true,
releaseRegistryId: normalized.releaseRegistryId,
manifestDigestHex: normalized.manifestDigestHex,
entryCount: normalized.assets.length,
totalBytes,
stagedAtEpochMs: now(),
assets: normalized.assets,
});
await ownedStep(
Promise.resolve(
cache.put(markerRequest(policy), jsonResponse(marker)),
),
);
// The marker is the activation record, so it is only a success
// once this call still owns the operation that wrote it.
assertOwned();
return browserDataSuccess(summaryFromMarker(marker));
} catch (error) {
// STO-RR-05. Only a candidate this call created is removed. A
// repair that failed part-way leaves every entry it did replace
// and every entry it never touched in place, so the release that
// was serving traffic before still is.
if (!preExistingCandidate) {
await dependencies.cacheStorage!.delete(cacheName);
}
throw error;
}
},
);
if (!result.ok) {
return observeFailure(
result,
dependencies.observer,
normalized.releaseRegistryId,
);
}
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_STAGE",
outcome: "SUCCEEDED",
releaseRegistryId: normalized.releaseRegistryId,
entryBucket: cacheEntryBucket(result.value.entryCount),
byteBucket: cacheByteBucket(result.value.totalBytes),
});
return result;
} catch (error) {
return observeFailure(
exceptionFailure(error, "CACHE_STAGE"),
dependencies.observer,
normalized.releaseRegistryId,
);
} finally {
owner.close();
}
},
async activateRelease(
releaseRegistryId: string,
manifestDigestHex: string,
options: NonNullable<
Parameters<PublicResponseCache["admin"]["activateRelease"]>[2]
> = {},
) {
const signal = options.signal;
const aborted = abortedResult(signal, "CACHE_ACTIVATE");
if (aborted) return aborted;
const availability = localMutationAvailability(
dependencies,
"CACHE_ACTIVATE",
);
if (availability) return availability;
if (
!policy.isReleaseRegistryIdAllowed(releaseRegistryId) ||
!SHA256_HEX.test(manifestDigestHex)
) {
return browserDataFailure("INVALID_INPUT", "CACHE_ACTIVATE");
}
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_ACTIVATE",
outcome: "STARTED",
releaseRegistryId,
});
try {
const result = await dependencies.mutationLock!.run(
signal,
async () => {
const cacheName = releaseCacheName(
policy,
releaseRegistryId,
manifestDigestHex,
);
const names = await dependencies.cacheStorage!.keys();
if (!names.includes(cacheName)) {
return browserDataFailure("NOT_FOUND", "CACHE_ACTIVATE", {
recovery: "REHYDRATE",
});
}
const cache = await dependencies.cacheStorage!.open(cacheName);
const markerResult = await readMarker(
cache,
policy,
dependencies.crypto,
);
if (!markerResult.ok) {
return rebaseFailure(markerResult.error, "CACHE_ACTIVATE");
}
const marker = markerResult.value;
if (
!marker ||
marker.releaseRegistryId !== releaseRegistryId ||
marker.manifestDigestHex !== manifestDigestHex
) {
return browserDataFailure(
"INTEGRITY_FAILED",
"CACHE_ACTIVATE",
{ recovery: "REHYDRATE" },
);
}
const candidate = await verifyReleaseCandidate(
cache,
marker.assets,
policy,
dependencies.crypto,
signal,
);
if (candidate.kind === "UNKNOWN") {
return rebaseFailure(
candidate.failure.error,
"CACHE_ACTIVATE",
);
}
if (candidate.kind === "REPAIRABLE") {
return browserDataFailure(
"INTEGRITY_FAILED",
"CACHE_ACTIVATE",
{ recovery: "REHYDRATE" },
);
}
const previousPointer = await readActivePointer(
dependencies.cacheStorage!,
policy,
);
// 0929/02-01. An unreadable pointer (damaged, or no longer valid
// under this policy) is replaced by this verified candidate with
// an empty rollback list, rather than blocking every later
// deployment. A transient read failure still stops activation.
if (
!previousPointer.ok &&
previousPointer.error.code !== "CORRUPT_DATA"
) {
return rebaseFailure(
previousPointer.error,
"CACHE_ACTIVATE",
);
}
const previous = previousPointer.ok
? previousPointer.value
: null;
const rollbackCandidateCacheNames = [
...(previous
? [
previous.candidateCacheName,
...previous.rollbackCandidateCacheNames,
]
: []),
]
.filter(
(name, index, all) =>
name !== cacheName && all.indexOf(name) === index,
)
.slice(0, policy.retainedPreviousReleaseCount);
const pointer: ActiveReleasePointer = Object.freeze({
schemaVersion: 1,
releaseRegistryId,
manifestDigestHex,
candidateCacheName: cacheName,
rollbackCandidateCacheNames: Object.freeze(
rollbackCandidateCacheNames,
),
activatedAtEpochMs: now(),
});
const control = await dependencies.cacheStorage!.open(
controlCacheName(policy),
);
await control.put(
activePointerRequest(policy),
jsonResponse(pointer),
);
return browserDataSuccess(summaryFromMarker(marker));
},
);
if (!result.ok) {
return observeFailure(
result,
dependencies.observer,
releaseRegistryId,
);
}
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_ACTIVATE",
outcome: "SUCCEEDED",
releaseRegistryId,
entryBucket: cacheEntryBucket(result.value.entryCount),
byteBucket: cacheByteBucket(result.value.totalBytes),
});
return result;
} catch (error) {
return observeFailure(
exceptionFailure(error, "CACHE_ACTIVATE"),
dependencies.observer,
releaseRegistryId,
);
}
},
async cleanupOwned(
request: NonNullable<
Parameters<PublicResponseCache["admin"]["cleanupOwned"]>[0]
> = {},
) {
const signal = request.signal;
const aborted = abortedResult(signal, "CACHE_DELETE");
if (aborted) return aborted;
const availability = localMutationAvailability(
dependencies,
"CACHE_DELETE",
);
if (availability) return availability;
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_DELETE",
outcome: "STARTED",
});
try {
const result = await dependencies.mutationLock!.run(
signal,
async () => {
const pointer = await readActivePointer(
dependencies.cacheStorage!,
policy,
);
if (!pointer.ok) {
return rebaseFailure(pointer.error, "CACHE_DELETE");
}
const names = await dependencies.cacheStorage!.keys();
const ownedNames = names.filter((name) =>
name.startsWith(policy.ownedCachePrefix),
);
let deleted = 0;
let retained = 0;
const lifecycleRetainedNames = new Set([
...(pointer.value
? [
pointer.value.candidateCacheName,
...pointer.value.rollbackCandidateCacheNames,
]
: []),
]);
for (const name of ownedNames) {
if (signal?.aborted) {
return browserDataFailure("ABORTED", "CACHE_DELETE");
}
if (
name === controlCacheName(policy) ||
lifecycleRetainedNames.has(name)
) {
retained += 1;
continue;
}
if (await dependencies.cacheStorage!.delete(name)) {
deleted += 1;
}
}
const report: PublicCacheCleanupReport = Object.freeze({
inspectedOwnedCaches: ownedNames.length,
deletedOwnedCaches: deleted,
retainedOwnedCaches: retained,
});
return browserDataSuccess(report);
},
);
if (!result.ok) {
return observeFailure(result, dependencies.observer);
}
observePublicCacheSafely(dependencies.observer, {
operation: "CACHE_DELETE",
outcome: "SUCCEEDED",
entryBucket: cacheEntryBucket(
result.value.inspectedOwnedCaches,
),
});
return result;
} catch (error) {
return observeFailure(
exceptionFailure(error, "CACHE_DELETE"),
dependencies.observer,
);
}
},
async inspect() {
if (!dependencies.cacheStorage) {
return unsupported("CACHE_LOOKUP", "RETRY");
}
try {
const names = await dependencies.cacheStorage.keys();
const owned = names.filter((name) =>
name.startsWith(policy.ownedCachePrefix),
);
const pointer = await readActivePointer(
dependencies.cacheStorage,
policy,
);
// 2026-11-03 02-05. A damaged pointer is the state this API is for,
// so it is reported with the candidates; a transient read is not.
if (!pointer.ok && pointer.error.code !== "CORRUPT_DATA") {
return pointer;
}
const active = pointer.ok ? pointer.value : null;
const candidates: PublicCacheInspection["releaseCandidates"][number][] =
[];
let unreadableOwnedCacheCount = 0;
for (const name of owned) {
if (name === controlCacheName(policy)) continue;
const cache = await dependencies.cacheStorage.open(name);
const marker = await readMarker(
cache,
policy,
dependencies.crypto,
);
if (!marker.ok || !marker.value) {
unreadableOwnedCacheCount += 1;
continue;
}
// 02-05. The marker only claims staging finished; `verified` means
// every entry is still present and matches, as activation checks.
const candidate = await verifyReleaseCandidate(
cache,
marker.value.assets,
policy,
dependencies.crypto,
undefined,
);
candidates.push(
Object.freeze({
releaseRegistryId: marker.value.releaseRegistryId,
verified: candidate.kind === "VERIFIED",
entryCount: marker.value.entryCount,
}),
);
}
return browserDataSuccess<PublicCacheInspection>(
Object.freeze({
activePointer: !pointer.ok
? "UNREADABLE"
: active
? "READABLE"
: "NONE",
activeReleaseRegistryId: active?.releaseRegistryId ?? null,
ownedCacheCount: owned.length,
unreadableOwnedCacheCount,
releaseCandidates: Object.freeze(candidates),
}),
);
} catch (error) {
return exceptionFailure(error, "CACHE_LOOKUP");
}
},
});
return Object.freeze({ responses, admin });
}
export function createPublicCacheWebLock(
lockManager: LockManager,
lockName: string,
): PublicCacheMutationLock {
if (lockName.length === 0) {
throw new TypeError("Public cache mutation lock name is required.");
}
const manager = lockManager as unknown as LockManagerLike;
return Object.freeze({
async run<Value>(
signal: AbortSignal | undefined,
task: () => Promise<Value>,
): Promise<Value> {
if (signal?.aborted) {
throw new DOMException("The operation was aborted.", "AbortError");
}
return await manager.request(
lockName,
{ mode: "exclusive", signal },
async (lock) => {
if (!lock) throw new CacheValidationFailure("BLOCKED");
return await task();
},
);
},
});
}
/**
* Build tooling and tests can use this helper to produce the exact digest
* accepted by stageRelease.
*/
export async function computePublicCacheManifestDigestHex(
crypto: Crypto,
releaseRegistryId: string,
assets: readonly PublicCacheAsset[],
policyInput: PublicCacheRuntimePolicy,
): Promise<string> {
const policy = resolvePublicCachePolicy(policyInput);
const cryptoSnapshot = snapshotCacheCrypto(crypto);
if (!policy.isReleaseRegistryIdAllowed(releaseRegistryId)) {
throw new TypeError("Public cache release registry ID is invalid.");
}
const normalized = normalizeAssets(assets, policy);
return await sha256Hex(
cryptoSnapshot,
new TextEncoder().encode(
canonicalManifest(releaseRegistryId, normalized),
),
);
}
async function readMarker(
cache: PublicCacheFacade,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
): Promise<BrowserDataResult<ReleaseMarker | null>> {
try {
const response = await cache.match(markerRequest(policy));
if (!response) return browserDataSuccess(null);
const value = await readBoundedJson(response, MAX_CONTROL_JSON_BYTES);
if (!isReleaseMarker(value, policy)) {
return browserDataFailure("CORRUPT_DATA", "CACHE_LOOKUP", {
recovery: "REHYDRATE",
});
}
const computedDigest = await sha256Hex(
crypto,
new TextEncoder().encode(
canonicalManifest(value.releaseRegistryId, value.assets),
),
);
if (
value.entryCount !== value.assets.length ||
value.totalBytes !==
value.assets.reduce(
(total, asset) => total + asset.expectedByteLength,
0,
) ||
computedDigest !== value.manifestDigestHex
) {
return browserDataFailure("CORRUPT_DATA", "CACHE_LOOKUP", {
recovery: "REHYDRATE",
});
}
return browserDataSuccess(value);
} catch (error) {
return exceptionFailure(error, "CACHE_LOOKUP");
}
}
async function readActivePointer(
cacheStorage: PublicCacheStorageFacade,
policy: PublicCacheRuntimePolicy,
names?: readonly string[],
): Promise<BrowserDataResult<ActiveReleasePointer | null>> {
try {
const name = controlCacheName(policy);
if (!(names ?? (await cacheStorage.keys())).includes(name)) {
return browserDataSuccess(null);
}
const cache = await cacheStorage.open(name);
const response = await cache.match(activePointerRequest(policy));
if (!response) return browserDataSuccess(null);
const value = await readBoundedJson(response, MAX_CONTROL_JSON_BYTES);
if (!isActivePointer(value, policy)) {
return browserDataFailure("CORRUPT_DATA", "CACHE_LOOKUP", {
recovery: "REHYDRATE",
});
}
return browserDataSuccess(value);
} catch (error) {
return exceptionFailure(error, "CACHE_LOOKUP");
}
}
/**
* 02-07. Keeps the verified read buffer, which nothing else references, and
* gives each stream its own copy so a consumer that mutates a chunk cannot
* change the body a later stream serves.
*/
function byteSourceFrom(stored: Uint8Array): ByteSource {
return Object.freeze({
byteLength: stored.byteLength,
async *stream(signal: AbortSignal) {
if (signal.aborted) {
yield browserDataFailure("ABORTED", "CACHE_LOOKUP");
return;
}
yield browserDataSuccess(Uint8Array.from(stored));
},
});
}
function summaryFromMarker(
marker: ReleaseMarker,
): PublicCacheReleaseSummary {
return Object.freeze({
releaseRegistryId: marker.releaseRegistryId,
entryCount: marker.entryCount,
totalBytes: marker.totalBytes,
stagedAtEpochMs: marker.stagedAtEpochMs,
});
}
type ReleaseCandidateVerdict =
| Readonly<{ kind: "VERIFIED" }>
/** An exact, owned entry is missing or no longer matches the manifest. */
| Readonly<{ kind: "REPAIRABLE" }>
/** Abort or an unreadable candidate: never success, never a silent delete. */
| Readonly<{ kind: "UNKNOWN"; failure: BrowserFailureResult }>;
const REPAIRABLE_READ_CODES: ReadonlySet<string> = new Set([
"INTEGRITY_FAILED",
"CORRUPT_DATA",
"POLICY_REJECTED",
"LIMIT_EXCEEDED",
]);
/**
* STO-04. The single verification authority shared by the stage fast path and
* activation, so "the marker says it is staged" can never stand in for "every
* entry is present and matches".
*/
async function verifyReleaseCandidate(
cache: Readonly<{ match(request: Request): Promise<Response | undefined> }>,
assets: readonly NormalizedAsset[],
policy: PublicCacheRuntimePolicy,
crypto: Readonly<{
digestSha256(bytes: Uint8Array<ArrayBuffer>): Promise<ArrayBuffer>;
}>,
signal: AbortSignal | undefined,
): Promise<ReleaseCandidateVerdict> {
for (const asset of assets) {
if (signal?.aborted) {
return Object.freeze({
kind: "UNKNOWN" as const,
failure: asFailure(
browserDataFailure("ABORTED", "CACHE_ACTIVATE"),
),
});
}
let cached: Response | undefined;
try {
cached = await cache.match(createNativeRequest(asset));
} catch {
return Object.freeze({
kind: "UNKNOWN" as const,
failure: asFailure(
browserDataFailure("UNAVAILABLE", "CACHE_ACTIVATE", {
retryable: true,
recovery: "RETRY",
}),
),
});
}
if (!cached) return Object.freeze({ kind: "REPAIRABLE" as const });
const verified = await readAndValidateResponse(
cached,
asset,
policy,
crypto,
signal,
);
if (!verified.ok) {
// 2026-11-03 02-02. Only a verdict about the stored bytes or headers is
// damage. A body read that failed (UNAVAILABLE, NOT_READABLE, ABORTED)
// says nothing about them, so it stays unknown and is retried.
return REPAIRABLE_READ_CODES.has(verified.error.code)
? Object.freeze({ kind: "REPAIRABLE" as const })
: Object.freeze({
kind: "UNKNOWN" as const,
failure: asFailure(verified),
});
}
}
return Object.freeze({ kind: "VERIFIED" as const });
}
/**
* STO-05. Staging is the only operation that reaches the network, so it is the
* only one that requires a fetcher.
*/
function stageAvailability(
dependencies: PublicResponseCacheDependencySnapshot,
): BrowserFailureResult | null {
return dependencies.cacheStorage &&
dependencies.fetcher &&
dependencies.mutationLock
? null
: unsupported("CACHE_STAGE", "ONLINE_ONLY");
}
/**
* Activation, rollback and cleanup are local Cache Storage mutations. Requiring
* a fetcher would block an offline rollback or a quota-recovery cleanup that
* needs no network at all.
*/
function localMutationAvailability(
dependencies: PublicResponseCacheDependencySnapshot,
operation: "CACHE_ACTIVATE" | "CACHE_DELETE",
): BrowserFailureResult | null {
return dependencies.cacheStorage && dependencies.mutationLock
? null
: unsupported(operation, "RETRY");
}
function unsupported(
operation: BrowserDataOperation,
recovery: "ONLINE_ONLY" | "RETRY",
): BrowserFailureResult {
return asFailure(
browserDataFailure("UNSUPPORTED", operation, { recovery }),
);
}
function rebaseFailure(
failure: BrowserDataFailure,
operation: BrowserDataOperation,
): BrowserFailureResult {
return {
ok: false,
error: Object.freeze({ ...failure, operation }),
};
}
function observeFailure(
result: BrowserDataResult<unknown>,
observer: PublicCacheSafeObserver | undefined,
releaseRegistryId?: string,
byteLength?: number,
): BrowserFailureResult {
if (result.ok) {
throw new TypeError("Expected a public cache failure result.");
}
observePublicCacheSafely(observer, {
operation: result.error.operation,
outcome: "FAILED",
failureCode: result.error.code,
releaseRegistryId,
byteBucket:
byteLength === undefined ? undefined : cacheByteBucket(byteLength),
});
return result;
}