Files
clean-architecture-frontend…/tests/unit/public-response-cache-repair.test.ts
T
DongHyeonka 3bfe6a8580 test(cache-storage): 조회가 eviction 판정 전에 캐시 목록을 다시 읽는지 고정한다
문제: 조회는 cache 이름 목록을 pointer보다 먼저 읽는다. 그 사이 다른
탭의 activation이 pointer를 새 캐시로 옮기면 목록에 그 캐시가 없다.
코드는 목록을 한 번 더 읽고서야 STORAGE_EVICTED를 낸다
(1101/02-04 ⑤, N39). 이 재확인을 지워도 테스트가 모두 통과했다. 빠지면
방금 배포한 release의 첫 조회가 "지워졌다"로 끝나고 REHYDRATE로 간다.

고른 방법: 첫 keys()만 배포 전 목록을 돌려주는 저장소로 r2 활성화 뒤
조회한다. adapter는 만들 때 keys를 잡아 두므로 저장소 하위 클래스로
한 번만 낡은 답을 준다.

위험·한계: 테스트만 바꾼다. 1101/02-04의 N38(host storageArea 비교)은
pulse wire 값을 만드는 하네스가 필요해 이번에 하지 않았다.

검증: N39 변이를 넣으면 이 테스트가 STORAGE_EVICTED로 실패하고(cache
단위 3파일 + tests/recipes 71건 중 1건), 되돌리면 같은 파일 14건 통과.
check:types:test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
2026-11-04 21:01:49 +09:00

635 lines
23 KiB
TypeScript

import { describe, expect, it } from "vitest";
import type { PublicCacheAsset } from "../../src/application/ports/browser-file-storage/cache-storage-ports.ts";
import {
activePointerRequest,
controlCacheName,
markerRequest,
} from "../../src/adapters/cache-storage/public-cache-codec.ts";
import {
createDefaultPublicCachePolicy,
resolvePublicCachePolicy,
type PublicCacheRuntimePolicy,
} from "../../src/adapters/cache-storage/public-cache-policy.ts";
import { createPublicResponseCacheAdapter } from "../../src/adapters/cache-storage/public-response-cache-adapter.ts";
import {
MemoryCacheStorage,
digestHex,
immediateLock,
manifestFor,
} from "./public-response-cache-fixture.ts";
/**
* STO-RR-04 / STO-RR-05. A release cache that is currently serving traffic is
* the last thing a repair may destroy. A transient marker read failure is not
* evidence of damage, and a repair that has not yet fetched anything has not
* yet earned the right to delete what still works.
*/
describe("public response cache repair is failure-atomic", () => {
async function stagedRelease(
releaseRegistryId: string,
observer?: (event: unknown) => void,
) {
const policy = createDefaultPublicCachePolicy(
"https://assets.example.test",
);
const firstBytes = new Uint8Array([1, 1, 1, 1]);
const secondBytes = new Uint8Array([2, 2, 2, 2]);
const assets: readonly PublicCacheAsset[] = [
{
absoluteUrl: "https://assets.example.test/first.js",
expectedByteLength: firstBytes.byteLength,
expectedContentType: "application/javascript",
integrity: {
algorithm: "SHA-256",
digestHex: await digestHex(firstBytes),
},
},
{
absoluteUrl: "https://assets.example.test/second.js",
expectedByteLength: secondBytes.byteLength,
expectedContentType: "application/javascript",
integrity: {
algorithm: "SHA-256",
digestHex: await digestHex(secondBytes),
},
},
];
const bodies = new Map<string, Uint8Array>([
[assets[0]!.absoluteUrl, firstBytes],
[assets[1]!.absoluteUrl, secondBytes],
]);
const cacheStorage = new MemoryCacheStorage();
const fetchLog: string[] = [];
let failFrom: string | null = null;
const adapter = createPublicResponseCacheAdapter({
cacheStorage: cacheStorage as unknown as CacheStorage,
crypto: globalThis.crypto,
mutationLock: immediateLock,
policy,
...(observer ? { observer } : {}),
fetcher: async (request: Request) => {
fetchLog.push(request.url);
if (failFrom !== null && request.url === failFrom) {
throw new TypeError("network is down");
}
const body = bodies.get(request.url);
if (!body) throw new TypeError(`unknown asset ${request.url}`);
return new Response(Uint8Array.from(body), {
headers: {
"cache-control": "public",
"content-type": "application/javascript",
},
});
},
});
const manifest = await manifestFor(releaseRegistryId, assets, policy);
expect(await adapter.admin.stageRelease(manifest)).toMatchObject({
ok: true,
});
expect(
await adapter.admin.activateRelease(
manifest.releaseRegistryId,
manifest.manifestDigestHex,
),
).toMatchObject({ ok: true });
const cacheName = [...cacheStorage.caches.keys()].find((name) =>
name.includes(releaseRegistryId),
);
if (!cacheName) throw new Error("staged cache missing");
return {
adapter,
assets,
cacheName,
cacheStorage,
fetchLog,
manifest,
setFailure(url: string | null) {
failFrom = url;
},
};
}
it("does not delete an active candidate when the marker read fails transiently", async () => {
const release = await stagedRelease("transient-marker");
const cache = release.cacheStorage.caches.get(release.cacheName)!;
const realMatch = cache.match.bind(cache);
let markerReads = 0;
const assetUrls = new Set(release.assets.map((asset) => asset.absoluteUrl));
cache.match = async (request: RequestInfo | URL) => {
const url =
request instanceof Request ? request.url : String(request);
if (!assetUrls.has(url)) {
markerReads += 1;
throw new DOMException("Storage is busy", "InvalidStateError");
}
return await realMatch(request);
};
const restaged = await release.adapter.admin.stageRelease(release.manifest);
expect(markerReads).toBeGreaterThan(0);
expect(restaged.ok).toBe(false);
expect(release.cacheStorage.caches.has(release.cacheName)).toBe(true);
cache.match = realMatch;
expect(
await release.adapter.responses.matchActiveExact({
absoluteUrl: release.assets[0]!.absoluteUrl,
}),
).toMatchObject({ ok: true });
});
it("reports a failed re-verification of a staged candidate as CACHE_STAGE (2026-11-01 02-03)", async () => {
const observations: Readonly<{ outcome?: string }>[] = [];
const release = await stagedRelease("reverify-unreadable", (event) =>
observations.push(event as Readonly<{ outcome?: string }>),
);
const cache = release.cacheStorage.caches.get(release.cacheName)!;
const realMatch = cache.match.bind(cache);
const assetUrls = new Set(release.assets.map((asset) => asset.absoluteUrl));
cache.match = async (request: RequestInfo | URL) => {
const url =
request instanceof Request ? request.url : String(request);
if (assetUrls.has(url)) {
throw new DOMException("Storage is busy", "InvalidStateError");
}
return await realMatch(request);
};
observations.length = 0;
const restaged = await release.adapter.admin.stageRelease(release.manifest);
expect(restaged).toMatchObject({
ok: false,
error: { code: "UNAVAILABLE", operation: "CACHE_STAGE" },
});
expect(
observations.filter(({ outcome }) => outcome === "FAILED"),
).toEqual([
expect.objectContaining({
operation: "CACHE_STAGE",
failureCode: "UNAVAILABLE",
}),
]);
});
it("reports a cached body that cannot be read during activation as retryable, not as damage (2026-11-03 02-02)", async () => {
const release = await stagedRelease("unreadable-body");
const cache = release.cacheStorage.caches.get(release.cacheName)!;
const realMatch = cache.match.bind(cache);
const assetUrls = new Set(release.assets.map((asset) => asset.absoluteUrl));
cache.match = async (request: RequestInfo | URL) => {
const url =
request instanceof Request ? request.url : String(request);
const stored = await realMatch(request);
if (!stored || !assetUrls.has(url)) return stored;
// The entry is there and its headers are intact; only reading the
// stored bytes fails, as a disk or browser I/O error does.
return new Response(
new ReadableStream<Uint8Array>({
pull(controller) {
controller.error(new TypeError("disk read failed"));
},
}),
{ headers: stored.headers },
);
};
const transient = (operation: string) => ({
ok: false,
error: {
code: "UNAVAILABLE",
operation,
retryable: true,
recovery: "RETRY",
},
});
expect(
await release.adapter.responses.matchActiveExact({
absoluteUrl: release.assets[0]!.absoluteUrl,
}),
).toMatchObject(transient("CACHE_LOOKUP"));
expect(
await release.adapter.admin.activateRelease(
release.manifest.releaseRegistryId,
release.manifest.manifestDigestHex,
),
).toMatchObject(transient("CACHE_ACTIVATE"));
// The stage fast path shares the verdict: an unreadable candidate is
// neither reused nor fetched again over the network.
const fetchesBefore = release.fetchLog.length;
expect(
await release.adapter.admin.stageRelease(release.manifest),
).toMatchObject(transient("CACHE_STAGE"));
expect(release.fetchLog).toHaveLength(fetchesBefore);
cache.match = realMatch;
expect(
await release.adapter.admin.activateRelease(
release.manifest.releaseRegistryId,
release.manifest.manifestDigestHex,
),
).toMatchObject({ ok: true });
});
it("still reports stored bytes that no longer match as an integrity failure", async () => {
const release = await stagedRelease("mismatched-body");
const cache = release.cacheStorage.caches.get(release.cacheName)!;
const index = cache.responses.findIndex(
(entry) => entry.request.url === release.assets[0]!.absoluteUrl,
);
const entry = cache.responses[index]!;
cache.responses.splice(index, 1, {
request: entry.request,
response: new Response(new Uint8Array([9, 9, 9, 9]), {
headers: entry.response.headers,
}),
});
expect(
await release.adapter.admin.activateRelease(
release.manifest.releaseRegistryId,
release.manifest.manifestDigestHex,
),
).toMatchObject({
ok: false,
error: {
code: "INTEGRITY_FAILED",
operation: "CACHE_ACTIVATE",
recovery: "REHYDRATE",
},
});
});
it("keeps every healthy asset when one repair fetch fails", async () => {
const release = await stagedRelease("partial-repair");
const cache = release.cacheStorage.caches.get(release.cacheName)!;
// Corrupt only the first asset's stored bytes.
const corrupted = cache.responses.findIndex(
(entry) => entry.request.url === release.assets[0]!.absoluteUrl,
);
expect(corrupted).toBeGreaterThanOrEqual(0);
cache.responses.splice(corrupted, 1);
release.setFailure(release.assets[0]!.absoluteUrl);
const restaged = await release.adapter.admin.stageRelease(release.manifest);
expect(restaged.ok).toBe(false);
// The cache still exists and the healthy asset is still served.
expect(release.cacheStorage.caches.has(release.cacheName)).toBe(true);
expect(
await release.adapter.responses.matchActiveExact({
absoluteUrl: release.assets[1]!.absoluteUrl,
}),
).toMatchObject({ ok: true });
});
it("still removes a candidate this call created when staging fails", async () => {
const policy = createDefaultPublicCachePolicy(
"https://assets.example.test",
);
const bytes = new Uint8Array([7, 7, 7, 7]);
const asset: PublicCacheAsset = {
absoluteUrl: "https://assets.example.test/fresh.js",
expectedByteLength: bytes.byteLength,
expectedContentType: "application/javascript",
integrity: {
algorithm: "SHA-256",
digestHex: await digestHex(bytes),
},
};
const cacheStorage = new MemoryCacheStorage();
const adapter = createPublicResponseCacheAdapter({
cacheStorage: cacheStorage as unknown as CacheStorage,
crypto: globalThis.crypto,
mutationLock: immediateLock,
policy,
fetcher: async () => {
throw new TypeError("network is down");
},
});
const manifest = await manifestFor("fresh-release", [asset], policy);
expect(await adapter.admin.stageRelease(manifest)).toMatchObject({
ok: false,
});
expect(await cacheStorage.keys()).toEqual([]);
});
it("repairs an evicted asset in place and keeps the release usable", async () => {
const release = await stagedRelease("in-place-repair");
const cache = release.cacheStorage.caches.get(release.cacheName)!;
const evicted = cache.responses.findIndex(
(entry) => entry.request.url === release.assets[1]!.absoluteUrl,
);
cache.responses.splice(evicted, 1);
expect(
await release.adapter.admin.stageRelease(release.manifest),
).toMatchObject({ ok: true });
expect(
await release.adapter.responses.matchActiveExact({
absoluteUrl: release.assets[1]!.absoluteUrl,
}),
).toMatchObject({ ok: true });
expect(
await release.adapter.responses.matchActiveExact({
absoluteUrl: release.assets[0]!.absoluteUrl,
}),
).toMatchObject({ ok: true });
});
});
/**
* 0929/02-01. The active pointer was checked against the policy of the build
* reading it, so lowering `retainedPreviousReleaseCount` or a damaged pointer
* stopped lookup, activation and cleanup for good.
*/
describe("public cache pointer after a policy change or damage (0929/02-01)", () => {
const origin = "https://assets.example.test";
const policyRetaining = (retainedPreviousReleaseCount: number) =>
resolvePublicCachePolicy({
...createDefaultPublicCachePolicy(origin),
retainedPreviousReleaseCount,
});
const assetUrl = (releaseRegistryId: string) =>
`${origin}/${releaseRegistryId}.js`;
const body = (releaseRegistryId: string) =>
new TextEncoder().encode(`release ${releaseRegistryId}`);
function adapterFor(
cacheStorage: MemoryCacheStorage,
policy: PublicCacheRuntimePolicy,
) {
return createPublicResponseCacheAdapter({
cacheStorage: cacheStorage as unknown as CacheStorage,
crypto: globalThis.crypto,
mutationLock: immediateLock,
policy,
fetcher: async (request: Request) =>
new Response(
Uint8Array.from(
body(new URL(request.url).pathname.slice(1, -".js".length)),
),
{
headers: {
"cache-control": "public",
"content-type": "application/javascript",
},
},
),
});
}
async function manifestOf(
releaseRegistryId: string,
policy: PublicCacheRuntimePolicy,
) {
const bytes = body(releaseRegistryId);
return await manifestFor(
releaseRegistryId,
[
{
absoluteUrl: assetUrl(releaseRegistryId),
expectedByteLength: bytes.byteLength,
expectedContentType: "application/javascript",
integrity: { algorithm: "SHA-256", digestHex: await digestHex(bytes) },
},
],
policy,
);
}
async function deploy(
adapter: ReturnType<typeof adapterFor>,
releaseRegistryId: string,
policy: PublicCacheRuntimePolicy,
) {
const manifest = await manifestOf(releaseRegistryId, policy);
expect(await adapter.admin.stageRelease(manifest)).toMatchObject({
ok: true,
});
return await adapter.admin.activateRelease(
manifest.releaseRegistryId,
manifest.manifestDigestHex,
);
}
it("keeps working after retainedPreviousReleaseCount is lowered", async () => {
const cacheStorage = new MemoryCacheStorage();
const before = policyRetaining(3);
const wide = adapterFor(cacheStorage, before);
for (const id of ["r1", "r2", "r3", "r4"]) {
expect(await deploy(wide, id, before)).toMatchObject({ ok: true });
}
const after = policyRetaining(1);
const narrow = adapterFor(cacheStorage, after);
expect(
await narrow.responses.matchActiveExact({ absoluteUrl: assetUrl("r4") }),
).toMatchObject({ ok: true, value: expect.anything() });
expect(await deploy(narrow, "r5", after)).toMatchObject({ ok: true });
expect(await narrow.admin.cleanupOwned()).toMatchObject({ ok: true });
expect(
await narrow.responses.matchActiveExact({ absoluteUrl: assetUrl("r5") }),
).toMatchObject({ ok: true, value: expect.anything() });
});
it("replaces a damaged pointer on the next verified activation", async () => {
const cacheStorage = new MemoryCacheStorage();
const policy = policyRetaining(1);
const adapter = adapterFor(cacheStorage, policy);
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
const control = await cacheStorage.open(controlCacheName(policy));
await control.put(
activePointerRequest(policy),
new Response('{"schemaVersion":1,"releaseRegis', {
headers: { "content-type": "application/json" },
}),
);
// A release that was never staged is still refused.
const unstaged = await manifestOf("r9", policy);
expect(
await adapter.admin.activateRelease(
unstaged.releaseRegistryId,
unstaged.manifestDigestHex,
),
).toMatchObject({ ok: false });
expect(await deploy(adapter, "r2", policy)).toMatchObject({ ok: true });
expect(await adapter.admin.cleanupOwned()).toMatchObject({ ok: true });
expect(
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r2") }),
).toMatchObject({ ok: true, value: expect.anything() });
});
it("shows a damaged pointer and the candidates it leaves behind in inspect (2026-11-03 02-05)", async () => {
const cacheStorage = new MemoryCacheStorage();
const policy = policyRetaining(1);
const adapter = adapterFor(cacheStorage, policy);
expect(await adapter.admin.inspect()).toMatchObject({
ok: true,
value: { activePointer: "NONE", activeReleaseRegistryId: null },
});
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
expect(await deploy(adapter, "r2", policy)).toMatchObject({ ok: true });
expect(await adapter.admin.inspect()).toMatchObject({
ok: true,
value: { activePointer: "READABLE", activeReleaseRegistryId: "r2" },
});
const control = await cacheStorage.open(controlCacheName(policy));
await control.put(
activePointerRequest(policy),
new Response('{"schemaVersion":1,"releaseRegis', {
headers: { "content-type": "application/json" },
}),
);
const inspected = await adapter.admin.inspect();
expect(inspected).toMatchObject({
ok: true,
value: {
activePointer: "UNREADABLE",
activeReleaseRegistryId: null,
ownedCacheCount: 3,
unreadableOwnedCacheCount: 0,
},
});
expect(
inspected.ok
? inspected.value.releaseCandidates
.map(({ releaseRegistryId, verified }) => ({
releaseRegistryId,
verified,
}))
.sort((left, right) =>
left.releaseRegistryId.localeCompare(right.releaseRegistryId),
)
: null,
).toEqual([
{ releaseRegistryId: "r1", verified: true },
{ releaseRegistryId: "r2", verified: true },
]);
// A pointer that could not be read right now is not reported as damage.
const realMatch = control.match.bind(control);
control.match = async () => {
throw new DOMException("Storage is busy", "InvalidStateError");
};
expect(await adapter.admin.inspect()).toMatchObject({
ok: false,
error: { code: "UNAVAILABLE", retryable: true },
});
control.match = realMatch;
});
it("does not clean up on a damaged pointer, which may name the release being served (2026-11-03 02-03)", async () => {
const cacheStorage = new MemoryCacheStorage();
const policy = policyRetaining(1);
const adapter = adapterFor(cacheStorage, policy);
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
expect(await deploy(adapter, "r2", policy)).toMatchObject({ ok: true });
const control = await cacheStorage.open(controlCacheName(policy));
await control.put(
activePointerRequest(policy),
new Response('{"schemaVersion":1,"releaseRegis', {
headers: { "content-type": "application/json" },
}),
);
const before = (await cacheStorage.keys()).sort();
expect(await adapter.admin.cleanupOwned()).toMatchObject({
ok: false,
error: { code: "CORRUPT_DATA", operation: "CACHE_DELETE" },
});
expect((await cacheStorage.keys()).sort()).toEqual(before);
});
it("repairs a damaged release marker by staging the same manifest again (2026-11-03 02-03)", async () => {
const cacheStorage = new MemoryCacheStorage();
const policy = policyRetaining(1);
const adapter = adapterFor(cacheStorage, policy);
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
const releaseName = (await cacheStorage.keys()).find((name) =>
name.includes("release:r1:"),
);
if (!releaseName) throw new Error("release cache missing");
const release = await cacheStorage.open(releaseName);
await release.put(
markerRequest(policy),
new Response('{"schemaVersion":1,"verif', {
headers: { "content-type": "application/json" },
}),
);
// REHYDRATE: the damaged candidate cannot be activated as it is ...
const manifest = await manifestOf("r1", policy);
expect(
await adapter.admin.activateRelease(
manifest.releaseRegistryId,
manifest.manifestDigestHex,
),
).toMatchObject({
ok: false,
error: { code: "CORRUPT_DATA", recovery: "REHYDRATE" },
});
// ... and staging it again is the recovery that hint promises.
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
expect(
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r1") }),
).toMatchObject({ ok: true, value: expect.anything() });
});
// 2026-11-01 02-04 (N39). The cache name list is read before the pointer.
// An activation in between moves the pointer to a cache that list does not
// have yet; the lookup lists again rather than report it evicted.
it("lists caches again before it reports the active release evicted", async () => {
// The adapter captures `keys` when it is built, so the stale answer is
// armed through the storage itself.
class StaleOnceCacheStorage extends MemoryCacheStorage {
staleNames: string[] | null = null;
override async keys(): Promise<string[]> {
const stale = this.staleNames;
this.staleNames = null;
return stale ?? (await super.keys());
}
}
const cacheStorage = new StaleOnceCacheStorage();
const policy = policyRetaining(1);
const adapter = adapterFor(cacheStorage, policy);
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
const namesBeforeR2 = await cacheStorage.keys();
expect(await deploy(adapter, "r2", policy)).toMatchObject({ ok: true });
cacheStorage.staleNames = namesBeforeR2;
expect(
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r2") }),
).toMatchObject({ ok: true, value: expect.anything() });
});
it("still stops activation when the pointer read fails transiently", async () => {
const cacheStorage = new MemoryCacheStorage();
const policy = policyRetaining(1);
const adapter = adapterFor(cacheStorage, policy);
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
const control = cacheStorage.caches.get(controlCacheName(policy))!;
const realMatch = control.match.bind(control);
control.match = async () => {
throw new DOMException("Storage is busy", "InvalidStateError");
};
expect(await deploy(adapter, "r2", policy)).toMatchObject({
ok: false,
error: { code: "UNAVAILABLE", operation: "CACHE_ACTIVATE" },
});
control.match = realMatch;
expect(
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r1") }),
).toMatchObject({ ok: true, value: expect.anything() });
});
});