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);