From 7e7614fd488a0f500499aa5d3b1cbeea5aa24ee1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:16:38 +0900 Subject: [PATCH] =?UTF-8?q?fix(cache-storage):=20=EC=86=90=EC=83=81=20poin?= =?UTF-8?q?ter=EC=97=90=EC=84=9C=EB=8F=84=20inspect=EA=B0=80=20=EC=83=81?= =?UTF-8?q?=ED=83=9C=EC=99=80=20=ED=9B=84=EB=B3=B4=EB=A5=BC=20=EB=B3=B4?= =?UTF-8?q?=EC=97=AC=20=EC=A4=80=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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 --- .../browser-file-and-origin-storage.md | 5 +- .../browser-file-storage-fakes.ts | 1 + .../public-response-cache-adapter.ts | 15 ++++- .../cache-storage-ports.ts | 9 +++ .../browser-file-storage-contracts.test.ts | 1 + .../unit/public-response-cache-repair.test.ts | 61 +++++++++++++++++++ 6 files changed, 88 insertions(+), 4 deletions(-) diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index d4ff71c7..72399f25 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -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은 제공하지 않는다. diff --git a/recipes/frontend-capabilities/browser-file-storage-fakes.ts b/recipes/frontend-capabilities/browser-file-storage-fakes.ts index 19baa3fc..473b2ed6 100644 --- a/recipes/frontend-capabilities/browser-file-storage-fakes.ts +++ b/recipes/frontend-capabilities/browser-file-storage-fakes.ts @@ -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, diff --git a/src/adapters/cache-storage/public-response-cache-adapter.ts b/src/adapters/cache-storage/public-response-cache-adapter.ts index c66c33fb..efd75876 100644 --- a/src/adapters/cache-storage/public-response-cache-adapter.ts +++ b/src/adapters/cache-storage/public-response-cache-adapter.ts @@ -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( 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), diff --git a/src/application/ports/browser-file-storage/cache-storage-ports.ts b/src/application/ports/browser-file-storage/cache-storage-ports.ts index 8072a33b..81851ea3 100644 --- a/src/application/ports/browser-file-storage/cache-storage-ports.ts +++ b/src/application/ports/browser-file-storage/cache-storage-ports.ts @@ -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; diff --git a/tests/recipes/browser-file-storage-contracts.test.ts b/tests/recipes/browser-file-storage-contracts.test.ts index 1b5c6d97..b571f41e 100644 --- a/tests/recipes/browser-file-storage-contracts.test.ts +++ b/tests/recipes/browser-file-storage-contracts.test.ts @@ -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, diff --git a/tests/unit/public-response-cache-repair.test.ts b/tests/unit/public-response-cache-repair.test.ts index adab7ff8..9f67c020 100644 --- a/tests/unit/public-response-cache-repair.test.ts +++ b/tests/unit/public-response-cache-repair.test.ts @@ -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);