diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index d86a7fb8..5e19e4f3 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -251,7 +251,7 @@ }, { "name": "adapters-do-not-know-other-concrete-adapters", - "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (clock, abort primitive, capacity guard), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", + "comment": "docs/architecture/layers.md §4: a concrete adapter never depends on another concrete adapter. The adapter kernel is shared on purpose and any adapter may import it: src/adapters/platform/** (shared mechanisms only: clock, abort primitive, capacity guard, IndexedDB connection and transaction, Retry-After, JSON member scanner; plus two bootstrap-only services, see layers.md), src/adapters/browser-file-storage/result.ts (browser-data result helpers) and src/adapters/cross-context-invalidation/index.ts (the cross-context invalidation transport and its types). Owner: frontend-platform. No new file-level exception is added here; a new shared primitive goes into src/adapters/platform/.", "severity": "error", "from": { "path": "^src/adapters/([^/]+)/" diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index d4ff71c7..d9762ec6 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -371,10 +371,18 @@ digest 또는 별도 검토된 streaming hash adapter를 사용한다. 세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`). `runtime.dispose()`(`:177-188`)가 이전 사용자가 고른 File 참조, preview lease, 진행 중 download(`download-delivery-adapter.ts:390-396`)를 한 번에 닫는다. - runtime을 route·feature보다 오래 사는 곳에서 만들었다면 server-state scope - reset participant(`src/adapters/query-cache/server-state-scope-runtime.ts:19`, - 등록 예 `src/bootstrap/runtime-adapters.ts:410-416`)로 `dispose()`를 등록하고 - 다음 세대에서 새 runtime을 만든다. dispose한 runtime은 다시 쓸 수 없다. + runtime을 route·feature보다 오래 사는 곳(`product-composition.ts`의 + capability)에서 만들었다면 제품 소유 파일만 고친다. `composeProduct`가 + `scopeParticipants`로 `dispose()`를 돌려주면 템플릿이 로그아웃·계정 전환마다 + FENCED와 READY 사이에서 부르고, 실패하면 READY로 가지 않는다 + (`ProductScopeParticipant`, `src/bootstrap/product-composition-contract.ts`). + `composeProduct`는 부팅 때 한 번만 불리므로 기능에는 runtime 대신 getter를 + 주고 그 뒤에서 세대마다 새 runtime을 만든다. 예제는 + `recipes/frontend-capabilities/browser-file-session-capability.ts`이고 + `tests/recipes/browser-file-session-capability.test.ts`가 계정 전환 뒤 이전 + runtime의 읽기가 `UNAVAILABLE`, 진행 중 download가 `ABORTED`(handoff 0회), + 다음 세대의 파일 선택이 성공함을 확인한다(2026-11-03 02-01). dispose한 + runtime은 다시 쓸 수 없다. - SVG, HTML, untrusted PDF 같은 active content를 same-origin object URL iframe에 직접 preview하지 않는다. 별도 격리 origin 또는 안전한 decode/re-encode 결과, 아니면 attachment-only 정책을 사용한다. @@ -439,7 +447,10 @@ stream-to-file에서 integrity를 close 전에 확인해야 하면 writable을 `INTEGRITY_FAILED` 또는 partial-save failure를 반환한다. 전략, media type, safe extension, integrity mode와 최대 bytes는 composition -registry가 소유한다. caller는 composition이 등록한 정확한 +registry가 소유한다. registry는 사용자 파일명에서 지우는 위험 확장자 +(`.exe`, `.html`, `.js` 등)이거나 그것으로 끝나는 safe extension을 조립 때 +거절한다(2026-11-01 02-02). media type과 확장자가 서로 맞는지는 아직 보지 +않는다. caller는 composition이 등록한 정확한 `FilePolicyReference` 객체, 아래 source union의 최소 입력, filename과 limit reduction만 전달한다. `policyKey`/`intention`이 같은 새 객체나 raw 전략을 제출할 수 없다. source는 다음처럼 분리한다. @@ -982,7 +993,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/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index f7915853..8e7143d6 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -90,14 +90,16 @@ host facade는 native `StorageEvent.storageArea`를 캡처한 `localStorage` 객 (`browser-cross-context-invalidation.ts:197-201`). 현재 epoch는 release 하나다. `cacheEpoch`는 release ID의 64-bit FNV-1a digest를 -`release.<16자리 hex>`로 쓴 값이다(`browser-cross-context-host.ts:45-51`, 조립 -`src/bootstrap/runtime-adapters.ts:364-366`). 세션 identity가 바뀌면 scope +`release.<16자리 hex>`로 쓴 값이다(`browser-cross-context-host.ts` +`crossContextCacheEpochForRelease`, 조립은 `src/bootstrap/runtime-adapters.ts`의 +`createServerStateGenerationStore` 콜백). 세션 identity가 바뀌면 scope runtime이 다음 server-state generation을 열고 -(`src/adapters/query-cache/server-state-scope-runtime.ts:148`), generation마다 -새 `QueryClient`와 새 cross-context transport(새 `sourceId`·`sourceEpoch`)를 -만든다(`src/bootstrap/server-state-generation-store.ts:50-57`, -`runtime-adapters.ts:359-372`). 이전 generation의 transport는 coordinator -dispose에서 닫힌다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:276-280`). +(`src/adapters/query-cache/server-state-scope-runtime.ts`의 +`activateNextGeneration` 호출), generation마다 새 `QueryClient`와 새 +cross-context transport(새 `sourceId`·`sourceEpoch`)를 만든다 +(`src/bootstrap/server-state-generation-store.ts:50-57`, 같은 콜백). 이전 +generation의 transport는 coordinator `dispose()`에서 닫힌다 +(`src/adapters/query-cache/tanstack-cache-coordinator.ts`). session/account epoch, opaque account partition과 durable namespace epoch는 아직 없다. wire event에 사용자·세션 scope가 없으므로 현재 cross-tab event는 같은 release의 등록 query topic을 빠르게 stale 처리하는 용도에 한정된다. diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md index 4c30f033..a57351d8 100644 --- a/docs/architecture/layers.md +++ b/docs/architecture/layers.md @@ -80,8 +80,14 @@ passing. which is shared on purpose and is the only adapter code an adapter may reach across a group for: -- `src/adapters/platform/**` — the system clock, the shared abort primitive and - the bounded-capacity guard +- `src/adapters/platform/**` — mechanisms more than one adapter group shares: + the system clock, the shared abort primitive, the bounded-capacity guard, + the IndexedDB connection and transaction helpers, `Retry-After` parsing and + the JSON member scanner. Two bootstrap-only platform services live there + too: the browser lifecycle runtime and the mutation intent factory (no + adapter imports them). A kernel file owns mechanics only, never names, + schemas, failure codes or observation shapes; the full list of what it must + never own is at the top of `indexeddb-connection.ts` - `src/adapters/browser-file-storage/result.ts` — the browser-data result and failure constructors - `src/adapters/cross-context-invalidation/index.ts` — the cross-context diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 9d09fdf9..6395af69 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -105,6 +105,7 @@ release admission refused for staging: - `src/features/product-capabilities.ts`: `needs`에 템플릿이 만들지 않는 capability를 적었을 때. 그 capability의 타입을 `ProductFeaturePlatformCapabilities`에 적는다. - `product-composition.ts` 안에서 `FeaturePlatformCapabilities`를 보강(`declare module`)하면 `check:types:node`가 그 키를 보지 못한다. - `src/bootstrap/product-composition.ts`: 위 capability의 값을 돌려줄 때. 제품 인증 프로필의 자격 증명도 여기서 준다. + - 로그아웃·계정 전환 때 닫아야 하는 것(파일 runtime 등)은 `scopeParticipants`로 돌려준다. 예제: `recipes/frontend-capabilities/browser-file-session-capability.ts`. - 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다. - 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../architecture/realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02). - `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때. diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 2829f533..dc245541 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -38,14 +38,25 @@ cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답 저장소 손상이다. 예전에는 이런 row 하나가 목록 전체를 실패시켜 authority의 모든 partition에서 reconcile과 GC가 멈췄다. 이제 나머지 row와 orphan GC는 계속 돌고, 관측은 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 남는다 - ([0929] 05-01). reconcile은 그 row를 지우지 않는다. 그 row가 속한 - partition이 승인된 purge로 통째로 지워질 때만 함께 지워진다(§7). + ([0929] 05-01). reconcile은 그 row를 지우지 않는다. 그 partition이 승인된 + purge로 통째로 지워질 때 함께 지워지는 것은 partition 키(`logicalKey`)를 + 읽을 수 있는 row뿐이다(§7). 승인된 LOGOUT/ACCOUNT_DELETION purge는 그런 + row를 보면 그 partition을 지운다(2026-11-03 05-01). + - `unattributedCorruptTransactions`: 위 수 가운데 `logicalKey`까지 읽을 수 + 없는 row 수다. 어느 partition에도 속하지 않아 partition 삭제도 지우지 + 못한다. 그래서 따로 세고 `DEGRADED` 관측에서 뺀다(2026-11-03 05-03). 예전에는 + 이런 row 하나가 reconcile마다 `DEGRADED`를 남겨 경보가 늘 켜졌다. 같은 수로 + 남아 있으면 할 일이 없다. 수가 늘면 키 없는 row를 쓴 writer(다른 release, + 외부 도구)를 찾는다. 이 row도 수동으로 지우지 않는다(3번). 그 row의 + staging은 partition 디렉터리 안에 있어 그 partition이 지워지면 함께 + 지워지지만, 이 row는 purge의 partition 삭제 조건에 들지 않는다. 3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할 근거가 사라지고 quota만 누수된다. 4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지 않는다. rollback은 새 v2 write admission을 닫고 v1+v2 reader를 유지하는 것으로 - 수행한다. runtime이 스스로 지우는 것은 승인된 purge가 손상 때문에 끝나지 못할 - 때의 그 partition 디렉터리 하나와 그 partition의 journal row뿐이다(§7). + 수행한다. runtime이 스스로 지우는 것은 승인된 purge가 손상이나 끝나지 않은 + transaction 때문에 끝나지 못할 때의 그 partition 디렉터리 하나와 그 partition의 + journal row뿐이다(§7). ## 1. 공통 원칙 @@ -58,8 +69,9 @@ incident 중에도 다음 작업은 금지한다. - origin의 모든 `caches.keys()` 삭제 - user-authored/unsynced IndexedDB 또는 OPFS data 자동 purge - OPFS의 예외도 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된 - journal row나 staging 때문에 끝나지 못할 때, runtime이 그 partition - 디렉터리 하나와 그 partition의 journal row만 지운다(§7 recovery). + row나 staging, 또는 그 partition의 끝나지 않은 put·delete 때문에 끝나지 못할 + 때, runtime이 그 partition 디렉터리 하나와 그 partition의 journal row만 + 지운다(§7 recovery). - schema version downgrade - 무한 reload/update loop - filename, path, record/object key, URL/query, digest, body를 incident log에 복사 @@ -438,26 +450,36 @@ VD-15 목표 runtime을 먼저 구현한다. - `COMMITTED` + file missing/corrupt: reconstructable만 server rehydrate; user-created private는 read-only/export/recovery - stale staging/orphan chunk는 grace period와 bounded mark/sweep 후 제거 -- `LOGOUT`/`ACCOUNT_DELETION` purge는 객체를 모두 지운 뒤 그 partition의 chunk를 +- `LOGOUT`/`ACCOUNT_DELETION` purge는 객체를 모두 지운 뒤 그 partition의 journal + row를 센다. 하나라도 있으면(다른 tab에서 진행 중인 put·delete, crash가 남긴 + `PREPARING`·`FILES_READY`, 키는 읽히는 손상 row) sweep 대신 아래 partition + 삭제로 간다(2026-11-03 05-01). 예전에는 이 row를 보지 않고 `COMPLETED`를 + 돌려줬다. 그래서 진행 중 put의 객체가 purge 뒤에도 읽혔고, `FILES_READY` row는 + 다음 reconcile이 commit해 객체로 되살렸다. row가 없으면 그 partition의 chunk를 grace 없이 sweep한다(05-04, `opfs-byte-store-adapter.ts` `enforcePolicies`). - journal이나 staging receipt가 참조하는 chunk는 이때도 지우지 않는다. report의 - `chunkSweep`이 `COMPLETED`여야 bytes가 지워진 것이다. `DEADLINE_REACHED`면 같은 + staging receipt가 참조하는 chunk는 이때도 지우지 않는다. 이 두 reason에서는 + report의 `chunkSweep`이 `COMPLETED`이거나 `partitionDeleted`가 있을 때 그 + partition의 bytes가 지워진 것이다. `DEADLINE_REACHED`면 같은 purge를 다시 호출하고, `STAGING_STATE_UNREADABLE`이면 읽을 수 없는 staging부터 처리한다. 다른 탭이 바꾸고 있던 객체를 지우지 못하면 report는 `moreObjectsAvailable: true`이고 `chunkSweep`이 없다. 이때도 같은 purge를 다시 호출한다([0929] 05-02) -- 손상 때문에 끝나지 못하는 `LOGOUT`/`ACCOUNT_DELETION` purge는 partition을 - 통째로 지운다([0929] 05-01, `opfs-byte-store-adapter.ts` `enforcePolicies`). +- 손상이나 끝나지 않은 transaction 때문에 끝나지 못하는 `LOGOUT`/ + `ACCOUNT_DELETION` purge는 partition을 통째로 지운다([0929] 05-01, + 2026-11-03 05-01, `opfs-byte-store-adapter.ts` `enforcePolicies`). - 조건: 정책이 그 reason을 허용하고, authority가 이번 purge의 proof를 내주고 consumer가 소비했을 때(IndexedDB의 database 전체 삭제와 같은 승인). 그리고 다음 중 하나를 만났을 때: 목록에서 건너뛴 손상 object row, 손상 row 때문에 - `CORRUPT_DATA`로 끝난 remove나 chunk sweep, `STAGING_STATE_UNREADABLE`. + `CORRUPT_DATA`로 끝난 remove나 chunk sweep, `STAGING_STATE_UNREADABLE`, 그 + partition 키를 가진 journal row(`countPartitionTransactions`가 1 이상). TTL·SESSION_END·UNTIL_SYNCED·PRESSURE는 손상 row를 건너뛰고 세기만 한다. - 범위: worker가 origin mutation lease를 쥔 채 `authorities///` 디렉터리를 지우고, 이어서 journal에서 그 partition 키로 시작하는 object·journal·chunk - reference row와 budget row를 지운다. 값을 읽지 않고 키로 찾으므로 손상 row도 - 지워진다. scope binding row는 남긴다. 다른 partition은 건드리지 않는다. + reference row와 budget row를 지운다. 값을 읽지 않고 키로 찾으므로 키가 남은 + 손상 row도 지워진다. journal row는 `logicalKey` 인덱스로 찾으므로 그 값까지 + 깨진 row는 남는다(§0 2번 `unattributedCorruptTransactions`). scope binding + row는 남긴다. 다른 partition은 건드리지 않는다. - 결과: `partitionDeleted: true`, `moreObjectsAvailable: false`, 건너뛴 row 수 `corruptObjects`. 이 report면 그 partition의 bytes는 모두 지워진 것이다. `chunkSweep`은 없다. 디렉터리는 지웠는데 journal 정리가 실패하면 실패를 @@ -479,9 +501,12 @@ VD-15 목표 runtime을 먼저 구현한다. approved purge meets another tab's put parked before …"(5가지 순서). - 한계: 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle bound(05-07)까지 삭제를 붙잡는다. purge의 `signal`을 abort하면 기다림을 - 멈추고 `ABORTED`를 반환한다. 삭제가 lock을 요청한 뒤 온 put의 데이터는 다른 - purge처럼 남는다(point-in-time). purge 전에 그 partition의 쓰기를 멈추는 - 것이 composition의 몫이다. + 멈추고 `ABORTED`를 반환한다. 삭제 뒤에 줄 선 put·delete도 자기 `signal`로 + 기다림을 멈춘다. 어느 쪽이든 partition lock 기다림은 + `mutationLockWaitTimeoutMs`(기본 10분)에서 `BLOCKED`(retryable)로 끝난다 + (2026-11-03 05-02). purge가 journal row를 센 뒤에 시작한 put, 삭제가 + lock을 요청한 뒤 온 put의 데이터는 남는다(point-in-time). purge 전에 그 + partition의 쓰기를 멈추는 것이 composition의 몫이다. - lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only - scope binding mismatch면 affected scope를 read-only로 격리하고 registry/ composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지 diff --git a/recipes/frontend-capabilities/browser-file-session-capability.ts b/recipes/frontend-capabilities/browser-file-session-capability.ts new file mode 100644 index 00000000..04d95996 --- /dev/null +++ b/recipes/frontend-capabilities/browser-file-session-capability.ts @@ -0,0 +1,58 @@ +import type { BrowserFileRuntime } from "../../src/adapters/browser-files/index.ts"; +import type { ProductScopeParticipant } from "../../src/bootstrap/product-composition-contract.ts"; + +/** What features receive: this session's runtime, asked for per operation. */ +export type SessionBrowserFiles = Readonly<{ + /** + * The current session's runtime, built on first use. Ask again for each + * operation; one kept past a sign-out answers `UNAVAILABLE`. + */ + current(): BrowserFileRuntime; +}>; + +/** + * 2026-11-03 02-01. How a product gives features a browser file runtime that + * lives for one session. The runtime does not know the session, and + * `composeProduct` runs once at boot, so the capability is a getter and the + * runtime behind it is disposed by a scope participant on every sign-out and + * account switch: the previous user's selected files, preview object URLs and + * running downloads end there. The next call to `current()` builds a fresh one. + * + * file-transfer is an opt-in recipe (`productionComposition: false`), so the + * template does not build this. A product that installs a feature using it + * augments `FeaturePlatformCapabilities` with `files: SessionBrowserFiles` and + * returns both halves from `src/bootstrap/product-composition.ts`: + * + * const browserFiles = createSessionBrowserFileCapability(() => + * createBrowserFileRuntime({ input, policies, limits, download }), + * ); + * return { + * capabilities: { files: browserFiles.files }, + * credentialProviders: {}, + * scopeParticipants: [browserFiles.scopeParticipant], + * }; + * + * The runtime options are the product's decisions (policies, limits, the + * download capability resolver); none is chosen here. + */ +export function createSessionBrowserFileCapability( + create: () => BrowserFileRuntime, +): Readonly<{ + files: SessionBrowserFiles; + scopeParticipant: ProductScopeParticipant; +}> { + let runtime: BrowserFileRuntime | null = null; + return Object.freeze({ + files: Object.freeze({ + current: () => (runtime ??= create()), + }), + scopeParticipant: Object.freeze({ + label: "browser-files", + close() { + const ending = runtime; + runtime = null; + ending?.dispose(); + }, + }), + }); +} diff --git a/recipes/frontend-capabilities/browser-file-storage-fakes.ts b/recipes/frontend-capabilities/browser-file-storage-fakes.ts index 19baa3fc..d23f572b 100644 --- a/recipes/frontend-capabilities/browser-file-storage-fakes.ts +++ b/recipes/frontend-capabilities/browser-file-storage-fakes.ts @@ -1649,8 +1649,11 @@ type MemoryDurableObjectStoreOptions = Readonly<{ * test written against it compiles against the runtime too. It keeps the * runtime's visible rules: a put is invisible until its logical commit, a * stale `expectedGeneration` is `CONFLICT`, a put that stopped mid-way leaves - * a journal row that `reconcile` rolls back (never resumes), and a LOGOUT or - * ACCOUNT_DELETION the policy allows leaves the partition empty. + * a journal row, and a LOGOUT or ACCOUNT_DELETION the policy allows leaves the + * partition empty. `reconcile` rolls a row that stopped while PREPARING back + * and commits one that stopped after FILES_READY, like the runtime's + * roll-forward; such a purge also drops every stopped row and reports + * `partitionDeleted` (2026-11-03 05-01, 05-04). * * It does not model the worker, Web Locks, the composition authority, chunk * dedup, orphan GC or the other maintenance reasons (`UNSUPPORTED`). Its @@ -1661,8 +1664,14 @@ export class MemoryDurableObjectStore implements DurableObjectStorePort, DurableObjectMaintenancePort { readonly #objects = new Map(); - /** Journal rows of puts that stopped before they committed or rolled back. */ - readonly #pending = new Set(); + /** + * Journal rows of puts that stopped before they committed or rolled back. + * A row that reached FILES_READY keeps the object its commit would publish. + */ + readonly #pending = new Map< + number, + Readonly<{ expectedGeneration: number | null; ready: MemoryObject | null }> + >(); readonly #scope: OpfsStorageScope; readonly #storagePolicy: BrowserStoragePolicy; readonly #maxObjectBytes: number; @@ -1711,7 +1720,10 @@ export class MemoryDurableObjectStore return dataFailure("CONFLICT", "OBJECT_WRITE", false, "REOPEN"); } const row = ++this.#sequence; - this.#pending.add(row); + this.#pending.set( + row, + Object.freeze({ expectedGeneration: request.expectedGeneration, ready: null }), + ); const stopped = (phase: "PREPARING" | "FILES_READY") => { if (this.#failurePhase !== phase) return null; this.#failurePhase = null; @@ -1755,8 +1767,6 @@ export class MemoryDurableObjectStore if (declared !== null && totalBytes !== declared) { return settle(dataFailure("INTEGRITY_FAILED", "OBJECT_WRITE")); } - const afterFilesReady = stopped("FILES_READY"); - if (afterFilesReady) return afterFilesReady; const chunkDigests = await Promise.all(chunks.map(sha256Hex)); const chunkSizeBytes = Math.max( @@ -1787,7 +1797,14 @@ export class MemoryDurableObjectStore }), storagePolicy: this.#storagePolicy, }); - this.#objects.set(request.objectId, { descriptor, chunks }); + const ready: MemoryObject = { descriptor, chunks }; + this.#pending.set( + row, + Object.freeze({ expectedGeneration: request.expectedGeneration, ready }), + ); + const afterFilesReady = stopped("FILES_READY"); + if (afterFilesReady) return afterFilesReady; + this.#objects.set(request.objectId, ready); this.#pending.delete(row); return dataSuccess(descriptor); } @@ -1853,13 +1870,26 @@ export class MemoryDurableObjectStore return dataFailure("INVALID_INPUT", "OBJECT_RECONCILE"); } const rows = [...this.#pending].slice(0, maxTransactions); - for (const row of rows) this.#pending.delete(row); + let committed = 0; + for (const [row, { expectedGeneration, ready }] of rows) { + this.#pending.delete(row); + // The runtime re-verifies a FILES_READY row and commits it under the + // same generation check a live put has; anything else is rolled back. + const current = ready && this.#objects.get(ready.descriptor.objectId); + if ( + ready && + (current?.descriptor.generation ?? null) === expectedGeneration + ) { + this.#objects.set(ready.descriptor.objectId, ready); + committed += 1; + } + } return dataSuccess( Object.freeze({ inspectedTransactions: rows.length, - committedTransactions: 0, - rolledBackTransactions: rows.length, - cleanedTransactions: 0, + committedTransactions: committed, + rolledBackTransactions: rows.length - committed, + cleanedTransactions: committed, inspectedOrphanChunks: 0, deletedOrphanChunks: 0, orphanGcStatus: "COMPLETED" as const, @@ -1895,6 +1925,10 @@ export class MemoryDurableObjectStore } const removedObjects = this.#objects.size; this.#objects.clear(); + // 2026-11-03 05-01. A stopped put goes with the partition, as the + // runtime's partition delete takes its row and its files. + const partitionDeleted = this.#pending.size > 0; + this.#pending.clear(); return dataSuccess( Object.freeze({ inspectedObjects: removedObjects, @@ -1902,7 +1936,9 @@ export class MemoryDurableObjectStore releasedBytes, moreObjectsAvailable: false, deadlineReached: false, - chunkSweep: "COMPLETED" as const, + ...(partitionDeleted + ? { partitionDeleted: true as const } + : { chunkSweep: "COMPLETED" as const }), }), ); } @@ -2051,6 +2087,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/scripts/test-browser-file-storage-runtime-removal.ts b/scripts/test-browser-file-storage-runtime-removal.ts index 399d9910..2dd386de 100644 --- a/scripts/test-browser-file-storage-runtime-removal.ts +++ b/scripts/test-browser-file-storage-runtime-removal.ts @@ -36,8 +36,9 @@ const runtimePaths = [ "src/adapters/storage/opfs", "tests/browser-capabilities", "tests/fixtures/browser-file-storage-boundaries", - // The composition example of this runtime goes with it. + // The composition examples of this runtime go with it. "recipes/frontend-capabilities/indexeddb-feature-capability.ts", + "recipes/frontend-capabilities/browser-file-session-capability.ts", // [0929] 05-03. These recipe contracts re-export this runtime's ports and // their fakes implement them, so they go with it too, with their test. ...RUNTIME_RECIPE_MODULES.map( diff --git a/src/adapters/browser-files/browser-file-policy-registry.ts b/src/adapters/browser-files/browser-file-policy-registry.ts index a4f639f0..4b253d41 100644 --- a/src/adapters/browser-files/browser-file-policy-registry.ts +++ b/src/adapters/browser-files/browser-file-policy-registry.ts @@ -15,6 +15,7 @@ import { assertFileInspectionPolicy, assertFileSelectionPolicy, EXACT_MEDIA_TYPE, + isForbiddenDownloadExtension, isPositiveSafeInteger, sanitizeSuggestedFileName, type RegisteredFileInspectionPolicy, @@ -452,6 +453,7 @@ function snapshotDownload( "BOUNDED_OBJECT_URL", ].includes(input.strategy) || !EXACT_MEDIA_TYPE.test(mediaType) || + isForbiddenDownloadExtension(safeExtension) || !isPositiveSafeInteger(input.maxTransferBytes) || !isPositiveSafeInteger(input.maxBufferedBytes) || input.maxTransferBytes > hardLimits.maxTransferBytes || diff --git a/src/adapters/browser-files/browser-file-vault.ts b/src/adapters/browser-files/browser-file-vault.ts index 8d36b126..7db2bfed 100644 --- a/src/adapters/browser-files/browser-file-vault.ts +++ b/src/adapters/browser-files/browser-file-vault.ts @@ -352,6 +352,15 @@ export class BrowserFileVault browserDataFailure("UNAVAILABLE", "FILE_INSPECT"), ); } + // 2026-11-03 02-04. release() may have run during the reads above; a + // receipt issued now would hold the released File until dispose. + if (!this.#records.has(request.ref)) { + return this.#observeFailureResult( + browserDataFailure("NOT_FOUND", "FILE_INSPECT", { + recovery: "RESELECT", + }), + ); + } const cancelled = abortedResult( request.signal, "FILE_INSPECT", diff --git a/src/adapters/browser-files/file-policy.ts b/src/adapters/browser-files/file-policy.ts index 988fc285..380df048 100644 --- a/src/adapters/browser-files/file-policy.ts +++ b/src/adapters/browser-files/file-policy.ts @@ -96,6 +96,17 @@ const DEFAULT_FORBIDDEN_EXTENSIONS = Object.freeze([ ".xll", ] as const); +/** + * 2026-11-01 02-02. A download policy's own extension may not be one a + * user-supplied file name is stripped of, nor end in one (`.tar.js`). + */ +export function isForbiddenDownloadExtension(extension: string): boolean { + const normalized = extension.normalize("NFC").toLowerCase(); + return DEFAULT_FORBIDDEN_EXTENSIONS.some((forbidden) => + normalized.endsWith(forbidden), + ); +} + export type SuggestedFileNamePolicy = Readonly<{ safeExtension: string; fallbackBaseName?: string; diff --git a/src/adapters/cache-storage/public-response-cache-adapter.ts b/src/adapters/cache-storage/public-response-cache-adapter.ts index 10d153e9..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), @@ -1071,6 +1080,13 @@ type ReleaseCandidateVerdict = /** Abort or an unreadable candidate: never success, never a silent delete. */ | Readonly<{ kind: "UNKNOWN"; failure: BrowserFailureResult }>; +const REPAIRABLE_READ_CODES: ReadonlySet = new Set([ + "INTEGRITY_FAILED", + "CORRUPT_DATA", + "POLICY_REJECTED", + "LIMIT_EXCEEDED", +]); + /** * 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 @@ -1117,12 +1133,15 @@ async function verifyReleaseCandidate( signal, ); if (!verified.ok) { - return verified.error.code === "ABORTED" - ? Object.freeze({ + // 2026-11-03 02-02. Only a verdict about the stored bytes or headers is + // damage. A body read that failed (UNAVAILABLE, NOT_READABLE, ABORTED) + // says nothing about them, so it stays unknown and is retried. + return REPAIRABLE_READ_CODES.has(verified.error.code) + ? Object.freeze({ kind: "REPAIRABLE" as const }) + : Object.freeze({ kind: "UNKNOWN" as const, failure: asFailure(verified), - }) - : Object.freeze({ kind: "REPAIRABLE" as const }); + }); } } return Object.freeze({ kind: "VERIFIED" as const }); diff --git a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts index e215e086..ea4b49c9 100644 --- a/src/adapters/storage/opfs/indexeddb-opfs-journal.ts +++ b/src/adapters/storage/opfs/indexeddb-opfs-journal.ts @@ -699,6 +699,7 @@ export function createIndexedDbOpfsJournal( (transaction, context) => { const rows: OpfsJournalTransaction[] = []; let corruptRows = 0; + let unattributedRows = 0; walkIndexedDbCursor({ request: transaction .objectStore(JOURNAL_STORE) @@ -720,6 +721,8 @@ export function createIndexedDbOpfsJournal( rows.push(cursor.value); } else { corruptRows += 1; + // 2026-11-03 05-03. No partition's key range holds it. + if (!hasPartitionKey(cursor.value)) unattributedRows += 1; } return { kind: "CONTINUE" }; }, @@ -730,6 +733,7 @@ export function createIndexedDbOpfsJournal( moreAvailable: summary.reason === "STOPPED" && rows.length === limit, corruptRows, + ...(unattributedRows ? { unattributedRows } : {}), }), ); }, @@ -864,6 +868,48 @@ export function createIndexedDbOpfsJournal( ); }, + async countPartitionTransactions(scope) { + if ( + !keyRange || + !isBoundScope(scope) || + !isValidOpfsStorageScope(scope) + ) { + return browserDataFailure( + keyRange ? "INVALID_INPUT" : "UNSUPPORTED", + "INDEXEDDB_READ", + ); + } + return await withDatabase("INDEXEDDB_READ", (db) => + runTransaction( + db, + [JOURNAL_STORE], + "readonly", + "INDEXEDDB_READ", + (transaction, context) => { + // 2026-11-03 05-01. The key range `removePartition` deletes, so a + // row counted here is a row that delete takes. + const scopeKey = storageScopeKey(scope); + let rows = 0; + walkIndexedDbCursor({ + request: transaction + .objectStore(JOURNAL_STORE) + .index(LOGICAL_KEY_INDEX) + .openCursor( + keyRange.bound(`${scopeKey}|`, `${scopeKey}|\uffff`), + ), + sink: context, + translate: translateFor("INDEXEDDB_READ"), + visit: () => { + rows += 1; + return { kind: "CONTINUE" }; + }, + done: () => context.succeed(rows), + }); + }, + ), + ); + }, + async removePartition(scope) { if ( !keyRange || @@ -927,6 +973,27 @@ export function createIndexedDbOpfsJournal( return Object.freeze(journal); + /** + * 2026-11-03 05-03. Whether a row's `logicalKey` lies in the key range + * `removePartition` deletes for some partition of this authority. + */ + function hasPartitionKey(value: unknown): boolean { + const key = + value && typeof value === "object" && "logicalKey" in value + ? value.logicalKey + : undefined; + if (typeof key !== "string") return false; + const [authority, namespaceToken, partitionToken, objectId] = + key.split("|"); + return ( + authority === dependencies.authorityToken && + objectId !== undefined && + [namespaceToken, partitionToken].every( + (token) => token !== undefined && SAFE_BOUNDARY_ID.test(token), + ) + ); + } + async function commitMutation( transactionId: string, fencingToken: string, diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index 0f68c3f6..9c918f51 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -23,6 +23,7 @@ import { browserDataFailure, browserDataSuccess, } from "../../browser-file-storage/result.ts"; +import { createAbortableOperation } from "../../platform/abortable-operation.ts"; import { byteBucket, observeOpfsSafely, @@ -221,6 +222,7 @@ export function createOpfsByteStoreAdapter( return await withTransactionLock( transactionId, "OBJECT_WRITE", + request.signal, async () => { // STO-01. The logical generation is reused across transactions; this // token makes the physical target unique so a late compensation can never @@ -495,6 +497,7 @@ export function createOpfsByteStoreAdapter( return await withTransactionLock( transactionId, "OBJECT_DELETE", + request.signal, async () => { const begun = await dependencies.journal.begin({ transactionId, @@ -636,6 +639,7 @@ export function createOpfsByteStoreAdapter( // skipped. The page is read again under those locks: a row listed while // its owner still ran may have moved on before the owner let go. const held = new Map void>(); + let unattributed: number; try { for (const transaction of listed.value.transactions) { let release: (() => void) | null; @@ -660,6 +664,7 @@ export function createOpfsByteStoreAdapter( report.moreTransactionsAvailable = page.value.moreAvailable; // [0929] 05-01. The journal skipped these rows; they stop nothing now. report.corruptTransactions = page.value.corruptRows; + unattributed = page.value.unattributedRows ?? 0; for (const transaction of page.value.transactions) { if (!held.has(transaction.transactionId)) continue; if (request.signal?.aborted) { @@ -706,12 +711,19 @@ export function createOpfsByteStoreAdapter( operation: "OBJECT_RECONCILE", transactionBucket: transactionBucket(report.inspectedTransactions), // A skipped corrupt row is observed, not hidden behind a success. - ...(report.corruptTransactions + // 2026-11-03 05-03. One no partition owns is reported, not observed: + // nothing clears it, so it would keep the signal on for good. + ...(report.corruptTransactions > unattributed ? { outcome: "DEGRADED", failureCode: "CORRUPT_DATA" } : { outcome: "SUCCEEDED" }), }); return browserDataSuccess( - Object.freeze({ ...report }), + Object.freeze({ + ...report, + ...(unattributed + ? { unattributedCorruptTransactions: unattributed } + : {}), + }), ); }, @@ -876,6 +888,22 @@ export function createOpfsByteStoreAdapter( } afterObjectId = page.value.nextObjectId; } + // 2026-11-03 05-01. A put or delete of this partition that has not + // finished holds bytes the object walk never sees and the sweep skips: + // one running in another tab, or a row a crash left (PREPARING, or + // FILES_READY, which the next reconcile would commit) or nothing can + // read. Any such row sends the purge to the partition delete below, + // which first waits for every live one. + let unfinished = 0; + if (sweeping && !request.signal?.aborted) { + const counted = await dependencies.journal.countPartitionTransactions( + dependencies.scope, + ); + if (!counted.ok) { + return rebaseFailure(counted.error, "OBJECT_RECONCILE"); + } + unfinished = counted.value; + } // 05-04. Removing an object leaves its chunks, and GC only takes a // chunk 24 h after it was written, so a purged user's bytes stayed on // the device. Once every object is gone the partition's chunks are swept @@ -884,6 +912,7 @@ export function createOpfsByteStoreAdapter( let chunkSweep: OpfsPolicyMaintenanceReport["chunkSweep"]; if ( sweeping && + !unfinished && !corruptObjects && !damaged && !moreObjectsAvailable && @@ -920,7 +949,7 @@ export function createOpfsByteStoreAdapter( // wait for every put and delete of the partition in any tab. const partitionDeleted = sweeping && - (corruptObjects > 0 || damaged) && + (corruptObjects > 0 || damaged || unfinished > 0) && !request.signal?.aborted; if (partitionDeleted) { const removed = await withPartitionLock( @@ -1101,6 +1130,7 @@ export function createOpfsByteStoreAdapter( async function withTransactionLock( transactionId: string, operation: "OBJECT_WRITE" | "OBJECT_DELETE", + signal: AbortSignal | undefined, run: () => Promise>, ): Promise> { let release: (() => void) | null; @@ -1115,7 +1145,7 @@ export function createOpfsByteStoreAdapter( // A fresh transaction id is never held; a holder means a duplicate id. if (!release) return browserDataFailure("CONFLICT", operation); try { - return await withPartitionLock("shared", operation, undefined, run); + return await withPartitionLock("shared", operation, signal, run); } finally { release(); } @@ -1130,6 +1160,11 @@ export function createOpfsByteStoreAdapter( * files after the directory went, the second step took its journal row, and * nothing was left to clean those files. Tested by "leaves no partition * bytes when an approved purge meets another tab's put parked before …". + * + * 2026-11-03 05-02. The wait ends on the caller's own abort and, like the + * worker's origin lease, at `mutationLockWaitTimeoutMs` as a retryable + * BLOCKED. A put or delete queued behind a long partition delete used to + * ignore its signal until that delete let go. */ async function withPartitionLock( mode: LockMode, @@ -1137,24 +1172,34 @@ export function createOpfsByteStoreAdapter( signal: AbortSignal | undefined, run: () => Promise>, ): Promise> { + const wait = createAbortableOperation({ + ...(signal ? { signal } : {}), + timeoutMs: policy.mutationLockWaitTimeoutMs, + }); let granted = false; try { return await requestLock( `${policy.mutationLockName}:partition:${scope.authorityToken}:${scope.namespaceToken}:${scope.partitionToken}`, - { mode, ...(signal ? { signal } : {}) }, + { mode, signal: wait.signal }, async () => { granted = true; + // Only the wait is bounded; aborting a granted request is a no-op. + wait.close(); return await run(); }, ); } catch (error) { if (granted) throw error; - return signal?.aborted + const terminal = wait.terminal(); + return terminal === "CALLER_ABORT" ? browserDataFailure("ABORTED", operation) - : browserDataFailure("UNAVAILABLE", operation, { - retryable: true, - recovery: "RETRY", - }); + : browserDataFailure( + terminal === "DEADLINE" ? "BLOCKED" : "UNAVAILABLE", + operation, + { retryable: true, recovery: "RETRY" }, + ); + } finally { + wait.close(); } } @@ -1610,6 +1655,7 @@ function snapshotOpfsJournal( listIncomplete, listCommittedObjects, isChunkReferenced, + countPartitionTransactions, removePartition, } = source; if ( @@ -1624,6 +1670,7 @@ function snapshotOpfsJournal( listIncomplete, listCommittedObjects, isChunkReferenced, + countPartitionTransactions, removePartition, ].some((method) => typeof method !== "function") ) { @@ -1640,6 +1687,7 @@ function snapshotOpfsJournal( listIncomplete: listIncomplete.bind(source), listCommittedObjects: listCommittedObjects.bind(source), isChunkReferenced: isChunkReferenced.bind(source), + countPartitionTransactions: countPartitionTransactions.bind(source), removePartition: removePartition.bind(source), }); } diff --git a/src/adapters/storage/opfs/opfs-policy.ts b/src/adapters/storage/opfs/opfs-policy.ts index c0776aa8..c1dc0e56 100644 --- a/src/adapters/storage/opfs/opfs-policy.ts +++ b/src/adapters/storage/opfs/opfs-policy.ts @@ -17,14 +17,17 @@ export type OpfsRuntimePolicy = Readonly<{ /** * R-5.3 (D-3). How long a request may queue for the origin mutation lock. * Another context's put holds that lock for its whole upload, so this wait - * is bounded on its own and never counted against `rpcTimeoutMs`. + * is bounded on its own and never counted against `rpcTimeoutMs`. The page + * bounds its wait for the partition lock by the same value (2026-11-03 + * 05-02). */ mutationLockWaitTimeoutMs: number; /** * 05-07. How long a put may wait for its source's next bytes. The put holds * the origin mutation lock from BEGIN to FINISH, so a stalled source would - * otherwise stop every tab's writes until their lock wait ran out. Keep it - * below `mutationLockWaitTimeoutMs` so a queued writer outlasts it. + * otherwise stop every tab's writes until their lock wait ran out. It must + * be below `mutationLockWaitTimeoutMs` so a queued writer outlasts it; the + * policy check refuses one that is not ([0929] 05-09). */ putIdleTimeoutMs: number; reconciliationBudgetMs: number; @@ -105,6 +108,8 @@ export function assertOpfsRuntimePolicy(policy: OpfsRuntimePolicy): void { !Number.isSafeInteger(policy.putIdleTimeoutMs) || policy.putIdleTimeoutMs < 1_000 || policy.putIdleTimeoutMs > 60 * 60_000 || + // [0929] 05-09. A queued writer must outlast a stalled one. + policy.putIdleTimeoutMs >= policy.mutationLockWaitTimeoutMs || !Number.isSafeInteger(policy.reconciliationBudgetMs) || policy.reconciliationBudgetMs < 1 || policy.reconciliationBudgetMs > 60_000 || 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/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index 1d21467e..7c638698 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -131,6 +131,13 @@ export type OpfsReconciliationReport = Readonly<{ * zero is storage damage for an operator to look at. */ corruptTransactions: number; + /** + * 2026-11-03 05-03. Of `corruptTransactions`, the rows whose partition key + * cannot be read either. No approved partition delete takes them, so they + * stay; they are not observed as `DEGRADED`, which is kept for damage a + * purge can clear. Present only when there were some. + */ + unattributedCorruptTransactions?: number; }>; export type OpfsPolicyMaintenanceReport = Readonly<{ @@ -145,9 +152,12 @@ export type OpfsPolicyMaintenanceReport = Readonly<{ moreObjectsAvailable: boolean; deadlineReached: boolean; /** - * 05-04. LOGOUT and ACCOUNT_DELETION only, once every object is removed: - * how the sweep of the partition's now unreferenced chunks ended. Chunk - * bytes are gone only when it is `COMPLETED`, or when `partitionDeleted`. + * 05-04. LOGOUT and ACCOUNT_DELETION only, once every object is removed and + * no put or delete of the partition is unfinished: how the sweep of the + * partition's now unreferenced chunks ended. For those two reasons the + * partition's bytes are gone exactly when this is `COMPLETED` or + * `partitionDeleted` is set; a put that begins after the purge reached its + * journal check is kept (2026-11-03 05-01). */ chunkSweep?: "COMPLETED" | "DEADLINE_REACHED" | "STAGING_STATE_UNREADABLE"; /** @@ -157,8 +167,11 @@ export type OpfsPolicyMaintenanceReport = Readonly<{ corruptObjects?: number; /** * [0929] 05-01. An approved LOGOUT or ACCOUNT_DELETION that damage kept - * from finishing removed the whole partition directory and the partition's - * journal rows instead. Every byte of the partition is gone. + * from finishing, or that found an unfinished put or delete of the + * partition (2026-11-03 05-01), removed the whole partition directory and + * the partition's journal rows instead, after every put and delete of the + * partition then running in any tab had returned. Every byte of the + * partition is gone. */ partitionDeleted?: true; }>; @@ -318,6 +331,12 @@ export type OpfsJournalPage = Readonly<{ transactions: readonly OpfsJournalTransaction[]; moreAvailable: boolean; corruptRows: number; + /** + * 2026-11-03 05-03. Of `corruptRows`, the rows without a readable partition + * key, which `removePartition` never reaches. Absent means none, or a + * journal that does not tell them apart. + */ + unattributedRows?: number; }>; export type OpfsCommittedObjectPage = Readonly<{ @@ -376,6 +395,14 @@ export interface OpfsJournalPort { scope: OpfsStorageScope, digestHex: string, ): Promise>; + /** + * 2026-11-03 05-01. How many journal rows are keyed to this one partition, + * readable or not: every put or delete of it that has not finished, live in + * some tab or left by a crash. Found by key, like `removePartition`. + */ + countPartitionTransactions( + scope: OpfsStorageScope, + ): Promise>; /** * [0929] 05-01. Deletes every row keyed to this one partition, readable or * not: committed objects, journal rows, chunk references and the budget. diff --git a/src/bootstrap/product-composition-contract.ts b/src/bootstrap/product-composition-contract.ts index 6f307a2f..97705adf 100644 --- a/src/bootstrap/product-composition-contract.ts +++ b/src/bootstrap/product-composition-contract.ts @@ -90,6 +90,18 @@ export type ProductCompositionContext = Readonly<{ isScopeReady(): boolean; }>; +/** + * 2026-11-03 02-01. Something a product built that must not outlive a session, + * such as a browser file runtime holding the previous user's files. The + * template closes it on every sign-out and account switch, after FENCED and + * before READY, at the step that releases offline leases. A close that throws + * or rejects keeps the scope from reaching READY, as the template's own do. + */ +export type ProductScopeParticipant = Readonly<{ + label: string; + close(): void | Promise; +}>; + export type ProductComposition = Readonly<{ capabilities: Readonly< Partial> @@ -106,4 +118,11 @@ export type ProductComposition = Readonly<{ onCredentialRejected?( binding: Readonly<{ operationId: string; authProfileId: string }>, ): void; + /** + * Closed in this order on each identity change. A capability that needs a + * fresh object for the next session hands features a getter and rebuilds + * behind it, as `recipes/frontend-capabilities/browser-file-session-capability.ts` + * does. + */ + scopeParticipants?: readonly ProductScopeParticipant[]; }>; diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 3e6215ae..c736d8cf 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -62,7 +62,10 @@ import { composeProduct, composeProductSessionOwner, } from "./product-composition.ts"; -import type { ProductComposition } from "./product-composition-contract.ts"; +import type { + ProductComposition, + ProductScopeParticipant, +} from "./product-composition-contract.ts"; import { createProductSessionOwnerContext } from "./product-session-owner-context.ts"; import { createInstalledContractRegistry } from "../features/installed-contract-contributions.ts"; import { @@ -383,6 +386,11 @@ export async function createRuntimeAdapters( crossContextInvalidation?.getStatus() ?? "DEGRADED_LOCAL_ONLY", }); }); + // 2026-11-03 02-01. The product's closers. `composeProduct` runs after the + // scope exists (its context needs the fence), so they join through this one + // slot, filled below. Each runs even when an earlier one fails, and any + // failure keeps the scope from READY, as for the template's own. + const productScopeParticipants: ProductScopeParticipant[] = []; const serverStateScope = createServerStateScopeRuntime({ session: authSession, diagnostics, @@ -395,6 +403,21 @@ export async function createRuntimeAdapters( label: "conditional-validators", close: () => conditionalValidators.clear(), }, + { + order: 10, + label: "product", + async close() { + let failed = false; + for (const participant of productScopeParticipants) { + try { + await participant.close(); + } catch { + failed = true; + } + } + if (failed) throw new Error("A product scope participant failed."); + }, + }, ], activateNextGeneration: () => serverStateGeneration.activateNext(), }); @@ -647,10 +670,12 @@ export async function createRuntimeAdapters( isScopeReady: () => serverStateScope.getPhase() === "READY", }) satisfies ProductComposition; // Read through the contract type: the product's own return type omits the - // optional hook when the product does not use it. + // optional fields when the product does not use them, and `product` keeps + // its narrow type above so a missing capability still fails the typecheck. const productContract: ProductComposition = product; const productCredentialProviders = productContract.credentialProviders; const onProductCredentialRejected = productContract.onCredentialRejected; + productScopeParticipants.push(...(productContract.scopeParticipants ?? [])); // Each installed contribution receives only the capabilities it declares. // The template's own capabilities come last, so a product cannot replace // them. 09-05. `indexedDb` is not built here: IndexedDB is an opt-in diff --git a/tests/browser-capabilities/opfs-runtime.spec.ts b/tests/browser-capabilities/opfs-runtime.spec.ts index cecf5a07..7157a7fc 100644 --- a/tests/browser-capabilities/opfs-runtime.spec.ts +++ b/tests/browser-capabilities/opfs-runtime.spec.ts @@ -229,13 +229,15 @@ type OpfsTabScope = Readonly<{ /** * Installs an OPFS runtime for `scope` in this tab and keeps it on - * `globalThis.__opfsTab` for later evaluate calls. + * `globalThis.__opfsTab` for later evaluate calls. `approvePurges` stands in + * for an authority that approves every LOGOUT and ACCOUNT_DELETION. */ async function installOpfsTab( page: import("@playwright/test").Page, scope: OpfsTabScope, + approvePurges = false, ): Promise { - return await page.evaluate(async (tabScope) => { + return await page.evaluate(async ({ tabScope, approvePurges }) => { const runtimeModulePath = "/src/adapters/storage/opfs/browser-opfs-runtime.ts"; const policyModulePath = "/src/adapters/storage/opfs/opfs-policy.ts"; @@ -272,11 +274,153 @@ async function installOpfsTab( unavailableFallback: "EXPORT_REQUIRED", }, policy, + ...(approvePurges + ? { + requestMaintenanceAuthority: () => ({ + authorized: true as const, + proofToken: `proof_${crypto.randomUUID().replaceAll("-", "")}`, + expiresAtEpochMs: Date.now() + 60_000, + }), + consumeMaintenanceAuthority: () => true, + } + : {}), }); return true; + }, { tabScope: scope, approvePurges }); +} + +/** Deletes everything the OPFS runtime wrote for `scope`'s authority. */ +async function removeOpfsAuthority( + page: import("@playwright/test").Page, + scope: OpfsTabScope, +): Promise { + return await page.evaluate(async (tabScope) => { + const journalModulePath = + "/src/adapters/storage/opfs/indexeddb-opfs-journal.ts"; + const policyModulePath = "/src/adapters/storage/opfs/opfs-policy.ts"; + const { opfsJournalDatabaseName } = (await import( + /* @vite-ignore */ journalModulePath + )) as typeof import("../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"); + const { DEFAULT_OPFS_RUNTIME_POLICY } = (await import( + /* @vite-ignore */ policyModulePath + )) as typeof import("../../src/adapters/storage/opfs/opfs-policy.ts"); + const deletion = await new Promise((resolve) => { + const request = indexedDB.deleteDatabase( + opfsJournalDatabaseName(tabScope.authorityToken), + ); + request.onsuccess = () => resolve("DELETED"); + request.onerror = () => resolve(request.error?.name ?? "UNKNOWN"); + request.onblocked = () => resolve("BLOCKED"); + }); + try { + const root = await ( + await navigator.storage.getDirectory() + ).getDirectoryHandle(DEFAULT_OPFS_RUNTIME_POLICY.rootDirectoryName); + await ( + await root.getDirectoryHandle("authorities") + ).removeEntry(tabScope.authorityToken, { recursive: true }); + } catch { + // Nothing was written for this authority. + } + return deletion; }, scope); } +// 2026-11-03 05-01 X1. The purge used to report a completed sweep while the +// other tab's put landed, and the object stayed readable after the account +// deletion. It now waits for that put and takes it with the partition. +test("05-01 an approved purge in another tab waits for a live put and takes it with the partition", async ({ + page, +}) => { + const secondPage = await page.context().newPage(); + const suffix = crypto.randomUUID().replaceAll("-", ""); + const scope: OpfsTabScope = { + namespace: "durable-objects", + authorityToken: `authority_${suffix}`, + namespaceToken: `namespace_${suffix}`, + partitionToken: `partition_${suffix}`, + }; + type Tab = import("../../src/adapters/storage/opfs/browser-opfs-runtime.ts").BrowserOpfsRuntime; + try { + await Promise.all([page.goto("/"), secondPage.goto("/")]); + if (!(await installOpfsTab(page, scope))) return; + expect(await installOpfsTab(secondPage, scope, true)).toBe(true); + + await page.evaluate(async () => { + const state = globalThis as unknown as { + __opfsTab: Tab; + __release?: () => void; + __put?: Promise; + }; + let streaming!: () => void; + const started = new Promise((resolve) => { + streaming = resolve; + }); + const gate = new Promise((resolve) => { + state.__release = resolve; + }); + state.__put = state.__opfsTab.objects.put({ + objectId: "object_tab_12345678", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: { + byteLength: 4, + async *stream() { + streaming(); + await gate; + yield { ok: true as const, value: new Uint8Array([2, 7, 1, 8]) }; + }, + }, + }); + await started; + }); + await secondPage.evaluate(() => { + const state = globalThis as unknown as { + __opfsTab: Tab; + __purge?: Promise; + }; + state.__purge = state.__opfsTab.maintenance.enforcePolicies({ + reason: "ACCOUNT_DELETION", + }); + }); + await page.waitForTimeout(250); + const put = await page.evaluate(async () => { + const state = globalThis as unknown as { + __release: () => void; + __put: Promise; + }; + state.__release(); + return await state.__put; + }); + const report = await secondPage.evaluate( + async () => + await (globalThis as unknown as { __purge: Promise }).__purge, + ); + const opened = await secondPage.evaluate(async () => { + const runtime = (globalThis as unknown as { __opfsTab: Tab }).__opfsTab; + const result = await runtime.objects.open({ + objectId: "object_tab_12345678", + }); + return result.ok ? "OPENED" : result.error.code; + }); + + expect(put).toMatchObject({ ok: true, value: { generation: 1 } }); + expect(report).toMatchObject({ + ok: true, + value: { moreObjectsAvailable: false, partitionDeleted: true }, + }); + expect(opened).toBe("NOT_FOUND"); + } finally { + for (const tab of [page, secondPage]) { + await tab.evaluate(() => + (globalThis as unknown as { __opfsTab?: Tab }).__opfsTab?.close(), + ); + } + expect(await removeOpfsAuthority(page, scope)).toBe("DELETED"); + await secondPage.close(); + } +}); + test("05-01 a reconcile in another tab skips a live put and the put stays readable", async ({ page, }) => { @@ -375,37 +519,7 @@ test("05-01 a reconcile in another tab skips a live put and the put stays readab (globalThis as unknown as { __opfsTab?: Tab }).__opfsTab?.close(), ); } - const cleanup = await page.evaluate(async (tabScope) => { - const journalModulePath = - "/src/adapters/storage/opfs/indexeddb-opfs-journal.ts"; - const policyModulePath = "/src/adapters/storage/opfs/opfs-policy.ts"; - const { opfsJournalDatabaseName } = (await import( - /* @vite-ignore */ journalModulePath - )) as typeof import("../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"); - const { DEFAULT_OPFS_RUNTIME_POLICY } = (await import( - /* @vite-ignore */ policyModulePath - )) as typeof import("../../src/adapters/storage/opfs/opfs-policy.ts"); - const deletion = await new Promise((resolve) => { - const request = indexedDB.deleteDatabase( - opfsJournalDatabaseName(tabScope.authorityToken), - ); - request.onsuccess = () => resolve("DELETED"); - request.onerror = () => resolve(request.error?.name ?? "UNKNOWN"); - request.onblocked = () => resolve("BLOCKED"); - }); - try { - const root = await ( - await navigator.storage.getDirectory() - ).getDirectoryHandle(DEFAULT_OPFS_RUNTIME_POLICY.rootDirectoryName); - await ( - await root.getDirectoryHandle("authorities") - ).removeEntry(tabScope.authorityToken, { recursive: true }); - } catch { - // Nothing was written for this authority. - } - return deletion; - }, scope); - expect(cleanup).toBe("DELETED"); + expect(await removeOpfsAuthority(page, scope)).toBe("DELETED"); await secondPage.close(); } }); diff --git a/tests/helpers/memory-opfs.ts b/tests/helpers/memory-opfs.ts new file mode 100644 index 00000000..ec226ffe --- /dev/null +++ b/tests/helpers/memory-opfs.ts @@ -0,0 +1,123 @@ +/** + * An in-memory Origin Private File System for the OPFS worker runtime: just + * the `FileSystemDirectoryHandle` / `FileSystemFileHandle` surface it uses. + * Moved out of `tests/unit/opfs-worker-runtime.test.ts` so the recipe tests + * can run the same runtime (2026-11-03 05-04). + */ + +export type MemoryNode = MemoryDirectory | MemoryFile; + +export class MemoryFile { + readonly kind = "file"; + bytes = new Uint8Array(); + lastModified = 0; + reads = 0; +} + +export class MemoryDirectory { + readonly kind = "directory"; + readonly children = new Map(); + + async getDirectoryHandle( + name: string, + options: FileSystemGetDirectoryOptions = {}, + ): Promise { + const current = this.children.get(name); + if (current instanceof MemoryDirectory) { + return current as unknown as FileSystemDirectoryHandle; + } + if (current || !options.create) throw notFound(); + const created = new MemoryDirectory(); + this.children.set(name, created); + return created as unknown as FileSystemDirectoryHandle; + } + + async getFileHandle( + name: string, + options: FileSystemGetFileOptions = {}, + ): Promise { + const current = this.children.get(name); + if (current instanceof MemoryFile) { + return fileHandle(current); + } + if (current || !options.create) throw notFound(); + const created = new MemoryFile(); + this.children.set(name, created); + return fileHandle(created); + } + + async removeEntry( + name: string, + options: FileSystemRemoveOptions = {}, + ): Promise { + const current = this.children.get(name); + if (!current) throw notFound(); + if ( + current instanceof MemoryDirectory && + current.children.size > 0 && + !options.recursive + ) { + throw new DOMException("Directory is not empty.", "InvalidModificationError"); + } + this.children.delete(name); + } + + async *entries(): AsyncIterableIterator< + [string, FileSystemDirectoryHandle | FileSystemFileHandle] + > { + for (const [name, node] of this.children) { + yield [ + name, + node instanceof MemoryDirectory + ? (node as unknown as FileSystemDirectoryHandle) + : fileHandle(node), + ]; + } + } + + has(path: readonly string[]): boolean { + let current: MemoryNode = this; + for (const segment of path) { + if (!(current instanceof MemoryDirectory)) return false; + const next = current.children.get(segment); + if (!next) return false; + current = next; + } + return true; + } +} + +function fileHandle(file: MemoryFile): FileSystemFileHandle { + return { + kind: "file", + name: "memory", + async getFile() { + file.reads += 1; + const blob = new Blob([Uint8Array.from(file.bytes)]); + Object.defineProperty(blob, "lastModified", { + value: file.lastModified, + }); + return blob as File; + }, + async createWritable() { + let pending = Uint8Array.from(file.bytes); + return { + async write(data: FileSystemWriteChunkType) { + if (!(data instanceof Uint8Array)) { + throw new TypeError("The test writer accepts Uint8Array only."); + } + pending = Uint8Array.from(data); + }, + async close() { + file.bytes = pending; + file.lastModified = Date.now(); + }, + async abort() {}, + } as unknown as FileSystemWritableFileStream; + }, + } as FileSystemFileHandle; +} + +function notFound(): DOMException { + return new DOMException("Entry was not found.", "NotFoundError"); +} diff --git a/tests/recipes/browser-file-session-capability.test.ts b/tests/recipes/browser-file-session-capability.test.ts new file mode 100644 index 00000000..7afb7aab --- /dev/null +++ b/tests/recipes/browser-file-session-capability.test.ts @@ -0,0 +1,284 @@ +// @vitest-environment jsdom + +import { afterEach, describe, expect, it, vi } from "vitest"; + +import type { LocalFileRef } from "../../src/application/ports/browser-file-storage/index.ts"; +import { + browserFilePolicyReference, + createBrowserFileRuntime, + type BrowserFilePolicyProfile, +} from "../../src/adapters/browser-files/index.ts"; +import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts"; +import { createSessionBrowserFileCapability } from "../../recipes/frontend-capabilities/browser-file-session-capability.ts"; + +/** + * 2026-11-03 02-01. A product wires the browser file runtime to the session by + * filling only its own `product-composition.ts`: the recipe capability goes to + * features, its scope participant to the template. The real + * `createRuntimeAdapters` runs; only the product-owned file is replaced, with + * what a product would write in it. + */ + +const selectPolicy = browserFilePolicyReference("session-file", "select-text"); +const downloadPolicy = browserFilePolicyReference( + "session-download", + "bounded-generated-bin", +); +const policies: readonly BrowserFilePolicyProfile[] = [ + { + reference: selectPolicy, + selection: { + policyId: "attachment-v1", + purpose: "attachment", + classification: "PERSONAL", + multiple: false, + maxCount: 1, + maxFileBytes: 8, + maxTotalBytes: 8, + allowEmpty: false, + accept: [{ mediaType: "text/plain", extensions: [".txt"] }], + }, + }, + { + reference: downloadPolicy, + download: { + strategy: "BOUNDED_OBJECT_URL", + mediaType: "application/octet-stream", + safeExtension: ".bin", + maxTransferBytes: 8, + maxBufferedBytes: 8, + integrity: "OPTIONAL", + }, + }, +]; + +const fixture = vi.hoisted(() => ({ + files: undefined as + | ReturnType["files"] + | undefined, + inputs: [] as HTMLInputElement[], + handoffs: 0, + owner: undefined as + | Readonly<{ switchUser(subject: string): void }> + | undefined, +})); + +function fileInput(): HTMLInputElement { + const input = document.createElement("input"); + input.type = "file"; + input.setAttribute("aria-label", "Attachment"); + Object.defineProperty(input, "click", { configurable: true, value: vi.fn() }); + document.body.append(input); + fixture.inputs.push(input); + return input; +} + +function externalOwner() { + const listeners = new Set<() => void>(); + let subject = "user-a"; + return { + readState: () => "authenticated", + readSubject: () => subject, + subscribe(listener: () => void) { + listeners.add(listener); + return () => listeners.delete(listener); + }, + beginSignIn: async () => {}, + signOut: async () => {}, + attachCredential: async () => ({ headers: {} }), + recoverSession: async () => "no-session", + notifyUnauthenticated: () => {}, + switchUser(next: string) { + subject = next; + for (const listener of listeners) listener(); + }, + }; +} + +/** The product-owned file, filled the way a product fills it. */ +vi.mock("../../src/bootstrap/product-composition.ts", () => ({ + composeProductSessionOwner: () => { + const owner = externalOwner(); + fixture.owner = owner; + return owner; + }, + composeProduct: () => { + const browserFiles = createSessionBrowserFileCapability(() => + createBrowserFileRuntime({ + input: fileInput(), + policies, + limits: { + hardMaxPreviewBytes: 8, + hardMaxObjectUrlBytes: 8, + hardMaxTransferBytes: 16, + }, + objectUrlApi: { + createObjectURL: () => "blob:session-download", + revokeObjectURL() {}, + }, + download: { + host: { + handoff() { + fixture.handoffs += 1; + }, + }, + browserManagedCapabilities: { + resolve: () => ({ + ok: false as const, + error: { + code: "POLICY_REJECTED" as const, + operation: "DOWNLOAD" as const, + retryable: false, + recovery: "NONE" as const, + }, + }), + }, + }, + }), + ); + fixture.files = browserFiles.files; + return { + capabilities: {}, + credentialProviders: {}, + scopeParticipants: [browserFiles.scopeParticipant], + }; + }, +})); + +let current: Awaited> | undefined; +afterEach(() => { + current?.infrastructure.dispose(); + current = undefined; + for (const input of fixture.inputs.splice(0)) input.remove(); + fixture.files = undefined; + fixture.handoffs = 0; +}); + +async function compose() { + current = await createRuntimeAdapters({ + runtime: { + config: { + APP_ENV: "local", + API_BASE_URL: "http://localhost:8080", + TELEMETRY_ENABLED: false, + AUTH_MODE: "external", + REQUEST_TIMEOUT_MS: 10_000, + MAX_RETRY_ATTEMPTS: 0, + RELEASE_MANIFEST_URL: "/release-manifest.json", + CONFIG_SCHEMA_VERSION: "2.0", + CAPABILITY_OVERRIDES: { + REALTIME: "DEFAULT", + WEB_WORKER: "DEFAULT", + SERVICE_WORKER: "DEFAULT", + OFFLINE_COMMANDS: "DEFAULT", + }, + FEATURE_OVERRIDES: {}, + }, + configSchema: "V2", + build: { + buildId: "build-a", + commitSha: "abc123", + routerBasePath: "/", + runtimeConfigUrl: "/config.json", + }, + validationDurationMs: 0, + }, + release: { + schemaVersion: 2, + appVersion: "0.1.0", + buildId: "build-a", + commitSha: "abc123", + configSchemaVersion: "2.0", + contractSet: { + setAlgorithm: "CA_CONTRACT_SET_V1", + setDigest: `sha256:${"0".repeat(64)}`, + packages: [], + }, + assetManifestHash: "hash-a", + releaseId: "release-a", + builtAt: "2026-07-25T00:00:00Z", + routeChunks: { "route-home": "assets/home.js" }, + }, + host: {}, + }); + const files = fixture.files; + const owner = fixture.owner; + if (!files || !owner) throw new Error("The product composition did not run"); + return { adapters: current, files, owner }; +} + +async function selectOne( + runtime: ReturnType["current"]>, + name: string, +) { + const pending = runtime.baselinePicker.select({ policy: selectPolicy }); + const input = fixture.inputs.at(-1)!; + Object.defineProperty(input, "files", { + configurable: true, + value: [new File(["text"], name, { type: "text/plain", lastModified: 1 })], + }); + input.dispatchEvent(new Event("change")); + return await pending; +} + +describe("a session-scoped browser file runtime (2026-11-03 02-01)", () => { + it("closes the previous user's files and downloads on an account switch and serves the next session a new runtime", async () => { + const { adapters, files, owner } = await compose(); + const previous = files.current(); + const selected = await selectOne(previous, "user-a.txt"); + if (!selected.ok || selected.value.kind !== "SELECTED") { + throw new Error(`The first selection failed: ${JSON.stringify(selected)}`); + } + const ref: LocalFileRef = selected.value.files[0]!.ref; + let producing!: () => void; + const started = new Promise((resolve) => { + producing = resolve; + }); + const download = previous.downloads.deliver({ + policy: downloadPolicy, + source: { + kind: "GENERATED", + bytes: { + byteLength: 1, + async *stream() { + producing(); + await new Promise(() => {}); + yield { ok: true as const, value: new Uint8Array([1]) }; + }, + }, + }, + suggestedFileName: "user-a-report", + maxTransferBytes: 8, + maxBufferedBytes: 8, + signal: new AbortController().signal, + onProgress() {}, + }); + await started; + + owner.switchUser("user-b"); + await vi.waitFor(() => + expect(adapters.infrastructure.serverStateScope.getPhase()).toBe("READY"), + ); + + expect( + await previous.content.readRange({ + ref, + offset: 0, + length: 1, + signal: new AbortController().signal, + }), + ).toMatchObject({ ok: false, error: { code: "UNAVAILABLE" } }); + expect(await download).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "DOWNLOAD" }, + }); + expect(fixture.handoffs).toBe(0); + + const next = files.current(); + expect(next).not.toBe(previous); + expect(await selectOne(next, "user-b.txt")).toMatchObject({ + ok: true, + value: { kind: "SELECTED" }, + }); + }); +}); diff --git a/tests/recipes/browser-file-storage-contracts.test.ts b/tests/recipes/browser-file-storage-contracts.test.ts index 1b5c6d97..f4e0202b 100644 --- a/tests/recipes/browser-file-storage-contracts.test.ts +++ b/tests/recipes/browser-file-storage-contracts.test.ts @@ -37,6 +37,17 @@ import type { StorageDurabilityPort, TransientPreviewPort, } from "../../src/application/ports/browser-file-storage/index.ts"; +import { browserDataFailure } from "../../src/adapters/browser-file-storage/result.ts"; +import { + createIndexedDbOpfsJournal, + createOpfsByteStoreAdapter, + createOpfsWorkerGateway, + createOpfsWorkerRuntime, + createWebLockLeaseManager, + resolveOpfsRuntimePolicy, +} from "../../src/adapters/storage/opfs/index.ts"; +import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; +import { MemoryDirectory } from "../helpers/memory-opfs.ts"; async function* byteChunks( ...values: ReadonlyArray @@ -587,7 +598,7 @@ describe("production browser file and storage recipe contracts", () => { stream: () => byteChunks(...values), }); - store.failNextPutAfter("FILES_READY"); + store.failNextPutAfter("PREPARING"); expect( await store.put({ objectId, @@ -603,7 +614,8 @@ describe("production browser file and storage recipe contracts", () => { ok: false, error: { code: "NOT_FOUND" }, }); - // Like the runtime, reconcile rolls a stopped put back; it never resumes. + // Like the runtime, reconcile rolls a put that stopped before FILES_READY + // back. One that stopped after it is committed (2026-11-03 05-04, below). expect(await store.reconcile()).toMatchObject({ ok: true, value: { rolledBackTransactions: 1, moreTransactionsAvailable: false }, @@ -733,6 +745,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, @@ -741,3 +754,207 @@ describe("production browser file and storage recipe contracts", () => { }); }); }); + +/** + * 2026-11-03 05-04. The fake rolled every stopped put back, while the runtime + * commits one that stopped after FILES_READY and rolls back one that stopped + * while PREPARING. A downstream test written against the fake then passed + * "a stopped upload is gone after reconcile" although the runtime brings the + * file back. The same scenarios now run on both and must agree. + */ +describe("the durable object fake reconciles a stopped put like the runtime (2026-11-03 05-04)", () => { + type StoppablePhase = "PREPARING" | "FILES_READY"; + type StoppableStore = Readonly<{ + store: DurableObjectStorePort & DurableObjectMaintenancePort; + stopNextPutAfter(phase: StoppablePhase): void; + }>; + + const scope = Object.freeze({ + namespace: "durable-objects", + authorityToken: "authority_12345678", + namespaceToken: "namespace_12345678", + partitionToken: "partition_12345678", + }); + const storagePolicy: BrowserStoragePolicy = Object.freeze({ + owner: "recipe-test", + namespace: "durable-objects", + classification: "PERSONAL", + authority: "LOCAL_FIRST", + accountScope: "OPAQUE_PARTITION", + retention: Object.freeze({ kind: "EXPLICIT_DELETE" }), + softBudgetBytes: 32, + hardBudgetBytes: 64, + evictionPriority: "USER_AUTHORED", + logoutAction: "EXPORT_THEN_PURGE", + accountDeletionAction: "PURGE_PARTITION", + pressureAction: "RETAIN", + unavailableFallback: "EXPORT_REQUIRED", + }); + + function fake(): StoppableStore { + const store = new MemoryDurableObjectStore({ + scope, + storagePolicy, + maxObjectBytes: 32, + }); + return { store, stopNextPutAfter: (phase) => store.failNextPutAfter(phase) }; + } + + /** The reference runtime on an in-memory OPFS root and IndexedDB. */ + function runtime(): StoppableStore { + const policy = resolveOpfsRuntimePolicy({ + chunkSizeBytes: 64 * 1024, + maxObjectBytes: 64 * 1024, + maxChunkCount: 1, + }); + const worker = createOpfsWorkerRuntime({ + root: new MemoryDirectory() as unknown as FileSystemDirectoryHandle, + crypto: globalThis.crypto, + policy, + leaseManager: createWebLockLeaseManager( + navigator.locks, + `${policy.mutationLockName}:${crypto.randomUUID()}`, + ), + dedicatedWorker: true, + supportsSynchronousAccessHandles: false, + }); + let listener: ((event: MessageEvent) => void) | undefined; + const gateway = createOpfsWorkerGateway({ + worker: { + postMessage(message) { + void worker + .handleRequest(message) + .then((response) => listener?.({ data: response } as MessageEvent)); + }, + addEventListener(_type, next) { + listener = next; + }, + removeEventListener() { + listener = undefined; + }, + }, + policy, + }); + const idb = new MemoryIndexedDbFactory(); + const journal = createIndexedDbOpfsJournal({ + authorityToken: scope.authorityToken, + factory: idb.factory, + keyRange: idb.keyRange, + }); + let stopAfter: StoppablePhase | null = null; + let compensationLost = false; + // The tab closes at this step: the journal write never lands and, before + // commit, neither does its compensation. + const crashed = async () => { + compensationLost = stopAfter === "PREPARING"; + stopAfter = null; + return browserDataFailure("UNAVAILABLE", "INDEXEDDB_WRITE", { + retryable: true, + recovery: "RETRY", + }); + }; + const { objects, maintenance } = createOpfsByteStoreAdapter({ + journal: { + ...journal, + markFilesReady: (...input) => + stopAfter === "PREPARING" ? crashed() : journal.markFilesReady(...input), + commitPut: (...input) => + stopAfter === "FILES_READY" ? crashed() : journal.commitPut(...input), + }, + worker: { + ...gateway, + async abortPreparedPut(input) { + if (!compensationLost) return await gateway.abortPreparedPut(input); + compensationLost = false; + return browserDataFailure("UNAVAILABLE", "OBJECT_WRITE", { + retryable: true, + recovery: "RETRY", + }); + }, + }, + scope, + storagePolicy, + policy, + requestMaintenanceAuthority: () => ({ + authorized: true as const, + proofToken: "proof_token_1234567890", + expiresAtEpochMs: Date.now() + 60_000, + }), + consumeMaintenanceAuthority: () => true, + }); + return { + store: { ...objects, ...maintenance }, + stopNextPutAfter(phase) { + stopAfter = phase; + }, + }; + } + + async function stoppedPut( + { store, stopNextPutAfter }: StoppableStore, + phase: StoppablePhase, + purgeBeforeReconcile: boolean, + ) { + const objectId = asDurableObjectId("object_opaque_0001"); + const opened = async () => { + const result = await store.open({ objectId }); + if (!result.ok) return result.error.code; + const bytes: number[] = []; + for await (const chunk of result.value.source.stream( + new AbortController().signal, + )) { + if (!chunk.ok) return chunk.error.code; + bytes.push(...chunk.value); + } + return new TextDecoder().decode(new Uint8Array(bytes)); + }; + stopNextPutAfter(phase); + const put = await store.put({ + objectId, + expectedGeneration: null, + mediaType: "application/octet-stream", + source: { byteLength: 4, stream: () => byteChunks("ab", "cd") }, + }); + const beforeReconcile = await opened(); + const purge = purgeBeforeReconcile + ? await store.enforcePolicies({ reason: "ACCOUNT_DELETION" }) + : null; + const reconciled = await store.reconcile(); + if (!reconciled.ok || (purge && !purge.ok)) { + throw new Error("maintenance failed"); + } + return { + putSucceeded: put.ok, + beforeReconcile, + purge: purge && { + partitionDeleted: purge.value.partitionDeleted ?? false, + chunkSweep: purge.value.chunkSweep ?? null, + }, + committedTransactions: reconciled.value.committedTransactions, + rolledBackTransactions: reconciled.value.rolledBackTransactions, + afterReconcile: await opened(), + }; + } + + it.each([ + ["FILES_READY", false, { committed: 1, rolledBack: 0, after: "abcd" }], + ["PREPARING", false, { committed: 0, rolledBack: 1, after: "NOT_FOUND" }], + ["FILES_READY", true, { committed: 0, rolledBack: 0, after: "NOT_FOUND" }], + ["PREPARING", true, { committed: 0, rolledBack: 0, after: "NOT_FOUND" }], + ] as const)( + "agrees on a put stopped after %s (account deleted before reconcile: %s)", + async (phase, purge, expected) => { + const fromRuntime = await stoppedPut(runtime(), phase, purge); + + expect(fromRuntime).toEqual({ + putSucceeded: false, + beforeReconcile: "NOT_FOUND", + purge: purge ? { partitionDeleted: true, chunkSweep: null } : null, + committedTransactions: expected.committed, + rolledBackTransactions: expected.rolledBack, + afterReconcile: expected.after, + }); + expect(await stoppedPut(fake(), phase, purge)).toEqual(fromRuntime); + }, + ); +}); diff --git a/tests/unit/browser-file-content.test.ts b/tests/unit/browser-file-content.test.ts index a1de678e..fde5dcbf 100644 --- a/tests/unit/browser-file-content.test.ts +++ b/tests/unit/browser-file-content.test.ts @@ -614,6 +614,107 @@ describe("browser file content policy", () => { }); }); + it("issues no receipt for a ref released while inspect() was reading it (2026-11-03 02-04)", async () => { + const vault = new BrowserFileVault({ policies: pngPolicies() }); + const captured = vault.captureFiles( + [ + new File( + [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])], + "released.png", + { type: "image/png", lastModified: 1 }, + ), + ], + pngSelectionPolicy, + ); + if (!captured.ok || !captured.value[0]) throw new Error("capture"); + const ref = captured.value[0].ref; + + // The user removes the file from the list before the check finishes. + const pending = vault.inspect({ + ref, + policy: pngPolicy, + signal: new AbortController().signal, + }); + vault.release(ref); + + expect(await pending).toMatchObject({ + ok: false, + error: { code: "NOT_FOUND", recovery: "RESELECT" }, + }); + expect(vault.activeReferenceCount).toBe(0); + expect(vault.activeVerificationCount).toBe(0); + expect(vault.retainedByteLength).toBe(0); + }); + + // 2026-11-03 02-03. Logout disposes the runtime while a call is in flight. + // The lease registry still hands out leases after dispose, so each + // consumer's own re-check is the only thing that keeps a URL from outliving + // the session. + it("creates no object URL for a preview whose runtime is disposed while it resolves", async () => { + let urlSequence = 0; + const leases = new ObjectUrlLeaseRegistry({ + createObjectURL: () => `blob:disposed-${urlSequence++}`, + revokeObjectURL() {}, + }); + const { preview, request } = await verifiedPngPreview(leases); + + const pending = preview.create(request(new AbortController().signal)); + preview.dispose(); + + expect(await pending).toMatchObject({ + ok: false, + error: { code: "UNAVAILABLE", operation: "PREVIEW" }, + }); + expect(urlSequence).toBe(0); + expect(leases.activeLeaseCount).toBe(0); + }); + + it("opens no byte source for a file whose vault is disposed while it loads", async () => { + const vault = new BrowserFileVault({ policies: pngPolicies() }); + const captured = vault.captureFiles( + [ + new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], "a.png", { + type: "image/png", + lastModified: 1, + }), + ], + pngSelectionPolicy, + ); + if (!captured.ok || !captured.value[0]) throw new Error("capture"); + + const pending = vault.openSource({ + ref: captured.value[0].ref, + signal: new AbortController().signal, + }); + vault.dispose(); + + expect(await pending).toMatchObject({ + ok: false, + error: { code: "UNAVAILABLE", operation: "FILE_READ" }, + }); + }); + + it("lets go of every selected File on dispose", () => { + const vault = new BrowserFileVault({ policies: pngPolicies() }); + expect( + vault.captureFiles( + [ + new File([new Uint8Array([0x89, 0x50, 0x4e, 0x47])], "a.png", { + type: "image/png", + lastModified: 1, + }), + ], + pngSelectionPolicy, + ), + ).toMatchObject({ ok: true }); + expect(vault.activeReferenceCount).toBe(1); + + vault.dispose(); + + expect(vault.activeReferenceCount).toBe(0); + expect(vault.retainedByteLength).toBe(0); + }); + it("returns ABORTED without a lease when the caller aborts right after create() (02-01)", async () => { const revoked: string[] = []; let urlSequence = 0; @@ -880,6 +981,83 @@ describe("browser file content policy", () => { ).toThrowError(DOMException); lease.release(); expect(leases.aggregateLeaseByteLength).toBe(0); + + // 2026-11-01 02-04 (N29). A free slot does not lift the byte cap. + const byBytes = new ObjectUrlLeaseRegistry( + { + createObjectURL: () => `blob:bytes-${urlSequence++}`, + revokeObjectURL() {}, + }, + { + hardMaxActiveLeases: 2, + hardMaxSingleLeaseBytes: 4, + hardMaxAggregateLeaseBytes: 6, + }, + ); + const held = byBytes.create(new Blob([new Uint8Array(4)])); + expect(() => + byBytes.create(new Blob([new Uint8Array(3)])), + ).toThrowError(DOMException); + expect(byBytes.activeLeaseCount).toBe(1); + held.release(); + expect(() => + byBytes.create(new Blob([new Uint8Array(3)])), + ).not.toThrow(); + }); + + // 2026-11-01 02-04 (N27). Inspecting again replaces the receipt: the file + // may have been checked against a different policy, so the old one ends. + it("ends the previous receipt when the same file is inspected again", async () => { + const policies = pngPolicies(); + const vault = new BrowserFileVault({ policies }); + const captured = vault.captureFiles( + [ + new File( + [new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])], + "again.png", + { type: "image/png", lastModified: 1 }, + ), + ], + pngSelectionPolicy, + ); + if (!captured.ok || !captured.value[0]) throw new Error("capture"); + const ref = captured.value[0].ref; + const receiptOf = async () => { + const inspected = await vault.inspect({ + ref, + policy: pngPolicy, + signal: new AbortController().signal, + }); + if (!inspected.ok || !inspected.value.verificationReceipt) { + throw new Error("inspect"); + } + return inspected.value.verificationReceipt; + }; + const first = await receiptOf(); + const second = await receiptOf(); + expect(vault.activeVerificationCount).toBe(1); + const preview = new BrowserTransientPreview({ + files: vault, + policies, + leases: new ObjectUrlLeaseRegistry({ + createObjectURL: () => "blob:again", + revokeObjectURL() {}, + }), + hardMaxPreviewBytes: 10, + }); + const create = (verificationReceipt: FileVerificationReceipt) => + preview.create({ + ref, + verificationReceipt, + policy: pngPolicy, + signal: new AbortController().signal, + }); + + expect(await create(first)).toMatchObject({ + ok: false, + error: { code: "POLICY_REJECTED" }, + }); + expect(await create(second)).toMatchObject({ ok: true }); }); it("converts native stream exceptions to closed chunk failures", async () => { diff --git a/tests/unit/browser-file-download.test.ts b/tests/unit/browser-file-download.test.ts index 4521d7e7..40effd97 100644 --- a/tests/unit/browser-file-download.test.ts +++ b/tests/unit/browser-file-download.test.ts @@ -293,9 +293,11 @@ describe("browser download delivery", () => { it("rejects cross-origin or query-bearing browser-managed targets", async () => { // 02-08. Each href breaks one rule, so neither check hides the other. + // 2026-11-01 02-04 (N30): a fragment is refused on its own too. for (const href of [ "https://evil.example/downloads/a", "/downloads/a?token=secret", + "/downloads/a#token=secret", ]) { const handoff = vi.fn(); const adapter = createDownloadDeliveryAdapter({ @@ -767,6 +769,39 @@ describe("browser download delivery", () => { expect(revoked).toEqual(["blob:download-1"]); }); + // [0929] 02-05. A handoff that throws hands nothing to the browser, so the + // lease made for it is revoked at once instead of waiting for dispose. + it("revokes the lease of a handoff that throws", async () => { + const revoked: string[] = []; + const leases = new ObjectUrlLeaseRegistry({ + createObjectURL: () => "blob:download-failed", + revokeObjectURL: (url) => revoked.push(url), + }); + const adapter = createDownloadDeliveryAdapter({ + ...HARD_LIMITS, + policies, + host: { + handoff() { + throw new DOMException("blocked", "NotAllowedError"); + }, + }, + browserManagedCapabilities: capabilityResolver(), + objectUrls: leases, + userActivation: { isActive: true }, + }); + + expect( + await adapter.deliver( + deliveryInput( + { kind: "GENERATED", bytes: byteSource([new Uint8Array([1, 2])]) }, + "BOUNDED_OBJECT_URL", + ), + ), + ).toMatchObject({ ok: false }); + expect(leases.activeLeaseCount).toBe(0); + expect(revoked).toEqual(["blob:download-failed"]); + }); + it("revokes only its own leases on dispose when the registry is shared (2026-11-01 02-01)", async () => { const revoked: string[] = []; let urlSequence = 0; diff --git a/tests/unit/browser-file-policy-registry.test.ts b/tests/unit/browser-file-policy-registry.test.ts index 5249d388..60d8e651 100644 --- a/tests/unit/browser-file-policy-registry.test.ts +++ b/tests/unit/browser-file-policy-registry.test.ts @@ -174,6 +174,34 @@ describe("browser file composition policy registry", () => { }); }); + // 2026-11-01 02-02. The download extension was checked for shape only, so a + // policy could hand `invoice.pdf` to the browser as `invoice.exe`. The + // extensions a user-supplied file name is stripped of are refused here too. + it.each([".exe", ".HTML", ".tar.js"])( + "refuses a download policy whose safe extension is %s", + (safeExtension) => { + expect( + () => + new BrowserFilePolicyRegistry({ + profiles: [ + { + reference: browserFilePolicyReference("downloads", "invoice"), + download: { + strategy: "BOUNDED_OBJECT_URL", + mediaType: "application/pdf", + safeExtension, + maxTransferBytes: 100, + maxBufferedBytes: 50, + integrity: "OPTIONAL", + }, + }, + ], + hardLimits, + }), + ).toThrow(TypeError); + }, + ); + it("binds verification receipts to the exact profile, not a reused policyId", async () => { const profileA = browserFilePolicyReference( "images-a", diff --git a/tests/unit/indexeddb-opfs-journal.test.ts b/tests/unit/indexeddb-opfs-journal.test.ts index daca31de..bd193f6e 100644 --- a/tests/unit/indexeddb-opfs-journal.test.ts +++ b/tests/unit/indexeddb-opfs-journal.test.ts @@ -508,7 +508,12 @@ describe("IndexedDB OPFS journal", () => { // [0929] 05-01. The row is counted, not returned and not deleted. expect(await journal.listIncomplete(10)).toEqual({ ok: true, - value: { transactions: [], moreAvailable: false, corruptRows: 1 }, + value: { + transactions: [], + moreAvailable: false, + corruptRows: 1, + unattributedRows: 1, + }, }); expect(factory.readRaw("opfs-journal", "transaction_88888888")).toMatchObject({ corrupt: true, @@ -865,6 +870,99 @@ describe("[0929] 05-01 a corrupt row is skipped and counted; a partition's rows ).toMatchObject({ preparedObject: { corrupt: true } }); }); + // 2026-11-03 05-03. The partition delete finds journal rows by their + // `logicalKey`. A damaged row that still has one goes with its partition; a + // row without one belongs to no partition, so no delete takes it. The page + // tells the two apart so an operator can. + it("tells a damaged journal row its partition delete takes from one no partition owns", async () => { + const { factory, journal } = createHarness(); + // Opens the database the seeds below write into. + expect(await journal.listIncomplete(10)).toMatchObject({ ok: true }); + factory.seed("opfs-journal", { + transactionId: "transaction_keyed001", + logicalKey: `${scopeKeyOf(scope)}|object_aaaa0001`, + startedAtEpochMs: 1, + phase: "GARBLED", + }); + factory.seed("opfs-journal", { + transactionId: "transaction_keyless1", + startedAtEpochMs: 2, + corrupt: true, + }); + + expect(await journal.listIncomplete(10)).toEqual({ + ok: true, + value: { + transactions: [], + moreAvailable: false, + corruptRows: 2, + unattributedRows: 1, + }, + }); + expect(await journal.removePartition(scope)).toMatchObject({ ok: true }); + + expect( + factory.readRaw("opfs-journal", "transaction_keyed001"), + ).toBeUndefined(); + expect( + factory.readRaw("opfs-journal", "transaction_keyless1"), + ).toMatchObject({ corrupt: true }); + expect(await journal.listIncomplete(10)).toEqual({ + ok: true, + value: { + transactions: [], + moreAvailable: false, + corruptRows: 1, + unattributedRows: 1, + }, + }); + }); + + it("counts the unfinished rows of one partition, a damaged one included (2026-11-03 05-01)", async () => { + const { factory, journal } = createHarness(); + await commitObject(journal, "transaction_obj00001", "object_aaaa0001", 1); + expect(await journal.countPartitionTransactions(scope)).toEqual({ + ok: true, + value: 0, + }); + expect( + await journal.begin( + beginInput("transaction_live0002", "object_bbbb0002", 1), + ), + ).toMatchObject({ ok: true }); + expect( + await journal.begin( + beginInput( + "transaction_kept0003", + "object_kept_0003", + 1, + otherPartition, + ), + ), + ).toMatchObject({ ok: true }); + // A row whose keys still read but whose value does not. + factory.seed("opfs-journal", { + ...(factory.readRaw("opfs-journal", "transaction_live0002") as object), + transactionId: "transaction_bad00004", + logicalKey: `${scopeKeyOf(scope)}|object_dddd0004`, + phase: "GARBLED", + }); + + expect(await journal.countPartitionTransactions(scope)).toEqual({ + ok: true, + value: 2, + }); + expect(await journal.countPartitionTransactions(otherPartition)).toEqual({ + ok: true, + value: 1, + }); + expect(await journal.removePartition(scope)).toMatchObject({ ok: true }); + expect(await journal.countPartitionTransactions(scope)).toEqual({ + ok: true, + value: 0, + }); + }); + it("removes every row keyed to one partition, the corrupt one included, and none of another", async () => { const { factory, journal } = createHarness(); await commitObject(journal, "transaction_obj00001", "object_aaaa0001", 1); diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index 2467ad41..fb60e1e3 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -243,6 +243,15 @@ function createJournal(): OpfsJournalPort & { ), ); }, + async countPartitionTransactions(scope) { + return browserDataSuccess( + [...transactions.values()].filter( + (transaction) => + transaction.scope.namespaceToken === scope.namespaceToken && + transaction.scope.partitionToken === scope.partitionToken, + ).length, + ); + }, async removePartition() { objects.clear(); transactions.clear(); diff --git a/tests/unit/opfs-worker-runtime.test.ts b/tests/unit/opfs-worker-runtime.test.ts index e3514111..e319754c 100644 --- a/tests/unit/opfs-worker-runtime.test.ts +++ b/tests/unit/opfs-worker-runtime.test.ts @@ -11,7 +11,10 @@ import type { BrowserStoragePolicy, ByteSource, } from "../../src/application/ports/browser-file-storage/shared.ts"; -import { browserDataSuccess } from "../../src/adapters/browser-file-storage/result.ts"; +import { + browserDataFailure, + browserDataSuccess, +} from "../../src/adapters/browser-file-storage/result.ts"; import { createOpfsByteStoreAdapter } from "../../src/adapters/storage/opfs/opfs-byte-store-adapter.ts"; import { createIndexedDbOpfsJournal } from "../../src/adapters/storage/opfs/indexeddb-opfs-journal.ts"; import { @@ -35,6 +38,11 @@ import { type OpfsWorkerRuntime, } from "../../src/adapters/storage/opfs/opfs-worker-runtime.ts"; import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts"; +import { + MemoryDirectory, + MemoryFile, + type MemoryNode, +} from "../helpers/memory-opfs.ts"; const scopeA: OpfsStorageScope = Object.freeze({ namespace: "durable-objects", @@ -68,123 +76,6 @@ const runtimePolicy = resolveOpfsRuntimePolicy({ orphanGracePeriodMs: 60_000, }); -type MemoryNode = MemoryDirectory | MemoryFile; - -class MemoryFile { - readonly kind = "file"; - bytes = new Uint8Array(); - lastModified = 0; - reads = 0; -} - -class MemoryDirectory { - readonly kind = "directory"; - readonly children = new Map(); - - async getDirectoryHandle( - name: string, - options: FileSystemGetDirectoryOptions = {}, - ): Promise { - const current = this.children.get(name); - if (current instanceof MemoryDirectory) { - return current as unknown as FileSystemDirectoryHandle; - } - if (current || !options.create) throw notFound(); - const created = new MemoryDirectory(); - this.children.set(name, created); - return created as unknown as FileSystemDirectoryHandle; - } - - async getFileHandle( - name: string, - options: FileSystemGetFileOptions = {}, - ): Promise { - const current = this.children.get(name); - if (current instanceof MemoryFile) { - return fileHandle(current); - } - if (current || !options.create) throw notFound(); - const created = new MemoryFile(); - this.children.set(name, created); - return fileHandle(created); - } - - async removeEntry( - name: string, - options: FileSystemRemoveOptions = {}, - ): Promise { - const current = this.children.get(name); - if (!current) throw notFound(); - if ( - current instanceof MemoryDirectory && - current.children.size > 0 && - !options.recursive - ) { - throw new DOMException("Directory is not empty.", "InvalidModificationError"); - } - this.children.delete(name); - } - - async *entries(): AsyncIterableIterator< - [string, FileSystemDirectoryHandle | FileSystemFileHandle] - > { - for (const [name, node] of this.children) { - yield [ - name, - node instanceof MemoryDirectory - ? (node as unknown as FileSystemDirectoryHandle) - : fileHandle(node), - ]; - } - } - - has(path: readonly string[]): boolean { - let current: MemoryNode = this; - for (const segment of path) { - if (!(current instanceof MemoryDirectory)) return false; - const next = current.children.get(segment); - if (!next) return false; - current = next; - } - return true; - } -} - -function fileHandle(file: MemoryFile): FileSystemFileHandle { - return { - kind: "file", - name: "memory", - async getFile() { - file.reads += 1; - const blob = new Blob([Uint8Array.from(file.bytes)]); - Object.defineProperty(blob, "lastModified", { - value: file.lastModified, - }); - return blob as File; - }, - async createWritable() { - let pending = Uint8Array.from(file.bytes); - return { - async write(data: FileSystemWriteChunkType) { - if (!(data instanceof Uint8Array)) { - throw new TypeError("The test writer accepts Uint8Array only."); - } - pending = Uint8Array.from(data); - }, - async close() { - file.bytes = pending; - file.lastModified = Date.now(); - }, - async abort() {}, - } as unknown as FileSystemWritableFileStream; - }, - } as FileSystemFileHandle; -} - -function notFound(): DOMException { - return new DOMException("Entry was not found.", "NotFoundError"); -} - const PHYSICAL_GENERATION_A = "a".repeat(32) as OpfsPhysicalGenerationId; function beginRequest( @@ -649,6 +540,7 @@ function referenceJournal(referenced: ReadonlySet): OpfsJournalPort { complete: unused, rollback: unused, listCommittedObjects: unused, + countPartitionTransactions: unused, removePartition: unused, async listIncomplete() { return browserDataSuccess({ @@ -2414,8 +2306,12 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh expect(filesUnder(root, scopeA)).toEqual([]); }); - it("never sweeps the chunk of a put that runs while the purge does", async () => { - const { tab } = sharedRootTabs(); + // 2026-11-03 05-01 X1. The purge used to walk past a put that began before + // it, report a completed sweep and leave that object readable. A put or + // delete of the partition that has not finished now sends the purge to the + // partition delete, which waits for it and then takes it. + it("waits for a put that began before the purge and takes it with the partition", async () => { + const { root, tab } = sharedRootTabs(); const purger = tab("p", authority); const writer = tab("w", authority); expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); @@ -2432,23 +2328,127 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh stalled.release(); expect(await put).toMatchObject({ ok: true }); - expect(await purge).toMatchObject({ ok: true, value: { removedObjects: 1 } }); - expect(await openedBytes(writer, "object_late_0001")).toEqual({ - generation: 1, - bytes: [5], + const report = await purge; + expect(report).toMatchObject({ + ok: true, + value: { + removedObjects: 1, + moreObjectsAvailable: false, + partitionDeleted: true, + }, }); + expect(report.ok && report.value.chunkSweep).toBeUndefined(); + expect(filesUnder(root, scopeA)).toEqual([]); + expect(await openedBytes(writer, "object_late_0001")).toBe("NOT_FOUND"); }); + // 2026-11-03 05-01 X2, X2b, X3. A put that stopped before it finished leaves + // its journal row and its staged files. The purge reported a completed sweep + // over them; the next reconcile then committed a FILES_READY put, so the + // account's file came back as a readable object. + it.each([ + ["stopped before commit (FILES_READY)", "commitPut", false], + ["stopped while uploading (PREPARING)", "markFilesReady", false], + ["whose journal row is damaged", "commitPut", true], + ] as const)( + "takes the partition when an approved purge finds a put %s", + async (_label, failingStep, damageRow) => { + const { root, idb, tab } = sharedRootTabs(); + const journal = createIndexedDbOpfsJournal({ + authorityToken: scopeA.authorityToken, + factory: idb.factory, + keyRange: idb.keyRange, + }); + const writerWorker = loopbackGateway( + createOpfsWorkerRuntime({ + root: root as unknown as FileSystemDirectoryHandle, + crypto: globalThis.crypto, + policy: runtimePolicy, + leaseManager: exclusiveLeases(), + dedicatedWorker: true, + supportsSynchronousAccessHandles: false, + }), + ); + const unavailable = async () => + browserDataFailure("UNAVAILABLE", "INDEXEDDB_WRITE", { + retryable: true, + recovery: "RETRY", + }); + // The tab crashes at this step: the journal write never lands and, + // before commit, its compensation never runs either. + const writer = tab("w", { + journal: { ...journal, [failingStep]: unavailable } as OpfsJournalPort, + worker: { + ...writerWorker, + abortPreparedPut: async () => + browserDataFailure("UNAVAILABLE", "OBJECT_WRITE", { + retryable: true, + recovery: "RETRY", + }), + }, + }); + const purger = tab("p", authority); + expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); + expect(await putBytes(writer, "object_dead_0001", [9, 9, 9])).toMatchObject({ + ok: false, + }); + expect(idb.readRaw("opfs-journal", "transaction_w_1")).toBeDefined(); + if (damageRow) { + idb.seed("opfs-journal", { + ...(idb.readRaw("opfs-journal", "transaction_w_1") as object), + phase: "GARBLED", + }); + } + + const report = await purger.maintenance.enforcePolicies({ + reason: "ACCOUNT_DELETION", + }); + + expect(report).toMatchObject({ + ok: true, + value: { moreObjectsAvailable: false, partitionDeleted: true }, + }); + expect(filesUnder(root, scopeA)).toEqual([]); + expect(idb.readRaw("opfs-journal", "transaction_w_1")).toBeUndefined(); + // Nothing is left for a later reconcile to bring back. + expect(await purger.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { committedTransactions: 0, corruptTransactions: 0 }, + }); + expect(await openedBytes(purger, "object_dead_0001")).toBe("NOT_FOUND"); + expect(filesUnder(root, scopeA)).toEqual([]); + }, + ); + // [0929] 05-02. Another tab overwrites the object the purge is removing, so // the purge's remove ends in CONFLICT. That purge is not finished and must - // not claim a completed chunk sweep. + // not claim a completed chunk sweep. The overwrite finishes between the + // purge's listing and its remove: one still running when the purge checks + // the journal sends it to the partition delete instead (2026-11-03 05-01). it("reports a purge that skipped a changing object as unfinished", async () => { - const { root, tab } = sharedRootTabs(); - const purger = tab("p", authority); - const writer = tab("w", authority); - expect(await putBytes(purger, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); + const { root, idb, tab } = sharedRootTabs(); + const journal = createIndexedDbOpfsJournal({ + authorityToken: scopeA.authorityToken, + factory: idb.factory, + keyRange: idb.keyRange, + }); const stalled = stalledSource(); - const overwrite = writer.objects.put({ + let overwrite: ReturnType | undefined; + const purger = tab("p", { + ...authority, + journal: { + ...journal, + async listCommittedObjects(request) { + const page = await journal.listCommittedObjects(request); + stalled.release(); + await overwrite; + return page; + }, + }, + }); + const writer = tab("w", authority); + expect(await putBytes(writer, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); + overwrite = writer.objects.put({ objectId: "object_secret_1", expectedGeneration: 1, mediaType: "application/octet-stream", @@ -2456,8 +2456,6 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh }); await stalled.streaming; const purge = purger.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }); - await new Promise((resolve) => setTimeout(resolve, 20)); - stalled.release(); expect(await overwrite).toMatchObject({ ok: true }); const first = await purge; @@ -2610,6 +2608,60 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh }); }); + // 2026-11-03 05-03 X4. A damaged journal row without a readable partition + // key outlives every approved partition delete. It used to keep each + // reconcile DEGRADED for good, with nothing the runbook lets anyone do. It + // is now counted apart and kept out of the partition damage signal; a row + // its partition delete would take still raises it. + it("reports a damaged journal row no partition owns apart from partition damage", async () => { + const { root, idb, tab } = sharedRootTabs(); + const outcomes: string[] = []; + const store = tab("s", { + ...authority, + observer: (observation) => { + if ( + observation.operation === "OBJECT_RECONCILE" && + observation.outcome !== "STARTED" + ) { + outcomes.push(`${observation.outcome}:${observation.failureCode ?? ""}`); + } + }, + }); + expect(await putBytes(store, "object_secret_1", [1, 2, 3])).toMatchObject({ ok: true }); + idb.seed("opfs-objects", corruptObjectRow(scopeA, "object_secret_2")); + idb.seed("opfs-journal", { + transactionId: "transaction_corrupt1", + startedAtEpochMs: 1, + corrupt: true, + }); + + expect( + await store.maintenance.enforcePolicies({ reason: "ACCOUNT_DELETION" }), + ).toMatchObject({ ok: true, value: { partitionDeleted: true } }); + expect(filesUnder(root, scopeA)).toEqual([]); + expect(idb.readRaw("opfs-journal", "transaction_corrupt1")).toMatchObject({ + corrupt: true, + }); + + expect(await store.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { corruptTransactions: 1, unattributedCorruptTransactions: 1 }, + }); + expect(outcomes).toEqual(["SUCCEEDED:"]); + + idb.seed("opfs-journal", { + transactionId: "transaction_keyed001", + logicalKey: `${scopeA.authorityToken}|${scopeA.namespaceToken}|${scopeA.partitionToken}|object_secret_3`, + startedAtEpochMs: 2, + phase: "GARBLED", + }); + expect(await store.maintenance.reconcile()).toMatchObject({ + ok: true, + value: { corruptTransactions: 2, unattributedCorruptTransactions: 1 }, + }); + expect(outcomes.at(-1)).toBe("DEGRADED:CORRUPT_DATA"); + }); + it("removes a partition directory only under the origin mutation lease", async () => { const root = new MemoryDirectory(); const leases = exclusiveLeases(); @@ -2790,6 +2842,131 @@ describe("05-04 a LOGOUT or ACCOUNT_DELETION purge leaves no partition bytes beh }); }); +// 2026-11-03 05-02. A put or delete queued behind a partition delete held the +// partition lock request without its caller's signal and without a bound, so +// cancelling it did nothing until the delete let go. +describe("05-02 a put or delete waiting on the partition lock", () => { + const lockName = (policy: typeof runtimePolicy) => + `${policy.mutationLockName}:partition:${scopeA.authorityToken}:${scopeA.namespaceToken}:${scopeA.partitionToken}`; + + afterEach(() => { + vi.useRealTimers(); + }); + + /** Another tab's partition delete holds the lock until `release`. */ + async function heldPartitionLock(policy: typeof runtimePolicy) { + const holding = checkpoint(); + const holder = navigator.locks.request( + lockName(policy), + { mode: "exclusive" }, + () => holding.pass(), + ); + await holding.reached; + return { + async release() { + holding.open(); + await holder; + }, + }; + } + + async function queuedOnPartitionLock( + policy: typeof runtimePolicy, + tick: () => Promise, + ) { + while ( + !(await navigator.locks.query()).pending?.some( + (lock) => lock.name === lockName(policy) && lock.mode === "shared", + ) + ) { + await tick(); + } + } + + const settledWithin = async (work: Promise, ms: number) => + await Promise.race([ + work, + new Promise<"STILL_WAITING">((resolve) => + setTimeout(() => resolve("STILL_WAITING"), ms), + ), + ]); + + it("ends a queued put and a queued delete as soon as their caller aborts", async () => { + const { tab } = sharedRootTabs(); + const store = tab("s"); + expect( + await store.objects.put({ + objectId: "object_kept_0001", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }), + ).toMatchObject({ ok: true }); + const held = await heldPartitionLock(runtimePolicy); + const controller = new AbortController(); + + const put = store.objects.put({ + objectId: "object_aborted01", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + signal: controller.signal, + }); + const removal = store.objects.remove({ + objectId: "object_kept_0001", + expectedGeneration: 1, + signal: controller.signal, + }); + await queuedOnPartitionLock( + runtimePolicy, + () => new Promise((resolve) => setTimeout(resolve, 1)), + ); + controller.abort(); + + expect(await settledWithin(put, 200)).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "OBJECT_WRITE" }, + }); + expect(await settledWithin(removal, 200)).toMatchObject({ + ok: false, + error: { code: "ABORTED", operation: "OBJECT_DELETE" }, + }); + await held.release(); + expect(await openedBytes(store, "object_aborted01")).toBe("NOT_FOUND"); + expect(await openedBytes(store, "object_kept_0001")).toEqual({ + generation: 1, + bytes: [6], + }); + }); + + it("ends a partition lock wait at the policy bound as a retryable BLOCKED", async () => { + const policy = resolveOpfsRuntimePolicy({ + ...runtimePolicy, + mutationLockWaitTimeoutMs: 300_000, + }); + const { tab } = sharedRootTabs(policy); + const store = tab("s"); + const held = await heldPartitionLock(policy); + vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] }); + + const put = store.objects.put({ + objectId: "object_blocked01", + expectedGeneration: null, + mediaType: "application/octet-stream", + source: oneByteSource(), + }); + await queuedOnPartitionLock(policy, () => vi.advanceTimersByTimeAsync(1)); + await vi.advanceTimersByTimeAsync(policy.mutationLockWaitTimeoutMs); + + expect(await put).toMatchObject({ + ok: false, + error: { code: "BLOCKED", operation: "OBJECT_WRITE", retryable: true }, + }); + vi.useRealTimers(); + await held.release(); + }); +}); + /** A step that parks until opened and says when something reached it. */ function checkpoint(): Readonly<{ reached: Promise; @@ -2857,6 +3034,29 @@ describe("05-07 a put whose source stops lets go of the origin lock", () => { expect(await putB).toMatchObject({ ok: true, value: { generation: 1 } }); stalled.release(); }); + + // [0929] 05-09. The test above holds only while a queued writer outlasts a + // stalled one. That ordering was a comment; a policy that breaks it is now + // refused when it is resolved. + it.each([ + ["equal to", 60_000], + ["longer than", 120_000], + ])("rejects an idle bound %s the lock wait", (_, putIdleTimeoutMs) => { + expect(() => + resolveOpfsRuntimePolicy({ + ...runtimePolicy, + mutationLockWaitTimeoutMs: 60_000, + putIdleTimeoutMs, + }), + ).toThrow(TypeError); + expect( + resolveOpfsRuntimePolicy({ + ...runtimePolicy, + mutationLockWaitTimeoutMs: putIdleTimeoutMs + 1, + putIdleTimeoutMs, + }).putIdleTimeoutMs, + ).toBe(putIdleTimeoutMs); + }); }); describe("05-10 the object id grammar is the prepared-object grammar", () => { diff --git a/tests/unit/public-response-cache-codec.test.ts b/tests/unit/public-response-cache-codec.test.ts index 5d5d8573..5c3dc7a1 100644 --- a/tests/unit/public-response-cache-codec.test.ts +++ b/tests/unit/public-response-cache-codec.test.ts @@ -157,6 +157,13 @@ describe("public cache codec and response validation (characterization)", () => expect(await stageCode([valid], response({ pragma: "no-cache" }))).toBe( "POLICY_REJECTED", ); + // 2026-11-01 02-04 (N26b, N26). Each directive or header on its own. + expect( + await stageCode([valid], response({ "cache-control": "no-cache" })), + ).toBe("POLICY_REJECTED"); + expect( + await stageCode([valid], response({ "set-cookie": "session=1" })), + ).toBe("POLICY_REJECTED"); expect( await stageCode([valid], response({ "www-authenticate": "Basic" })), ).toBe("POLICY_REJECTED"); diff --git a/tests/unit/public-response-cache-repair.test.ts b/tests/unit/public-response-cache-repair.test.ts index 3ae5807c..554ee1b6 100644 --- a/tests/unit/public-response-cache-repair.test.ts +++ b/tests/unit/public-response-cache-repair.test.ts @@ -4,6 +4,7 @@ import type { PublicCacheAsset } from "../../src/application/ports/browser-file- import { activePointerRequest, controlCacheName, + markerRequest, } from "../../src/adapters/cache-storage/public-cache-codec.ts"; import { createDefaultPublicCachePolicy, @@ -173,6 +174,94 @@ describe("public response cache repair is failure-atomic", () => { ]); }); + 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({ + 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)!; @@ -377,6 +466,151 @@ 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("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 { + 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); diff --git a/tests/unit/runtime-adapters-product-scope-participants.test.ts b/tests/unit/runtime-adapters-product-scope-participants.test.ts new file mode 100644 index 00000000..698a7723 --- /dev/null +++ b/tests/unit/runtime-adapters-product-scope-participants.test.ts @@ -0,0 +1,152 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import type { ProductScopeParticipant } from "../../src/bootstrap/product-composition-contract.ts"; +import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts"; + +/** + * 2026-11-03 02-01. A product hands the template what must close with a + * session through `ProductComposition.scopeParticipants`, so it never edits + * `runtime-adapters.ts`. The real `createRuntimeAdapters` runs; only the + * product-owned file is replaced. + */ + +const fixture = vi.hoisted(() => ({ + participants: [] as ProductScopeParticipant[], + owner: undefined as Readonly<{ switchUser(subject: string): void }> | undefined, +})); + +vi.mock("../../src/bootstrap/product-composition.ts", () => ({ + composeProductSessionOwner: () => { + const listeners = new Set<() => void>(); + let subject = "user-a"; + const owner = { + readState: () => "authenticated", + readSubject: () => subject, + subscribe(listener: () => void) { + listeners.add(listener); + return () => listeners.delete(listener); + }, + beginSignIn: async () => {}, + signOut: async () => {}, + attachCredential: async () => ({ headers: {} }), + recoverSession: async () => "no-session", + notifyUnauthenticated: () => {}, + switchUser(next: string) { + subject = next; + for (const listener of listeners) listener(); + }, + }; + fixture.owner = owner; + return owner; + }, + composeProduct: () => ({ + capabilities: {}, + credentialProviders: {}, + scopeParticipants: fixture.participants, + }), +})); + +let current: Awaited> | undefined; +afterEach(() => { + current?.infrastructure.dispose(); + current = undefined; + fixture.participants = []; +}); + +async function compose() { + current = await createRuntimeAdapters({ + runtime: { + config: { + APP_ENV: "local", + API_BASE_URL: "http://localhost:8080", + TELEMETRY_ENABLED: false, + AUTH_MODE: "external", + REQUEST_TIMEOUT_MS: 10_000, + MAX_RETRY_ATTEMPTS: 0, + RELEASE_MANIFEST_URL: "/release-manifest.json", + CONFIG_SCHEMA_VERSION: "2.0", + CAPABILITY_OVERRIDES: { + REALTIME: "DEFAULT", + WEB_WORKER: "DEFAULT", + SERVICE_WORKER: "DEFAULT", + OFFLINE_COMMANDS: "DEFAULT", + }, + FEATURE_OVERRIDES: {}, + }, + configSchema: "V2", + build: { + buildId: "build-a", + commitSha: "abc123", + routerBasePath: "/", + runtimeConfigUrl: "/config.json", + }, + validationDurationMs: 0, + }, + release: { + schemaVersion: 2, + appVersion: "0.1.0", + buildId: "build-a", + commitSha: "abc123", + configSchemaVersion: "2.0", + contractSet: { + setAlgorithm: "CA_CONTRACT_SET_V1", + setDigest: `sha256:${"0".repeat(64)}`, + packages: [], + }, + assetManifestHash: "hash-a", + releaseId: "release-a", + builtAt: "2026-07-25T00:00:00Z", + routeChunks: { "route-home": "assets/home.js" }, + }, + host: {}, + }); + const owner = fixture.owner; + if (!owner) throw new Error("The product session owner was not asked"); + return { scope: current.infrastructure.serverStateScope, owner }; +} + +describe("product scope participants (2026-11-03 02-01)", () => { + it("closes each one, in order, on every identity change before READY", async () => { + const closed: string[] = []; + fixture.participants = [ + { label: "first", close: () => void closed.push("first") }, + { + label: "second", + async close() { + await Promise.resolve(); + closed.push("second"); + }, + }, + ]; + const { scope, owner } = await compose(); + expect(closed).toEqual([]); + + owner.switchUser("user-b"); + expect(scope.getPhase()).toBe("FENCED"); + await vi.waitFor(() => expect(scope.getPhase()).toBe("READY")); + expect(closed).toEqual(["first", "second"]); + + owner.switchUser("user-c"); + await vi.waitFor(() => expect(closed).toHaveLength(4)); + await vi.waitFor(() => expect(scope.getPhase()).toBe("READY")); + }); + + it("keeps the scope from READY when one fails, and still closes the rest", async () => { + const closed: string[] = []; + fixture.participants = [ + { + label: "broken", + close() { + throw new Error("cannot close"); + }, + }, + { label: "after", close: () => void closed.push("after") }, + ]; + const { scope, owner } = await compose(); + + owner.switchUser("user-b"); + + await vi.waitFor(() => expect(scope.getPhase()).toBe("FAILED")); + expect(closed).toEqual(["after"]); + }); +}); diff --git a/tests/unit/storage-registry.test.ts b/tests/unit/storage-registry.test.ts index 7259492e..44e03db1 100644 --- a/tests/unit/storage-registry.test.ts +++ b/tests/unit/storage-registry.test.ts @@ -11,7 +11,7 @@ import { type StorageKeyInput, } from "../../src/contracts/storage-keys.ts"; -type StorageFailureMode = "none" | "quota" | "security"; +type StorageFailureMode = "none" | "quota" | "firefox-quota" | "security"; function createStorage(options: { initial?: Readonly>; @@ -54,6 +54,10 @@ function throwFor(mode: StorageFailureMode): void { if (mode === "quota") { throw new DOMException("private quota detail", "QuotaExceededError"); } + if (mode === "firefox-quota") { + // Older Firefox names the quota error this way, with code 1014. + throw new DOMException("private quota detail", "NS_ERROR_DOM_QUOTA_REACHED"); + } if (mode === "security") { throw new DOMException("private security detail", "SecurityError"); } @@ -278,6 +282,22 @@ describe("storage registry", () => { ); }); + // 2026-11-01 05-06. The second quota name was in the adapter's list but no + // test sent it, so dropping it went unseen. + it("falls back to memory on Firefox's quota error name too", () => { + const { storage: localStorage } = createStorage({ + writeFailure: "firefox-quota", + }); + const adapter = createBrowserStorageAdapter({ localStorage }); + + expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({ + ok: false, + fallback: "memory", + error: { kind: "STORAGE_QUOTA_EXCEEDED" }, + }); + expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" }); + }); + it("discards data from a previous schema version", () => { const { storage: localStorage, values, removeItem } = createStorage({ initial: { @@ -396,6 +416,41 @@ describe("storage registry", () => { expect(removeItem).toHaveBeenCalledWith(expiring.physicalKey); }); + // 2026-11-01 05-06. A record is expired at its expiry instant, not after it. + it.each([ + [100, undefined], + [101, "private-expiring"], + ])("reads a record expiring at %i at time 100 as %s", (expiresAt, value) => { + const expiring = defineStorageKey({ + logicalName: "EXPIRING_PREFERENCE", + scope: "preference", + name: "expiring", + backend: "localStorage", + classification: "public-preference", + schemaVersion: 1, + valueCodec: "opaque-string-v1", + ttl: 10, + migration: "discard", + quotaFallback: "memory", + }); + const { storage } = createStorage({ + initial: { + [expiring.physicalKey]: serializedEnvelope("private-expiring", { + expiresAt, + }), + }, + }); + const adapter = createBrowserStorageAdapter({ + localStorage: storage, + now: () => 100, + resolveDefinition: definitionResolver({ + EXPIRING_PREFERENCE: expiring, + }), + }); + + expect(adapter.read("EXPIRING_PREFERENCE")).toEqual({ ok: true, value }); + }); + it("prioritizes a failed-write memory envelope over stale persistent data and expires it", () => { let timestamp = 100; const expiring = defineStorageKey({