chore(review): 1103 저장소·파일 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-01~02-05 05-01~05-04 # Conflicts: # docs/manual/03-outside-feature-folder.md # src/bootstrap/product-composition-contract.ts # src/bootstrap/runtime-adapters.ts
This commit is contained in:
@@ -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/([^/]+)/"
|
||||
|
||||
@@ -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은 제공하지 않는다.
|
||||
|
||||
@@ -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 처리하는 용도에 한정된다.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
|
||||
|
||||
@@ -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/<authorityToken>/<namespaceToken>/<partitionToken>` 디렉터리를
|
||||
지우고, 이어서 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를 이동하거나 추측 복구 금지
|
||||
|
||||
@@ -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();
|
||||
},
|
||||
}),
|
||||
});
|
||||
}
|
||||
@@ -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<string, MemoryObject>();
|
||||
/** Journal rows of puts that stopped before they committed or rolled back. */
|
||||
readonly #pending = new Set<number>();
|
||||
/**
|
||||
* 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,
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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 ||
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -867,7 +867,12 @@ export function createPublicResponseCacheAdapter(
|
||||
dependencies.cacheStorage,
|
||||
policy,
|
||||
);
|
||||
if (!pointer.ok) return pointer;
|
||||
// 2026-11-03 02-05. A damaged pointer is the state this API is for,
|
||||
// so it is reported with the candidates; a transient read is not.
|
||||
if (!pointer.ok && pointer.error.code !== "CORRUPT_DATA") {
|
||||
return pointer;
|
||||
}
|
||||
const active = pointer.ok ? pointer.value : null;
|
||||
|
||||
const candidates: PublicCacheInspection["releaseCandidates"][number][] =
|
||||
[];
|
||||
@@ -903,8 +908,12 @@ export function createPublicResponseCacheAdapter(
|
||||
}
|
||||
return browserDataSuccess<PublicCacheInspection>(
|
||||
Object.freeze({
|
||||
activeReleaseRegistryId:
|
||||
pointer.value?.releaseRegistryId ?? null,
|
||||
activePointer: !pointer.ok
|
||||
? "UNREADABLE"
|
||||
: active
|
||||
? "READABLE"
|
||||
: "NONE",
|
||||
activeReleaseRegistryId: active?.releaseRegistryId ?? null,
|
||||
ownedCacheCount: owned.length,
|
||||
unreadableOwnedCacheCount,
|
||||
releaseCandidates: Object.freeze(candidates),
|
||||
@@ -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<string> = 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 });
|
||||
|
||||
@@ -699,6 +699,7 @@ export function createIndexedDbOpfsJournal(
|
||||
(transaction, context) => {
|
||||
const rows: OpfsJournalTransaction[] = [];
|
||||
let corruptRows = 0;
|
||||
let unattributedRows = 0;
|
||||
walkIndexedDbCursor<BrowserDataFailure>({
|
||||
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<number>(
|
||||
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<BrowserDataFailure>({
|
||||
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,
|
||||
|
||||
@@ -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<string, () => 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<OpfsReconciliationReport>(
|
||||
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<Value>(
|
||||
transactionId: string,
|
||||
operation: "OBJECT_WRITE" | "OBJECT_DELETE",
|
||||
signal: AbortSignal | undefined,
|
||||
run: () => Promise<BrowserDataResult<Value>>,
|
||||
): Promise<BrowserDataResult<Value>> {
|
||||
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<Value>(
|
||||
mode: LockMode,
|
||||
@@ -1137,24 +1172,34 @@ export function createOpfsByteStoreAdapter(
|
||||
signal: AbortSignal | undefined,
|
||||
run: () => Promise<BrowserDataResult<Value>>,
|
||||
): Promise<BrowserDataResult<Value>> {
|
||||
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),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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 ||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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<BrowserDataResult<boolean>>;
|
||||
/**
|
||||
* 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<BrowserDataResult<number>>;
|
||||
/**
|
||||
* [0929] 05-01. Deletes every row keyed to this one partition, readable or
|
||||
* not: committed objects, journal rows, chunk references and the budget.
|
||||
|
||||
@@ -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<void>;
|
||||
}>;
|
||||
|
||||
export type ProductComposition = Readonly<{
|
||||
capabilities: Readonly<
|
||||
Partial<Omit<FeaturePlatformCapabilities, TemplatePlatformCapabilityId>>
|
||||
@@ -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[];
|
||||
}>;
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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<boolean> {
|
||||
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<string> {
|
||||
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<string>((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<unknown>;
|
||||
};
|
||||
let streaming!: () => void;
|
||||
const started = new Promise<void>((resolve) => {
|
||||
streaming = resolve;
|
||||
});
|
||||
const gate = new Promise<void>((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<unknown>;
|
||||
};
|
||||
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<unknown>;
|
||||
};
|
||||
state.__release();
|
||||
return await state.__put;
|
||||
});
|
||||
const report = await secondPage.evaluate(
|
||||
async () =>
|
||||
await (globalThis as unknown as { __purge: Promise<unknown> }).__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<string>((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();
|
||||
}
|
||||
});
|
||||
|
||||
@@ -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<string, MemoryNode>();
|
||||
|
||||
async getDirectoryHandle(
|
||||
name: string,
|
||||
options: FileSystemGetDirectoryOptions = {},
|
||||
): Promise<FileSystemDirectoryHandle> {
|
||||
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<FileSystemFileHandle> {
|
||||
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<void> {
|
||||
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");
|
||||
}
|
||||
@@ -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<typeof createSessionBrowserFileCapability>["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<ReturnType<typeof createRuntimeAdapters>> | 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<NonNullable<typeof fixture.files>["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<void>((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" },
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -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<string>
|
||||
@@ -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<unknown>) => void) | undefined;
|
||||
const gateway = createOpfsWorkerGateway({
|
||||
worker: {
|
||||
postMessage(message) {
|
||||
void worker
|
||||
.handleRequest(message)
|
||||
.then((response) => listener?.({ data: response } as MessageEvent<unknown>));
|
||||
},
|
||||
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);
|
||||
},
|
||||
);
|
||||
});
|
||||
|
||||
@@ -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 () => {
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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<string, MemoryNode>();
|
||||
|
||||
async getDirectoryHandle(
|
||||
name: string,
|
||||
options: FileSystemGetDirectoryOptions = {},
|
||||
): Promise<FileSystemDirectoryHandle> {
|
||||
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<FileSystemFileHandle> {
|
||||
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<void> {
|
||||
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<string>): 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<typeof writer.objects.put> | 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<unknown>,
|
||||
) {
|
||||
while (
|
||||
!(await navigator.locks.query()).pending?.some(
|
||||
(lock) => lock.name === lockName(policy) && lock.mode === "shared",
|
||||
)
|
||||
) {
|
||||
await tick();
|
||||
}
|
||||
}
|
||||
|
||||
const settledWithin = async <Value,>(work: Promise<Value>, 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<void>;
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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<Uint8Array>({
|
||||
pull(controller) {
|
||||
controller.error(new TypeError("disk read failed"));
|
||||
},
|
||||
}),
|
||||
{ headers: stored.headers },
|
||||
);
|
||||
};
|
||||
const transient = (operation: string) => ({
|
||||
ok: false,
|
||||
error: {
|
||||
code: "UNAVAILABLE",
|
||||
operation,
|
||||
retryable: true,
|
||||
recovery: "RETRY",
|
||||
},
|
||||
});
|
||||
|
||||
expect(
|
||||
await release.adapter.responses.matchActiveExact({
|
||||
absoluteUrl: release.assets[0]!.absoluteUrl,
|
||||
}),
|
||||
).toMatchObject(transient("CACHE_LOOKUP"));
|
||||
expect(
|
||||
await release.adapter.admin.activateRelease(
|
||||
release.manifest.releaseRegistryId,
|
||||
release.manifest.manifestDigestHex,
|
||||
),
|
||||
).toMatchObject(transient("CACHE_ACTIVATE"));
|
||||
// The stage fast path shares the verdict: an unreadable candidate is
|
||||
// neither reused nor fetched again over the network.
|
||||
const fetchesBefore = release.fetchLog.length;
|
||||
expect(
|
||||
await release.adapter.admin.stageRelease(release.manifest),
|
||||
).toMatchObject(transient("CACHE_STAGE"));
|
||||
expect(release.fetchLog).toHaveLength(fetchesBefore);
|
||||
|
||||
cache.match = realMatch;
|
||||
expect(
|
||||
await release.adapter.admin.activateRelease(
|
||||
release.manifest.releaseRegistryId,
|
||||
release.manifest.manifestDigestHex,
|
||||
),
|
||||
).toMatchObject({ ok: true });
|
||||
});
|
||||
|
||||
it("still reports stored bytes that no longer match as an integrity failure", async () => {
|
||||
const release = await stagedRelease("mismatched-body");
|
||||
const cache = release.cacheStorage.caches.get(release.cacheName)!;
|
||||
const index = cache.responses.findIndex(
|
||||
(entry) => entry.request.url === release.assets[0]!.absoluteUrl,
|
||||
);
|
||||
const entry = cache.responses[index]!;
|
||||
cache.responses.splice(index, 1, {
|
||||
request: entry.request,
|
||||
response: new Response(new Uint8Array([9, 9, 9, 9]), {
|
||||
headers: entry.response.headers,
|
||||
}),
|
||||
});
|
||||
|
||||
expect(
|
||||
await release.adapter.admin.activateRelease(
|
||||
release.manifest.releaseRegistryId,
|
||||
release.manifest.manifestDigestHex,
|
||||
),
|
||||
).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
code: "INTEGRITY_FAILED",
|
||||
operation: "CACHE_ACTIVATE",
|
||||
recovery: "REHYDRATE",
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps every healthy asset when one repair fetch fails", async () => {
|
||||
const release = await stagedRelease("partial-repair");
|
||||
const cache = release.cacheStorage.caches.get(release.cacheName)!;
|
||||
@@ -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<string[]> {
|
||||
const stale = this.staleNames;
|
||||
this.staleNames = null;
|
||||
return stale ?? (await super.keys());
|
||||
}
|
||||
}
|
||||
const cacheStorage = new StaleOnceCacheStorage();
|
||||
const policy = policyRetaining(1);
|
||||
const adapter = adapterFor(cacheStorage, policy);
|
||||
expect(await deploy(adapter, "r1", policy)).toMatchObject({ ok: true });
|
||||
const namesBeforeR2 = await cacheStorage.keys();
|
||||
expect(await deploy(adapter, "r2", policy)).toMatchObject({ ok: true });
|
||||
cacheStorage.staleNames = namesBeforeR2;
|
||||
|
||||
expect(
|
||||
await adapter.responses.matchActiveExact({ absoluteUrl: assetUrl("r2") }),
|
||||
).toMatchObject({ ok: true, value: expect.anything() });
|
||||
});
|
||||
|
||||
it("still stops activation when the pointer read fails transiently", async () => {
|
||||
const cacheStorage = new MemoryCacheStorage();
|
||||
const policy = policyRetaining(1);
|
||||
|
||||
@@ -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<ReturnType<typeof createRuntimeAdapters>> | 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"]);
|
||||
});
|
||||
});
|
||||
@@ -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<Record<string, string>>;
|
||||
@@ -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({
|
||||
|
||||
Reference in New Issue
Block a user