donghyeon.kang/clean-architecture-frontend-template
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

fix: make public cache staging repairable

Browse Source 
STO-03: reject at composition any policy that enables Vary variants while
stripping vary from the stored response allowlist, since every stored variant
would collide on the same cache key.

STO-04: extract one verifyReleaseCandidate authority shared by the stage fast
path and activation. A matching release marker is a claim, not evidence, so a
restage now re-verifies each entry, deletes only the owned candidate on a
mismatch and refetches. Abort or an unreadable candidate is never stage success
and never moves the active pointer.

STO-05: split the availability guard. Staging keeps the fetcher requirement
with ONLINE_ONLY recovery; activation, rollback and cleanup need only cache
storage and the mutation lock, so an offline rollback or quota-recovery cleanup
is no longer reported UNSUPPORTED.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-08-13 23:28:22 +09:00
co-authored by Claude Opus 5
parent ba79060a83
commit b893d95b36
5 changed files with 312 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/adapters/cache-storage/public-cache-policy.ts
+5
View File
@@ -132,6 +132,11 @@ export function assertPublicCachePolicy(
policy.allowedVaryHeaderNames.some(
(name) => !policy.allowedRequestHeaderNames.includes(name),
) ||
// STO-03. Enabling variants while stripping `vary` from stored responses
// makes every variant collide on the same cache key, so the combination is
// rejected at composition instead of producing an unusable candidate.
(policy.allowedVaryHeaderNames.length > 0 &&
!policy.allowedResponseHeaderNames.includes("vary")) ||
policy.forbiddenQueryParameterNames.some((name) => name.length === 0) ||
policy.allowedQueryParameterNames.some((name) =>
policy.forbiddenQueryParameterNames.includes(name),
src/adapters/cache-storage/public-response-cache-adapter.ts
+130 -39
View File
@@ -241,7 +241,7 @@ export function createPublicResponseCacheAdapter(
const aborted = abortedResult(signal, "CACHE_LOOKUP");
if (aborted) return aborted;
if (!dependencies.cacheStorage) {
return unsupported("CACHE_LOOKUP");
return unsupported("CACHE_LOOKUP", "RETRY");
}
let assetRequest: NormalizedAsset;
try {
@@ -389,10 +389,7 @@ export function createPublicResponseCacheAdapter(
const signal = options.signal;
const aborted = abortedResult(signal, "CACHE_STAGE");
if (aborted) return aborted;
const availability = mutationAvailability(
dependencies,
"CACHE_STAGE",
);
const availability = stageAvailability(dependencies);
if (availability) return availability;
let normalized: NormalizedReleaseManifest;
@@ -438,8 +435,28 @@ export function createPublicResponseCacheAdapter(
normalized.manifestDigestHex &&
marker.value.entryCount === normalized.assets.length
) {
return browserDataSuccess(summaryFromMarker(marker.value));
// 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.
return verified.failure;
}
}
// Only this owned candidate is removed; the network restage below
// repairs it.
await dependencies.cacheStorage!.delete(cacheName);
}
@@ -535,7 +552,7 @@ export function createPublicResponseCacheAdapter(
const signal = options.signal;
const aborted = abortedResult(signal, "CACHE_ACTIVATE");
if (aborted) return aborted;
const availability = mutationAvailability(
const availability = localMutationAvailability(
dependencies,
"CACHE_ACTIVATE",
);
@@ -589,31 +606,25 @@ export function createPublicResponseCacheAdapter(
);
}
for (const asset of marker.assets) {
if (signal?.aborted) {
return browserDataFailure("ABORTED", "CACHE_ACTIVATE");
}
const cached = await cache.match(createNativeRequest(asset));
if (!cached) {
return browserDataFailure(
"INTEGRITY_FAILED",
"CACHE_ACTIVATE",
{ recovery: "REHYDRATE" },
);
}
const verified = await readAndValidateResponse(
cached,
asset,
policy,
dependencies.crypto,
signal,
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" },
);
if (!verified.ok) {
return rebaseFailure(
verified.error,
"CACHE_ACTIVATE",
);
}
}
const previousPointer = await readActivePointer(
@@ -692,7 +703,7 @@ export function createPublicResponseCacheAdapter(
const signal = request.signal;
const aborted = abortedResult(signal, "CACHE_DELETE");
if (aborted) return aborted;
const availability = mutationAvailability(
const availability = localMutationAvailability(
dependencies,
"CACHE_DELETE",
);
@@ -771,7 +782,7 @@ export function createPublicResponseCacheAdapter(
async inspect() {
if (!dependencies.cacheStorage) {
return unsupported("CACHE_LOOKUP");
return unsupported("CACHE_LOOKUP", "RETRY");
}
try {
const names = await dependencies.cacheStorage.keys();
@@ -1640,24 +1651,104 @@ function summaryFromMarker(
});
}
function mutationAvailability(
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 }>;
/**
* 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): 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) {
return verified.error.code === "ABORTED"
? Object.freeze({
kind: "UNKNOWN" as const,
failure: asFailure(verified),
})
: Object.freeze({ kind: "REPAIRABLE" as const });
}
}
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,
operation: BrowserDataOperation,
): BrowserFailureResult | null {
return dependencies.cacheStorage &&
dependencies.fetcher &&
dependencies.mutationLock
? null
: unsupported(operation);
: 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: "ONLINE_ONLY",
}),
browserDataFailure("UNSUPPORTED", operation, { recovery }),
);
}