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
This commit is contained in:
DongHyeonka
2026-11-04 20:16:38 +09:00
parent f19d4c6e9c
commit 7e7614fd48
6 changed files with 88 additions and 4 deletions
@@ -982,7 +982,10 @@ active pointer의 rollback 목록 길이는 읽을 때 현재
pointer(`CORRUPT_DATA`: 손상, 또는 지금 정책으로 허용되지 않는 ID)는 조회와
cleanup을 계속 막지만, 다음 `activateRelease`가 전체 재검증을 통과한 후보로
rollback 목록 없이 덮어쓴다. pointer 읽기의 일시 오류는 activation을 멈춘다
(0929/02-01).
(0929/02-01). 그동안 `inspect()`는 멈추지 않고 `activePointer: "UNREADABLE"`과
남은 후보 목록을 돌려준다. 운영자는 다음 activation이 무엇을 덮어쓰고 그 뒤
cleanup이 무엇을 지울지 볼 수 있다. 일시 오류에서는 inspect도 실패한다
(2026-11-03 02-05).
현재 `cleanupOwned()`와 `inspect()`는 위 ownership/integrity 경계를 지키지만
cache count에 대한 cursor, per-invocation max count와 deadline은 제공하지 않는다.
@@ -2051,6 +2051,7 @@ export class MemoryPublicResponseCache
// Every release here was staged after its entries passed policy, so each
// owned cache is readable and each candidate is verified.
return success({
activePointer: this.#activeReleaseId === null ? "NONE" : "READABLE",
activeReleaseRegistryId: this.#activeReleaseId,
ownedCacheCount: this.#releases.size,
unreadableOwnedCacheCount: 0,
@@ -867,7 +867,12 @@ export function createPublicResponseCacheAdapter(
dependencies.cacheStorage,
policy,
);
if (!pointer.ok) return pointer;
// 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][] =
[];
@@ -903,8 +908,12 @@ export function createPublicResponseCacheAdapter(
}
return browserDataSuccess<PublicCacheInspection>(
Object.freeze({
activeReleaseRegistryId:
pointer.value?.releaseRegistryId ?? null,
activePointer: !pointer.ok
? "UNREADABLE"
: active
? "READABLE"
: "NONE",
activeReleaseRegistryId: active?.releaseRegistryId ?? null,
ownedCacheCount: owned.length,
unreadableOwnedCacheCount,
releaseCandidates: Object.freeze(candidates),
@@ -40,6 +40,15 @@ export type CachedPublicResponse = Readonly<{
}>;
export type PublicCacheInspection = Readonly<{
/**
* 2026-11-03 02-05. `UNREADABLE` is a damaged pointer, or one this policy
* no longer accepts: lookup and cleanup stop on it and the next verified
* activation replaces it with an empty rollback list. The candidates are
* still listed so the operator can see what that activation and the
* cleanup after it will keep. A transient pointer read is a failure.
*/
activePointer: "NONE" | "READABLE" | "UNREADABLE";
/** `null` unless `activePointer` is `READABLE`. */
activeReleaseRegistryId: string | null;
ownedCacheCount: number;
unreadableOwnedCacheCount: number;
@@ -733,6 +733,7 @@ describe("production browser file and storage recipe contracts", () => {
expect(await cache.inspect()).toEqual({
ok: true,
value: {
activePointer: "READABLE",
activeReleaseRegistryId: "release-1",
ownedCacheCount: 1,
unreadableOwnedCacheCount: 0,
@@ -465,6 +465,67 @@ describe("public cache pointer after a policy change or damage (0929/02-01)", ()
).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("still stops activation when the pointer read fails transiently", async () => {
const cacheStorage = new MemoryCacheStorage();
const policy = policyRetaining(1);