fix: 2026-09-24 src 리뷰 전 항목 반영 (1·2·3차) #2

Merged
donghyeon.kang merged 154 commits from fix/src-review-round3 into main 2026-09-24 06:57:23 +00:00
323 changed files with 23107 additions and 9163 deletions
+11
View File
@@ -167,6 +167,17 @@
"path": "^src/(application|features)"
}
},
{
"name": "contracts-do-not-know-presentation-or-bootstrap",
"comment": "Q-6.7-12. `src/contracts` is shared vocabulary read by every layer, including the service worker and web worker builds. Importing presentation or the composition root from it would pull React and the whole app into those builds. There is no such import today; this keeps it that way.",
"severity": "error",
"from": {
"path": "^src/contracts"
},
"to": {
"path": "^src/(presentation|bootstrap)"
}
},
{
"name": "generic-presentation-does-not-compose-the-product",
"comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.",
+3
View File
@@ -24,3 +24,6 @@ artifacts/tests/visual/
.env
.env.*
!.env.example
# graphify knowledge-graph output (local analysis, not part of the product).
graphify-out/
+228
View File
@@ -0,0 +1,228 @@
# SPEC: src 리뷰(2026-09-24) 긴급·필수 항목 수정
## 목적
`docs/reviews/2026-09-24-src-full-review.md`의 **긴급 1건 + 필수 46건**을 고친다. 권장·사소 항목은 이번 범위가 아니다.
각 요구사항 ID(R-x.y)는 리뷰 문서의 섹션 번호(6.x-y)와 같다. 문제 설명, 근거 코드, 실패 시나리오는 리뷰 문서를 기준으로 한다. 이 문서에는 **무엇이 되면 완료인지**와 **방향이 여러 개인 항목의 결정**만 적는다.
## 범위 밖
- 리뷰의 권장·사소 항목. 단, 같은 코드 줄을 고치다가 자연히 해결되는 경우는 예외다.
- `src/` 밖의 리팩터링. 단, R-0이 요구하는 스크립트와 설정 변경, 그리고 버그를 고정하고 있는 기존 테스트의 수정은 포함한다.
- 공개 포트 시그니처의 파괴적 변경. 추가만 허용한다.
## 공통 완료 기준 (모든 요구사항)
1. 버그를 재현하는 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이는 재현할 수 없는 항목은 fake/fixture로 조건을 만들어 재현한다.
2. `corepack pnpm check:architecture`, `check:types:app`, `check:types:test`, `lint`, `test:unit`, `test:component`이 통과한다.
3. adapter 파일을 추가하거나 이동하면 `docs/reviews/adapters/INVENTORY.md`를 함께 고치고 `check:adapter-inventory`가 통과한다.
4. adapter 간 공용 로직은 `src/adapters/platform/`(kernel)으로, 공유 어휘는 `src/contracts/`로 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다.
5. 요구사항 하나에 커밋 하나. 커밋 메시지에 R-ID를 적는다.
## 요구사항
### R-0 빌드 기반 (긴급)
- 깨끗한 체크아웃(`src/.generated/` 없음)에서 `dev`, `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 사전 수동 명령 없이 동작한다.
- CI 게이트도 같은 조건에서 통과한다.
### R-1 browser-transfer
- R-1.1 `dispose()`가 deadline 초과로 실패한 뒤 작업이 끝나면, 다시 호출할 때 store를 닫고 `CLOSED`가 된다.
- R-1.2 opaque ID 문법은 한 곳에서 정의한다. control plane이 받은 ID는 presigned 계층도 받는다.
- R-1.3 동시성 정책 검증은 `partSize × maxConcurrency × copyFactor`를 기준으로 한다. 기본 정책은 이 검증을 통과하고, createSession은 **실제 worker 수**를 요청한다.
- R-1.4 크기나 part 수 한도 초과는 `LIMIT_EXCEEDED`로 보고된다.
### R-2 browser-files / cache-storage / cross-context
- R-2.1 BOUNDED_OBJECT_URL 전략에서 source open이 실패하거나 abort되면 `deliver()`는 reject하지 않고 Result를 반환한다. 늦게 온 lease는 닫힌다.
- R-2.2 source별 sequence watermark는 이벤트 TTL로 지워지지 않는다. 60초 넘게 쉰 뒤의 seq N+1은 `NEXT`다.
- R-2.3 broadcast 발행이 실패해도 수신 listener는 유지된다. broadcast를 받을 수 없는 탭은 `DEGRADED`로 보고된다.
- R-2.4 picker/save picker 함수는 options 객체에 bind되지 않는다. `window` 함수를 그대로 주입해도 동작한다.
- R-2.5 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 받아들인다. `content-type`이 허용 응답 헤더에 없는 정책은 정책 검증에서 거부된다.
### R-3 http / query-cache / auth
- R-3.1 경로 값 `.`과 `..`는 V3와 V2 모두에서 `PATH_VALUE_INVALID`(V2는 `PATH_PARAMETER_INVALID`)로 거부된다.
- R-3.2 세션 알림은 (상태, 주체)가 바뀔 때만 scope fence를 건다. demo 어댑터는 같은 값이면 알리지 않는다. V3의 요청 전 자격증명 없음은 `onUnauthenticated()`를 부르지 않는다. 서버 401만 부른다. **[고위험: 인증·캐시]**
- R-3.3 5xx/408/425 응답의 problem 바디가 유효하지 않으면 HTTP status를 담은 서버 장애로 분류된다. 요청 쪽 위반은 서버 응답 오류(`ENVELOPE_MISMATCH`)로 매핑되지 않는다.
- R-3.4 자격증명 헤더 값은 전송 전에 ByteString(제어문자 없음)으로 검증된다. 실패는 요청 전 단계의 인증 결함으로 분류된다. 대소문자만 다른 중복 헤더는 거부된다. **[고위험: 인증]**
- R-3.5 feature 바인딩에서 `mapSuccess`/`mapProblem`이 던지면 `MAPPING_CONTRACT_VIOLATION` Result로 반환되고 effect가 보존된다.
### R-4 realtime
- R-4.1 `await quiescence` 뒤 DRAINING이면 recovery는 authority를 호출하지 않고 실패한다.
- R-4.2 `retryable:true`인 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`는 서버 hint가 없어도 재연결 대상이다(reconnect와 polling 모두).
- R-4.3 barrier가 필요 없는 recovery(barrier NONE)는 전송을 닫지 않고 계속된다.
- R-4.4 SSE 파서는 문자마다 인코딩하지 않는다. 250KB chunk 처리가 기존 대비 10배 이상 빨라진다(수동 측정 기록).
### R-5 storage
- R-5.1 orphan 후보 목록은 커서로 이어서 볼 수 있다. 참조 중 청크가 100개를 넘어도 뒤의 orphan이 지워진다. **[고위험: 삭제]**
- R-5.2 dedup으로 재사용한 청크는 grace period 보호를 다시 받는다(mtime 갱신). **[고위험: 삭제]**
- R-5.3 mutation lock 대기 시간은 60초 RPC 타임아웃에 포함되지 않는다. lock 대기는 별도 상한 정책값으로 제한된다.
- R-5.4 파티션 purge는 손상 행이 있어도 끝까지 지운다. 손상은 observe로 보고한다. **[고위험: 삭제]**
- R-5.5 prepared-object 검증은 한 모듈에서 한다. 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증되고, 현재 정책값은 새로 쓰는 데이터에만 적용된다. **[고위험: 데이터 판독]**
### R-6 service-worker / web-push
- R-6.1 확정 이후 메시지(ACCEPTED/RELOAD_REQUIRED)는 `registration.waiting`이 비어도 성공으로 처리된다. 메시지는 nonce/kind로 먼저 거른다.
- R-6.2 drain 요청과 응답은 요청자 빌드와 무관하게 워커 buildId + nonce로 짝을 맞춘다. 다른 빌드 탭이 있어도 활성화가 끝난다.
- R-6.3 앱이 `reloadRequired`/`updateWaiting`을 구독할 수 있다. current 캐시에 없는 asset은 previous 캐시에서 찾는다.
- R-6.4 첫 방문에서 설치 중인 워커는 `ACTIVE`로 보고되지 않는다.
- R-6.5 JavaScript MIME 동의어를 허용한다. `content-encoding`이 있으면 Content-Length와 압축 해제 크기를 비교하지 않는다.
- R-6.6 fetch 핸들러는 manifest에 있는 same-origin GET(비 navigate) 요청에만 `respondWith`를 부른다.
- R-6.7 reconcile에서 서버가 `ABSENT`이면, local association이 ACTIVE였던 경우에만 재등록한다. 그 밖에는 native 구독을 해제한다. **[고위험: 동의]**
### R-7 contracts
- R-7.1 멱등 키는 `^[\x21-\x7E]{1,256}$`만 허용한다. 이 버그를 고정한 기존 테스트도 고친다.
- R-7.2 FEATURE_OVERRIDES의 키(기능 ID)는 설정 이름 금지어 검사 대상이 아니다.
- R-7.3 릴리스 매니페스트 URL은 해석 뒤 origin과 pathname이 입력과 같아야 한다. 탭, 개행, 인코딩된 점 세그먼트는 거부된다.
- R-7.4 REST V2의 COMMAND는 POST/PUT/PATCH/DELETE만 허용된다. `semantics`/`replayPolicy`는 enum으로 검증된다. **[고위험: CSRF]**
- R-7.5 operationId 문법은 contracts 한 곳에서 정의하고 텔레메트리와 진단이 재사용한다. V3가 받는 operationId의 실패 이벤트는 드롭되지 않는다.
### R-8 presentation
- R-8.1 청크 복구 실패 상태는 라우트가 바뀌면 초기화된다. 실패 화면에 "한 번 새로고침" 버튼이 있다.
- R-8.2 WebKit(`Importing a module script failed`)과 Vite CSS preload 실패가 청크 실패로 인식된다.
- R-8.3 선택한 로케일이 preferences에 저장되고 새로고침 뒤에도 유지된다. 세션이 바뀌어도 로케일과 테마는 초기화되지 않는다. unmount 시 router가 dispose된다.
- R-8.4 로케일 변경은 제목과 문구만 갱신한다. 포커스 이동, 스크롤, route 변경 보고는 일어나지 않는다.
- R-8.5 인증필요/잘못된 주소/비활성 기능 화면에서도 제목, 포커스, route 텔레메트리가 동작한다.
- R-8.6 모바일 드로어에서 링크로 이동하면 포커스가 새 페이지(h1/main)로 간다. 메뉴 버튼으로 가지 않는다.
- R-8.7 context 라우트 게이트웨이는 context가 바뀌면 이전 routes로 매칭하지 않는다. 모듈 로드 청크 실패는 `recoverChunk`를 거친다.
- R-8.8 `enabled:false` 쿼리는 로딩으로 표시되지 않는다.
### R-9 bootstrap / platform
- R-9.1 TTL 안에 reload 마커가 있으면 키와 상관없이 자동 reload하지 않는다(세션당 최대 1회). 번갈아 오는 키 테스트를 추가하고, 연속 reload를 기대하던 테스트를 고친다.
- R-9.2 dedup 창 안의 중복 발생 횟수가 수집기로 전달된다.
- R-9.3 리댁션은 문자열 중간의 자격증명, URL 쿼리의 토큰, 이메일을 가린다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin` 계열을 추가한다. **[고위험: 보안]**
## 결정 (방향이 여러 개였던 항목의 기본값)
| ID | 결정 | 이유 |
|---|---|---|
| D-1 (R-0) | 생성 파일을 커밋하지 않는다. 생성 파일을 읽는 진입점(스크립트 또는 package script) 앞에서 생성기를 실행한다. | 6f6c48e가 앱별 생성(`PRODUCT_APP_ID`)을 의도했으므로 gitignore를 유지한다. |
| D-2 (R-1.3) | 기본 `maxConcurrency`를 실제 동작값에 맞춘다. 메모리 한도(`maxInFlightBytes`)는 올리지 않는다. | 지금 기본 동작(동시 1)을 바꾸지 않고, 문서와 코드만 일치시킨다. 다운스트림이 올릴 수 있다. |
| D-3 (R-5.3) | lock 범위는 줄이지 않는다(GC·dedup 정합성). lock 대기만 RPC 타임아웃에서 빼고, 별도 상한을 둔다. | 범위를 줄이면 R-5.2 같은 경합이 새로 생긴다. |
| D-4 (R-2.3) | 발행 쪽 이중 쓰기(broadcast + storage)는 하지 않는다. 수신 유지 + DEGRADED 보고만 한다. | 가장 작은 변경으로 흔한 경로(발행 1회 실패)를 고친다. |
| D-5 (R-8.3) | 로케일 저장은 테마와 같은 `preferences` 경로를 쓴다. Locale/Theme provider는 scope fence 바깥으로 올린다. | 이미 있는 테마 패턴을 재사용한다. |
| D-6 (R-9.2) | 누적 count는 dedup 창이 닫힐 때나 다음 flush 때 요약 이벤트의 `occurrences`로 보낸다. | 기존 이벤트 스키마(`occurrences`)를 그대로 쓴다. |
| D-7 (R-6.3) | previous 캐시 fallback은 hashed URL에만 적용한다. | hashed URL은 같은 URL이면 같은 내용이라 안전하다. |
---
# 2차 라운드: 권장·사소 항목과 1차 후속 결정
1차 라운드(R-0 ~ R-9.3)는 `9bef702`로 main에 병합했다. 2차 라운드에서는 리뷰의 **권장·사소 항목 전부**와 1차에서 남긴 결정 두 건을 처리한다. 요구사항 ID는 `Q-<리뷰 섹션>` 형식이다(예: Q-6.1-5 = 리뷰 6.1-5).
## 공통 완료 기준 (2차)
1차 공통 기준과 같다. 여기에 두 가지를 더한다.
- **동작을 바꾸지 않는 정리(파일 분리, 중복 합치기)**: 새 RED 테스트 대신 기존 테스트가 안전망이다. 해당 경로에 테스트가 없으면 현재 동작을 고정하는 테스트(characterization)를 먼저 추가한다.
- **번들**: 정리가 끝난 뒤 `check:optional-recipes`가 통과해야 한다. 예산은 올리지 않는다(D-11).
## 요구사항
### browser-transfer
- Q-6.1-5 worker 하나가 실패하면 transfer 단위 abort로 나머지 worker를 즉시 멈춘다.
- Q-6.1-6 해석할 수 없는 checkpoint 행이 있어도 abort는 그 행을 지우고 ORPHANED로 보고한다.
- Q-6.1-7 PRIMARY_REQUIRED probe를 쓰는 preset은 fit이 cover/contain/fill일 때만 정책을 통과한다(D-12).
- Q-6.1-8 probe의 decode는 EXIF/irot 회전을 적용하지 않는다(`imageOrientation: "none"`).
- Q-6.1-9 presigned HTTP helper를 한 모듈로 합친다. statusFailure recovery를 통일하고, 쓰지 않는 `compensateLateResponse`는 삭제한다. download Content-Length를 엄격하게 파싱하고, runtime attempt는 kernel `createAbortableOperation`을 쓴다.
- Q-6.1-3b part마다 일어나는 방어적 복사 중 겹치는 것(`Uint8Array.from`과 `slice()`)을 하나로 줄인다.
- Q-6.1-10 `resumable-upload-runtime.ts`에서 서버 응답 검증과 의존성 snapshot 래퍼를 별도 모듈로 분리한다. 동작은 바꾸지 않는다.
- Q-6.1-11 vault `register`는 snapshot 값만 읽는다.
### browser-files / cache-storage / cross-context
- Q-6.2-6 cache 조회 비용: JSON은 chunk를 모아 읽고, 검증된 marker는 메모리에 캐시하고, asset 탐색은 Map으로 한다.
- Q-6.2-7 browser-files의 abort race를 kernel `race`와 compensate로 교체한다. 늦게 도착한 lease와 writable은 닫는다.
- Q-6.2-8 native `cancel`을 한 번이라도 관찰했으면 focus fallback을 끈다.
- Q-6.2-9 host factory가 비활성으로 끝날 때 observe로 보고한다. epoch는 releaseId를 인코딩해서 만든다.
- Q-6.2-10 파일명 자르기를 O(n)으로 바꾸고, 중복 호출을 하나로 줄인다.
- Q-6.2-11 `public-response-cache-adapter.ts`와 `download-delivery-adapter.ts`에서 코덱·검증 모듈을 분리한다. 동작은 바꾸지 않는다.
- Q-6.2-12 `MEDIA_TYPE`/opaque 정규식과 `positiveSafeInteger` 중복을 합치고, `object-url-lease.ts`의 죽은 분기를 지운다.
### http / browser-rpc / query-cache / auth
- Q-6.3-6 요청 종료 사유 판정을 `terminalOutcomeFor` 하나로 모은다. 백오프 중 scope fence는 scope 종료로 분류된다.
- Q-6.3-7 명령의 최종 effect는 누적 certainty와 합친다. `MAYBE_APPLIED`면 재시도하지 않는다.
- Q-6.3-8 namespace 무효화를 병렬로 실행한다.
- Q-6.3-9 RPC 명령이 전송 뒤 실패하면 `MAYBE_APPLIED`로 보고한다. 재시도 전에 scope를 확인하고, 소비자가 abort한 stream은 정리한다.
- Q-6.3-11 V2 401 복구를 재시도 예산과 분리한다. "롤백 가능 seam" 문서의 잘못된 주장을 고친다(V2와 V3는 wire 형식이 다르다).
- Q-6.3-12 cursor pagination의 누적 직렬화와 `push(...)` 한도 문제를 고친다. 쓰지 않는 `validTransportFailure`를 삭제하고, 따옴표가 닫히지 않은 `W/"` ETag를 거부한다.
- Q-6.3-3b V2도 5xx/408/425의 HTML/빈 바디를 status를 담은 서버 장애로 분류하고 재시도 대상으로 둔다.
### realtime
- Q-6.4-5 chunk당 item 상한을 넘으면 실패하지 않고 다음 처리로 넘긴다. COMMENT는 상수 객체를 쓴다.
- Q-6.4-6 dedupe는 FIFO로 제거하고, fingerprint는 해시로 저장하고, prune은 `break`한다. 가득 차도 전체 recovery를 하지 않는다.
- Q-6.4-7 재시도 예산은 유효 신호가 있고 `stableOpenMs`가 지났을 때만 초기화한다.
- Q-6.4-8 realtime 내부의 DataSnapshot과 abort/timeout race 헬퍼를 한 벌로 합친다. Retry-After 파싱과 JSON 중복 키 스캐너는 kernel(`src/adapters/platform/`)로 올리고, http retry-policy와 web-push codec도 이를 쓴다.
- Q-6.4-9 반복되는 attempt 정리를 `endAttempt()`로 뽑고, 무시되던 `_recovery` 파라미터를 없앤다.
- Q-6.4-10 probe 버퍼 상한을 현재 버퍼 기준으로 계산한다.
- Q-6.4-11 사소 항목: poll execute가 throw하면 retryable OFFLINE으로 둔다. BOM은 한 번만 제거하고, 이중 encode와 이벤트마다 만드는 TextEncoder를 없애고, 잘못 붙은 JSDoc을 옮긴다.
### storage
- Q-6.5-6 openObject는 사전 검증에서 manifest만 대조하고, root digest는 스트림 끝에서 확인한다.
- Q-6.5-7 IndexedDB 저장 행 타입·검증기·측정 공식을 `indexeddb-records.ts` 하나로 모은다. 동작은 바꾸지 않는다.
- Q-6.5-8 삭제 후 재생성하면 revision/generation이 다시 시작한다는 점을 port 주석과 문서에 명시한다(D-13).
- Q-6.5-9 보상이 실패해도 put의 원래 실패 코드를 유지하고, recovery만 RECONCILE로 바꾼다.
- Q-6.5-10 kernel: `succeed` 뒤에 온 `fail`이 이기도록 하고, settle된 뒤의 upgrade는 abort한다.
### service-worker / web-push
- Q-6.6-6b fetch 가로채기를 "same-origin GET, navigate 아님, 해시 파일명 또는 manifest URL"로 넓힌다. previous 캐시 fallback이 옛 빌드 chunk에 실제로 동작해야 한다(1차 T29/T32 후속, 사용자 결정).
- Q-6.6-8 후보 캐시 이름이 active 캐시와 같으면 설치 실패 시 지우지 않는다.
- Q-6.6-9 activate는 오래된 캐시부터 지우고, marker 쓰기 실패가 삭제를 막지 않는다.
- Q-6.6-10b 페이지 쪽 활성화 deadline에 워커 drain 시간과 여유분을 더한다.
- Q-6.6-11 알림 클릭이 거절되면 handoff 데이터 없이 앱 루트를 연다. 조용한 push drop은 트레이드오프를 문서에 명시한다(D-14).
- Q-6.6-12 web-push codec primitive(base64url, OPAQUE_ID, validAuthority, exactRecord)를 한 모듈로 합친다. page controller가 주입받은 document를 쓴다.
### contracts
- Q-6.7-6 exact-key/스냅샷 구현을 `exact-snapshot.ts` 하나로 모으고 배열 스냅샷을 추가한다. iterator·getter 우회를 막는다.
- Q-6.7-7 검증된 인덱스·레지스트리는 `createReadOnlyRegistry`를 쓰고 row마다 스냅샷해서 얼린다.
- Q-6.7-8 검증기 프로토콜과 `MappingResult`의 기준 모양을 하나로 정하고, 나머지는 호환 alias나 어댑터로 둔다(D-15).
- Q-6.7-9 REST 인증 프로필은 설치된 레지스트리 하나를 기준으로 한다. V2 resolve도 검증된 레지스트리를 쓴다.
- Q-6.7-10 배포 승인은 IPv6 loopback·ULA·link-local, IPv4-mapped, CGNAT, `0.0.0.0/8`, `.internal`/`.local`을 사설 주소로 본다. 로컬 호스트 목록은 한 곳에 둔다.
- Q-6.7-11 레지스트리 조회는 `Object.hasOwn`으로 한다. 목록에 없는 offline 전이는 false를 반환한다.
- Q-6.7-12 release-tokens는 비교하지 않은 값을 통과로 보고하지 않는다. contract-set 중복은 실패 코드로 반환한다. query-keys 정렬은 필요할 때만 한다. dependency-cruiser에 contracts → presentation/bootstrap 금지 규칙을 추가한다.
### presentation
- Q-6.8-9 디자인시스템 링크(`PageActionBar`, `Breadcrumbs`, `LinkButton`)는 router `Link`로 렌더한다. Pagination은 다른 검색 파라미터를 보존한다.
- Q-6.8-10 로딩·인증필요·404 화면을 하나씩으로 합치고, 세션 액션은 hook 하나로 묶는다. reject 시 멈추던 임시 로딩도 고친다.
- Q-6.8-11 Tooltip: `aria-describedby`를 포커스되는 자식에 붙이고, Escape로 닫는다.
- Q-6.8-12 Pagination은 현재 페이지 주변과 처음·끝만 보여주고(windowing), landmark 중첩을 없앤다.
- Q-6.8-13a 플랫폼 라우트의 `none` 코덱은 모르는 쿼리 파라미터를 거부하지 않고 무시한다(D-16).
- Q-6.8-13b 폼 제출은 비동기 검증 중에도 두 번 일어나지 않는다. 저장 직후 이동할 때 dirty guard가 뜨지 않는다.
- Q-6.8-13c 기본 fallback 문구는 현재 로케일을 따른다. SearchField를 지우면 입력으로 포커스를 돌려준다.
- Q-6.8-13d `theme.css`를 여러 파일로 나눈다. 빌드 결과 CSS 바이트가 달라지지 않아야 한다.
### application / features / bootstrap / platform (+ telemetry adapter)
- Q-6.9-4 텔레메트리 전송 계층을 하나로 합친다(rate limit, credentials `omit`, `pagehide` flush, dispose abort). best-effort fetch에 타임아웃을 둔다(6.3-10 포함).
- Q-6.9-5 킬스위치로 끈 feature는 `features.get()`이 API를 돌려주지 않는다.
- Q-6.9-6 adapter contribution의 featureId가 중복되거나 소속 module과 다르면 throw한다.
- Q-6.9-7 execution context interaction에 완료/정리 API를 두어 부모 signal listener가 남지 않게 한다.
- Q-6.9-8 부트 중에 정적 boot shell(로딩 표시, `aria-busy`)을 보여준다.
- Q-6.9-9 chunk와 boot의 "한 번만 reload" 가드를 공용 guard 하나로 합친다.
- Q-6.9-10 검증을 통과한 config 값만 safe 에러에 싣는다.
- Q-6.9-11 텔레메트리 버퍼는 필요한 공간이 확보될 때만 낮은 severity를 지운다. 주석을 코드와 맞춘다.
- Q-6.9-12 re-export만 하는 `reference-feature-runtime.tsx`를 삭제한다. CI 전용 정책(`promotion-readiness`, `performance-budgets`)은 src 소비자가 없으면 `scripts/`로 옮긴다. 메시지 로케일은 하드코딩하지 않고 카탈로그에서 도출한다.
### 통합
- Q-B 번들 예산: 모든 레인을 병합한 뒤 `check:optional-recipes`를 통과시킨다. 필요하면 해당 번들 코드를 줄인다(D-11).
## 결정 (2차)
| ID | 결정 |
|---|---|
| D-11 | 번들 예산은 올리지 않는다. 코드를 줄여 맞춘다(사용자 결정). |
| D-12 | PRIMARY_REQUIRED는 fit cover/contain/fill만 허용한다. 비율을 유지하는 fit은 probe를 쓰지 않는 preset에서만 허용한다. |
| D-13 | 삭제 뒤 revision 재시작(ABA)은 스키마를 바꾸지 않고 문서로 계약을 명시한다. tombstone 도입은 저장 스키마 변경이라 범위 밖이다. |
| D-14 | 클릭 실패 시 앱 루트를 연다. push drop은 설계 의도로 두고 문서에 명시한다. |
| D-15 | `external-contract-runtime`의 모양을 기준으로 삼는다. 다른 쪽은 호환 alias나 어댑터로 유지한다(공개 타입을 삭제하지 않음). |
| D-16 | 플랫폼 라우트의 모르는 쿼리 파라미터는 무시한다(strip). URL은 건드리지 않는다. |
---
# 3차 라운드: 남은 문제 8건
2차 뒤에 남은 문제 8건을 처리한다(사용자 결정 2026-09-24). ID는 `R3-n`이다.
- R3-1 HTTP V2: 408/425 응답을 안전하거나 멱등인 요청에 한해 재시도한다. `client.ts`의 Retry-After 파싱은 kernel `platform/retry-after.ts`를 쓴다.
- R3-2 업로드 fetch transport의 Retry-After 파싱도 kernel을 쓴다. file-transfer 번들은 동작을 바꾸지 않는 축소로 예산 대비 여유를 546B(1%) 이상 확보한다. 예산은 바꾸지 않는다.
- R3-3 세션 subject: demo 어댑터가 subject를 제공해서, 같은 사용자의 인증 상태 알림(토큰 갱신 등)은 캐시를 비우지 않는다. subject를 주지 않는 외부 owner는 fail-closed로 동작하고, 그 사실과 `readSubject` 구현 방법을 문서에 적는다.
- R3-4 꺼 둔(`enabled:false`) 쿼리는 `idle` 상태로 표시한다. loading이나 empty가 아니다. `AsyncSurface`는 idle에서 로딩이나 빈 상태 문구를 보여주지 않는다.
- R3-5 SSE 파서는 디코딩 전 바이트 단위로 줄 경계를 찾는다. 멀티바이트 입력에서도 원래 파서 대비 10배 이상 빨라진다(수동 벤치로 측정).
- R3-6 실제 브라우저 검증: 모바일 드로어 이동 후 포커스, bind하지 않은 picker 호출, 서비스 워커 두 빌드 간 업데이트와 옛 chunk의 이전 캐시 fallback, `application/javascript`와 gzip 응답의 static 설치, 실제 Cache API의 `Vary: Accept-Encoding`을 Playwright 스펙으로 확인한다. 여러 탭 OPFS 경합은 결정적으로 재현할 수 있으면 넣고, 없으면 그 이유를 기록한다.
- R3-7 WebKit: 시스템 라이브러리를 설치한 뒤 Playwright 스위트 전체를 WebKit으로 돌린다(Safari 청크 오류 메시지 포함).
- R3-8 원격 반영: 3차가 끝나면 브랜치를 push하고 Gitea PR을 만든다(사용자 결정).
-3
View File
@@ -27,9 +27,6 @@
},
"sourceMap": {
"public": false
},
"serviceWorker": {
"enabled": false
}
}
}
-22
View File
@@ -119,26 +119,6 @@
"branches": 75
}
},
{
"path": "src/application/policies/performance-budgets.ts",
"owner": "application-policy",
"minimum": {
"lines": 80,
"statements": 80,
"functions": 80,
"branches": 40
}
},
{
"path": "src/application/policies/promotion-readiness.ts",
"owner": "release-runtime",
"minimum": {
"lines": 95,
"statements": 95,
"functions": 95,
"branches": 95
}
},
{
"path": "src/application/use-cases/decide-chunk-recovery.ts",
"owner": "application-runtime",
@@ -212,8 +192,6 @@
"src/adapters/telemetry/best-effort-telemetry.ts",
"src/application/create-application.ts",
"src/contracts/compatibility.ts",
"src/application/policies/performance-budgets.ts",
"src/application/policies/promotion-readiness.ts",
"src/application/use-cases/decide-chunk-recovery.ts",
"src/bootstrap/load-release-manifest.ts",
"src/bootstrap/read-bounded-boot-json.ts",
@@ -2604,7 +2604,7 @@ export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({
- remaining episode budget 초과 hint: reconnect 종료;
- attempts/exhausted: `DEGRADED`, explicit recovery action;
- automatic new episode cooldown: 300,000ms;
- valid event/heartbeat 또는 60s stable open 후 attempt counter reset;
- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset;
- offline state에서는 timer 대신 `online` signal을 기다림.
### 14.4 error classification
@@ -525,6 +525,14 @@ recipe의 feature-facing `StoredRecord<T>` view model과 혼동하지 않는다.
`writtenAtEpochMs`, synchronization, `measuredBytes`, `eligibleAtEpochMs`는 record
envelope에 중복 저장하지 않고 `retentionStore` sidecar에 둔다.
revision은 살아 있는 record 하나 안에서만 순서를 매긴다(D-13). `remove`는 행을
tombstone 없이 지우므로 같은 key를 다시 만들면 revision이 1부터 다시 시작한다.
그래서 `(key, revision)`은 key의 전체 수명에서 유일하지 않다. 삭제 전에
revision N을 읽은 writer는 재생성된 record가 N에 도달하면 `expectedRevision: N`
CAS로 그 record를 덮어쓸 수 있다. 이 구분이 필요한 호출자는 revision과 함께
자기가 소유한 값(server version, payload 안의 ID)을 비교한다. tombstone으로
번호를 이어 가는 방식은 저장 스키마 변경이라 이 템플릿 범위 밖이다.
- structured clone 성공을 업무 schema 검증으로 간주하지 않는다.
- 모든 read는 `unknown`에서 runtime codec으로 envelope와 payload version을
검증한 뒤 domain value로 mapping한다.
@@ -752,7 +760,9 @@ CLEANED -> journal 제거
- journal row와 budget reservation은 physical cleanup effect가
`CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash,
malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를
그대로 남기고 `OBJECT_RECONCILE`로 반환한다.
그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면
`QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다
(Q-6.5-9). journal rollback이 실패해도 같다.
- coordinator가 `abortPreparedPut()` 하나만 소유한다. worker client는 prepare 실패
시 별도의 fire-and-forget abort를 발행하지 않는다. 중복 보상은 아직 남아 있어야
할 journal row를 조기에 지우는 경로였다.
@@ -771,6 +781,11 @@ CLEANED -> journal 제거
`STORAGE_EVICTED`; reconstructable만 rehydrate한다.
- delete는 logical row tombstone을 먼저 commit해 신규 open을 막고 physical bytes를
나중에 정리한다.
- delete가 끝나면 logical row가 없어지므로 같은 object ID의 다음 put은
generation 1부터 다시 시작한다(D-13). 삭제 전에 기억한 generation이나
`expectedGeneration`은 다른 객체와 일치할 수 있다. `(objectId, generation)`을
객체 수명 전체의 식별자로 쓰지 않고, 필요하면 integrity root digest를 함께
비교한다.
- operation ID로 replay를 deduplicate한다.
`Web Locks`를 쓰면 고정된 origin mutation lock과 AbortSignal/timeout을 사용한다.
@@ -360,7 +360,10 @@ resume through upload()
정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다.
현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체
삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는
`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로
보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다.
`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local
checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은
다음을 제공한다.
@@ -545,6 +548,9 @@ DOM, persisted state, telemetry 또는 query cache에 장기 보관하지 않는
private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NONE`으로
낮출 수 없다. probe는 `credentials: omit`, redirect 금지, exact response URL과
`Cache-Control: no-store`를 실제 response에서 확인한다.
probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야 통과하므로
`PRIMARY_REQUIRED` preset의 `fit`은 `cover`/`contain`/`fill`만 허용한다(D-12).
원본 비율을 유지하는 `inside`/`outside`는 probe를 쓰지 않는 preset에서만 쓴다.
실제 `<img crossorigin="anonymous">`는 same-origin일 때 cookie를 보낼 수
있으므로 registry는 CDN origin이 composition의 application origin과 같으면
생성 단계에서 거절한다. private CDN 응답은 cookie나 ambient authorization에
@@ -618,7 +618,8 @@ stream + epoch별 `lastAppliedSequence`를 기준으로 처리한다.
| `sequence == lastApplied + 1` | 순차 적용 |
| `sequence > lastApplied + 1` | gap; delta 적용 중지, `RESYNC_REQUIRED` |
| unknown `streamEpoch` | old/new epoch를 섞지 않고 registered snapshot 또는 session rebuild |
| dedupe/queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
| dedupe window 가득 참 | 가장 오래된 항목부터 제거(FIFO)하고 계속 적용. 창에서 밀려난 재전송은 `sequence <= lastApplied`로 drop |
| queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery |
| captured old runtime generation | late callback safe drop + aggregate diagnostic |
| current connection의 `scopeBinding` mismatch | effect/sequence/cursor 0, freshness `UNKNOWN`, close + session revalidation + registered recovery |
@@ -763,8 +764,9 @@ effectiveDelay = max(localDelay, validServerNotBefore)
bound로 취급한다. `effectiveDelay`가 implementation max delay나 남은 elapsed
budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해
`DEGRADED`/`STALE`로 전환한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. stable-open
window 또는 valid heartbeat/event 뒤에만 reset한다.
- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid
heartbeat/event를 받았고 stable-open window도 지났을 때만 reset한다(둘 중
하나만으로는 reset하지 않는다).
- stream reconnect는 realtime recovery coordinator, credential recovery는
session owner, Poll attempt 사이 cadence는 poll coordinator가 각각 소유한다.
Poll-bound REST transport retry와 Query retry는 끈다. 같은 logical recovery의
@@ -1411,6 +1413,20 @@ Service Worker는 언제든 종료될 수 있다. in-memory cursor, queue, auth
timer를 authority로 사용하지 않는다. `waitUntil`도 무제한 lifetime을 보장하지
않으므로 large fetch, retry loop, data migration을 넣지 않는다.
**조용한 drop은 설계 의도다(D-14).** 검증에 실패한 push(EXPIRED,
RELEASE_MISMATCH, association mismatch, fence 읽기 실패, handler deadline 초과,
malformed/unknown)는 알림을 띄우지 않고 끝난다. 계정 정보가 없는 generic
알림으로 대신 띄우지 않는 이유는 logout·계정 전환 뒤에 도착한 push가 어떤
형태로든 사용자에게 보이면 안 되기 때문이다. 대가는 두 가지다.
- Chrome은 `userVisibleOnly` push가 알림 없이 끝나면 "This site has been updated
in the background" 같은 기본 알림을 대신 띄울 수 있다.
- Safari(WebKit)는 알림 없는 push가 반복되면 구독을 취소할 수 있다.
그래서 drop은 드물어야 한다. backend는 ACTIVE association에만 보내고, 짧은
server TTL을 쓰고, release를 바꾼 직후에는 이전 release epoch로 보내지 않는다.
drop은 `web_push_hint_processed`의 `FAILED` + reason으로 관측한다.
### 8.5 Notification content와 click
- title/body/icon/action은 closed notification registry가 만든다.
@@ -1438,8 +1454,14 @@ type NotificationClickDataV1 = Readonly<{
worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bounded, non-sensitive
envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry,
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch는
route를 열지 않고 notification을 닫는다. 이미 표시된 notification은 logout 뒤
current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch
(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고
요청한 route 대신 **앱 루트(`<origin>/`)를 handoff 데이터 없이 연다**(D-14).
사용자의 탭이 아무 반응 없이 사라지지 않게 하되, 거절된 click의 route와
notification 정보는 페이지로 넘기지 않는다. 결과는 여전히 실패로 보고하고
(`web_push_click_dispatched` `FAILED` + reason, `nativeEffect`는 루트 창의
확실성), 브라우저가 창 열기를 거절한 native 실패나 deadline/abort 뒤에는 루트를
다시 시도하지 않는다. 이미 표시된 notification은 logout 뒤
OS notification center에 남을 수 있으므로 copy는 항상 account-neutral하고
민감하지 않아야 하며, `getNotifications()` cleanup 성공을 privacy 보장으로
과장하지 않는다.
+14
View File
@@ -53,6 +53,20 @@ An external owner implements `readState`, `subscribe`, `beginSignIn`,
`signOut`, `attachCredential`, `recoverSession`, and
`notifyUnauthenticated`. It owns token acquisition and storage.
The owner may also implement `readSubject()`. The server-state cache is cleared
only when the session state or the subject changes, so a token refresh for the
same user keeps cached data. `readSubject()` must return:
- an opaque, non-empty string that stays the same for one user across token
refreshes and differs between users, such as a hashed account id
- `null` when nobody is signed in
- never an access token, refresh token, or any other credential
Without `readSubject()` (or when it returns `null` or `""` while
authenticated), the runtime cannot tell a refresh from an account switch, so
every notification from an authenticated owner clears server state. This is the
safe default. The `demo` adapter reports one fixed demo user as its subject.
## Extending the starter
The steps below describe the current extension path. New platform work should follow
@@ -31,6 +31,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
`allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이
`TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지
않기 위한 cross-field invariant다.
- `allowedResponseHeaderNames`에 `content-type`이 없는 policy도 composition에서
`TypeError`로 실패한다. activation이 저장된 `content-type`을 다시 검증하기
때문이다.
- `Vary: Accept-Encoding`은 policy 없이 항상 허용한다. `Accept-Encoding`은
script가 만든 Request에 들어가지 않는 금지 헤더라 저장과 조회 요청 모두 이
값이 없다. nginx `gzip_vary`와 대부분의 CDN이 이 헤더를 붙인다.
## 1. 변경할 수 없는 복구 원칙
@@ -54,7 +60,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
2. `cache.operation.failed`와 `storage.operation.failed`의 allowlisted
operation/outcome/reason만으로 범위를 좁힌다.
3. runtime status가 `ACTIVE_BROADCAST`, `ACTIVE_STORAGE_FALLBACK`,
`DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지 확인한다.
`DEGRADED_STORAGE_FALLBACK`, `DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지
확인한다. `DEGRADED_STORAGE_FALLBACK`은 BroadcastChannel open에 실패한 tab이다.
다른 tab이 broadcast로만 보낸 event를 받지 못한다.
4. 현재 tab의 mutation 성공 후 local namespace가 stale 처리되는지 확인한다.
5. 다른 tab의 오래된 화면이 단순 stale 표시인지, 실제 server authorization
우회인지 분리한다. authorization 우회는 cache incident가 아니라 P1 security
@@ -70,7 +78,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle
- `BROADCAST_PUBLISH_FAILED`
- `STORAGE_LISTENER_FAILED`
- `STORAGE_PUBLISH_FAILED`
- runtime status `DEGRADED_LOCAL_ONLY`
- `INVALID_CACHE_EPOCH`, `SECURE_RANDOM_UNAVAILABLE`(OPEN FAILED): runtime을
만들지 못해 이 tab은 cross-tab 무효화 없이 `DEGRADED_LOCAL_ONLY`로 동작한다
- runtime status `DEGRADED_STORAGE_FALLBACK` 또는 `DEGRADED_LOCAL_ONLY`
### 확인
+3 -1
View File
@@ -18,7 +18,9 @@ The provider-independent cache defaults are:
- HTML: `no-cache`
- runtime config and release manifest: `no-store`
- public source maps: disabled
- service worker/offline cache: disabled
- service worker/offline cache: disabled, unless the static selection in
`src/features/installed-runtime-capabilities.ts` is `ACTIVE`; then `dist`
holds exactly the selected `service-worker.js`
HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
to the declared allowlist; a cache-correct response with a mismatched
+827
View File
@@ -0,0 +1,827 @@
# src/ 전체 코드 리뷰
> 검토일: 2026-09-24
>
> 검토 기준: `main` / `e59994a`
>
> 검토 범위: `src/` 전체 (diff 리뷰 아님). 약 8.7만 줄, 9개 영역
>
> 검토 관점: 정확성, 보안, 성능, 구조(중복·경계·파일 크기), 테스트 공백
>
> 판정: **NEEDS_FIX**
>
> 이 문서는 리뷰 결과 기록이다. 이 리뷰에서 코드는 수정하지 않았다.
## 1. 결론
레이어 규칙과 입력 경계 검증은 전반적으로 잘 지켜져 있다. presentation이 adapter를 직접 import하는 곳이 없고, 신뢰할 수 없는 입력은 크기 상한과 정확한 키 검사를 거친 뒤에 파싱한다.
문제는 세 가지로 모인다.
1. **깨끗한 체크아웃에서 게이트가 깨진다.** 생성 파일을 만드는 단계가 dev/build/test/CI 어디에도 없다.
2. **버그가 모듈과 모듈이 이어지는 지점에 몰려 있다.** 모듈 하나하나는 테스트가 있지만, 연결 부분은 테스트가 없다.
3. **같은 로직이 여러 벌로 복사되어 규칙이 서로 다르다.** 한 곳을 고쳐도 다른 복사본은 그대로 남는다.
## 2. 검토 방법과 표기
```text
src/ 8.7만 줄 → 9개 영역으로 분할 → 리뷰 에이전트 9개가 병렬로 읽음
→ 오케스트레이터가 주요 12건을 코드에서 직접 재확인 → 게이트 직접 실행
```
| 영역 | 경로 | 규모 |
|---|---|---|
| 1 | `src/adapters/browser-transfer/` | 약 12.8k줄 |
| 2 | `src/adapters/browser-files/`, `cache-storage/`, `cross-context-invalidation/` | 약 8k줄 |
| 3 | `src/adapters/http/`, `browser-rpc/`, `query-cache/`, `auth/`, `diagnostics/`, `telemetry/` | 약 8.2k줄 |
| 4 | `src/adapters/realtime/` | 약 10.3k줄 |
| 5 | `src/adapters/storage/`, `platform/`, `browser-file-storage/` | 약 14.9k줄 |
| 6 | `src/adapters/web-push/`, `service-worker/` | 약 5.9k줄 |
| 7 | `src/contracts/` | 약 8.3k줄 |
| 8 | `src/presentation/` | 약 7.8k줄 |
| 9 | `src/application/`, `features/`, `bootstrap/`, `platform/`, `apps/`, `contexts/` | 약 10.6k줄 |
리뷰 전제 (소유자 결정, `refactor-direction-decisions` 참조):
- 이 레포는 템플릿이다. 레포 안에서 쓰는 곳이 없는 코드나 빈 레지스트리는 다운스트림용 seam이므로 "죽은 코드"로 보지 않았다. 다만 갈라진 중복 복사본은 문제로 봤다.
- adapter 배럴(`index.ts`)은 공개 경계다.
- adapter는 다른 concrete adapter를 import할 수 없다. 예외는 `src/adapters/platform/`(폴더 전체), `src/adapters/browser-file-storage/result.ts`, `src/adapters/cross-context-invalidation/index.ts`다.
표기:
- **심각도**: 긴급(데이터 손실·보안 구멍·기능 고장) / 필수(실제 버그 또는 고쳐야 할 구조 문제) / 권장 / 사소
- **확신도**: 확인됨(코드 경로를 따라가 반드시 일어남을 확인) / 가능성(조건에 따라 일어남. 확인 방법을 적음)
- **✓ 재확인**: 오케스트레이터가 코드를 직접 다시 읽어 확인한 항목. 나머지는 에이전트 보고이고, 일부는 에이전트가 레포 밖 scratchpad의 node 스크립트로 재현했다.
## 3. 게이트 실행 결과
깨끗한 체크아웃(`e59994a`, `src/.generated/` 없음):
| 게이트 | 결과 |
|---|---|
| `corepack pnpm check:architecture` | 실패 — `ERR_MODULE_NOT_FOUND: src/.generated/product-feature-index.ts` |
| `corepack pnpm check:types:app` | 실패 — TS 에러 20개 |
| `corepack pnpm lint` | 통과 |
| `corepack pnpm test:unit` | 실패 — 131개 파일 중 18개 실패 |
| `corepack pnpm test:component` | 실패 — 25개 파일 중 13개 실패 |
| `corepack pnpm verify:documentation` | 실패 — 같은 `ERR_MODULE_NOT_FOUND` |
`node scripts/generate-product-feature-index.ts` 실행 후:
| 게이트 | 결과 |
|---|---|
| `check:architecture` | 통과 |
| `check:types:app` | 통과 |
| `test:unit` | 통과 — 1779/1779 |
| `test:component` | 통과 — 132/132 |
| `verify:documentation` | `PASS_SCOPED` |
생성한 `src/.generated/`는 확인 뒤 다시 지웠다. `dev`와 `build`는 실행하지 않았다. 두 명령 모두 같은 import를 거치므로 실패할 것으로 보인다.
## 4. 먼저 고칠 것
| 순위 | 항목 | 위치 | 섹션 |
|---|---|---|---|
| 1 | 깨끗한 체크아웃에서 게이트 실패 | `src/features/installed-product-manifest.ts:4` | 6.0 |
| 2 | 경로 값 `..`가 다른 엔드포인트로 요청을 보냄 | `src/adapters/http/http-contract-bridge.ts:191` | 6.3-1 |
| 3 | 로그아웃 해제 실패 뒤 새 계정이 opt-in 없이 push 등록됨 | `src/adapters/web-push/push-subscription-adapter.ts:345` | 6.6-7 |
| 4 | 파티션 purge가 손상 행 1개에 영구히 막힘 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2584` | 6.5-4 |
| 5 | 멱등 키 앞뒤 공백이 잘려 두 명령이 같은 키가 됨 | `src/contracts/mutation-intent.ts:34` | 6.7-1 |
| 6 | 롤링 배포 중 부트 reload 무한 반복 | `src/platform/release/release-mismatch-recovery.ts:59` | 6.9-1 |
| 7 | 킬스위치 기능 ID에 금지어가 있으면 부팅 실패 | `src/contracts/env.ts:80` | 6.7-2 |
| 8 | WS/SSE가 네트워크 끊김·서버 재시작 뒤 재연결 안 함 | `src/adapters/realtime/reconnect-coordinator.ts:1661` | 6.4-2 |
| 9 | 빌드가 다른 탭이 있으면 SW 활성화가 항상 30초 타임아웃 | `src/adapters/service-worker/service-worker-lifecycle.ts:368` | 6.6-2 |
| 10 | 세션 알림마다 캐시 전체 비움 + 앱 트리 remount | `src/adapters/query-cache/server-state-scope-runtime.ts:90` | 6.3-2, 6.8-3 |
## 5. 영역을 가로지르는 패턴
### 5.1 갈라진 복사본
같은 개념이 여러 벌 구현되어 있고 규칙이 서로 다르다. 한 벌만 고치면 나머지는 그대로 남는다.
| 개념 | 복사본 위치 | 차이 |
|---|---|---|
| abort/timeout race | browser-files(`download-delivery-adapter.ts:1032`, `browser-file-vault.ts:872`), realtime 6곳, browser-transfer runtime(`resumable-upload-runtime.ts:1299`) | kernel `src/adapters/platform/abortable-operation.ts`의 `createAbortableOperation`을 쓰지 않음. 일부는 늦게 도착한 자원을 닫지 않음 |
| opaque ID 정규식 | `resumable-upload/checkpoint-schema.ts:11`, `presigned/*`, web-push 3곳 | 첫 글자·길이 규칙이 다름 |
| exact-key 스냅샷 | contracts 6곳(`exact-snapshot.ts:66`, `read-only-registry.ts:54`, `browser-rpc.ts:399`, `realtime-streams.ts:529`, `cache-invalidation.ts:208`, `service-worker-static-manifest.ts:98`), realtime 3곳, web-push | enumerable·getter·Proxy 처리 수준이 다름. 두 곳은 우회 가능 |
| IndexedDB 저장 행 검증 | `indexeddb-runtime.ts`, `indexeddb-maintenance.ts`, `indexeddb-governance.ts` | 필드 추가 시 한쪽만 고치면 정상 행이 손상으로 판정됨 |
| OPFS prepared-object 검증 | worker, journal, client | 정책 변경 시 기존 객체가 읽히지 않음 |
| 텔레메트리 전송기 | `src/adapters/telemetry/best-effort-telemetry.ts`, `feature-telemetry.ts`, `src/platform/telemetry/telemetry-pipeline.ts` | rate limit 합산 40/분, credentials 설정·body 스키마가 다름 |
| "한 번만 reload" 가드 | `src/application/use-cases/decide-chunk-recovery.ts`, `src/platform/release/release-mismatch-recovery.ts` | 키 형식·TTL·마커 삭제 규칙이 다름 |
| operationId 형식 | `telemetry.ts:111`, `external-contract-runtime.ts:237`, `api-operations.ts:54`, `browser-rpc.ts:185` | 텔레메트리 규칙이 가장 엄격해서 실패 이벤트가 드롭됨 |
| 자격증명 헤더 검증 | `http-contract-bridge.ts:83`, `http-execution-v3.ts:1100`, `auth/external-session-adapter.ts:37` | CR/LF만 막음. 길이를 UTF-16과 UTF-8로 따로 셈 |
수렴할 곳은 이미 있다. adapter 공용 로직은 `src/adapters/platform/`(규칙 변경 불필요), 공유 어휘는 `src/contracts/exact-snapshot.ts`와 `read-only-registry.ts`다.
### 5.2 테스트가 없는 연결 지점
모듈 단위 테스트는 각자의 동작을 고정한다. 그런데 연결된 두 모듈이 서로 다른 약속을 하고 있다.
- 전송 계층 ↔ reconnect: 전송은 `PROVIDER_UNAVAILABLE retryable:true`를 보내는데 reconnect는 이를 종료로 처리한다 (6.4-2).
- event consumer ↔ stream coordinator ↔ 전송: barrier NONE 스트림이 recovery 한 번에 종료된다 (6.4-3).
- SW page controller ↔ worker: drain 요청과 응답의 필터가 서로 맞지 않는다 (6.6-1, 6.6-2).
- 세션 알림 ↔ scope fence ↔ presentation 트리: 알림마다 캐시 비움과 remount가 일어난다 (6.3-2, 6.8-3).
- cross-tab 수신 ↔ query-cache coordinator: GAP이 전체 무효화로 이어진다 (6.2-2).
### 5.3 텔레메트리
영역 3과 9에서 같이 나왔다. occurrences가 항상 1이다 (6.9-2). 리댁션이 문자열 시작 부분만 검사한다 (6.9-3). camelCase operationId의 API 실패 이벤트가 드롭된다 (6.7-5). best-effort fetch에는 타임아웃이 없다 (6.3-10).
## 6. 영역별 발견
### 6.0 공통 — 깨끗한 체크아웃에서 게이트 실패
**[긴급·확인됨 ✓]**
- 위치: `src/features/installed-product-manifest.ts:4`
- 문제: 이 파일이 `../.generated/product-feature-index.ts`를 import한다. `.gitignore:4`가 `.generated/`를 제외하므로 이 파일은 커밋되지 않는다. 생성 명령은 `generate:feature-index`(`scripts/generate-product-feature-index.ts`)인데, `dev`/`build`(`scripts/build-frontend.ts`)/`check:*`/`test:*` 스크립트, `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, README 어디에도 이 명령을 먼저 실행하는 단계가 없다.
- 시나리오: 레포를 새로 clone한 사람이나 CI는 아키텍처 검사, 타입체크, 단위·컴포넌트 테스트를 모두 실패한다(3장 참조).
- 도입 시점: `6f6c48e`(도메인 확장 리팩터링).
- 수정 방향: `generate:feature-index`를 `pre*` 스크립트나 각 게이트 앞에 붙이고, CI 게이트에 `check:feature-index`를 추가한다. 또는 생성물을 커밋하고 `check:feature-index`로 최신 여부만 검사한다.
### 6.1 browser-transfer (`src/adapters/browser-transfer/`)
요약: 보안 경계는 탄탄하다(vault 식별자, 1회용 replay guard, redirect/credential 차단, 스트리밍 SHA-256, 이미지 헤더 bounds check). 결함은 resumable upload의 수명 관리, 정책 처리, 실패 분류, 그리고 계층 간 ID 규칙 불일치에 몰려 있다.
1. **[필수·확인됨 ✓] `dispose()` 결과가 캐시되어 한 번 실패하면 영구히 CLOSING**
- 위치: `resumable-upload/resumable-upload-runtime.ts:331`, `:363-369`
- 문제: `drain ??= (async () => …)()`가 cleanup deadline을 넘기면 `UNAVAILABLE, retryable:true`를 반환하고 그 promise를 계속 들고 있다. 뒤에서 `quiescent`가 결국 `"DRAINED"`가 되어도 기다리는 쪽이 없다. 그래서 `checkpoints.close()`와 `lifecycle = "CLOSED"`가 실행되지 않는다.
- 시나리오: provider가 느려 첫 `dispose()`가 EXPIRED로 끝남 → 몇 초 뒤 작업은 모두 끝남 → 호출자가 retryable을 믿고 다시 `dispose()` → 같은 실패가 그대로 돌아옴. IDB 연결도 열린 채 남는다.
- 수정 방향: EXPIRED일 때 `drain = null`로 되돌리거나, `quiescent.then`으로 늦게라도 store를 닫고 CLOSED로 전환한다.
- 테스트: `tests/unit/resumable-upload-runtime-teardown.test.ts`는 첫 실패만 확인한다. 재호출 시나리오는 없다.
2. **[필수·불일치는 확인됨, 실제 발생은 가능성] opaque ID 문법이 계층마다 다름**
- 위치: `resumable-upload/checkpoint-schema.ts:11`, `presigned/presigned-capability-http-provider.ts:38`, `:380-383`, `presigned/presigned-transfer-executor.ts:1213-1223`
- 문제: control plane은 `/^[A-Za-z0-9_-]{8,512}$/`를 받고, presigned 계층은 `/^[a-z0-9][a-z0-9._:-]{0,255}$/i`로 다시 검사한다. presigned 쪽은 `-`/`_`로 시작하는 ID와 256자를 넘는 ID를 거부한다.
- 시나리오: 서버가 base64url 랜덤 ID를 발급하면 약 3%가 `-`/`_`로 시작한다. 세션 생성과 checkpoint 저장은 통과하지만, 이후 part마다 `issueUploadPart`가 `INVALID_INPUT`(재시도 안 함)으로 실패한다. 같은 ACTIVE 세션을 재사용하므로 만료나 abort 전까지 계속 실패한다. complete에서 받은 resourceId를 `issueDownload`에 넘길 때도 같다.
- 수정 방향: ID 문법을 한 곳에 두고 provider와 executor가 import한다.
- 테스트: fixture는 안전한 ID만 쓴다.
3. **[필수·확인됨] 기본 정책에서 동시 업로드가 조용히 1로 줄어듦 (문서와 반대)**
- 위치: `resumable-upload/runtime-policy.ts:101-117`, `:140-141`, `resumable-upload-runtime.ts:806-819`
- 문제: 기본값에서 `maxInFlightBytes 20MiB / (partSize 5MiB × copyFactor 4) = 1`이라 `workerCount = min(3, …, 1) = 1`이다. `maxConcurrency: 3`은 효과가 없는데 createSession은 서버에 concurrency 3을 요청한다. `docs/architecture/presigned-transfer-and-image-cdn.md:257`은 `partSize × concurrency × copyFactor`가 한도를 넘으면 시작 전에 거절하라고 한다. 코드는 `partSize × copyFactor`만 검사하고 조용히 clamp한다. copyFactor 4는 part마다 방어적 복사가 4~5번 일어나서 필요하다(`presigned-upload-part-executor.ts:274`의 `Uint8Array.from`, executor `slice()` 등).
- 수정 방향: 정책 검증에 `maxConcurrency`를 곱해 문서대로 거절하거나 기본값을 맞춘다. 겹치는 복사는 하나로 줄인다.
- 테스트: 테스트는 항상 정책을 override해서 기본 정책의 실제 동시성은 검증하지 않는다.
4. **[필수·확인됨 ✓] 크기 초과 파일이 `LIMIT_EXCEEDED`가 아니라 `INVALID_INPUT`으로 보고됨**
- 위치: `resumable-upload-runtime.ts:1755-1761`, `:217-221`, `:385-392`
- 문제: `snapshotRequest`가 한도 초과에 TypeError를 던지고 `upload()`의 catch가 `INVALID_INPUT`으로 바꾼다. `executeUpload`의 `LIMIT_EXCEEDED` 분기는 같은 policy로 다시 검사하므로 실행될 수 없다.
- 시나리오: 6GB 파일을 올리면 UI가 "파일이 너무 큽니다" 대신 "잘못된 입력"을 받는다.
- 수정 방향: `snapshotRequest`에서 크기 검사를 빼고 `executeUpload` 분기를 살린다.
- 테스트: 없음.
5. **[권장·확인됨] 한 worker가 실패해도 다른 worker가 취소되지 않음**
- 위치: `resumable-upload-runtime.ts:820-865`
- 문제: `firstFailure`는 다음 루프에서만 확인한다. in-flight worker는 retry 횟수만큼 issue와 PUT을 반복한다(시도당 30초 timeout + backoff). 호출자는 최악의 경우 몇 분 뒤에 실패를 받는다.
- 수정 방향: transfer 단위 AbortController를 `request.signal`과 합치고 `firstFailure` 설정 시 abort한다.
- 테스트: 없음.
6. **[권장·가능성] 손상되었거나 모르는 schema의 checkpoint 행이 upload와 abort를 모두 막음**
- 위치: `resumable-upload/indexeddb-checkpoint-store.ts:314-318`, `resumable-upload-runtime.ts:1149-1150`
- 시나리오: 같은 DB 버전에서 새 빌드가 schemaVersion 2 행을 씀 → 롤백 → 해당 uploadKey는 read와 abort가 모두 `CORRUPT_DATA`로 영구 실패. 복구하려면 partition 전체를 삭제해야 한다.
- 확인 방법: 새 schema 행을 넣고 abort를 호출한다.
- 수정 방향: abort 경로에 "해석할 수 없는 행은 revision을 무시하고 삭제" 분기를 두고 ORPHANED로 보고한다.
7. **[권장·가능성] image preset `fit: "inside"/"outside"` + PRIMARY_REQUIRED probe 조합에서 비율이 다른 asset이 모두 실패**
- 위치: `image-cdn/image-cdn-policy.ts:116-122`, `:468`, `image-cdn-runtime.ts:496-503`, `:1019-1020`, `browser-image-probe.ts:211-219`
- 문제: probe는 decode 크기가 `primary.pixelWidth × pixelHeight`와 정확히 같아야 통과한다. inside/outside는 원본 비율을 유지하므로 크기가 다르게 나와 `INTEGRITY_FAILED`가 된다. PRIVATE_SIGNED는 PRIMARY_REQUIRED가 강제라 이 조합을 쓸 수 없다.
- 확인 방법: 대상 CDN의 fit 의미를 확인한다. 테스트는 `fit: "cover"`만 쓴다.
- 수정 방향: PRIMARY_REQUIRED일 때 fit을 cover/contain/fill로 제한하거나, 예상 출력 크기를 계산해 비교한다.
8. **[권장·가능성] 이미지 probe가 EXIF/`irot` 회전을 고려하지 않음**
- 위치: `image-cdn/browser-image-probe.ts:51-53`, `:231-235`
- 문제: 헤더 파서는 회전 전 크기를 읽고, `createImageBitmap`은 기본으로 EXIF orientation을 적용한다. orientation 5~8 JPEG나 `irot` AVIF는 폭과 높이가 뒤바뀌어 거절된다(fail-closed라 보안 문제는 아님).
- 확인 방법: CDN이 출력에서 EXIF를 제거하는지 확인한다.
- 수정 방향: `createImageBitmap(blob, { imageOrientation: "none" })`.
9. **[권장·확인됨] presigned HTTP helper 중복과 동작 차이, 죽은 helper**
- 위치: `presigned/presigned-transfer-executor.ts:997-1178`, `presigned/presigned-capability-http-provider.ts:834-1032`, `resumable-upload-runtime.ts:1299-1349`
- 문제:
- `createAbortScope`, `readWithSignal`, `transferFailure`, `isAbortSignal`, `byteBucket`, `cancelBody`가 두 파일에 거의 그대로 있다.
- `statusFailure`의 401/403 recovery가 executor는 `REISSUE_CAPABILITY`, provider는 `NONE`이다.
- executor의 `compensateLateResponse`(`:1052`)는 호출하는 곳이 없다.
- download의 `Number(declaredLength)`(`:787`)는 `"1e3"`, `"0x10"`, `""`를 통과시킨다.
- runtime의 `invokeProviderAttempt`만 kernel `createAbortableOperation`을 쓰지 않는다.
- 수정 방향: `presigned/http-common.ts`로 모으고 runtime attempt를 kernel 위로 옮긴다.
10. **[권장·확인됨] `resumable-upload-runtime.ts` 2298줄**
- 위치: `resumable-upload-runtime.ts:1422-1705`, `:1772-2020`
- 문제: upload 흐름, retry/deadline, 서버 응답 검증, 의존성 snapshot 래퍼 8개가 한 파일에 있다. 검증과 snapshot만 분리해도 약 800줄이 줄어든다.
11. **[사소·확인됨] vault `register`가 snapshot 뒤에 원본 객체를 다시 읽음**
- 위치: `presigned/presigned-capability-vault.ts:279-287`
- 문제: 중복 receipt 검사는 `registration.capabilityReceipt`(원본)를 읽고 저장은 `snapshot.capabilityReceipt`로 한다. stateful issuer면 중복 검사를 우회할 수 있다. issuer가 내부 코드라 영향은 작다.
- 수정 방향: 세 곳 모두 `snapshot.capabilityReceipt`를 쓴다.
잘 된 점: presigned vault의 SSRF·capability 유출 방어(WeakMap 식별자, 1회용 replay guard, `redirect: "error"`, `credentials: "omit"`, 경로 이중 인코딩 차단). 이미지 헤더 파서의 bounds check와 P-256 서명 검증. adapter 간 import 규칙 준수.
### 6.2 browser-files / cache-storage / cross-context-invalidation
요약: 다운로드 abort 경로에서 Result 계약이 깨지고, cross-tab 무효화가 60초마다 전체 무효화로 떨어진다. 기본 cache 정책은 실제 CDN 응답을 거부하고, 조회 비용이 크다.
1. **[필수·확인됨] BOUNDED_OBJECT_URL + presigned source에서 open 실패 시 `deliver()`가 reject되고 lease가 샘**
- 위치: `src/adapters/browser-files/download-delivery-adapter.ts:733-743`
- 문제: `promptAndStream`은 `resolveByteSource`를 try/finally 안에서 부르지만 `boundedObjectUrlHandoff`는 try 밖에서 부른다. `resolveByteSource`는 `open()` 동기 throw(1085), open 중 abort(1095), `pendingOpen` reject 때 throw한다.
- 시나리오: 사용자가 취소 → `deliver()`가 `{ok:false, ABORTED}` 대신 AbortError로 reject된다. observer 기록도 없다. `closeHeldSource`가 호출되지 않아 늦게 온 lease는 `compensateLateSource`(1039)가 닫지 않는다.
- 수정 방향: `resolveByteSource`부터 try/finally로 감싸고 catch에서 `mapDownloadException`으로 Result를 반환한다.
- 테스트: 기존 테스트는 PROMPT_AND_STREAM만 쓴다.
2. **[필수·확인됨 ✓] sequence 기준점이 이벤트 TTL(60초)과 함께 삭제되어 60초 이상 쉰 뒤 이벤트가 매번 GAP**
- 위치: `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts:494-503`, `:544-554`
- 문제: watermark가 `expiresAt: event.expiresAt`로 저장되고 `pruneTracking`이 지운다. 다음 이벤트는 `!previous && event.sequence > 1`로 GAP이 된다. 받는 쪽 `src/adapters/query-cache/tanstack-cache-coordinator.ts:106-110`은 GAP이면 모든 topic을 무효화한다.
- 시나리오: 탭 A에서 몇 분에 한 번 수정할 때마다 탭 B가 모든 namespace의 active 쿼리를 다시 가져온다.
- 수정 방향: watermark 수명을 이벤트 TTL과 분리한다. 메모리는 이미 `sourceCapacity` LRU로 제한된다.
- 테스트: TTL 테스트(`tests/unit/cross-tab-invalidation.test.ts:618`)는 서로 다른 source에 seq 1만 보낸다.
3. **[필수·확인됨] storage fallback 탭이 다른 탭의 이벤트를 못 받는데 상태는 정상으로 표시됨**
- 위치: `browser-cross-context-invalidation.ts:349-373`
- 문제: broadcast 발행에 성공하면 storage pulse를 쓰지 않는다. `postMessage`가 한 번 실패한 탭은 `closeBroadcast()`(369)로 수신 listener까지 제거한다. 그 뒤로 다른 탭의 broadcast를 못 받는데 status는 `ACTIVE_STORAGE_FALLBACK`이다.
- 수정 방향: 발행 실패 시 송신만 storage로 바꾸고 수신은 유지한다. 또는 발행 쪽이 broadcast와 storage 모두에 쓴다(eventId dedupe 있음). 아니면 DEGRADED로 보고한다.
- 테스트: `tests/unit/cross-tab-invalidation.test.ts:463`은 발행 탭에 `failPost = true`를 걸어 문제 경로를 우회한다.
4. **[필수·확인됨(Web IDL 기준)] 브라우저 picker 함수를 options 객체에 bind함**
- 위치: `src/adapters/browser-files/browser-file-picker.ts:434-435`, `download-delivery-adapter.ts:225-229`
- 문제: `showOpenFilePicker.bind(options)`는 `this`를 options로 고정한다. Window operation은 `this`가 Window가 아니면 TypeError("Illegal invocation")를 던진다. `window.showOpenFilePicker`를 그대로 넘기면 매번 실패한다.
- 확인 방법: `window.showOpenFilePicker.call({}, {})`가 TypeError인지 본다. user gesture 없이 확인할 수 있다.
- 수정 방향: bind 없이 호출하거나 composition 단계에서 `window`에 bind한 host를 주입한다.
5. **[필수·코드 경로 확인됨, 전제는 실제 서버 동작] 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 전부 거부**
- 위치: `src/adapters/cache-storage/public-response-cache-adapter.ts:1299-1333`, `public-cache-policy.ts:69`
- 문제: `allowedVaryHeaderNames: []`라 Vary가 있으면 `POLICY_REJECTED`다. nginx `gzip_vary`와 대부분의 CDN이 JS/CSS에 이 헤더를 붙인다. `accept-encoding`은 브라우저가 Request에서 지우는 금지 헤더라 정책으로 풀기도 어렵다. `allowedResponseHeaderNames`에서 `content-type`을 빼면 activate가 항상 `INTEGRITY_FAILED`가 되는데 `assertPublicCachePolicy`가 이를 막지 않는다.
- 수정 방향: `accept-encoding`을 브라우저 관리 Vary로 따로 허용하고, `content-type` 필수 검사를 정책 검증에 추가한다.
- 테스트: `tests/browser-capabilities/public-cache-storage.spec.ts:106-125`는 Vary 없는 응답만 쓴다.
6. **[권장·확인됨] 캐시 조회 한 번의 비용이 큼**
- 위치: `public-response-cache-adapter.ts:1453`, `:263-319`, `:1540-1544`
- 문제: `matchActiveExact` 한 번에 `keys()` 2번, 2 MiB 버퍼 2개(총 4 MiB) 선할당, 최대 10k asset marker 전체 재검증과 SHA-256, 선형 탐색, 본문 SHA-256과 복사 3~4회가 일어난다. SW처럼 요청마다 조회하면 페이지 로드 한 번에 수백 MiB 할당이 생긴다.
- 수정 방향: JSON은 chunk를 모아 읽고, 검증된 marker를 `cacheName+manifestDigest`로 메모리 캐시하고, asset 탐색은 Map으로 바꾼다.
7. **[권장·가능성] kernel의 abort race를 손으로 다시 구현해 틈이 생김**
- 위치: `download-delivery-adapter.ts:1032-1050`, `:1482-1524`, `browser-file-vault.ts:872-891`
- 문제: `combineAbortSignals`(동일 복사본 2개), `awaitWithSignal`, `compensateLateSource`가 `src/adapters/platform/abortable-operation.ts:90`을 다시 구현한다. abort 직후 finally 전 몇 microtask 사이에 lease가 resolve되면 아무도 닫지 않는다. `awaitWithSignal(handle.createWritable(), signal)`(595)은 늦게 온 writable을 abort하지 않는다(Chrome `.crswap` 임시 파일).
- 수정 방향: kernel `race`와 compensate로 교체한다.
8. **[권장·가능성] native `cancel` 지원 브라우저에서도 focus fallback이 켜져 있어 느린 `change`가 버려짐**
- 위치: `src/adapters/browser-files/browser-file-picker.ts:301-317`
- 시나리오: Android 클라우드 provider처럼 파일을 받아온 뒤 change를 보내는 경우, 사용자가 파일을 골랐는데 "취소됨"으로 처리된다.
- 수정 방향: native `cancel`을 한 번이라도 관찰하면 fallback을 끈다.
- 테스트: `tests/unit/browser-file-picker.test.ts:215`는 grace 안에 도착하는 경우만 본다.
9. **[권장·확인됨] host factory가 조용히 `undefined`를 반환해 cross-tab 기능이 진단 없이 꺼짐**
- 위치: `src/adapters/cross-context-invalidation/browser-cross-context-host.ts:52-62`
- 시나리오: `RELEASE_ID`가 `1.2.3+sha.abc`, `feature/x`, `app@1.2.3`처럼 `+`, `/`, `@`를 포함하거나 120자를 넘으면 `cacheEpoch` 검사에 실패해 `undefined`가 반환된다. `RELEASE_ID` 자체는 빈 문자열만 아니면 통과한다(`src/contracts/deployment-admission.ts:95-106`).
- 수정 방향: 반환 전 `observe(OPEN, FAILED)`를 호출하고, epoch는 releaseId를 hash/인코딩해 만든다.
10. **[권장·확인됨] 파일명 자르기가 O(n²)이고 입력 길이 상한이 없음**
- 위치: `src/adapters/browser-files/file-policy.ts:357-362`
- 시나리오: 서버가 10만 자 파일명을 주면 약 10^10번 연산으로 탭이 멈춘다. deliver 한 번에 두 번 호출된다(`download-delivery-adapter.ts:318`, `:1003`).
- 수정 방향: 루프 전에 `maxUtf8Bytes`개 code point로 먼저 자른다.
11. **[권장·확인됨] 1000줄 넘는 파일 2개**
- `public-response-cache-adapter.ts`(1949줄): facade, 조회/stage/activate/cleanup, 매니페스트·marker 코덱(약 400줄), 응답 검증(약 200줄).
- `download-delivery-adapter.ts`(1528줄): 전략 3개, 입력 검증, abort 유틸.
12. **[사소·확인됨] 중복 helper와 죽은 분기**
- `MEDIA_TYPE` 정규식 3곳: `object-url-lease.ts:187`, `download-delivery-adapter.ts:137`, `browser-file-policy-registry.ts:84`.
- `safeOpaqueValue`(`browser-file-vault.ts:868`)와 `safeGeneratedToken`(`download-delivery-adapter.ts:1376`)이 같은 정규식이다.
- `object-url-lease.ts:112-118`의 안쪽 `if`는 바깥 조건과 반대라 실행되지 않는다.
잘 된 점: cross-context wire 이벤트의 파싱 검증(key 집합, 크기, epoch, topic 허용 목록, TTL). cache stage 경로의 abort 뒤 쓰기 차단과 교체본 검증 전 기존 candidate 보존. object URL의 단일 lease registry.
### 6.3 http / browser-rpc / query-cache / auth / diagnostics / telemetry
요약: V3 실행기의 자원 한도, 마감, abort 관리는 좋다. 문제는 URL 조립, 오류 분류, 자격증명 헤더 검증, 세션 변경 시 scope fence에 있다.
1. **[필수·확인됨 ✓] 경로 값 `.`/`..`가 URL 정규화로 다른 엔드포인트를 가리킴**
- 위치: `src/adapters/http/http-contract-bridge.ts:185-205`, `src/adapters/http/request-builder.ts:72-86`, `:106`
- 문제: `/`와 `\`만 막는다. `encodeURIComponent("..")`는 `..` 그대로이고 `new URL`이 상위 경로로 해석한다. 결과가 base 경로 아래라 `URL_ORIGIN_ESCAPED`도 통과한다.
- 시나리오: `/v1/projects/{p}/members/{m}`에 `m=".."` → `/v1/projects/p1/`. DELETE 명령이면 멤버가 아니라 프로젝트 쪽으로 요청이 간다. 레퍼런스 스키마 `resourceId: z.string().trim().min(1).max(120)`(`reference-schemas.ts:24`)는 `".."`를 통과시킨다. V2도 `base.pathname =` 대입에서 같은 정규화가 일어난다.
- 수정 방향: 값이 `"."`이나 `".."`이면 `PATH_VALUE_INVALID`로 거절한다. `src/contracts/release-artifacts.ts:37`에 같은 규칙이 있다.
- 테스트: `PATH_VALUE_INVALID`, `URL_ORIGIN_ESCAPED` 모두 없음.
2. **[필수·흐름은 확인됨, 무한 반복은 가능성] 세션 알림마다 무조건 scope fence + V3가 "요청 전 자격증명 없음"과 "서버 401"을 구분하지 못함**
- 위치: `src/adapters/query-cache/server-state-scope-runtime.ts:90-105`, `src/adapters/http/http-execution-v3.ts:709-712` / `1155-1163`, `src/adapters/auth/external-session-adapter.ts:111-114`, `:135`
- 문제: scope 런타임은 `session.subscribe` 알림마다 상태 비교 없이 generation을 올리고, 진행 중 요청을 abort하고, 캐시를 비운다. V3는 요청 전 `UNAUTHENTICATED`와 서버 401을 같은 결과로 돌려주고, 조합 루트(`src/bootstrap/runtime-adapters.ts:462`, `:520`)가 둘 다 `onUnauthenticated()`를 부른다. demo `setState`는 값이 같아도 알림을 보낸다.
- 시나리오: 로그아웃 상태에서 V3 쿼리 실행 → `onUnauthenticated` → 알림 → fence → 캐시 비움 → 쿼리 재마운트 → 반복 가능. `recovery-pending` 상태의 요청은 demo가 `"unauthenticated"`로 덮어 복구가 끊긴다. 외부 owner가 토큰 갱신 때도 알림을 보내면 갱신마다 캐시가 비워진다. presentation 쪽 영향은 6.8-3.
- 확인 방법: demo 모드, 로그아웃 상태에서 쿼리가 켜진 페이지를 열고 FENCED 이벤트 횟수를 센다.
- 수정 방향: (state, 식별자)가 바뀔 때만 fence한다. demo `setState`는 같은 값이면 알리지 않는다. V3의 요청 전 판정을 서버 401과 구분한다.
- 테스트: "상태가 그대로인 알림" 테스트 없음.
3. **[필수·확인됨] 게이트웨이 5xx(HTML/빈 바디)가 계약 위반으로 분류되어 status가 사라지고 "지원팀 문의, 재시도 불가"로 표시**
- 위치: `src/adapters/http/http-execution-v3.ts:1486-1510`, `:300-306`, `src/adapters/http/feature-http-binding.ts:356-362`, `:366-390`, `src/adapters/http/client.ts:858-869`
- 문제: nginx `text/html` 502는 재시도 후 `CONTRACT_VIOLATION{CONTENT_TYPE_MISMATCH}`, 빈 바디는 `PROBLEM_SCHEMA_INVALID`가 된다. metadata가 없어 `httpStatus`와 `http_status_group`이 빠진다. 바인딩을 거치면 `retryable:false`, `action:"contact-support"`다. V2는 content-type 검사가 status 검사보다 먼저이고 `retry-policy.ts:1`에 이 종류가 없어 재시도도 안 한다. 입력 검증 실패(`FINAL_REQUEST_INVARIANT_FAILED`)와 `MISSING_IDEMPOTENCY_KEY`도 기본값 `ENVELOPE_MISMATCH`로 떨어진다(`feature-http-binding.ts:388`).
- 수정 방향: 5xx/408/425에서 problem 바디가 유효하지 않으면 status를 담은 서버 장애로 끝낸다. 요청 쪽 위반은 `VALIDATION_REJECTED` 계열로 매핑한다.
- 테스트: 없음.
4. **[필수·확인됨] 자격증명 헤더 값 검증이 CR/LF만 막아, NUL/비 Latin-1 토큰이 "전송 후 네트워크 실패"로 분류됨**
- 위치: `src/adapters/http/http-contract-bridge.ts:83-90`, `http-execution-v3.ts:893-907`, `:927`, `src/adapters/auth/external-session-adapter.ts:37-46`
- 문제: `new Headers({authorization:"Bearer 한"})`는 TypeError, `fetch`는 reject된 Promise를 준다. V3는 `fetcher()`가 Promise를 반환한 시점에 `DISPATCHED`로 표시하므로 명령은 `MAYBE_APPLIED` + NETWORK_FAILURE, 쿼리는 재시도 예산만 쓴다. 검증기가 3벌이고, auth 어댑터는 대소문자만 다른 중복 헤더를 조용히 합친다. `decodeCredentialPatch`(`http-execution-v3.ts:1100-1106`)는 UTF-16 길이, bridge는 UTF-8 바이트로 잰다.
- 수정 방향: bridge 한 곳에서 제어문자 없는 ByteString을 검사하고, `checkFinalInvariants`에서 `new Headers(headers)`를 미리 만들어 본다.
- 테스트: `CREDENTIAL_HEADER_VALUE_INVALID` 테스트 없음.
5. **[필수·확인됨] feature 바인딩이 `mapSuccess`/`mapProblem` 예외를 잡지 않음**
- 위치: `src/adapters/http/feature-http-binding.ts:300`, `:311`
- 문제: V2(`client.ts:919-956`), `mapWithBoundaryRegistry`, RPC `mapResponse`는 try/catch로 감싸는데 여기만 없다. 매퍼가 던지면 `execute`가 reject되고, 서버가 `APPLIED_CONFIRMED`로 확정한 명령도 `normalizeUnknownFailure`를 거쳐 `MAYBE_APPLIED`가 된다(`src/presentation/adapters/query/application-query.ts:726-727`).
- 수정 방향: 두 호출을 감싸 `MAPPING_CONTRACT_VIOLATION`에 `effect: outcome.effect`를 실어 반환한다.
- 테스트: 없음.
6. **[권장·확인됨] 백오프 중 scope fence가 TIMEOUT으로 분류됨 + 종료 사유 판정이 6곳에 복사됨**
- 위치: `http-execution-v3.ts:941-950`, `:1031-1040`
- 문제: 재시도 sleep 중 로그아웃하면 `terminalCancellation === "SCOPE_FENCE"`인데 코드는 `"CALLER"`만 확인해 `TRANSPORT_FAILURE{TIMEOUT}`이 된다. 사용자에게 "시간 초과, 재시도"가 뜬다. 같은 판정이 679-692, 813-822, 915-927, 941-950, 986-998, 1031-1040에 따로 있고 scope 종료가 위치에 따라 세 가지 결과로 나온다. `execute()`는 약 620줄이다.
- 수정 방향: `terminalOutcomeFor(owner, phase)` 헬퍼로 모은다.
- 테스트: caller abort 중 sleep은 있음(`tests/unit/http-execution-v3.test.ts:687`), scope fence 중 sleep은 없음.
7. **[권장·코드 경로 확인됨, 영향은 분류기에 따라 가능성] 명령의 최종 effect가 누적 certainty와 합쳐지지 않음**
- 위치: `http-execution-v3.ts:1045`, `:1486-1497`, `:1579`
- 시나리오: IDEMPOTENT DELETE가 504(빈 바디, 실제로는 적용됨) → 재시도 → 404 → 분류기가 `NOT_APPLIED`로 판정하면 최종 결과가 "적용 안 됨, 재시도 가능"이 된다.
- 수정 방향: 명령이면 `finish` 직전 `joinMutationEffectCertainty(logical, attempt)`를 적용하거나, `MAYBE_APPLIED`면 retryHint를 false로 둔다.
- 테스트: 없음.
8. **[권장·확인됨] 무효화가 namespace별 refetch를 하나씩 기다림**
- 위치: `src/adapters/query-cache/tanstack-cache-coordinator.ts:79-89`
- 문제: TanStack 5의 `invalidateQueries`는 active refetch가 끝나야 resolve되는데 for 루프에서 순차 await한다. `lease.release()`도 이를 기다린다.
- 수정 방향: `Promise.allSettled`로 병렬 실행.
9. **[권장·가능성] Browser RPC 명령 경로에 effect certainty와 scope 확인이 없음**
- 위치: `src/adapters/browser-rpc/browser-rpc-runtime.ts:352-401`, `:424-435`, `:487-499`, `:1535-1574`
- 문제: `NON_REPLAYABLE`/`KEYED_COMMAND` unary가 전송 후 timeout/THREW/`UNAVAILABLE`이면 `retryable:true`, `action:"retry"`로 나간다. 재시도 전 generation을 확인하지 않아 로그아웃 뒤에도 이전 사용자 요청이 재전송될 수 있다. server stream은 소비자가 `return()`을 안 부르면 `RPC_STREAM_DRAINING`에 막힌다.
- 수정 방향: 전송 후 실패에 `effect: "MAYBE_APPLIED"`를 붙이고, 매 attempt 전 `safeIsCurrent`를 확인하고, abort 리스너에서 항목을 정리한다.
10. **[권장·확인됨] best-effort 텔레메트리 fetch에 타임아웃이 없고 전송기가 두 벌**
- 위치: `src/adapters/telemetry/best-effort-telemetry.ts:211-238`, `src/adapters/telemetry/feature-telemetry.ts:23-36`
- 문제: 수집기가 응답하지 않으면 `activeFlush`가 끝나지 않아 이후 flush가 모두 이 Promise를 받고, 큐가 차면 세션 동안 텔레메트리가 꺼진다. feature 쪽은 `credentials:"omit"`, best-effort 쪽은 기본값(same-origin)이라 쿠키가 같이 간다.
- 수정 방향: `AbortSignal.timeout(...)`을 걸고 `createFetchTelemetryTransport` 하나로 통일한다.
11. **[권장·확인됨] V2 관련 두 가지**
- 401 복구가 재시도 예산에 묶여 있다(`src/adapters/http/client.ts:339-344`). `MAX_RETRY_ATTEMPTS=0`이거나 503 → 401 순서면 복구 없이 로그아웃된다. `auth-recovery.test.ts`에 없음.
- "롤백 가능 seam" 문제가 알려진 것보다 넓다(`src/adapters/http/schema-registry.ts:12-16`). 슬롯 4개를 모두 주입해도 V2는 `{success,data,meta}` 봉투를, V3는 DTO 자체를 검증한다(`http-execution-v3.ts:1325`). 같은 백엔드로 V2로 되돌리면 모든 응답이 `ENVELOPE_MISMATCH`다.
12. **[권장/사소·확인됨] 기타**
- `src/adapters/query-cache/cursor-pagination-runtime.ts:111-114`: 페이지마다 누적 items 전체를 `JSON.stringify`(O(pages × 누적 크기)). `items.push(...page.items)`는 큰 페이지에서 RangeError로 reject된다.
- `browser-rpc-runtime.ts:1468`의 `validTransportFailure`는 쓰는 곳이 없고 RPC-RR-04 주석이 금지한 직접 속성 읽기를 한다. `decodeTransportFailure`와 중복이다.
- `src/adapters/query-cache/conditional-validator-store.ts:141-146`: 닫는 따옴표 없는 `W/"`를 유효 ETag로 받는다.
잘 된 점: V3의 모든 대기(자격증명, lease, fetch, 바디, 백오프)를 하나의 수명 signal과 경쟁시키고 늦은 응답의 바디를 취소한다. 바디는 선언 길이 → 스트림 누적 → JSON 구조 예산 순으로 제한한다. conditional validator 키를 튜플 `JSON.stringify`로 만들어 구분자 충돌을 막았다.
### 6.4 realtime (`src/adapters/realtime/`)
요약: 경계 검증과 상한은 꼼꼼하다. 문제는 모듈 연결 지점에 있다. 멈춘 effect와 recovery가 겹치고, WS/SSE가 끊김 뒤 재연결하지 않고, barrier NONE 스트림이 recovery 한 번에 종료된다. SSE 파서는 느리다.
1. **[필수·확인됨] recovery가 DRAINING effect와 동시에 실행되고 `recoveryRequired`를 해제함**
- 위치: `src/adapters/realtime/stream-coordinator.ts:707-721`
- 문제: DRAINING 검사는 진입 시점(`:666`)에만 있다. `await quiescence` 뒤에는 closed/abort/scope만 본다. 그 사이 effect가 timeout으로 DRAINING이 되어도 recovery가 authority를 호출하고 `:843`에서 커밋한다. 늦게 끝난 effect가 snapshot을 덮어쓸 수 있다(RT-RR-01/02가 막으려던 상황).
- 재현: `recover(SEQUENCE_GAP) called; effectStillRunning=true` → `hasResumeState:true` → `late effect settled`.
- 수정 방향: `await quiescence` 직후 `state.lifecycle === "DRAINING"`이면 실패를 반환한다.
- 테스트: 없음(`:503`은 협조적 apply, `:1282`는 scheduler 고장만).
2. **[필수·확인됨 ✓] 네트워크 끊김, 서버 재시작, 502/504 뒤 재연결하지 않음**
- 위치: `src/adapters/realtime/reconnect-coordinator.ts:1661-1671`
- 문제: `reconnectable()`은 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`에 `serverNotBeforeMs`가 없으면 `retryable:true`여도 false를 반환한다. 전송 계층은 hint 없이 이 값을 보낸다: WS `RESTART`/`NETWORK_LOST`(1006/1001/1012, `websocket/websocket-connection.ts:1923-1930`), error 이벤트(`:429-443`), SSE 502/504(`sse/fetch-sse-connection.ts:588-590`). WS에는 Retry-After가 없어 hint가 생길 수 없다. 결과적으로 WS는 IDLE_TIMEOUT, CONNECT_TIMEOUT, OFFLINE일 때만 재연결한다. 설계 문서(`docs/architecture/realtime-events-web-push-and-bounded-polling.md:1008`, `:1150-1156`)는 이들을 bounded reconnect로 정의한다. polling도 같은 규칙이다(`polling/bounded-poll-coordinator.ts:344-351`).
- 수정 방향: "hint 필수" 조건을 빼고 `retryable`만 본다. 전송 계층은 hint가 필요한데 없으면 이미 `retryable:false`를 보낸다(SSE `:573-587`, WS OVERLOADED `:1931-1937`).
- 테스트: 양쪽 동작이 각각 고정되어 있다(`realtime-reconnect-coordinator.test.ts:308-331`, `websocket-connection.test.ts:930-957`). 둘을 잇는 통합 테스트는 없다.
3. **[필수·확인됨] barrier NONE 스트림이 recovery 한 번으로 PROTOCOL_MISMATCH 종료**
- 위치: `src/adapters/realtime/event-consumer.ts:181-194`
- 문제: consumer는 모든 `RECOVERED`를 `RECOVERY_COMMITTED`로 넘긴다. SNAPSHOT_ONLY + barrier NONE 스트림은 barrier를 기다리지 않는다(`stream-coordinator.ts:844-848`). 전송이 연결을 닫고 → reconnect가 `confirmTransportBarrier` 호출(`reconnect-coordinator.ts:769-803`) → `stream-coordinator.ts:986-994`가 PROTOCOL_MISMATCH를 반환하고 종료된다.
- 재현: gap 이벤트 → `RECOVERY_COMMITTED` → `confirmTransportBarrier: PROTOCOL_MISMATCH`.
- 수정 방향: barrier가 필요 없는 recovery는 `CONTINUE`로 넘긴다. disposition에 barrier 필요 여부를 싣는다.
- 테스트: `event-consumer.test.ts`는 accept를 mock해서 이 조합을 못 본다.
4. **[필수·확인됨] SSE 파서가 문자마다 `TextEncoder.encode`를 호출해 250KB chunk에 120~170ms**
- 위치: `src/adapters/realtime/sse/sse-parser.ts:166-167`
- 측정: 250KB chunk 121~169ms(약 2MB/s). 같은 데이터를 `split`으로 처리하면 1.3ms.
- 문제: 메인 스레드 코드라 재연결 직후 replay 같은 몰아치는 수신이 long task가 된다.
- 수정 방향: `indexOf`로 줄바꿈을 찾아 `slice`하고 UTF-8 길이는 코드포인트 범위로 계산하거나 줄마다 한 번만 센다.
- 테스트: 성능 테스트 없음.
5. **[권장·가능성] `maxItemsPerChunk`(256)를 넘으면 non-retryable QUEUE_OVERFLOW로 종료**
- 위치: `sse/sse-parser.ts:282-294`, `fetch-sse-connection.ts:437-441`
- 재현: 333바이트 이벤트 300개(104KB) chunk 하나 → `QUEUE_OVERFLOW retryable:false`.
- 문제: 메모리는 `maxChunkBytes`가 이미 막는다. 이 상한은 정상적인 몰아치기 수신만 죽인다.
- 확인 방법: replay 중 실제 reader chunk 크기를 측정한다.
- 수정 방향: 남은 텍스트를 다음 처리로 넘기거나 상한을 없앤다. COMMENT는 상수 객체를 재사용한다.
6. **[권장·확인됨] dedupe가 가득 차면 매번 전체 recovery, fingerprint로 원문 전체 저장**
- 위치: `stream-coordinator.ts:490-502`, `event-codec.ts:189`, `stream-coordinator.ts:1108-1126`
- 문제: 초당 3.4건 이상(2048건/600초)이 계속 오면 윈도우마다 snapshot 재수신과 재연결이 일어난다. fingerprint가 canonical envelope 전체(최대 64KB)라 4MB 한도가 빨리 찬다. `pruneDedupe`는 시간순 항목에서 `break` 대신 `continue`를 써서 매번 전부 훑는다. 주석끼리도 어긋난다(`:621` "eviction 금지", `:1681` "2,048 ID 또는 10분").
- 수정 방향: FIFO 제거, fingerprint는 해시로, prune에서 `break`.
7. **[권장·확인됨] heartbeat 한 번이면 재시도 예산이 초기화되어 불안정한 서버에 끝없이 재연결**
- 위치: `reconnect-coordinator.ts:950-961`, `:980-990`, `reconnect-policy.ts:135`
- 시나리오: 연결 후 `:` comment 하나 보내고 끊는 서버/프록시 → `attemptIndex`가 0에 머물고 대기가 [0, baseDelay)라 `maxAttempts`/`maxElapsed`에 도달하지 못한다. 여러 클라이언트가 동시에 몰린다.
- 수정 방향: 유효 신호가 있고 동시에 `stableOpenMs`가 지났을 때만 초기화한다.
8. **[권장·확인됨] 같은 로직의 복사본과 동작 차이**
- DataSnapshot 3벌: `result.ts:141`(`Object.hasOwn` + frozen 계산), `reconnect-coordinator.ts:1485`(`"value" in`), `polling/bounded-poll-coordinator.ts:789`(enumerable 검사 없음, null prototype 거부).
- abort/timeout race 6종: `fetch-sse-connection.ts:601`, `reconnect-coordinator.ts:1036`, `:1058`(전역 `setTimeout` 사용), `bounded-poll-coordinator.ts:563`, `:605`, `live-poll-handoff-coordinator.ts:673`, `:696`(본문 동일), `stream-coordinator.ts:204`, WS 인라인 2곳.
- 영역 밖: `json-member-scanner.ts`와 `web-push/push-codec.ts:211`(최상위 키만 검사). `reconnect-policy.ts:147`과 `http/retry-policy.ts:17`(http 쪽은 `" "`를 0ms로, `"1e3"`, `"1.5"`도 허용).
- 수정 방향: realtime 내부는 `result.ts`로, 여러 adapter 공용은 kernel로 올린다.
9. **[권장·확인됨] 거대 함수와 무시되는 파라미터**
- `reconnect-coordinator.ts:307-1016`: `run()` 약 700줄. 정리 코드 4줄이 약 15번 반복된다.
- `websocket/websocket-connection.ts:1987-2003`: `failure()`/`connectionFailure()`의 4번째 인자 `_recovery`를 무시한다. 호출부 41곳이 값을 넘기지만 효과가 없다.
- 수정 방향: `endAttempt()` 헬퍼, `_recovery`는 제거하거나 receipt에 싣는다.
10. **[권장·확인됨] probe 버퍼 상한이 현재 버퍼가 아니라 누적 수신량 기준**
- 위치: `src/adapters/realtime/live-poll-handoff-coordinator.ts:266-282`
- 문제: `acceptedEvents`/`acceptedBytes`가 drain(`:522-541`)에서 줄지 않는다. 활성화 중 누적 256건을 넘으면 `failClosed()`로 영구 CLOSED.
- 테스트: 없음.
11. **[사소]**
- `bounded-poll-coordinator.ts:284-289`: `execute` throw가 무조건 OFFLINE + `retryable:false` 종료(`:344-351`). 다른 곳의 OFFLINE은 retryable이다.
- `sse-parser.ts:56-59`, `:138-141`: BOM을 두 번 제거한다(스펙은 한 번).
- `event-codec.ts:104`, `:108`: 원문을 두 번 encode한다.
- `fetch-sse-connection.ts:308`: 이벤트마다 `new TextEncoder()`.
- `websocket-protocol.ts:472-484`: `exceedsUtf8ByteLimit` JSDoc이 `utf8ByteLength` 위에 붙어 있다.
잘 된 점: 신뢰할 수 없는 프레임 처리 순서(바이트 상한 → 중복 키 스캔 → `JSON.parse` → 정확한 키 검사 → freeze). 모든 queue/buffer/rate의 상한. generation/lease로 늦은 콜백 차단. 위험 경로 대부분의 단위 테스트(15개 파일).
### 6.5 storage / adapter kernel / browser-file-storage
요약: kernel(connection/transaction/abortable)과 Web Storage 코덱은 튼튼하다. OPFS GC가 멈추고, dedup 재사용 청크를 지울 수 있고, 전역 lock과 60초 RPC 타임아웃이 겹친다. IndexedDB purge는 손상 행 하나에 막히고, 저장 스키마 검증기가 갈라져 있다.
1. **[필수·확인됨 ✓] OPFS orphan GC가 앞쪽 100개에서 더 나아가지 못함**
- 위치: `src/adapters/storage/opfs/opfs-worker-runtime.ts:995-1022`, `opfs-byte-store-adapter.ts:1099-1158`
- 문제: worker의 `listOrphanCandidates`는 참조 여부를 모르고 "staging에 없고 24시간 넘은 청크"를 디렉터리 순서로 최대 100개 준다. 커밋된 청크도 포함된다. coordinator는 참조 중이면 건너뛴다. 프로토콜에 이어 볼 커서가 없다(`opfs-worker-protocol.ts:119`).
- 시나리오: 하루 넘은 커밋 청크가 100개를 넘으면 매번 같은 100개(전부 참조 중)만 받는다. 뒤에 있는 진짜 orphan은 지워지지 않고 쿼터가 샌다. 상태는 `DEADLINE_REACHED`로 보고된다.
- 수정 방향: `LIST_ORPHAN_CANDIDATES`에 `afterDigest` 커서를 추가한다.
- 테스트: `tests/unit/opfs-worker-runtime.test.ts:428`은 청크 1개만.
2. **[필수·가능성] dedup으로 재사용한 오래된 청크를 GC가 지워 커밋된 객체 손실**
- 위치: `opfs-worker-runtime.ts:1197-1211`, `:1059-1063`, `opfs-byte-store-adapter.ts:1127-1141`
- 문제: `writeImmutableChunk`는 같은 digest가 있으면 바로 `return`해 `lastModified`가 갱신되지 않는다. 참조 확인(메인 스레드 IDB)과 삭제(worker)가 원자적이지 않다.
- 시나리오(탭 2개): 참조 0인 오래된 청크 D → 탭1 reconcile이 `isChunkReferenced(D)=false` 읽음 → 탭2가 같은 파일 재업로드, D 재사용, refcount 1, staging 삭제 → 탭1의 `DELETE_ORPHAN_CHUNK`가 D 삭제 → 그 객체를 열면 `INTEGRITY_FAILED`.
- 발생 조건: 같은 탭에서는 lock FIFO가 막는다. 여러 탭에서 스레드가 지연될 때만 열린다.
- 수정 방향: dedup hit 때 mtime을 갱신한다.
- 테스트: 없음.
3. **[필수·확인됨] origin 전체 lock을 업로드 내내 잡음 + 60초 RPC 타임아웃 → 동시 업로드 실패**
- 위치: `opfs-worker-runtime.ts:362`, `:538-541`, `opfs-policy.ts:47`, `:51`, `opfs-worker-client.ts:170-176`
- 문제: `beginPut`이 공용 Web Lock(`ca-frontend-opfs-v1:mutation`)을 FINISH/ABORT까지 잡는다. 다른 BEGIN_PUT, REMOVE_OBJECT, FINALIZE_PUT, GC가 기다리고 각 RPC는 60초 타임아웃이다.
- 시나리오: 2GiB 파일 A와 작은 파일 B를 동시에 put → A가 60초를 넘기면 B는 `UNAVAILABLE`(`opfs-worker-client.ts:612-616`). 같은 시간 remove는 logical delete만 커밋되고 DEGRADED. journal 행이 COMMITTED로 남아 같은 objectId 재업로드가 reconcile 전까지 CONFLICT.
- 수정 방향: lock을 objectId/scope 단위로 좁히거나 page 쪽 put 큐를 둔다. 최소한 한계를 주석과 문서로 명시한다.
- 테스트: worker 테스트는 배타적이지 않은 `immediateLeases`(`tests/unit/opfs-worker-runtime.test.ts:202`)를 써서 경합을 보지 않는다.
4. **[필수·확인됨] IndexedDB 파티션 purge(LOGOUT/ACCOUNT_DELETION/SESSION_END)가 손상 행 하나에 영구히 막힘**
- 위치: `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2584-2619`, `:2485-2531`, `:2533-2582`
- 문제: purge가 지울 행까지 `isStoredRecord` 등으로 검증하고 budget 카운터도 확인한다. 하나라도 어긋나면 `CORRUPT_DATA`로 트랜잭션이 abort되고 다음 batch도 처음부터 다시 시작한다. `deleteDatabase` 같은 우회 경로가 없다.
- 시나리오: sidecar 없는 record 1개나 budget 카운터 1 차이로 계정 삭제가 매번 실패하고 개인 데이터가 기기에 남는다.
- 수정 방향: 파티션 purge는 값 검증 없이 key로 지우고 COMPLETE 때 budget을 0으로 리셋한다. 손상은 observe로만 보고한다.
- 테스트: 손상 행 테스트는 RETENTION_SWEEP에만 있다(`tests/unit/indexeddb-runtime.test.ts:1035`).
5. **[필수·확인됨] prepared-object 검증기 3벌 → OPFS 정책을 바꾸면 기존 객체를 못 읽음**
- 위치: `opfs-worker-runtime.ts:1687-1783`(`:1739`), `indexeddb-opfs-journal.ts:1624-1720`, `opfs-worker-client.ts:664-677`
- 문제: journal은 `chunkSizeBytes >= 1`만, worker는 현재 정책값과 정확히 같아야 통과, client는 얕은 검사만 한다. `isSupportedPhysicalSchema` 3벌(`client:646`, `worker:1677`, `journal:1614`), `stableJson` 2벌(NaN 처리 다름: `worker:1648` throw, `journal:1722` `"null"`).
- 시나리오: `chunkSizeBytes`를 4MiB → 8MiB로 바꾸면(`opfs-policy.ts:77-79` 허용 범위) 기존 객체 전부 `INTEGRITY_FAILED`, FILES_READY reconcile은 `CORRUPT_DATA`, COMMITTED reconcile은 `INVALID_INPUT`으로 계속 실패.
- 수정 방향: 검증기를 한 모듈로 합치고, 저장된 객체는 manifest의 `chunkSizeBytes`로 검증한다. 정책값은 새로 쓰는 데이터에만 적용한다.
6. **[권장·확인됨, 타임아웃은 가능성] `openObject`가 객체 전체를 두 번 읽고 두 번 해시함**
- 위치: `opfs-worker-client.ts:335-347`, `opfs-worker-runtime.ts:691-735`, `:737-763`
- 문제: VERIFY_OBJECT가 모든 청크를 읽고 해시한 뒤 READ_CHUNK가 다시 읽고 해시한다. 2GiB 객체는 첫 바이트 전에 2GiB를 처리해야 하고, 60초 RPC 안에 못 끝나면 영영 열 수 없다.
- 수정 방향: 사전 검증은 manifest 대조만 하고 root digest는 스트림 끝에서 확인한다.
7. **[권장·확인됨] IndexedDB 저장 스키마 타입·검증기가 runtime/maintenance/governance에 복제됨**
- 위치: `indexeddb-runtime.ts:59-90`, `:225-303`, `indexeddb-maintenance.ts:40-79`, `:124-229`, `indexeddb-governance.ts:282-305`
- 문제: `Stored*` 타입, `isStored*`, 측정 공식, `countBucket`, `failureOf`가 두 파일에 있고 governance에 세 번째 budget 검사가 있다. 한쪽만 고치면 정상 행이 손상으로 판정된다(4번과 겹치면 purge도 막힘). runtime은 2744줄이고 CAS 하나(`:1647-1878`)가 콜백 10단 중첩이다.
- 수정 방향: `indexeddb-records.ts`로 모은다.
8. **[권장·확인됨] 삭제 후 재생성 시 revision/generation이 1로 돌아감 (ABA)**
- 위치: `indexeddb-runtime.ts:1693`, `:1955`, `opfs-byte-store-adapter.ts:204`
- 시나리오: 삭제 전에 revision 1을 읽은 writer가 `expectedRevision: 1`로 CAS하면 새 레코드를 덮어쓴다. OPFS도 `open({generation: 1})`이 다른 객체를 돌려줄 수 있다.
- 수정 방향: 마지막 revision을 tombstone으로 남기고 이어서 번호를 매긴다. 의도라면 port 주석에 명시한다.
9. **[사소·확인됨] 보상이 실패하면 put의 원래 실패 원인이 가려짐**
- 위치: `opfs-byte-store-adapter.ts:248-264`
- 시나리오: 사용자 취소(ABORTED)나 쿼터 초과에 ABORT_PUT 보상까지 실패하면 `CONFLICT`/`OBJECT_RECONCILE`만 받는다.
- 수정 방향: 원래 코드를 유지하고 recovery만 `RECONCILE`로 바꾼다.
10. **[사소·확인됨] kernel 계약의 작은 구멍 2개 (현재 걸리는 호출자 없음)**
- `src/adapters/platform/indexeddb-transaction.ts:246-277`: `succeed()` 뒤 `fail(x)`가 오면 x가 버려진다("first failure wins"와 다름).
- `src/adapters/platform/indexeddb-connection.ts:328-359`: caller abort가 upgrade보다 먼저 settle되어도 `onupgradeneeded`가 migration을 커밋한다.
- 수정 방향: `fail`이 성공 후보를 덮어쓰게 하고, `onupgradeneeded` 첫 줄에 `if (settled) { abortUpgrade(); return; }`.
잘 된 점: kernel이 settle-once, 늦은 연결 닫기, 리스너/타이머 정리를 한 곳에서 처리하며 예전 4벌 상태 기계를 대체했다. worker 응답 디코더가 accessor, 미정의 key, kind 불일치를 거절한다. 쿼리 페이지네이션이 "페이지 가득 참"과 "스캔 한도 도달"의 재개 지점을 구분한다.
### 6.6 web-push / service-worker
요약: 업데이트 활성화(페이지 ↔ 대기 워커 메시지)에 막히는 경로가 3개 있다. 첫 방문에 설치 중인 워커를 ACTIVE로 보고한다. Web Push는 입력 검증과 클릭 URL 제한이 튼튼하지만, logout 뒤 해제 실패 시 새 계정을 자동 등록한다.
1. **[필수·가능성(높음)] 활성화 성공 응답을 페이지가 PROTOCOL_MISMATCH로 처리**
- 위치: `src/adapters/service-worker/service-worker-page-controller.ts:334`
- 문제: 워커는 `skipWaiting()` 뒤에 `ACTIVATE_ACCEPTED`/`ACTIVATED_RELOAD_REQUIRED`를 보낸다(`service-worker-lifecycle.ts:292-305`). 이때 `registration.waiting`은 이미 `null`이다. 속성 갱신이 메시지보다 먼저 오면 `registration?.waiting !== waiting` 검사에 걸린다.
- 시나리오: 활성화는 확정됐는데 요청한 탭은 실패로 알고 새로고침하지 않는다. 옛 빌드 코드로 새 워커 아래에서 계속 돈다.
- 확인 방법: 실제 Chromium에서 두 빌드로 업데이트를 돌리는 Playwright 테스트.
- 수정 방향: 확정 이후 메시지는 `registration.active === waiting`도 허용하고, nonce/kind로 먼저 거른 뒤 source를 검사한다.
- 테스트: 성공 경로 테스트 없음. fixture가 `registration.waiting`을 바꾸지 않는다.
2. **[필수·확인됨 ✓] 다른 빌드 탭이 하나라도 있으면 활성화가 항상 30초 타임아웃**
- 위치: `service-worker-lifecycle.ts:364-370`, `:381-395`, `service-worker-page-controller.ts:209-215`
- 문제: 워커가 drain 요청을 `targetBuildId: requesterBuildId`로 보낸다. 페이지는 target이 자기 빌드가 아니면 `TARGET_BUILD_MISMATCH`로 버린다. 워커도 `sourceBuildId !== requesterBuildId` 응답을 무시한다.
- 시나리오: 배포 후 탭 A는 빌드 N, 새로고침한 탭 B는 N+1(navigation이 NETWORK_ONLY라 항상 이렇게 됨). B가 활성화를 요청하면 A가 답하지 않아 30초 뒤 `CLIENT_DRAIN_TIMEOUT`. 반대도 같다. Chrome이 얼린 백그라운드 탭도 활성화를 막는다.
- 수정 방향: requester 빌드 필터를 없애고 워커 자신의 buildId와 nonce로만 짝을 맞춘다.
- 테스트: 없음.
3. **[필수·확인됨] 요청하지 않은 탭은 활성화 뒤에도 새로고침하지 않고, 새 워커는 이전 캐시를 안 씀**
- 위치: `service-worker-page-controller.ts:242`, `service-worker-lifecycle.ts:194-199`, `:220-226`, `src/contracts/service-worker.ts:147-152`
- 문제: 모든 탭에 `ACTIVATED_RELOAD_REQUIRED`를 보내지만 일반 리스너는 `observe()`만 하고, `ServiceWorkerRuntimeHost`에 앱에 알릴 방법이 없다. 새 워커의 `onFetch`는 현재 캐시만 읽는다. 옛 빌드 lazy chunk는 네트워크로 가고 서버에서 지웠으면 ChunkLoadError. `onActivate`가 남긴 이전 캐시는 어디서도 읽지 않고, `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`:199`)는 아무 일도 안 한다. 6시간마다 `registration.update()`로 waiting이 생겨도 앱에 알리는 경로가 없다.
- 수정 방향: host 계약에 `onReloadRequired`/`onUpdateWaiting` 구독을 추가하고, current miss 때 marker로 찾은 previous 캐시를 fallback으로 읽는다.
4. **[필수·확인됨] 첫 방문에서 `start()`가 설치 중인 워커를 `ACTIVE`로 보고**
- 위치: `service-worker-page-controller.ts:183-197`
- 문제: `register()`는 `installing` 상태에서 resolve된다. 첫 방문에는 `active`/`waiting`이 `null`이라 `{kind:"ACTIVE"}`를 돌려준다. 설치가 실패해도(5번) 매 방문 ACTIVE를 보고한다.
- 수정 방향: `installing`이 있으면 `statechange`를 제한 시간 안에서 기다리거나, `!container.controller`면 `RELOAD_TO_ENABLE`/INSTALLING을 반환한다.
- 테스트: fixture가 `installing: null`로 고정.
5. **[필수·가능성] 흔한 서버 설정에서 static 설치가 항상 실패**
- 위치: `service-worker-static-assets.ts:250-256`, `:319-327`
- 문제: content-type을 정확 일치로 비교한다(`.js` → `text/javascript`). `application/javascript`로 응답하는 서버에서 `CONTENT_TYPE_INVALID`. `Content-Encoding: gzip/br` + `Content-Length`(압축 크기)를 압축 해제 크기와 비교해 `BYTES_MISMATCH`.
- 확인 방법: nginx gzip_static 또는 `application/javascript`로 dist를 서빙하고 install이 rejected 되는지 본다.
- 수정 방향: JS MIME 동의어 집합을 쓰고, `content-encoding`이 있으면 Content-Length 비교를 건너뛴다(크기는 스트림 바이트와 sha256으로 이미 검증).
6. **[필수·확인됨 ✓] fetch 핸들러가 모든 요청에 `respondWith` 호출 (성능)**
- 위치: `src/adapters/service-worker/service-worker-entry.ts:92-103`
- 문제: navigation, API, cross-origin까지 `onFetch → fetch(request)`를 거친다. `PWA_STATIC_ASSETS` 없이 WEB_PUSH만 선택해도 그렇다. navigation preload도 꺼져 있어 모든 이동과 API 호출이 "워커 부팅 → 네트워크"로 직렬화된다.
- 수정 방향: GET이고 navigate가 아니고 `runtime.manifestUrls.has(url)`일 때만 `respondWith`를 부른다.
- 테스트: 없음.
7. **[필수·확인됨] logout 뒤 native 구독이 남으면 `reconcile`이 새 계정을 opt-in 없이 자동 등록**
- 위치: `src/adapters/web-push/push-subscription-adapter.ts:345-354`, `:876-880`, `push-association-fence-store.ts:246-256`
- 시나리오: 오프라인 logout → `unsubscribe()` 실패 → fence는 REVOKED, native 구독은 살아 있음 → 사용자 B 부팅 → `reconcile(B)` → 서버 `ABSENT` → `registerAndActivate`. fence store도 REVOKED → 다른 epoch ACTIVE 전환을 허용한다. 설계 문서의 "새 account opt-in은 consent 재평가", "기존 association 재사용 금지"와 어긋난다. 이전에 연기한 WP-04와는 다른 문제다.
- 수정 방향: `ABSENT` 재등록은 local association이 ACTIVE였던 경우(크래시 복구)에만 하고, REVOKED/UNASSOCIATED면 native를 unsubscribe한다.
- 테스트: 없음.
8. **[권장·확인됨] asset 목록이 같은 두 워커 빌드에서 설치가 실패하면 현재 쓰는 캐시를 지움**
- 위치: `service-worker-static-assets.ts:126`, `:150-151`, `scripts/generate-service-worker-assets.ts:89-91`
- 문제: 캐시 이름이 asset 목록 digest로만 정해져 같은 `VITE_BUILD_ID`로 워커만 바뀐 빌드는 active 워커와 같은 캐시에 설치한다. 실패 시 `caches.delete(cacheName)`이 서빙 중인 캐시와 marker를 지운다.
- 수정 방향: 후보 캐시 이름이 active 캐시와 같으면 설치를 건너뛰거나 실패해도 지우지 않는다.
9. **[권장·확인됨] activate가 marker를 쓴 뒤에야 오래된 캐시를 지움**
- 위치: `service-worker-lifecycle.ts:171-198`
- 문제: 공간 부족으로 `currentCache.put(marker)`가 throw하면 삭제 루프가 실행되지 않는다. 공간이 영영 회복되지 않는다.
- 수정 방향: 삭제를 먼저 하고 marker 쓰기는 try/catch로 감싼다.
10. **[권장·확인됨] 활성화 대기 중 관련 없는 메시지로 PROTOCOL_MISMATCH + 페이지·워커 타임아웃 동일**
- 위치: `service-worker-page-controller.ts:317-337`, `:299`
- 문제: `SYNC_WAKE_OBSERVED`(`service-worker-entry.ts:161-166`)나 `CACHE_RESET_RESULT`가 오면 nonce/kind 확인 전에 source 검사에 걸려 실패한다. 두 deadline이 모두 `clientDrainMs`(30초)라 마지막 탭이 29초에 답하면 페이지는 TIMEOUT인데 워커는 `skipWaiting`까지 확정한다.
- 수정 방향: nonce/kind로 먼저 거르고, 페이지 deadline에 여유분을 더한다.
11. **[권장·가능성] push/알림 클릭을 거절할 때 사용자에게 아무것도 보여주지 않음**
- 위치: `src/adapters/web-push/inbound/push-event-adapter.ts:106-150`, `inbound/notification-click-adapter.ts:110-114`, `:163-170`
- 문제: EXPIRED, RELEASE_MISMATCH, fence 읽기 실패, deadline 초과가 알림 없이 끝난다. Chrome은 대신 "This site has been updated in the background"를 띄운다. Safari는 조용한 push가 반복되면 구독을 취소한다고 알려져 있다. 클릭도 `expiresAt`(최대 24시간) 초과나 fence 불일치면 창을 열지 않는다. drop 자체는 설계 의도다.
- 확인 방법: WebKit의 조용한 push 정책 문서 확인.
- 수정 방향: 계정 정보 없는 generic 알림 fallback, 클릭 실패 시 앱 루트 열기. 또는 트레이드오프를 문서에 명시한다.
12. **[사소·확인됨] web-push 중복 helper, 파일 비대, 버려지는 주입값**
- `base64UrlDecode` 2벌: `push-subscription-adapter.ts:1093`(`>>>`), `push-registration-gateway.ts:298`(`>>`), 끝 비트 검증 조건도 다르다.
- `OPAQUE_ID` 3벌: `push-codec.ts:11`, `push-association-fence-store.ts:19`, `push-registration-gateway.ts:9`.
- `validAuthority` 2벌: `push-association-fence-store.ts:668`, `push-registration-gateway.ts:247`(null 방어 없음 → TypeError).
- `push-subscription-adapter.ts` 1139줄.
- `service-worker-page-controller.ts:268`이 전역 `document`를 쓴다. `src/bootstrap/register-service-worker.ts:22`는 `host.document`를 받지만 넘기지 않는다.
- 수정 방향: `web-push/codec-primitives.ts`로 모은다.
잘 된 점: push payload에서 제목·본문·URL을 받지 않고 registry 고정 문구와 same-origin 경로만 쓴다. static 설치의 sha256 검증, 바이트 상한, all-or-nothing, deadline 뒤 정리. 캐시·등록 소유권 판정으로 남의 캐시를 지우는 경로가 없다.
### 6.7 contracts (`src/contracts/`)
요약: 입력 검증 함수 5개가 잘못된 값을 통과시킨다(멱등 키, 설정 키, 매니페스트 URL, REST 명령 메서드, operationId). 모두 에이전트가 node로 재현했다. 스냅샷·exact-key 로직이 모듈마다 달라 두 곳에서 불변식이 깨진다. 레이어 위반은 없고 1000줄 넘는 파일도 없다(최대 `browser-rpc.ts` 979줄).
1. **[필수·확인됨] 멱등 키 검증이 fetch가 잘라내거나 거부할 값을 통과시킴**
- 위치: `src/contracts/mutation-intent.ts:34`
- 문제: `trim()` 후 비어 있지 않은지와 C0/C1 제어문자만 검사한다. 주석은 "never trimmed"라고 한다.
- 시나리오 A: `" order-1 "`가 통과하고 `Headers.set`이 `order-1`로 잘라 보낸다. 서로 다른 두 명령이 같은 키를 갖고 두 번째는 재전송으로 처리되어 적용되지 않는다.
- 시나리오 B: `"키-값"`이 통과하고 `headers.set`이 ByteString TypeError를 던진다. `src/adapters/http/client.ts:772`의 catch가 `NETWORK_UNREACHABLE`(재시도 가능)로 바꾼다.
- 수정 방향: `^[\x21-\x7E]{1,256}$`로 제한한다(`realtime-events.ts:77` `HEADER_SAFE_CURSOR`와 같은 규칙).
- 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`이 `"키-값"`, `"ключ"`를 유효 키로 고정하고 있다. 함께 고쳐야 한다.
2. **[필수·확인됨 ✓] 설정 키 금지어 검사가 FEATURE_OVERRIDES 안의 기능 ID까지 걸러 킬스위치 사용 시 부팅 실패**
- 위치: `src/contracts/env.ts:73-89`
- 문제: `assertSafeConfigNames`가 중첩 객체 키까지 재귀 검사한다. FEATURE_OVERRIDES의 키는 설정 이름이 아니라 기능 ID(데이터)다. `release-artifacts.ts:67`의 기능 ID 정규식은 `cookie-consent`, `password-reset`, `token-wallet`을 허용한다.
- 시나리오: 장애 중 `{"FEATURE_OVERRIDES":{"cookie-consent":"DISABLED"}}`를 배포하면 `load-runtime-config.ts:110`에서 `CONFIG_SECRET_NAME_REJECTED`가 나고 앱 전체가 부팅되지 않는다.
- 수정 방향: 값을 키로 쓰는 맵은 재귀에서 빼거나, 그런 기능 ID를 빌드 시점에 거부한다.
- 테스트: 없음.
3. **[필수·확인됨] 릴리스 매니페스트 URL의 same-origin 검사를 탭 문자로 우회**
- 위치: `src/contracts/release-artifacts.ts:28`
- 문제: `//` 시작, `?`, `#`, `\`, `%2f`만 검사한다. WHATWG URL 파서는 탭/CR/LF를 지운다. `"/\t/evil.example/m.json"`이 통과해 `https://evil.example/m.json`이 된다. `/a/%2e%2e/b`도 통과 후 `/b`가 된다. 설정은 운영자가 관리해 원격 공격 경로는 아니지만 검증 약속이 깨져 있다.
- 수정 방향: `new URL(v, "https://x.invalid")`로 해석해 origin 유지와 `pathname === v`를 확인하거나, `^/[A-Za-z0-9._~/-]+$` 허용 목록.
- 테스트: `tests/runtime-schema/runtime-config.test.ts:49-54`는 `..`와 `?`만.
4. **[필수·확인됨] REST V2가 COMMAND를 GET으로 허용하고 CSRF 필요 여부는 메서드로만 판단**
- 위치: `src/contracts/api-operations.ts:182`, `src/contracts/rest-profiles.ts:240`
- 문제: `validateRestOperation`은 QUERY가 GET/HEAD인지만 보고, `semantics`/`replayPolicy` enum도 검증하지 않는다. `resolveRestSecurityProfiles`는 `unsafe`를 메서드로만 정한다. `{semantics:"COMMAND", method:"GET"}` + SAME_ORIGIN_COOKIE + csrf NONE이 통과한다. browser-rpc(`browser-rpc.ts:652-666`)와 V3(`external-contract-runtime.ts:448-469`)는 이 규칙을 강제한다. 지금 설치된 쿠키 프로필이 없어 잠재 결함이다.
- 수정 방향: COMMAND면 POST/PUT/PATCH/DELETE만 허용하고 enum을 검증한다.
- 테스트: 없음.
5. **[필수·확인됨] operationId 형식이 4곳에서 달라 API 실패 텔레메트리가 드롭됨**
- 위치: `src/contracts/telemetry.ts:111`, `src/contracts/external-contract-runtime.ts:237`
- 문제: V3 합성은 `^[A-Za-z][A-Za-z0-9_.-]{0,127}$`(camelCase 허용), 텔레메트리 `operation_id`는 `^[A-Z][A-Z0-9_]{0,63}$`다. `api.request.failed`가 `invalid-attribute-value`로 떨어지고 `best-effort-telemetry.ts:162`에서 drop된다. diagnostics `SAFE_VALUE`(`diagnostics.ts:123`)는 64자 제한이다. `api-operations.ts:54`, `browser-rpc.ts:185`는 `{2,79}`다. `http_status_group`도 diagnostics `[0-9]xx`, 텔레메트리 `[1-5]xx`로 다르다.
- 수정 방향: OPERATION_ID를 contracts에 하나만 두고 재사용한다.
6. **[권장·확인됨] 스냅샷 불변식이 모듈마다 달라 두 곳에서 뚫림**
- (a) `external-contract-runtime.ts:751` vs `:770`: TEMPLATE_FIXTURE의 이벤트 기여 금지 검사는 `.length`로, 설치는 iterator로 한다. 배열에 `Symbol.iterator`를 달면 길이 0으로 통과 후 이벤트가 설치된다. `exact-snapshot.ts:154`의 `snapshotExactArray`를 쓰지 않는다.
- (b) `realtime-streams.ts:529` `hasExactKeys`가 `Object.keys`만 봐서 getter를 허용하고, 검증과 `{...input}` 복사에서 두 번 읽는다(`:465-486`). getter로 `maxEventBytes` 999,999,999가 설치된다(하드 상한 65,536).
- exact-key 구현 6곳: `exact-snapshot.ts:66`, `read-only-registry.ts:54`(try/catch 없음), `browser-rpc.ts:399`(enumerable 미검사), `realtime-streams.ts:529`, `cache-invalidation.ts:208`, `service-worker-static-manifest.ts:98`.
- 입력이 컴파일 시점 코드라 권장으로 분류했다.
- 수정 방향: `exact-snapshot.ts`로 통일하고 배열 스냅샷을 추가한다.
- 테스트: `tests/unit/contract-registry-immutability.test.ts`는 객체 단위만.
7. **[권장·확인됨] 검증된 인덱스/레지스트리가 수정 가능한 상태로 반환됨**
- 위치: `src/contracts/query-invalidation.ts:185`, `:232`, `web-worker.ts:138`, `offline-command.ts:152`, `runtime-capabilities.ts:199`
- 문제: `Object.freeze({ namespacesForTopic: new Map(...) })`는 바깥만 얼린다. `.clear()`가 동작한다. 나머지는 바깥 배열만 얼려 내부 상한값 객체를 바꿀 수 있다. `read-only-registry.ts` 주석(LIVE-02)이 바로 이 버그를 설명한다.
- 수정 방향: `createReadOnlyRegistry`를 쓰고 각 row를 스냅샷해 얼린다.
8. **[권장·확인됨] 같은 개념이 두 모양: 검증기 프로토콜 2개, `MappingResult` 2개**
- `RuntimeValidator.safeParse`(`external-contract-runtime.ts:43-50`, path 배열) vs `RuntimeSchemaCodec.parse`(`schema-registry.ts:18-28`, path 문자열). reference feature가 zod 래퍼를 두 번 쓴다(`reference-feature-contract-contribution.ts:34`, `:88`).
- `MappingResult`: `boundary-mapper.ts:6` `{ok:false, code}` vs `external-contract-runtime.ts:84` `{ok:false, error:{kind, code}}`. 잘못 import해도 컴파일된다.
- 수정 방향: 각각 하나로 합친다.
9. **[권장·확인됨] 인증 프로필 기준 원본이 둘로 갈림**
- 위치: `external-contract-runtime.ts:337`, `rest-profiles.ts:235`
- 문제: 합성은 모듈 전역 `INSTALLED_REST_AUTH_PROFILES`, 실행기는 주입된 `dependencies.authProfiles`(`http-execution-v3.ts:413`)를 쓴다. V2 클라이언트는 검증 안 된 `REST_AUTH_PROFILES`를 직접 쓴다(`client.ts:565`). BEARER_HEADER + `credentials:"same-origin"`이 install에서는 거부되지만 resolve에서는 통과한다.
- 수정 방향: resolve가 `InstalledRestAuthProfiles`를 받게 하고 합성은 레지스트리를 매개변수로 받는다.
10. **[권장·확인됨] 배포 승인이 IPv6·사설 대역 호스트를 공개 주소로 봄**
- 위치: `src/contracts/deployment-admission.ts:139`
- 문제: `https://[::ffff:127.0.0.1]/`, `[fd00::1]`, `[fe80::1]`, `100.64.0.1`, `0.1.2.3`, `api.internal`이 production 승인을 받는다. 로컬 호스트 목록이 3곳에 따로 있다(`browser-rpc.ts:780`, `rest-profiles.ts`, 이 파일).
- 테스트: IPv4 사설 대역만(`tests/unit/deployment-admission.test.ts:67-68`).
11. **[사소·확인됨] 레지스트리 조회가 프로토타입 체인까지 내려감**
- `getApiOperation("constructor")`가 `Object` 함수를 반환(`api-operations.ts:203`).
- `getStorageDefinition("__proto__")`가 `Object.prototype`을 반환(`storage-keys.ts:162`).
- `isAllowedOfflineTransition`이 모르는 상태에 TypeError를 던짐(`offline-command.ts:102`). false가 맞다.
- 지금 호출자는 상수만 넘긴다. 수정: `Object.hasOwn`.
12. **[사소·확인됨] 조용한 통과와 자잘한 문제**
- `release-tokens.ts:62`: runtime 쪽 `assetManifestHash`를 release 자신의 값으로 채워 비교가 항상 일치한다. "비교 안 함"이 아니라 "통과"로 나온다.
- `contract-set.ts:119`: `expected`에 packageId 중복 + `expectedSetDigest` 없음이면 예외가 나서 Promise가 reject된다.
- `query-keys.ts:217`: 새 identity intern마다 전체 row 복사·정렬(O(n log n), n ≤ 4096).
- `.dependency-cruiser.json`은 contracts → presentation/bootstrap 방향을 막지 않는다(현재 위반은 없음).
잘 된 점: `contract-set-canonical.ts`의 정규화(길이 접두, UTF-8 바이트 정렬, 중복 거부). `realtime-events.ts`의 시퀀스(BigInt 상한)·타임스탬프 검증, `cache-invalidation.ts`의 크기·TTL·clock skew 제한. `read-only-registry.ts`의 Map 불변 처리.
### 6.8 presentation (`src/presentation/`)
요약: adapter 직접 import, `any`, `@ts-ignore`, `dangerouslySetInnerHTML`은 없다. 버그는 라우팅에 몰려 있다. React Router가 형제 라우트의 컴포넌트 인스턴스를 재사용하는 점, route-change 부수효과(포커스·제목·텔레메트리)의 위치에서 청크 복구 고착, 로케일 초기화, 포커스 버그가 나온다. 상태 화면과 세션 액션이 여러 벌이다.
1. **[필수·확인됨 ✓] 청크 복구 실패 화면이 다른 라우트로 이동해도 풀리지 않음**
- 위치: `src/presentation/boundaries/chunk-recovery-boundary.tsx:38-84`, `src/presentation/routes/app-router.tsx:316-326`
- 문제: React Router 7.18은 `RenderedRoute`에 key를 붙이지 않아 형제 라우트 이동 시 `ChunkRecoveryBoundary`까지 같은 인스턴스가 재사용된다. boundary에 resetKey/key가 없어 `error`/`support` 상태가 남는다. 실패 화면(`:109-114`)에 재시도·새로고침 버튼이 없다.
- 시나리오: 오프라인에서 아직 안 받은 `/examples/states`로 이동 → 청크 실패 → `manifest-unavailable`로 `support` → 메모리에 있는 홈으로 돌아가도 "화면 자산을 복구하지 못했습니다"가 계속 보인다. 브라우저 새로고침만이 탈출구다.
- 수정 방향: `<ChunkRecoveryBoundary key={definition.routeId} …>` 또는 resetKey + `componentDidUpdate`. 실패 화면에 `action.reloadOnce` 버튼.
- 테스트: `tests/component/chunk-recovery-boundary.test.tsx`에 리셋 케이스 없음.
2. **[필수·확인됨] Safari와 Vite CSS preload 실패를 청크 실패로 인식하지 못함**
- 위치: `chunk-recovery-boundary.tsx:27-36`
- 문제: 판별 문자열에 WebKit `"Importing a module script failed."`와 Vite `"Unable to preload CSS for …"`가 없다. Safari 사용자는 배포 뒤 옛 청크 요청 시 일반 렌더 오류로 분류되어 reload-once 복구가 실행되지 않는다.
- 수정 방향: 두 문자열을 추가하고, bootstrap에서 `vite:preloadError`도 받는다.
- 테스트: Chrome 메시지 하나만.
3. **[필수·확인됨] 로케일이 저장되지 않고 세션이 바뀔 때마다 ko-KR로 초기화**
- 위치: `src/presentation/i18n/locale-provider.tsx:76`, `:81`, `app-router.tsx:497`, `src/presentation/adapters/query/server-state-scope-provider.tsx:31-35`
- 문제: 로케일이 `useState`에만 있고 preferences 포트에 locale 항목이 없다(테마는 `preferences.setColorScheme`으로 저장됨). `LocaleProvider`는 `AppRouter` 안, `AppRouter`는 `ServerStateScopeProvider` 아래에 있다. 세션 알림 → scope `FENCED`(`server-state-scope-runtime.ts:90-104`) → transitionFallback 렌더로 앱 트리 전체 unmount → `READY`에서 `ko-KR`로 다시 mount된다.
- 시나리오: en-US를 고르고 로그인/로그아웃하면 한국어로 돌아간다.
- 같은 remount의 추가 영향: 작성 중 폼 입력이 dirty guard 없이 사라진다(가능성, auth owner의 알림 빈도에 따름). `AppRouter:489`의 `useMemo` browser router가 `dispose()`되지 않아 remount마다 popstate 리스너가 쌓인다.
- 수정 방향: locale을 preferences 포트로 저장하고, Locale/Theme provider를 scope fence 바깥(bootstrap)으로 올리고, unmount 시 `router.dispose()`.
- 테스트: `tests/e2e/i18n.spec.ts`, `tests/component/locale-platform.test.tsx`에 저장·세션 전환 케이스 없음.
4. **[필수·확인됨] 언어를 바꾸면 포커스 이동, 맨 위 스크롤, route 변경 재보고**
- 위치: `app-router.tsx:145-171`
- 문제: `RouteLifecycle` effect 의존성에 `message`/`resolve`가 있고, 이 둘이 locale 변경마다 새로 만들어진다(`locale-provider.tsx:108`). `docs/architecture/routing-pages-and-patterns.md:467`의 "locale 변경은 title과 copy만 다시 렌더" 계약과 어긋난다.
- 가능성: `location.key` 의존 때문에 해시만 바뀌는 이동(스킵 링크, `ErrorSummary`의 `#field`)에서도 다시 실행될 수 있다. 브라우저 확인 필요.
- 수정 방향: 제목 effect(locale 의존)와 포커스·스크롤·텔레메트리 effect(`pathname`+`search` 의존)를 나눈다.
- 테스트: 없음.
5. **[필수·확인됨] 인증필요·잘못된 주소·비활성 기능 화면에서 제목·포커스·텔레메트리가 동작하지 않음**
- 위치: `app-router.tsx:304-314`, `:316-335`
- 문제: `RouteLifecycle`이 `content` 안에만 있는데 `ProtectedRoute`, `InvalidRouteSurface`, `DisabledFeatureSurface`는 `content`를 렌더하지 않는다.
- 시나리오: 익명 상태에서 reference 라우트에 들어가면 `document.title`이 이전 페이지 그대로이고, 포커스가 NavLink에 남아 스크린리더 사용자는 페이지가 바뀐 것을 모른다. 텔레메트리도 빠진다.
- 수정 방향: `RouteLifecycle`을 `RegisteredRoute` 최상단으로 올린다.
6. **[필수·확인됨] 모바일 드로어로 이동하면 포커스가 햄버거 버튼으로 감**
- 위치: `src/presentation/layouts/app-shell.tsx:44-46`, `:153-161`, `src/presentation/design-system/primitives/core.tsx:374-391`
- 문제: 자식 effect `RouteLifecycle`이 `main.focus()`를 먼저 부르지만 modal이 열려 있어 main이 inert다. 부모 effect가 드로어를 닫고, `Dialog`가 `setTimeout`으로 `returnFocusRef`(메뉴 버튼)에 포커스를 복원한다. 데스크톱은 h1이 포커스를 받는다.
- 수정 방향: 네비게이션으로 닫힐 때는 포커스 복원을 끄거나, route 포커스를 dialog 닫힘 뒤로 미룬다.
- 테스트: `tests/e2e/app-shell.spec.ts`는 Escape 닫기만.
7. **[필수·확인됨] context 라우트 게이트웨이가 이전 context의 routes로 한 번 렌더되고 청크 실패 복구를 거치지 않음**
- 위치: `app-router.tsx:375-419`
- 문제 (a): `ContextRouteGateway`도 key 없이 재사용된다. context A → B 이동 첫 렌더에서 A의 routes로 B 경로를 매칭해 `NOT_FOUND`가 mount되고 텔레메트리·제목·포커스가 한 번 튄다. 지금은 context가 하나라 드러나지 않지만 하나 더 추가하면 바로 발생한다.
- 문제 (b): `loadRoutes()`의 dynamic import 실패 시 `RouteFailureSurface`만 보이고 `recoverChunk`(reload-once)를 거치지 않는다. 도메인 확장의 주 경로가 배포 직후 청크 실패 복구에서 빠져 있다.
- 수정 방향: `key={routeModule.id}` 또는 `{moduleId, routes}` 상태. 로드 실패는 `isChunkLoadFailure`로 판별해 `recoverChunk`로 넘긴다.
8. **[필수·확인됨 ✓] `useApplicationQuery({enabled:false})`가 영원히 로딩으로 보임**
- 위치: `src/presentation/adapters/query/application-query.ts:180`
- 문제: TanStack Query v5에서 데이터 없는 disabled 쿼리는 `isPending=true`(fetchStatus `idle`)다. `isInitialLoading: query.isPending`을 그대로 넘긴다.
- 시나리오: 선행 값을 기다리는 의존 쿼리가 `AsyncSurface`에서 계속 스켈레톤과 `aria-busy`를 보여준다.
- 수정 방향: `query.isLoading`(isPending && isFetching)을 넘긴다.
- 테스트: `enabled` 케이스 없음.
9. **[권장·확인됨] 디자인시스템 링크가 router와 basename을 우회**
- 위치: `src/presentation/templates/page-templates.tsx:247-254`, `design-system/primitives/navigation.tsx:24`, `:178`, `core.tsx:78-105`
- 문제: `PageActionBar` link, `Breadcrumbs`, `LinkButton`이 모두 `<a href>`다. `routerBasePath`가 `/`가 아닌 배포에서 basename이 빠진 URL로 이동하고, 전체 리로드로 query cache와 UI 상태가 날아간다. `Pagination`의 `href="?page=N"`은 다른 검색 파라미터를 지운다.
- 수정 방향: `to`를 받아 `Link`로 렌더한다.
10. **[권장·확인됨] 상태 화면과 세션 액션이 여러 벌**
- 로딩: `components/async-surface.tsx:9`, `app-router.tsx:64`, `app-router.tsx:407-413`(라벨 없음), `chunk-recovery-boundary.tsx:96`, `pages/home-page.tsx:29-37`과 `examples/platform-overview-page.tsx:287-295`(`.catch` 없어 reject 시 멈춤).
- 인증필요: `ProtectedRoute`(`app-router.tsx:243-273`), `AuthRequiredSurface`(`state-surfaces.tsx:31`), `StatusPage variant="unauthenticated"`.
- 404: `NotFoundPage`, `NotFoundSurface`, `StatusPage`.
- 세션 액션: `app-shell.tsx:48`, `app-router.tsx:213`, `auth-example-page.tsx:13`(세 번째만 `returnTo`에서 hash 누락).
- 수정 방향: route 레벨도 `LoadingSurface`/`StatusPage` 하나로, 세션 액션은 hook 하나로.
11. **[권장·확인됨] Tooltip 설명이 보조기술에 전달되지 않음**
- 위치: `src/presentation/design-system/primitives/overlays.tsx:114`
- 문제: `aria-describedby`가 포커스 안 받는 wrapper `<span>`에 붙어 있다. 내용이 항상 DOM에 있고 opacity만 0이다. Escape로 닫을 수 없다(WCAG 1.4.13).
- 수정 방향: `cloneElement`로 자식에 `aria-describedby`를 주입하고 Escape 닫기를 추가한다.
- 테스트: 없음.
12. **[권장·확인됨] Pagination이 페이지 수만큼 링크를 전부 렌더**
- 위치: `design-system/primitives/navigation.tsx:160`
- 문제: `pageCount=5000`이면 링크 5000개, Tab 이동이 사실상 불가능하다. `CollectionPage`의 `<nav>` 안에 `Pagination`의 `<nav>`가 중첩된다.
- 수정 방향: 현재 페이지 주변 + 처음/끝만 보여주는 windowing.
13. **[사소/가능성] 기타**
- `routes/platform-route-codecs.ts:4`: `none` 코덱이 `.strict()`라 `/?utm_source=x`나 OAuth 콜백 파라미터가 "잘못된 주소"가 된다. 정책 문서는 "보존 또는 제거를 선언"하라고 한다.
- `forms/use-app-form.ts:176-205`(가능성): `pendingRef`가 `await schema.safeParseAsync` 뒤에 설정되어 비동기 refine이 있으면 두 번 제출될 수 있다.
- `use-dirty-navigation-guard.tsx:9`(가능성): `useBlocker(when)`이 마지막 commit 시점 값을 써서 저장 직후 `navigate()`에 "저장하지 않은 변경" 다이얼로그가 뜬다.
- `render-error-boundary.tsx:55-57`, `message-contract.ts:75`: 기본 fallback이 ko-KR로 고정.
- `forms.tsx:399-402`: SearchField 지우기 버튼 unmount로 포커스가 body로 빠진다.
- `styles/theme.css` 1435줄.
잘 된 점: `useApplicationMutation`의 unknown effect 채널, scope fence, 낙관적 레이어와 컴포넌트 테스트 3개. `Dialog`의 native `<dialog>` + `showModal`과 세대 번호 포커스 복원, `ErrorSummary`의 첫 오류 필드 포커스. `route-codecs`가 cast 없이 zod parse 후에만 사용하고, `SafeText`로 HTML 해석을 차단한다.
### 6.9 application / features / bootstrap / platform (+ apps, contexts)
요약: 레이어 방향은 지켜진다(application은 contracts/ports만 import, platform → apps는 dependency-cruiser 예외). 부트 JSON 리더와 트래픽 budget lease 반환은 정확하다. 버그는 부트 reload 무한 반복, 텔레메트리 횟수, 리댁션이다. 세 건 모두 에이전트가 `node --experimental-strip-types`로 재현했다.
1. **[필수·확인됨 ✓] 부트 mismatch reload가 키가 번갈아 바뀌면 무한 반복**
- 위치: `src/platform/release/release-mismatch-recovery.ts:52-66`, `src/bootstrap/boot-release-recovery.ts:29-37`
- 문제: 마커는 하나이고 이전 키와 **같은 키**일 때만 reload를 막는다. 키가 `buildId:code:releaseId`라서 로드밸런서가 R10/R11을 번갈아 주면 A→B→A→B로 바뀌고 매번 새 키로 판정된다. 시뮬레이션에서 번갈아 20번 부트하면 reload 20번. 주석의 "a persistently mixed deployment cannot loop"는 사실이 아니다.
- 수정 방향: TTL 안에 마커가 있으면 키와 무관하게 `show-failure`. 세션당 자동 reload 최대 1회.
- 테스트: `tests/release/mixed-replica.test.ts:94`는 같은 키만, `release-mismatch-recovery.test.ts:64`는 다른 키면 연속 reload하는 동작을 기대값으로 고정하고 있다.
2. **[필수·확인됨] 텔레메트리 `occurrences`가 운영에서 사실상 항상 1**
- 위치: `src/platform/telemetry/telemetry-pipeline.ts:165`, `:182`, `:229`
- 문제: 기본 스케줄이 `queueMicrotask`라 첫 이벤트가 바로 전송되고 그때 count는 1이다. 60초 dedup 창 안의 중복은 `counters.deduplicated`만 올리고 보고되지 않는다. 같은 error 1000번 emit → 전송 1건, occurrences 1. 버퍼에서 드롭된 이벤트도 fingerprint가 dedup에 남아 60초 동안 전송되지 않는다.
- 수정 방향: 창이 닫힐 때나 다음 flush에서 누적 count를 요약 이벤트로 보낸다.
- 테스트: `tests/platform/telemetry/telemetry-pipeline.test.ts:93`이 `schedule: () => {}`로 자동 flush를 꺼서 25를 기대한다. 운영 경로 미검증.
3. **[필수·확인됨] 리댁션이 키 이름 deny-list와 "문자열 시작" 정규식에만 의존**
- 위치: `src/platform/telemetry/redact-telemetry.ts:31`, `:51`
- 문제: `SECRET_VALUE`가 `^`로 고정되어 `"request failed: Authorization: Bearer abc"`처럼 중간의 자격증명을 못 잡는다. URL 쿼리(`?access_token=...`)도 통과한다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin`이 없고 이메일 처리가 없다. 실측에서 다섯 값이 모두 원문 그대로 나왔다. reference-feature는 enum만 보내 당장 유출은 없지만 payload가 `unknown`인 공용 파이프라인이다.
- 수정 방향: 앵커 제거, URL 쿼리 제거, 이메일 마스킹, 키 목록 보강. 더 안전하게는 feature별 payload allow-list.
4. **[권장·확인됨] 텔레메트리 파이프라인 두 벌**
- 위치: `src/bootstrap/runtime-adapters.ts:303`, `:528`, `src/platform/telemetry/telemetry-pipeline.ts:146`, `src/adapters/telemetry/best-effort-telemetry.ts:176`
- 문제: 같은 `TELEMETRY_ENDPOINT`로 따로 보낸다. 분당 한도 합계 40, body 스키마·credentials 다름, feature 쪽은 `pagehide` flush·`onDrop` 진단·dispose abort가 없다.
- 수정 방향: 전송 계층 하나, port는 projection만 다르게.
5. **[권장·확인됨] 킬스위치(`FEATURE_OVERRIDES`)가 feature input 생성에 적용되지 않음**
- 위치: `src/features/installed-feature-adapters.ts:25`, `src/bootstrap/runtime-adapters.ts:423`, `:540`
- 문제: `composeFeatureAdapterInputs`에 설치된 ID 전체를 넘긴다. 같은 함수에서 `activeFeatureIds`를 계산하고도 안 쓴다. disabled feature도 `application.features.get()`이 API를 준다. 막는 곳은 라우터(`app-router.tsx:304`)뿐이다.
- 수정 방향: active ID를 넘긴다.
- 테스트: `tests/component/product-feature-switch.test.tsx`는 라우트만.
6. **[권장·확인됨] adapter contribution의 featureId 중복·불일치가 조용히 덮어씀**
- 위치: `src/features/feature-adapter-contribution.ts:166`, `:175`
- 시나리오: reference-feature를 복사해 새 feature를 만들며 featureId를 안 바꾸면 `features.get("reference-feature")`가 다른 구현을 반환한다. route codec과 메시지 카탈로그는 중복이면 throw하는데 여기만 없다.
- 수정 방향: `Object.hasOwn` 중복 검사, `installed.featureId !== contribution.featureId`면 throw.
7. **[권장·확인됨(현재 잠재)] 정상 종료한 interaction이 부모 signal에 abort listener를 남김**
- 위치: `src/platform/execution/execution-context.ts:102-108`
- 문제: 완료/dispose API가 없어 오래 사는 signal을 부모로 주면 interaction마다 listener와 AbortController가 쌓인다. 지금은 `signal`을 넘기는 호출자가 없다(`http-execution-v3.ts:455`).
- 수정 방향: `dispose()`/`complete()` 추가 또는 `AbortSignal.any([parent, own])`.
8. **[권장·확인됨] 부트 완료까지 최대 약 10초 빈 화면**
- 위치: `src/bootstrap/main.tsx:27`, `:33`, `index.html`
- 문제: config(5초) → manifest(5초) → contract set 검증 뒤에야 첫 render. `#root`는 비어 있고 `aria-busy`도 없다.
- 수정 방향: `index.html`에 정적 boot shell을 넣거나 await 전에 로딩 surface를 render한다.
9. **[사소·확인됨] "한 번만 reload" 로직 두 벌**
- 위치: `src/application/use-cases/decide-chunk-recovery.ts:35-46` vs `src/platform/release/release-mismatch-recovery.ts`
- 문제: chunk 쪽은 키 `a/b->c/d`, TTL 없음, 마커 안 지움. boot 쪽은 키 `a:code:b`, TTL 10분, 정상 부트 시 삭제. 한쪽을 고쳐도 다른 쪽은 남는다.
- 수정 방향: 공용 guard 하나로.
10. **[사소·확인됨] 검증 실패 config 원본 값이 "safe" 에러에 실려 화면·진단에 나감**
- 위치: `src/bootstrap/load-runtime-config.ts:122-127`
- 문제: `CONFIG_SCHEMA_INVALID` 때 미검증 `RELEASE_ID`/`CONFIG_SCHEMA_VERSION`(최대 64KB)이 BootErrorShell과 진단에 들어간다. React escape로 XSS는 아니지만 파일 상단 주석의 "never carries a validation value"와 어긋난다.
- 수정 방향: 검사를 통과한 값만 넣는다.
11. **[사소·확인됨] 버퍼가 낮은 severity를 지운 뒤 들어온 이벤트도 버림**
- 위치: `src/platform/telemetry/telemetry-buffer.ts:91-103`
- 예: maxBytes 300, info 50 + error 240 상태에서 warning 100 → info를 지워도 공간이 부족해 warning도 드롭. 주석("incoming이 더 중요하지 않으면 드롭")과 달리 같은 severity면 가장 오래된 항목을 지운다.
- 수정 방향: 필요 공간을 먼저 계산해 들어갈 수 있을 때만 지운다.
12. **[사소·확인됨] 구조 정리**
- `src/features/reference-feature/presentation/reference-feature-runtime.tsx`는 같은 이름 `.ts`의 re-export만 한다. 확장자 없는 import가 모호해진다.
- `src/application/policies/promotion-readiness.ts`, `performance-budgets.ts`는 CI 스크립트만 쓰는 로직인데 런타임 application 레이어에 있다.
- `src/features/installed-feature-messages.ts`의 로케일이 `ko-KR`/`en-US`로 하드코딩되어 다른 로케일 카탈로그가 조용히 빠진다.
잘 된 점: `read-bounded-boot-json.ts`가 크기 선확인, fatal UTF-8, 타임아웃과 외부 abort를 한 함수에서 처리한다. 릴리스 identity 비교를 `checkReleaseCoherence` 하나로 모았다. `concurrency-budget`의 멱등 lease 반환과 abort된 waiter 제거가 정확하다.
## 7. 이 리뷰의 한계
- **✓ 재확인** 12건과 6.0을 뺀 나머지는 에이전트 보고다. 일부는 에이전트가 scratchpad node 스크립트로 재현했지만 그 스크립트는 레포에 남기지 않았다.
- "가능성" 항목 중 다수(6.1-6/7/8, 6.2-7/8, 6.5-2, 6.6-1/5/11, 6.8-4 일부, 6.8-13)는 실제 브라우저, 탭 2개 이상, 실제 CDN/서버 설정이 있어야 확인된다.
- `dev`, `build`, e2e, browser-capabilities 테스트는 실행하지 않았다.
- `src/` 밖(`scripts/`, `tests/`, `recipes/`, 설정 파일)은 범위 밖이다. 6.0은 원인이 `src/`의 import라서 포함했다.
- 영역당 발견 수를 약 12건으로 제한했으므로 모든 결함을 망라한 목록은 아니다.
@@ -16,7 +16,7 @@ No Critical issue was found. Five High findings are implementation blockers or n
4. N-04: telemetry dispose only removes pagehide; queued callbacks, future emit calls, and in-flight delivery survive runtime teardown.
5. N-05: the conditional-validator key codec is delimiter-ambiguous and lets two valid bindings overwrite each other. It is not composed into HTTP yet, so this is a rollout blocker rather than a current request-path incident.
The current reference feature uses V3. The older createHttpClient path remains exported and is still the documented rollback/compatibility seam, so its replay and cancellation defects cannot be dismissed as dead code.
The current reference feature uses V3. The older createHttpClient path remains exported and is still the documented rollback/compatibility seam, so its replay and cancellation defects cannot be dismissed as dead code. (2026-09-24, Q-6.3-11: the comments no longer call it a rollback seam; V2 and V3 use different wire shapes, so a rollback also needs a V2-envelope server.)
## 2. Method, severity, and confidence
@@ -60,16 +60,19 @@ All 24 files below were read in full.
| src/adapters/diagnostics/bounded-diagnostics.ts | Bounded in-memory diagnostics projection/sink and safe pre-mount boot evidence | DiagnosticsPort; contracts/diagnostics.ts and telemetry.ts; bootstrap | Preserve fail-isolated projection and cloning. Harden non-finite capacity. V3 producer fix belongs primarily in bootstrap. |
| src/adapters/http/bounded-body-reader.ts | Declared-length and streamed byte ceilings, stream cancellation/release isolation, forbidden-body probing, strict UTF-8/JSON decode | V3 executor; bounded-body-reader tests | Keep as the single bounded response primitive. It already contains the cleanup behavior missing from bounded-json.ts. |
| src/adapters/http/bounded-json.ts | Legacy response stream reader and JSON decoder | legacy client.ts | Replace internals with bounded-body-reader delegation, then remove with V2 retirement. Current cancel/release failures can reject. |
| src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Deprecate after callers are migrated. |
| src/adapters/http/client.ts | Legacy/V2 operation lookup, profiles, auth recovery, retries, total deadline, response validation/mapping, diagnostics and telemetry | legacy contracts and ports; runtime-adapters createRuntimeHttpClient | Compatibility-only but exported. Fix empty keyed replay, cooperative auth cancellation, and common body-reader use before relying on it for rollback. Not a drop-in rollback for V3: V2 validates the `{success,data,meta}` envelope and V3 the bare DTO, so a rollback needs the four slots and a V2-envelope server (Q-6.3-11). 401 recovery is a single replay outside the retry budget. Deprecate after callers are migrated. |
| src/adapters/http/http-contract-bridge.ts | V3 request projection, URL/body bounds, credential patch type, final request invariant | external-contract-runtime.ts; V3 executor | Preserve descriptor-owned request projection. Change credential authority: patch cannot own credentials or transport headers; final invariant must compare exact resolved profile. |
| src/adapters/http/http-effect-certainty.ts | Converts physical-attempt state and problem descriptors into mutation certainty/UI projection | V3 executor; contracts | Preserve explicit certainty vocabulary. Add a monotonic logical-execution certainty join used across retries. |
| src/adapters/http/http-execution-v3.ts | Descriptor-driven V3 lifetime: validation, projection, credentials, deadline, retry, fetch, response admission, effect verdict and observation | external contracts, scope, mutation intent, bridge, bounded reader, certainty, retry policy | Main correction site for N-01, N-02, N-03 and cooperative cancellation. Keep one retry authority and closed result union. |
| src/adapters/http/request-builder.ts | Legacy path/query construction and origin/base-prefix checks | legacy client; ApiOperation | Keep while V2 remains. Do not reuse it to weaken V3 descriptor projection. |
| src/adapters/http/resource-mapper.ts | Thin legacy operation-payload mapper delegation | boundary-mapper; legacy client | No standalone defect. Remove only with V2, not as part of the correctness patch. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3 | legacy client and V3 executor | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/retry-policy.ts | Legacy retry decision/backoff plus parseRetryAfter reused by V3; parsing delegates to kernel platform/retry-after.ts (Q-6.4-8) | legacy client and V3 executor; platform/retry-after.ts | Keep deterministic parse/backoff seam. V2 must additionally prove a valid key before keyed replay. |
| src/adapters/http/platform-error-mapping.ts | Maps feature-less V3 transport outcomes (cancel, timeout, network, response-invalid) to the platform AppError envelope; feature-owned outcomes return null | http-execution-v3.ts outcomes; platform/errors; feature HTTP binding | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row). |
| src/adapters/http/schema-registry.ts | Legacy Zod envelope/request/payload validation and clone | legacy client/tests | No standalone defect. Remains V2-only and should not be merged with installed external validators. |
| src/adapters/platform/browser-lifecycle.ts | Single owner of visibility/network/focus/page/beforeunload listeners and lifecycle snapshots | optional-runtime-host.ts | Preserve centralized listener ownership and idempotent dispose. Clarify or redesign dirty-source attachment semantics; selection item O-02. |
| src/adapters/platform/browser-mutation-intent-factory.ts | Secure intent/idempotency UUIDs plus monotonic creation time, normalized by defineMutationIntent | MutationIntentFactory port; bootstrap | Keep. Share one idempotency-key validator so external inputs and generated values have identical bounds. |
| src/adapters/platform/json-member-scanner.ts | Non-recursive duplicate-member and structure-budget scan before `JSON.parse`; moved from realtime in 2nd round (Q-6.4-8) | realtime event codec and WS protocol; web-push hint codec | Keep. Single scanner; web-push now checks every depth, not only top-level keys. |
| src/adapters/platform/retry-after.ts | Strict Retry-After parser: delta-seconds or IMF-fixdate, no guessed delays (Q-6.4-8) | realtime reconnect policy / SSE; http retry-policy.ts | Keep. Rejects blank, decimal and exponent values the old http copy accepted. |
| src/adapters/platform/system-clock.ts | Wall clock and abortable sleep with listener/timer cleanup | ClockPort; legacy HTTP | Keep. Existing unit test covers abort cleanup behavior. |
| src/adapters/query-cache/conditional-validator-store.ts | In-memory ETag CAS sidecar keyed by scope, definition, identity, representation and cache revision | bootstrap scope reset; future conditional HTTP/query join | Fix tuple codec before composition. Preserve validator grammar, generation/revision checks and bounded capacity. |
| src/adapters/query-cache/cursor-pagination-runtime.ts | Bounded cursor chain, page/snapshot/loop/item/byte validation | cursor pagination contract; currently available but not composed | Add post-await abort admission or an abort race. Current pre-await-only check can admit a late page. |
@@ -77,6 +80,8 @@ All 24 files below were read in full.
| src/adapters/query-cache/tanstack-cache-coordinator.ts | Maps registry topics to query namespace invalidation, coalesces remote hints, defers under mutation leases, resets/disposes | TanStack Query, invalidation contracts, cross-context runtime | Keep invalidate-only remote authority, generation guard, reset serialization and bounded registry validation. Add teardown characterization if dispose becomes async. |
| src/adapters/query-cache/tanstack-query-cache.ts | Creates QueryClient defaults and QueryCachePort read/write/invalidate adapter with diagnostics | TanStack Query, QueryCachePort, errors/diagnostics | Keep retry disabled and clone-on-write. Clone-on-read is an optional port-semantics decision, not a confirmed production defect. |
| src/adapters/telemetry/best-effort-telemetry.ts | Allowlisted bounded oldest-drop telemetry queue, scheduled/pagehide flush, sink isolation and evidence | TelemetryPort, telemetry/diagnostic contracts, bootstrap | Add terminal lifecycle state, joined flush promise and in-flight abort; ensure runtime composition disposes it. |
| src/adapters/telemetry/feature-telemetry.ts | Feature TelemetryPort adapter over the platform telemetry pipeline; fetch transport to the collector endpoint | platform/telemetry pipeline; TelemetryPort; bootstrap | Keep. Registered 2026-09-24 (added in 6f6c48e without a ledger row); shares the collector with best-effort-telemetry (review 6.9-4). |
| src/adapters/telemetry/telemetry-collector.ts | The one collector transport behind both telemetry ports: shared send-rate window, `credentials: "omit"`, `cache: "no-store"`, per-request deadline through the kernel abort primitive, one `pagehide` fan-out | platform/telemetry send rate; adapters/platform abort and capacity kernel; bootstrap | Keep. Added 2026-09-24 for review 6.9-4 / 6.3-10: a hung collector no longer stalls later flushes, and the two ports no longer send 20+20 per minute. |
## 4. Traced boundary inventory
@@ -6,9 +6,9 @@
- 방식: 코드 리뷰만 수행했다. 이 문서 외 구현 파일은 수정하지 않았다.
- 결론: **Critical 0, High 4, Medium 3**이다. R-01~R-06은 코드상 확정된 lifecycle/immutability/resource 문제이고, R-07은 문서에도 미완료라고 명시된 production promotion blocker다. 두 runtime 모두 현재 `AVAILABLE_NOT_COMPOSED`이므로 production traffic 사고로 과장하지 않는다.
## 1. 21/21 파일 inventory와 책임
## 1. 20/20 파일 inventory와 책임
아래 경로는 모두 저장소 루트 기준 full path이며, 범위의 구현 파일 21개를 모두 읽었다.
아래 경로는 모두 저장소 루트 기준 full path이며, 범위의 구현 파일 21개를 모두 읽었다. 2차 라운드(Q-6.4-8)에서 `json-member-scanner.ts`는 kernel `src/adapters/platform/`로 옮겨 [Network/state](./01-network-and-state.md) 표에서 다룬다.
| # | full path | 책임 | 주요 의존성 / downstream | 판정 |
|---:|---|---|---|---|
@@ -16,23 +16,22 @@
| 2 | `src/adapters/browser-rpc/index.ts` | Browser RPC public adapter export surface | runtime, transport, unavailable adapter | 새 lease/install type export 필요 |
| 3 | `src/adapters/browser-rpc/transport.ts` | provider-neutral unary/stream transport result와 runtime identity 계약 | `src/contracts/browser-rpc.ts` | R-01, R-07 |
| 4 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | 선택되지 않은 runtime의 명시적 fail-closed Null Object | `transport.ts` | 유지; 새 stream lease shape만 맞춤 |
| 5 | `src/adapters/realtime/event-codec.ts` | raw JSON byte/shape/registry/schema 검증, immutable DTO와 semantic fingerprint 생성 | realtime contracts, schema registry, JSON scanner, result codec | 유지 |
| 5 | `src/adapters/realtime/event-codec.ts` | raw JSON byte/shape/registry/schema 검증, immutable DTO와 semantic fingerprint 생성 | realtime contracts, schema registry, kernel JSON scanner, result codec | 유지 |
| 6 | `src/adapters/realtime/event-consumer.ts` | SSE/WS cursor 규칙을 codec 결과와 결합하고 common stream coordinator outcome으로 투영 | realtime ports/contracts, event codec, stream coordinator | 유지 |
| 7 | `src/adapters/realtime/index.ts` | common realtime adapter public export surface | codec, consumer, reconnect, handoff, stream, sub-index | R-02/R-03 lifecycle type export 필요 |
| 8 | `src/adapters/realtime/json-member-scanner.ts` | `JSON.parse` 전 duplicate member와 structure budget을 비재귀적으로 검사 | 독립 utility | 유지 |
| 9 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | LIVE/POLL 단일 effect writer, generation fence, quiescence/checkpoint, probe buffer와 전환 | `ClockPort`, realtime result/ports | R-03 |
| 10 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | visible/online finite lease, single-flight poll, retry hint, response/apply deadline, non-cooperative task drain | bounded polling policy, `ClockPort`, realtime result | 유지 |
| 11 | `src/adapters/realtime/polling/index.ts` | polling public exports | bounded poll coordinator | 유지 |
| 12 | `src/adapters/realtime/reconnect-coordinator.ts` | 단일 reconnect owner, online gate, retry budget, session close authority, exact recovery proof, post-abort DRAINING | reconnect policy, `ClockPort`, realtime ports/result | 유지 |
| 13 | `src/adapters/realtime/reconnect-policy.ts` | immutable reconnect policy, full jitter, elapsed budget, Retry-After 계산/검증 | 독립 policy | 유지 |
| 14 | `src/adapters/realtime/result.ts` | hostile/mutable collaborator result를 exact own-data snapshot으로 canonicalize | realtime ports/contracts | 유지; R-04의 기준 패턴 |
| 15 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | fixed same-origin fetch-stream SSE, response/media/open gate, read/event deadline, cursor rule, bounded reader cancel | `ClockPort`, event authority/result, parser, reconnect policy | 유지; R-02 common drain과 함께 검증 |
| 16 | `src/adapters/realtime/sse/index.ts` | SSE public exports | fetch connection, parser | 유지 |
| 17 | `src/adapters/realtime/sse/sse-parser.ts` | strict incremental UTF-8 SSE parser, BOM/line ending/id/retry/event buffer ceiling | realtime contracts/result | 유지 |
| 18 | `src/adapters/realtime/stream-coordinator.ts` | per-stream sequential effect, dedupe/order, recovery, checkpoint/barrier, scope generation fence | event authority port, realtime contracts, mapper registry, codec/result | R-02 |
| 19 | `src/adapters/realtime/websocket/index.ts` | WebSocket connection/protocol public exports | connection, protocol | 유지 |
| 20 | `src/adapters/realtime/websocket/websocket-connection.ts` | 한 physical WS의 handshake/subscription/tombstone/FIFO/heartbeat/apply gate/recovery close | `ClockPort`, realtime contracts/result, WS protocol | 유지; R-02 upstream timeout과 함께 검증 |
| 21 | `src/adapters/realtime/websocket/websocket-protocol.ts` | exact closed JSON frame decode/encode, duplicate key/structure/sequence/frame byte 검증 | realtime contracts, JSON scanner | R-05 |
| 8 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | LIVE/POLL 단일 effect writer, generation fence, quiescence/checkpoint, probe buffer와 전환 | `ClockPort`, realtime result/ports | R-03 |
| 9 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | visible/online finite lease, single-flight poll, retry hint, response/apply deadline, non-cooperative task drain | bounded polling policy, `ClockPort`, realtime result | 유지 |
| 10 | `src/adapters/realtime/polling/index.ts` | polling public exports | bounded poll coordinator | 유지 |
| 11 | `src/adapters/realtime/reconnect-coordinator.ts` | 단일 reconnect owner, online gate, retry budget, session close authority, exact recovery proof, post-abort DRAINING | reconnect policy, `ClockPort`, realtime ports/result | 유지 |
| 12 | `src/adapters/realtime/reconnect-policy.ts` | immutable reconnect policy, full jitter, elapsed budget; Retry-After 파서는 kernel `platform/retry-after.ts`를 re-export | kernel retry-after | 유지 |
| 13 | `src/adapters/realtime/result.ts` | hostile/mutable collaborator result를 exact own-data snapshot으로 canonicalize | realtime ports/contracts | 유지; R-04의 기준 패턴 |
| 14 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | fixed same-origin fetch-stream SSE, response/media/open gate, read/event deadline, cursor rule, bounded reader cancel | `ClockPort`, event authority/result, parser, reconnect policy | 유지; R-02 common drain과 함께 검증 |
| 15 | `src/adapters/realtime/sse/index.ts` | SSE public exports | fetch connection, parser | 유지 |
| 16 | `src/adapters/realtime/sse/sse-parser.ts` | strict incremental UTF-8 SSE parser, BOM/line ending/id/retry/event buffer ceiling | realtime contracts/result | 유지 |
| 17 | `src/adapters/realtime/stream-coordinator.ts` | per-stream sequential effect, dedupe/order, recovery, checkpoint/barrier, scope generation fence | event authority port, realtime contracts, mapper registry, codec/result | R-02 |
| 18 | `src/adapters/realtime/websocket/index.ts` | WebSocket connection/protocol public exports | connection, protocol | 유지 |
| 19 | `src/adapters/realtime/websocket/websocket-connection.ts` | 한 physical WS의 handshake/subscription/tombstone/FIFO/heartbeat/apply gate/recovery close | `ClockPort`, realtime contracts/result, WS protocol | 유지; R-02 upstream timeout과 함께 검증 |
| 20 | `src/adapters/realtime/websocket/websocket-protocol.ts` | exact closed JSON frame decode/encode, duplicate key/structure/sequence/frame byte 검증 | realtime contracts, kernel JSON scanner | R-05 |
## 2. 추적한 contracts, ports, bootstrap, tests, docs
@@ -43,6 +43,7 @@
| `src/adapters/browser-files/browser-file-vault.ts` | transient native File/handle 보관, opaque ref, inspection receipt, bounded range/source | file port/shared/result/policy registry. File이 application 경계를 넘지 않고 receipt가 exact file/profile에 묶이는 설계가 좋다. |
| `src/adapters/browser-files/create-browser-file-runtime.ts` | vault/picker/preview/download를 선택적으로 조립하고 일괄 dispose | 위 adapters 및 application contracts. optional capability를 제품 선택 없이 bootstrap에 암묵 조립하지 않는 점을 유지. preview 조립 전 GAP-01 gate 필요. |
| `src/adapters/browser-files/download-delivery-adapter.ts` | browser handoff, foreground save stream, bounded object URL download, integrity/progress/cancellation | file/authorized-download ports, policy registry, object URL lease, Result. STO-02와 STO-08; stream close truth/backpressure는 유지. |
| `src/adapters/browser-files/download-input-validation.ts` | download 요청 snapshot, policy/limit/activation 검증, presigned·browser-managed capability 검증, canonical handoff target 해석 | file/authorized-download ports, policy registry, `file-policy.ts`, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/browser-files/file-observer.ts` | file-safe observation DTO를 공통 browser observation으로 변환 | shared port/result. raw filename/ref 비노출 유지. |
| `src/adapters/browser-files/file-policy.ts` | policy input validation, MIME/extension/signature/hard byte caps, immutable resolved policy | file/shared contracts. closed allowlist 및 absolute ceiling을 유지. |
| `src/adapters/browser-files/index.ts` | browser-file public exports | 위 모듈. native implementation detail export 확장을 피한다. |
@@ -53,7 +54,9 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/cache-storage/index.ts` | public cache policy/adapter barrel | optional public static cache만 export; private/range cache로 일반화하지 않는다. |
| `src/adapters/cache-storage/public-cache-codec.ts` | manifest 정규화·canonical digest 입력, marker/active pointer 검증, bounded control JSON 읽기, owned cache 이름, 검증 실패 → Result 매핑 | cache ports/result/policy. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-cache-policy.ts` | same-origin/public-only release 정책, URL/header/query/size/retention hard limits | cache ports/shared. STO-03 policy cross-field invariant 누락. 기본 policy에는 `vary`가 있어 기본-path 테스트는 통과한다. |
| `src/adapters/cache-storage/public-cache-response-validation.ts` | network/cached response 수용 검증: status, cache directive, Content-Type, Vary, bounded body, digest | `public-cache-codec.ts`, policy, Result. Q-6.2-11에서 adapter에서 그대로 옮겼다(동작 불변). |
| `src/adapters/cache-storage/public-response-cache-adapter.ts` | manifest canonicalization/digest, anonymous fetch, bounded body 검증, candidate marker-last staging, explicit activation, exact lookup/reverify, owned cleanup/inspect | cache ports/result/policy, CacheStorage/fetch/Crypto/Web Lock snapshot. STO-03~05 및 GAP-02. private/auth/opaque/206 거절과 current+previous 보존은 유지. |
### 1.4 `storage` root / IndexedDB
@@ -67,6 +70,7 @@
| `src/adapters/storage/indexeddb/indexeddb-governance.ts` | opaque dataset scope/physical DB identity 및 frozen policy binding | indexeddb/shared ports. account/business ID를 physical name에 쓰지 않는 양방향 binding 유지. |
| `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | post-open codec migration 및 idempotency receipt prune, keyset checkpoint, budget/revision fencing | IndexedDB port/types/failure/governance. async transform outside tx, row+sidecar+budget+checkpoint atomic commit은 좋다. STO-06 및 temporal drain lease 개선 후보. |
| `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | additive-only contiguous DDL planner/validator | indexeddb types. destructive DDL 거절 유지. |
| `src/adapters/storage/indexeddb/indexeddb-records.ts` | runtime·maintenance·dataset binding이 함께 쓰는 저장 행 타입, 검증기, record 바이트 측정, `countBucket`/`failureOf` | IndexedDB port/shared/types. Q-6.5-7: 복사본 3벌을 하나로 합쳤다. 실패 코드는 호출부가 정한다(runtime `INVALID_INPUT`, maintenance `MIGRATION_FAILED`). budget의 `hardBudgetBytes` 상한은 binding 검증에서만 본다. |
| `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | generic repository open/read/query/CAS/delete, idempotency, retention, lifecycle purge, connection lifecycle | indexeddb ports/types/governance/failure/migrations. transaction `complete` truth, versionchange close, shared open/abort isolation, exact budgets 유지. lifecycle proof는 현재 문서 계약(형식 검증 후 폐기)과 일치하므로 결함으로 분류하지 않았다. |
| `src/adapters/storage/indexeddb/indexeddb-types.ts` | adapter-local codec/query/schema/dependency contracts | application indexeddb/shared ports. `isOldWriterDrainConfirmed()` boolean은 provider가 전체 window를 보장한다는 문서 전제; lease형으로 강화 권고. |
@@ -79,6 +83,7 @@
| `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | logical object/journal/budget/chunk refcount의 IDB authority; begin/files-ready/commit/rollback/reconcile pages | OPFS ports, IDB failure, policy. journal+object+budget CAS atomicity가 좋다. STO-01 수정에서 incomplete row를 cleanup 확인 전 삭제하지 않아야 한다. |
| `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | logical journal과 physical worker를 saga로 조정, put/open/remove, reconcile/policy maintenance | OPFS/shared ports, journal, worker gateway, policy. STO-01의 journal/physical compensation ordering 결함 위치. |
| `src/adapters/storage/opfs/opfs-policy.ts` | root/lock/chunk/object/RPC/reconcile/GC hard limits 및 scope validation | shared/opfs ports. opaque physical path와 absolute caps 유지. |
| `src/adapters/storage/opfs/opfs-prepared-object.ts` | page·journal·worker가 함께 쓰는 prepared-object 검증기 하나 | OPFS/shared ports, opfs-policy scope 검증. R-5.5: 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증하고 현재 정책값은 새 쓰기에만 적용. |
| `src/adapters/storage/opfs/opfs-worker-client.ts` | request correlation/timeout/abort/transferable chunking, worker gateway, streamed reads | protocol/policy/shared Result. STO-01의 untracked abort cleanup 및 STO-07의 shallow response parse. |
| `src/adapters/storage/opfs/opfs-worker-protocol.ts` | page↔DedicatedWorker request/response union 및 gateway contract | OPFS/shared ports. STO-07; protocol version/kind/effect certainty 추가 필요. |
| `src/adapters/storage/opfs/opfs-worker-runtime.ts` | DedicatedWorker OPFS physical layout, lock lease, immutable chunk, manifest/staging receipt, abort/finalize/remove/GC | protocol/policy/OPFS ports/Web Lock/Crypto. STO-01의 generation-only cleanup과 lease release 순서. sync handle `finally close` 등은 유지. |
+4 -1
View File
@@ -35,6 +35,7 @@
| --- | --- | --- | --- |
| `browser-transfer/index.ts` | 하위 capability export | KEEP | public export 증가는 각 capability 계획에서만 수행 |
| `presigned/index.ts` | presigned public surface | KEEP | `BT-PRE-04`에서 vault issuer 노출만 축소 검토 |
| `presigned/http-common.ts` | executor·provider 공용 HTTP 메커니즘(abort scope, status 표, Content-Length 파싱, body 취소) | KEEP | Q-6.1-9. 두 벌이던 사본을 합쳤다. status 표는 여기 한 벌만 둔다 |
| `presigned/incremental-sha256.ts` | streaming SHA-256 | KEEP | WebCrypto `digest()`로 바꾸면 전체 buffering이 되므로 교체 금지 |
| `presigned/presigned-capability-http-provider.ts` | BFF capability 발급, strict decode | CONTRACT_GAP | `BT-PRE-02`, `BT-PRE-03`, `BT-X-01` |
| `presigned/presigned-capability-vault.ts` | identity capability 보관/폐기 | REFACTOR | `BT-PRE-04` |
@@ -45,8 +46,10 @@
| `resumable-upload/index.ts` | resumable public surface | KEEP | facade 호환 유지 |
| `resumable-upload/indexeddb-checkpoint-store.ts` | scope-bound CAS store/admin | VERIFIED_DEFECT | `BT-UP-03` |
| `resumable-upload/presigned-upload-part-executor.ts` | multipart와 presigned bridge | VERIFIED_DEFECT | `BT-UP-04` |
| `resumable-upload/resumable-upload-runtime.ts` | session state/retry/part scheduling/commit | REFACTOR | `BT-UP-05`, `BT-UP-06` |
| `resumable-upload/resumable-upload-runtime.ts` | session state/retry/part scheduling/commit | REFACTOR | `BT-UP-05`, `BT-UP-06`. Q-6.1-10에서 검증·snapshot 래퍼를 분리 |
| `resumable-upload/runtime-dependencies.ts` | runtime 주입 의존성 검증과 메서드 snapshot, clock/random guard | KEEP | Q-6.1-10. runtime 파일에서 분리, 동작 불변 |
| `resumable-upload/runtime-policy.ts` | hard bound snapshot | KEEP | 값 변경은 contract migration으로만 수행 |
| `resumable-upload/upload-response-validation.ts` | session/status/part capability/receipt strict decoder | KEEP | Q-6.1-10. runtime 파일에서 분리, 동작 불변 |
| `resumable-upload/upload-byte-source.ts` | stream/range source snapshot과 hashing | KEEP/REFACTOR | runtime에서 source preparation Strategy로 주입 |
| `resumable-upload/upload-cancellation-channel.ts` | best-effort cross-context cancel hint | KEEP | backend/CAS가 authority라는 주석과 동작 유지 |
| `resumable-upload/upload-mutation-lock.ts` | Web Lock exclusive mutation | PLANNED_GAP | `BT-UP-07` |
@@ -30,6 +30,7 @@ Web Push는 현재 `AVAILABLE_NOT_COMPOSED`이고 제품 선택도 `NOT_SELECTED
| `service-worker-protocol.ts` | page-worker strict message codec/nonce | CONTRACT_GAP | `SW-06`, `SW-10` |
| `service-worker-removal.ts` | exact registration/cache ownership cleanup | VERIFIED_DEFECT | `SW-03` |
| `service-worker-static-assets.ts` | static manifest/install/cache policy | KEEP/REFACTOR | `SW-01`, `SW-05`, `SW-09` |
| `web-push/codec-primitives.ts` | 공유 검증 primitive(base64url decode, opaque id, authority, exact record) | KEEP | Q-6.6-12에서 4개 파일의 복사본을 합침. 복사본이 다르던 곳은 더 엄격한 쪽을 유지 |
| `web-push/index.ts` | public exports | KEEP | product selection 전 surface 확대 금지 |
| `web-push/notification-registry.ts` | closed copy/route registry | KEEP | arbitrary copy/URL 허용 금지 |
| `web-push/push-association-fence-store.ts` | durable authority state machine | VERIFIED_DEFECT | `WP-01`, `WP-02` |
+137 -124
View File
@@ -18,129 +18,142 @@
| 8 | `src/adapters/browser-files/browser-file-vault.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 9 | `src/adapters/browser-files/create-browser-file-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 10 | `src/adapters/browser-files/download-delivery-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 11 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 16 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 44 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 45 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 46 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 47 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 48 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 49 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 50 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 51 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 52 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 80 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 81 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 82 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 83 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 97 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 98 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 99 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 104 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 105 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 106 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 122 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 123 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 124 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 125 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 126 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 127 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 128 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 129 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 11 | `src/adapters/browser-files/download-input-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 12 | `src/adapters/browser-files/file-observer.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 13 | `src/adapters/browser-files/file-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 14 | `src/adapters/browser-files/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 15 | `src/adapters/browser-files/object-url-lease.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 16 | `src/adapters/browser-rpc/browser-rpc-runtime.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 17 | `src/adapters/browser-rpc/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 18 | `src/adapters/browser-rpc/transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 19 | `src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 20 | `src/adapters/browser-transfer/image-cdn/README.md` | [Browser transfer](./04-browser-transfer.md) |
| 21 | `src/adapters/browser-transfer/image-cdn/browser-image-probe.ts` | [Browser transfer](./04-browser-transfer.md) |
| 22 | `src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 23 | `src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 24 | `src/adapters/browser-transfer/image-cdn/image-header-metadata.ts` | [Browser transfer](./04-browser-transfer.md) |
| 25 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 26 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) |
| 27 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 28 | `src/adapters/browser-transfer/presigned/http-common.ts` | [Browser transfer](./04-browser-transfer.md) |
| 29 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) |
| 30 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 31 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) |
| 32 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) |
| 33 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 34 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) |
| 35 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) |
| 36 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) |
| 37 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 45 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 46 | `src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts` | [Browser transfer](./04-browser-transfer.md) |
| 47 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 48 | `src/adapters/cache-storage/public-cache-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 49 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 50 | `src/adapters/cache-storage/public-cache-response-validation.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 51 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 52 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/platform/json-member-scanner.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/platform/retry-after.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 84 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 85 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 86 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 87 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 88 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 101 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 102 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 103 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 104 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 108 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 109 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 110 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 111 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 131 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 134 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 135 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 145 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 146 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **133/133**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **146/146**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
+3 -1
View File
@@ -57,7 +57,9 @@ RP-07 구현 이후 이 기반은 저장소 내부 디자인 시스템 플랫폼
3. 앱 셸, 예제와 reference feature는 public design-system barrel을 소비한다.
4. 문자 glyph는 semantic Lucide facade로 교체됐다.
5. token은 세 CSS 파일로 분리됐고 `theme.css`는 layout/component styling만
소유한다.
소유한다. `theme.css`는 import 순서만 정하는 진입점이고, 실제 규칙은
`styles/theme/` 아래 파일(base, shell, primitives, templates, pages,
responsive)에 같은 순서로 있다.
6. runtime gallery는 있지만 격리된 story, interaction story, 시각 회귀 기준선이
없다.
7. 사용자 문구가 한국어 literal로 고정되어 locale과 RTL 계약이 없다.
+12 -1
View File
@@ -7,7 +7,18 @@
<title>Clean Architecture Frontend</title>
</head>
<body>
<div id="root"></div>
<div id="root">
<!-- Q-6.9-8. Static boot shell: visible while config, manifest and
contract checks run; the first React render replaces it. -->
<div
class="state-surface state-surface--loading"
role="status"
aria-busy="true"
data-boot-shell=""
>
불러오는 중
</div>
</div>
<script type="module" src="/src/bootstrap/main.tsx"></script>
</body>
</html>
+51 -51
View File
@@ -9,26 +9,26 @@
"pnpm": ">=11.0.0 <12.0.0"
},
"scripts": {
"dev": "vite",
"build": "node scripts/build-frontend.ts",
"dev": "node scripts/generate-product-feature-index.ts && vite",
"build": "node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts",
"build:profile": "node scripts/generate-runtime-config.ts",
"build:release-candidate": "corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security && corepack pnpm verify:release && node scripts/verify-supply-chain-artifacts.ts && node scripts/create-release-candidate.ts",
"build:release-candidate": "node scripts/generate-product-feature-index.ts && corepack pnpm build && corepack pnpm generate:supply-chain && corepack pnpm scan:security && corepack pnpm verify:release && node scripts/verify-supply-chain-artifacts.ts && node scripts/create-release-candidate.ts",
"preview": "vite preview",
"lint": "eslint src scripts tests recipes .storybook vite.config.ts vitest.config.ts playwright*.config.ts --max-warnings=0",
"check:architecture": "node scripts/check-architecture.ts",
"check:design-system": "node scripts/check-design-system.ts",
"check:design-system:fixture": "node scripts/check-design-system.ts --fixture",
"check:i18n": "node scripts/check-i18n.ts",
"check:i18n:fixture": "node scripts/check-i18n.ts --fixture",
"check:architecture": "node scripts/generate-product-feature-index.ts && node scripts/check-architecture.ts",
"check:design-system": "node scripts/generate-product-feature-index.ts && node scripts/check-design-system.ts",
"check:design-system:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-design-system.ts --fixture",
"check:i18n": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts",
"check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture",
"check:adapter-inventory": "node scripts/check-adapter-inventory.ts",
"check:remediation-ledger": "node scripts/check-remediation-ledger.ts",
"check:release-admission": "node scripts/check-release-admission.ts",
"check:diagnostics": "node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/check-diagnostics.ts --fixture",
"check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts",
"check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture",
"check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker",
"check:types:app": "tsc --project tsconfig.app.json",
"check:types:node": "tsc --project tsconfig.node.json",
"check:types:test": "tsc --project tsconfig.test.json",
"check:types:app": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.app.json",
"check:types:node": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.node.json",
"check:types:test": "node scripts/generate-product-feature-index.ts && tsc --project tsconfig.test.json",
"check:types:recipes": "node scripts/check-optional-recipe-types.ts",
"check:types:fixture": "tsc -p tests/fixtures/typecheck/tsconfig.port-call.json",
"check:types:fixture:ts-port": "tsc -p tests/fixtures/typecheck/tsconfig.port-implementation.json",
@@ -39,11 +39,11 @@
"check:types:fixture:failure-kind": "tsc -p tests/fixtures/typecheck/tsconfig.failure-kind.json",
"check:types:fixture:reference-operation": "tsc -p tests/fixtures/typecheck/tsconfig.reference-operation.json",
"check:types:fixture:async-overlay": "tsc -p tests/fixtures/typecheck/tsconfig.async-overlay.json",
"check:types:fixture:route-runtime": "tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:route-runtime": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.route-runtime.json",
"check:types:fixture:page-action": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.page-action.json",
"check:types:fixture:icon-button": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.icon-button.json",
"check:types:fixture:i18n-key": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-key.json",
"check:types:fixture:i18n-params": "node scripts/generate-product-feature-index.ts && tsc -p tests/fixtures/typecheck/tsconfig.message-params.json",
"check:types:fixture:diagnostics": "tsc -p tests/fixtures/typecheck/tsconfig.diagnostics-port.json",
"check:types:fixture:image-resolve-signal": "tsc -p tests/fixtures/typecheck/tsconfig.image-cdn-resolve-signal.json",
"test:runtime-schema": "node scripts/run-vitest.ts run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
@@ -59,8 +59,8 @@
"test:e2e:dev": "playwright test --config playwright.dev.config.ts",
"test:browser-capabilities": "playwright test --config playwright.capabilities.config.ts",
"verify:browser-capability-evidence": "node scripts/verify-browser-capability-evidence.ts",
"storybook": "storybook dev -p 6006",
"build:storybook": "storybook build -o artifacts/storybook/static",
"storybook": "node scripts/generate-product-feature-index.ts && storybook dev -p 6006",
"build:storybook": "node scripts/generate-product-feature-index.ts && storybook build -o artifacts/storybook/static",
"test:storybook": "playwright test --config playwright.storybook.config.ts",
"test:visual": "playwright test --config playwright.visual.config.ts",
"test:visual:update": "playwright test --config playwright.visual.config.ts --update-snapshots",
@@ -70,8 +70,8 @@
"check:http-scenario-evidence:fixture": "node scripts/check-test-evidence.ts --scenario-only --source-root tests/fixtures/test-evidence/scenarios/source --policy tests/fixtures/test-evidence/scenarios/policy.json --catalog tests/fixtures/test-evidence/scenarios/catalog.json --receipt tests/fixtures/test-evidence/scenarios/receipt.json --artifact artifacts/quality/http-scenario-evidence-fixture.json",
"check:test-evidence:source": "node scripts/check-test-evidence.ts --source-only --artifact artifacts/quality/test-evidence-source.json",
"check:test-evidence:fixture": "node scripts/check-test-evidence.ts --source-root tests/fixtures/test-evidence/forbidden --artifact artifacts/quality/test-evidence-fixture.json",
"test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/verify-a11y-manual.ts",
"test:a11y": "node scripts/generate-product-feature-index.ts && playwright test --grep @a11y && node scripts/write-a11y-report.ts",
"review:a11y-manual": "node scripts/generate-product-feature-index.ts && node scripts/verify-a11y-manual.ts",
"test:sample-removal": "node scripts/test-sample-removal.ts",
"test:optional-recipe-removal": "node scripts/test-optional-recipe-removal.ts",
"test:browser-file-storage-removal": "node scripts/test-browser-file-storage-runtime-removal.ts",
@@ -83,46 +83,46 @@
"test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:contract && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature && corepack pnpm test:platform && corepack pnpm check:release-coherence && corepack pnpm test:recipes",
"verify:lockfile": "corepack pnpm install --frozen-lockfile --ignore-scripts",
"check:frozen-lockfile:fixture": "node scripts/check-frozen-lockfile-fixture.ts",
"generate:artifact-schemas": "node scripts/generate-artifact-schemas.ts",
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
"generate:supply-chain": "node scripts/generate-supply-chain.ts",
"verify:local-evidence": "node scripts/verify-release-candidate.ts && node scripts/verify-release.ts && node scripts/verify-supply-chain-artifacts.ts && node scripts/verify-archived-local-evidence.ts && node scripts/verify-release-candidate.ts",
"verify:promotion": "node scripts/verify-exact-promotion-bundle.ts",
"generate:artifact-schemas": "node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts",
"check:artifact-schemas": "node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"generate:supply-chain": "node scripts/generate-product-feature-index.ts && node scripts/generate-supply-chain.ts",
"verify:local-evidence": "node scripts/generate-product-feature-index.ts && node scripts/verify-release-candidate.ts && node scripts/verify-release.ts && node scripts/verify-supply-chain-artifacts.ts && node scripts/verify-archived-local-evidence.ts && node scripts/verify-release-candidate.ts",
"verify:promotion": "node scripts/generate-product-feature-index.ts && node scripts/verify-exact-promotion-bundle.ts",
"update:dependency-baseline": "node scripts/update-dependency-baseline.ts",
"check:supply-chain:fixtures": "node scripts/check-supply-chain-fixtures.ts",
"check:supply-chain:provider-fixtures": "node scripts/check-supply-chain-provider-fixtures.ts",
"verify:reproducible-build": "node scripts/verify-reproducible-build.ts",
"check:supply-chain:fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-supply-chain-fixtures.ts",
"check:supply-chain:provider-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-supply-chain-provider-fixtures.ts",
"verify:reproducible-build": "node scripts/generate-product-feature-index.ts && node scripts/verify-reproducible-build.ts",
"scan:security": "node scripts/security-scan.ts",
"scan:security:fixture": "node scripts/security-scan.ts --policy tests/fixtures/security/secret-detection/forbidden-policy.json --artifact artifacts/security/scan-fixture.sarif",
"check:security:fixtures": "node scripts/check-security-fixtures.ts",
"check:browser-security": "node scripts/check-browser-security.ts",
"check:browser-file-storage-boundaries": "node scripts/check-browser-file-storage-boundaries.ts",
"check:realtime-boundaries": "node scripts/check-realtime-boundaries.ts",
"check:realtime-boundaries": "node scripts/generate-product-feature-index.ts && node scripts/check-realtime-boundaries.ts",
"check:realtime-boundaries:fixture": "node scripts/check-realtime-boundary-fixtures.ts",
"check:optional-recipes": "node scripts/check-optional-recipes.ts --require-dist",
"check:optional-recipes:source": "node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/check-registries.ts",
"check:registries:structure": "node scripts/check-registries.ts --no-baseline",
"check:registries:compatibility-fixtures": "node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/check-registries.ts --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/check-compatibility.ts",
"verify:release": "node scripts/verify-release.ts",
"verify:hosting-headers": "node scripts/verify-hosting-headers.ts",
"check:bundle": "node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts",
"test:performance": "node scripts/test-performance.ts",
"collect:web-vitals-evidence": "node scripts/collect-web-vitals-evidence.ts",
"drill:runbook": "node scripts/drill-runbook.ts",
"check:optional-recipes": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts --require-dist",
"check:optional-recipes:source": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipes.ts",
"check:optional-recipe-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-optional-recipe-fixtures.ts",
"check:registries": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts",
"check:registries:structure": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --no-baseline",
"check:registries:compatibility-fixtures": "node scripts/generate-product-feature-index.ts && node scripts/check-registry-compatibility-fixtures.ts",
"check:registries:baseline-fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --approval tests/fixtures/registry/compatibility/tampered-approval.json --artifact artifacts/quality/registry-baseline-fixture.json",
"check:registries:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
"check:routes:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-registries.ts --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
"verify:compatibility": "node scripts/generate-product-feature-index.ts && node scripts/check-compatibility.ts",
"verify:release": "node scripts/generate-product-feature-index.ts && node scripts/verify-release.ts",
"verify:hosting-headers": "node scripts/generate-product-feature-index.ts && node scripts/verify-hosting-headers.ts",
"check:bundle": "node scripts/generate-product-feature-index.ts && node scripts/generate-supply-chain.ts && node scripts/check-bundle.ts",
"test:performance": "node scripts/generate-product-feature-index.ts && node scripts/test-performance.ts",
"collect:web-vitals-evidence": "node scripts/generate-product-feature-index.ts && node scripts/collect-web-vitals-evidence.ts",
"drill:runbook": "node scripts/generate-product-feature-index.ts && node scripts/drill-runbook.ts",
"drill:runbooks": "corepack pnpm drill:runbook -- FE-RB-001 && corepack pnpm drill:runbook -- FE-RB-002 && corepack pnpm drill:runbook -- FE-RB-003 && corepack pnpm drill:runbook -- FE-RB-004 && corepack pnpm drill:runbook -- FE-RB-005",
"ci:gate": "node scripts/run-ci-gate.ts",
"ci:gate": "node scripts/generate-product-feature-index.ts && node scripts/run-ci-gate.ts",
"generate:ci-workflow": "node scripts/generate-ci-workflow.ts",
"check:ci-workflow": "node scripts/generate-ci-workflow.ts --check",
"check:ci": "corepack pnpm check:artifact-schemas && node scripts/check-ci-contract.ts && corepack pnpm check:ci-workflow",
"verify:documentation": "node scripts/verify-documentation-readiness.ts",
"build:app-only": "vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-contract-set.ts",
"verify:documentation": "node scripts/generate-product-feature-index.ts && node scripts/verify-documentation-readiness.ts",
"build:app-only": "node scripts/generate-product-feature-index.ts && vite build && node scripts/generate-build-manifest.ts",
"generate:contract-set": "node scripts/generate-product-feature-index.ts && node scripts/generate-contract-set.ts",
"check:types:web-worker": "tsc --project tsconfig.web-worker.json",
"check:types:service-worker": "tsc --project tsconfig.service-worker.json",
"check:types:fixture:http-operation-input": "tsc -p tests/fixtures/typecheck/tsconfig.http-operation-input.json",
+9 -1
View File
@@ -201,7 +201,15 @@ async function main(): Promise<void> {
// 23 → 22: `storage/indexeddb/indexeddb-maintenance.ts`가 같은 이유로 지웠다.
// 22 → 21: `storage/indexeddb/indexeddb-runtime.ts`가 같은 이유로 지웠다.
// 이것으로 IndexedDB 어댑터 4벌이 모두 커널을 쓴다.
const HAND_ROLLED_ABORT_CEILING = 21;
// 21 → 19: `browser-files/download-delivery-adapter.ts`와
// `browser-files/browser-file-vault.ts`가 커널 race로 옮겨갔다(Q-6.2-7).
// 19 → 18: `browser-file-storage/storage-manager-adapter.ts`의 inspection
// 대기가 커널 race로 옮겨갔다(Q-B).
// 17 → 16: `browser-transfer/image-cdn/image-cdn-runtime.ts`의 검증 deadline과
// probe 대기가 커널 operation으로 옮겨갔다(R3-2).
// 16 → 15: `browser-files/browser-file-picker.ts`의 native input 대기와
// system picker 대기가 커널 operation으로 옮겨갔다(R3-2).
const HAND_ROLLED_ABORT_CEILING = 15;
const handRolledScan = spawnSync(
"git",
["grep", "-l", 'addEventListener("abort"', "--", "src/adapters"],
+1 -1
View File
@@ -1,6 +1,6 @@
import { readFile } from "node:fs/promises";
import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.ts";
import { evaluateBundleBudget } from "./lib/performance-budgets.ts";
import {
bundleOutputInventoryArtifactSchema,
bundlePerformanceArtifactSchema,
+1 -1
View File
@@ -5,7 +5,7 @@ import {
evaluatePromotionReadiness,
PROMOTION_FORMULA,
type GateResult,
} from "../src/application/policies/promotion-readiness.ts";
} from "./lib/promotion-readiness.ts";
import {
loadCiGateContract,
indexCiGateContract,
+7 -1
View File
@@ -28,8 +28,14 @@ for (const [layer, file, tokens] of tokenLayers) {
}
}
// theme.css only imports the files under styles/theme/, so check them all.
const styleFiles = (
await readdir("src/presentation/styles", { recursive: true })
)
.filter((file) => file.endsWith(".css"))
.map((file) => path.join("src/presentation/styles", file));
const cssSources = await Promise.all(
[...Object.values(tokenFiles), "src/presentation/styles/theme.css"].map(
[...Object.values(tokenFiles), ...styleFiles].map(
async (file) => ({ file, source: await readFile(file, "utf8") }),
),
);
+1 -1
View File
@@ -3,7 +3,7 @@ import { mkdir, readFile } from "node:fs/promises";
import {
evaluateFieldBudget,
percentile75,
} from "../src/application/policies/performance-budgets.ts";
} from "./lib/performance-budgets.ts";
import { fieldWebVitalsArtifactSchema } from "./contracts/release-artifacts.ts";
import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
+5 -2
View File
@@ -4,7 +4,7 @@ import path from "node:path";
import { z } from "zod";
import { PROMOTION_FORMULA } from "../../src/application/policies/promotion-readiness.ts";
import { PROMOTION_FORMULA } from "../lib/promotion-readiness.ts";
import {
RELEASE_CANDIDATE_EVIDENCE_PATHS,
RELEASE_CANDIDATE_MANIFEST_PATH,
@@ -573,7 +573,10 @@ export async function loadCiGateContract(
throw new TypeError("check:ci must use the exact canonical non-recursive orchestration");
}
const canonicalCheckCiDependencies = {
"check:artifact-schemas": "node scripts/generate-artifact-schemas.ts --check",
// R-0. The schema generator imports src, which loads the gitignored
// product index, so the index is rendered first.
"check:artifact-schemas":
"node scripts/generate-product-feature-index.ts && node scripts/generate-artifact-schemas.ts --check",
"check:ci-workflow": mode === "canonical"
? "node scripts/generate-ci-workflow.ts --check"
: "node scripts/generate-ci-workflow.ts --check --reduced-removal-fixture",
+2 -1
View File
@@ -10,6 +10,7 @@ import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import {
HASHED_STATIC_ASSET_NAME,
SERVICE_WORKER_BOUNDS,
SERVICE_WORKER_SCRIPT_PATH,
type StaticAssetManifestV1,
@@ -38,7 +39,7 @@ const EXCLUDED_FILES: ReadonlySet<string> = new Set([
]);
/** Vite emits content-hashed names; only those may be treated as immutable. */
const HASHED_NAME = /-[A-Za-z0-9_-]{8,}\.[a-z0-9]+$/;
const HASHED_NAME = HASHED_STATIC_ASSET_NAME;
export async function collectStaticAssets(
distDirectory: string,
+27
View File
@@ -1,4 +1,31 @@
import type { InstalledServiceWorkerSelection } from "../../src/contracts/service-worker.ts";
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
const PUBLIC_SERVICE_WORKER = /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i;
/**
* A built `dist` may ship a worker script only when the static selection is
* `ACTIVE`, and then only the selected script at the app root.
*/
export function checkPublicServiceWorkers(
distFiles: readonly string[],
selection: InstalledServiceWorkerSelection | null,
) {
const found = distFiles.filter((file) => PUBLIC_SERVICE_WORKER.test(file));
const allowed: string[] =
selection?.mode === "ACTIVE" ? [selection.scriptPath] : [];
const passed =
found.length === allowed.length &&
found.every((file) => allowed.includes(file));
return {
surface: "serviceWorker",
header: "enabled",
expected: allowed.length > 0,
observed: found.length > 0,
passed,
...(passed ? {} : { reason: `dist worker scripts: ${found.join(", ") || "none"}` }),
};
}
/**
* A release gate must not promote a local preview server as live hosting
+12
View File
@@ -47,6 +47,18 @@ for (const key of [
delete testEnvironment[key];
}
// src/.generated is gitignored; every suite imports the product index, so a
// fresh checkout must render it before Vitest resolves the module graph.
const generated = spawnSync(
process.execPath,
[fileURLToPath(new URL("./generate-product-feature-index.ts", import.meta.url))],
{ stdio: "inherit", env: testEnvironment },
);
if (generated.status !== 0) {
process.stderr.write("Product feature index generation failed.\n");
process.exit(generated.status ?? 1);
}
const result = spawnSync(
process.execPath,
[vitestEntry, ...process.argv.slice(2)],
+1 -1
View File
@@ -5,7 +5,7 @@ import process from "node:process";
import { chromium } from "@playwright/test";
import { evaluateLabBudget } from "../src/application/policies/performance-budgets.ts";
import { evaluateLabBudget } from "./lib/performance-budgets.ts";
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
import { labPerformanceArtifactSchema } from "./contracts/release-artifacts.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
+11 -13
View File
@@ -1,7 +1,11 @@
import { mkdir, readFile, readdir } from "node:fs/promises";
import { INSTALLED_RUNTIME_CAPABILITIES } from "../src/features/installed-runtime-capabilities.ts";
import { hostingHeadersArtifactSchema } from "./contracts/release-artifacts.ts";
import { classifyLiveHostingBaseUrl } from "./lib/hosting-probe.ts";
import {
checkPublicServiceWorkers,
classifyLiveHostingBaseUrl,
} from "./lib/hosting-probe.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
type Document = Record<string, unknown>;
@@ -63,9 +67,6 @@ const baseUrl = process.env.HOSTING_BASE_URL;
const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null;
const distFiles = (await readdir("dist", { recursive: true })).map(String);
const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map"));
const publicServiceWorkers = distFiles.filter((file) =>
/(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i.test(file),
);
let responses: ResponseHeaders = {};
let mode: HostingMode;
@@ -184,15 +185,12 @@ results.push({
observed: publicSourceMaps.length > 0,
passed: sourceMapPolicy.public === false && publicSourceMaps.length === 0,
});
const serviceWorkerPolicy = recordValue(cacheSurfaces.serviceWorker);
results.push({
surface: "serviceWorker",
header: "enabled",
expected: false,
observed: publicServiceWorkers.length > 0,
passed:
serviceWorkerPolicy.enabled === false && publicServiceWorkers.length === 0,
});
results.push(
checkPublicServiceWorkers(
distFiles,
INSTALLED_RUNTIME_CAPABILITIES.serviceWorker,
),
);
const passed = results.every((result) => result.passed);
await mkdir("artifacts/release", { recursive: true });
@@ -9,6 +9,11 @@ import { CREDENTIAL_HEADER_NAMES } from "../../contracts/rest-profiles.ts";
export type ExternalSessionOwner = Readonly<{
readState(): SessionState;
/**
* Opaque, stable per-user id, never a token; see `SessionGateway.getSubject`.
* Without it every authenticated notification clears server state.
*/
readSubject?(): string | null;
subscribe(listener: () => void): () => void;
beginSignIn(returnTo?: string): Promise<void>;
signOut(): Promise<void>;
@@ -35,6 +40,8 @@ export function validateCredentialPatch(value: unknown): CredentialPatch {
for (const [name, headerValue] of Object.entries(headers)) {
const normalizedName = name.toLowerCase();
if (
// Names that differ only in case would silently overwrite each other.
Object.hasOwn(projected, normalizedName) ||
!ALLOWED_CREDENTIAL_HEADERS.has(normalizedName) ||
typeof headerValue !== "string" ||
headerValue.length === 0 ||
@@ -53,6 +60,7 @@ export function createExternalAuthSessionAdapter(
): AuthSessionPort {
return Object.freeze({
getState: () => owner.readState(),
getSubject: () => owner.readSubject?.() ?? null,
subscribe: (listener) => owner.subscribe(listener),
beginSignIn: (returnTo) => owner.beginSignIn(returnTo),
signOut: () => owner.signOut(),
@@ -101,6 +109,9 @@ const DEMO_PATCH = Object.freeze({
headers: Object.freeze({ authorization: DEMO_AUTHORIZATION_MARKER }),
});
/** The one demo user. A stable subject lets a re-notification keep the cache. */
const DEMO_SUBJECT = "demo-user";
export function createDemoSessionAdapter(
initialState: SessionState = "unauthenticated",
demoPatch: CredentialPatch = DEMO_PATCH,
@@ -109,11 +120,15 @@ export function createDemoSessionAdapter(
let state = initialState;
const listeners = new Set<() => void>();
const setState = (next: SessionState) => {
// A notification means "the session changed"; repeating the same value
// would make every subscriber redo its work for nothing.
if (next === state) return;
state = next;
for (const listener of listeners) listener();
};
return Object.freeze({
getState: () => state,
getSubject: () => (state === "authenticated" ? DEMO_SUBJECT : null),
subscribe(listener) {
listeners.add(listener);
return () => listeners.delete(listener);
@@ -8,6 +8,7 @@ import {
browserDataSuccess,
mapBrowserDataException,
} from "./result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
export type StorageManagerFacade = Readonly<{
estimate(): Promise<Readonly<{ usage?: number; quota?: number }>>;
@@ -155,48 +156,22 @@ function snapshotPressurePolicy(
return snapshot;
}
/**
* The kernel race: a caller abort ends the wait, and a native call that settles
* afterwards — including one that rejects — is consumed rather than leaked.
*/
async function awaitStorageInspection<Value>(
inspection: Promise<Value>,
signal: AbortSignal | undefined,
): Promise<Value | typeof STORAGE_INSPECTION_ABORTED> {
if (!signal) return await inspection;
if (signal.aborted) {
// The native calls have already been invoked. Consume a later rejection
// even though the caller no longer waits for their result.
void inspection.catch(() => undefined);
return STORAGE_INSPECTION_ABORTED;
const operation = createAbortableOperation({ signal });
try {
const raced = await operation.race(inspection);
if (raced.kind === "REJECTED") throw raced.reason;
return raced.kind === "VALUE" ? raced.value : STORAGE_INSPECTION_ABORTED;
} finally {
operation.close();
}
return await new Promise<Value | typeof STORAGE_INSPECTION_ABORTED>(
(resolve, reject) => {
let settled = false;
const finish = (
outcome:
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "ABORTED" }>
| Readonly<{ kind: "ERROR"; error: unknown }>,
): void => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
if (outcome.kind === "VALUE") {
resolve(outcome.value);
} else if (outcome.kind === "ABORTED") {
resolve(STORAGE_INSPECTION_ABORTED);
} else {
reject(outcome.error);
}
};
const onAbort = (): void => finish({ kind: "ABORTED" });
signal.addEventListener("abort", onAbort, { once: true });
inspection.then(
(value) => finish({ kind: "VALUE", value }),
(error: unknown) => finish({ kind: "ERROR", error }),
);
if (signal.aborted) onAbort();
},
);
}
async function inspectPersistenceState(
+106 -106
View File
@@ -23,6 +23,7 @@ import {
} from "./file-observer.ts";
import type { RegisteredFileSelectionPolicy } from "./file-policy.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
type UserActivationState = Readonly<{ isActive: boolean }>;
@@ -54,7 +55,8 @@ interface DisposableFilePicker extends FilePickerPort {
/**
* Focus can return before some engines dispatch the file input change event.
* This grace keeps the fallback from misclassifying a real selection as a
* dismissal. The native cancel event remains authoritative and immediate.
* dismissal. The native cancel event remains authoritative and immediate, and
* once a picker has seen it the fallback is no longer installed.
*/
export const DEFAULT_NATIVE_PICKER_FOCUS_GRACE_MS = 1_000;
@@ -97,6 +99,12 @@ export class NativeInputFilePicker implements DisposableFilePicker {
#pending = false;
#disposed = false;
#abortPending: (() => void) | undefined;
/**
* Q-6.2-8. Once this engine has dispatched a native `cancel`, dismissal is
* reported natively, so the focus heuristic would only turn a slow `change`
* (a cloud provider still fetching the file) into a false dismissal.
*/
#nativeCancelObserved = false;
constructor(options: NativeInputFilePickerOptions) {
this.#input = options.input;
@@ -200,23 +208,25 @@ export class NativeInputFilePicker implements DisposableFilePicker {
try {
request = snapshotSelectionRequest(input);
} catch {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("INVALID_INPUT", "FILE_SELECT"),
);
}
if (this.#disposed) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("UNAVAILABLE", "FILE_SELECT"),
);
}
const cancelled = abortedResult(request.signal, "FILE_SELECT");
if (cancelled) return this.#finishObservation(cancelled);
if (cancelled) return observeSelection(this.#observer, cancelled);
const resolvedPolicy = this.#resolveSelection(
request.policy,
request.limits,
);
if (!resolvedPolicy.ok) {
return this.#finishObservation(resolvedPolicy);
return observeSelection(this.#observer, resolvedPolicy);
}
const policy = resolvedPolicy.value;
if (
@@ -225,17 +235,20 @@ export class NativeInputFilePicker implements DisposableFilePicker {
this.#inputEvents.getAttribute,
)
) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("INVALID_INPUT", "FILE_SELECT"),
);
}
if (this.#pending) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("BLOCKED", "FILE_SELECT"),
);
}
if (this.#userActivation && !this.#userActivation.isActive) {
return this.#finishObservation(
return observeSelection(
this.#observer,
browserDataFailure("PERMISSION_DENIED", "FILE_SELECT"),
);
}
@@ -248,6 +261,8 @@ export class NativeInputFilePicker implements DisposableFilePicker {
let settled = false;
let focusTimer: unknown;
const signal = request.signal;
// The kernel operation owns the caller signal listener.
const operation = createAbortableOperation({ signal });
const finish = (
outcome: BrowserDataResult<FileSelectionOutcome>,
): void => {
@@ -255,7 +270,7 @@ export class NativeInputFilePicker implements DisposableFilePicker {
settled = true;
this.#inputEvents.remove("change", onChange);
this.#inputEvents.remove("cancel", onCancel);
signal?.removeEventListener("abort", onAbort);
operation.close();
this.#windowEvents?.remove("focus", onWindowFocus);
if (focusTimer !== undefined) {
this.#scheduler.clearTimeout(focusTimer);
@@ -293,9 +308,10 @@ export class NativeInputFilePicker implements DisposableFilePicker {
: captured,
);
};
const onCancel = (): void => dismiss();
const onAbort = (): void =>
finish(browserDataFailure("ABORTED", "FILE_SELECT"));
const onCancel = (): void => {
this.#nativeCancelObserved = true;
dismiss();
};
const abortPending = (): void =>
finish(browserDataFailure("ABORTED", "FILE_SELECT"));
const onWindowFocus = (): void => {
@@ -318,8 +334,11 @@ export class NativeInputFilePicker implements DisposableFilePicker {
this.#inputEvents.add("change", onChange, { once: true });
this.#inputEvents.add("cancel", onCancel, { once: true });
signal?.addEventListener("abort", onAbort, { once: true });
this.#windowEvents?.add("focus", onWindowFocus);
// Settles only when the operation ends; after `finish` this is a no-op.
void operation.race(new Promise<never>(() => {})).then(abortPending);
if (!this.#nativeCancelObserved) {
this.#windowEvents?.add("focus", onWindowFocus);
}
this.#abortPending = abortPending;
try {
this.#input.accept = pickerAcceptValue(policy);
@@ -332,9 +351,10 @@ export class NativeInputFilePicker implements DisposableFilePicker {
}
},
);
return this.#finishObservation(result);
return observeSelection(this.#observer, result);
} catch (error) {
return this.#finishObservation(
return observeSelection(
this.#observer,
mapBrowserDataException(error, "FILE_SELECT"),
);
} finally {
@@ -356,33 +376,6 @@ export class NativeInputFilePicker implements DisposableFilePicker {
// Some test doubles or constrained DOM hosts expose a readonly value.
}
}
#finishObservation(
result: BrowserDataResult<FileSelectionOutcome>,
): BrowserDataResult<FileSelectionOutcome> {
if (result.ok) {
const dismissed = result.value.kind === "DISMISSED";
const bytes =
result.value.kind === "SELECTED"
? result.value.files.reduce(
(total, candidate) => total + candidate.sizeBytes,
0,
)
: null;
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: dismissed ? "DISMISSED" : "SUCCESS",
byteBucket: byteBucket(bytes),
});
} else {
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "FAILED",
failureCode: result.error.code,
});
}
return result;
}
}
export type SystemOpenPickerAcceptType = Readonly<{
@@ -431,8 +424,11 @@ export class EnhancedFilePicker implements DisposableFilePicker {
if (typeof options.showOpenFilePicker !== "function") {
throw new TypeError("Enhanced file picker API is invalid.");
}
// Bound to undefined, not to options: `window.showOpenFilePicker` throws
// "Illegal invocation" for any other receiver, and Web IDL maps an
// undefined receiver to the global object.
this.#showOpenFilePicker =
options.showOpenFilePicker.bind(options);
options.showOpenFilePicker.bind(undefined);
this.#captureHandles =
options.vault.captureHandles.bind(options.vault);
this.#releaseFile = options.vault.release.bind(options.vault);
@@ -457,30 +453,36 @@ export class EnhancedFilePicker implements DisposableFilePicker {
try {
request = snapshotSelectionRequest(input);
} catch {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("INVALID_INPUT", "FILE_SELECT"),
);
}
if (this.#disposed) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("UNAVAILABLE", "FILE_SELECT"),
);
}
const cancelled = abortedResult(request.signal, "FILE_SELECT");
if (cancelled) return this.#observe(cancelled);
if (cancelled) return observeSelection(this.#observer, cancelled);
const resolvedPolicy = this.#resolveSelection(
request.policy,
request.limits,
);
if (!resolvedPolicy.ok) return this.#observe(resolvedPolicy);
if (!resolvedPolicy.ok) {
return observeSelection(this.#observer, resolvedPolicy);
}
const policy = resolvedPolicy.value;
if (this.#pending) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("BLOCKED", "FILE_SELECT"),
);
}
if (this.#userActivation && !this.#userActivation.isActive) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("PERMISSION_DENIED", "FILE_SELECT"),
);
}
@@ -496,9 +498,10 @@ export class EnhancedFilePicker implements DisposableFilePicker {
request.signal,
);
const aborted = abortedResult(request.signal, "FILE_SELECT");
if (aborted) return this.#observe(aborted);
if (aborted) return observeSelection(this.#observer, aborted);
if (handles.length === 0) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataSuccess(
Object.freeze({ kind: "DISMISSED" as const }),
),
@@ -509,7 +512,8 @@ export class EnhancedFilePicker implements DisposableFilePicker {
policy,
request.signal ?? new AbortController().signal,
);
return this.#observe(
return observeSelection(
this.#observer,
captured.ok
? browserDataSuccess(
Object.freeze({
@@ -521,20 +525,23 @@ export class EnhancedFilePicker implements DisposableFilePicker {
);
} catch (error) {
if (error instanceof PickerDisposedError) {
return this.#observe(
return observeSelection(
this.#observer,
browserDataFailure("ABORTED", "FILE_SELECT"),
);
}
if (error instanceof DOMException && error.name === "AbortError") {
const aborted = abortedResult(input.signal, "FILE_SELECT");
if (aborted) return this.#observe(aborted);
return this.#observe(
if (aborted) return observeSelection(this.#observer, aborted);
return observeSelection(
this.#observer,
browserDataSuccess(
Object.freeze({ kind: "DISMISSED" as const }),
),
);
}
return this.#observe(
return observeSelection(
this.#observer,
mapBrowserDataException(error, "FILE_SELECT"),
);
} finally {
@@ -561,59 +568,52 @@ export class EnhancedFilePicker implements DisposableFilePicker {
new DOMException("Picker aborted", "AbortError"),
);
}
return new Promise((resolve, reject) => {
let settled = false;
const finish = (callback: () => void): void => {
if (settled) return;
settled = true;
signal?.removeEventListener("abort", onAbort);
if (this.#abortPending === abortPending) {
this.#abortPending = undefined;
}
callback();
};
const abortPending = (): void =>
finish(() => reject(new PickerDisposedError()));
const onAbort = (): void =>
finish(() =>
reject(new DOMException("Picker aborted", "AbortError")),
);
this.#abortPending = abortPending;
signal?.addEventListener("abort", onAbort, { once: true });
picker.then(
(handles) => finish(() => resolve(handles)),
(error: unknown) => finish(() => reject(error)),
);
const operation = createAbortableOperation({ signal });
const abortPending = (): void => operation.close();
this.#abortPending = abortPending;
return operation.race(picker).then((outcome) => {
if (this.#abortPending === abortPending) {
this.#abortPending = undefined;
}
operation.close();
if (outcome.kind === "VALUE") return outcome.value;
throw outcome.kind === "REJECTED"
? outcome.reason
: outcome.terminal === "CALLER_ABORT"
? new DOMException("Picker aborted", "AbortError")
: new PickerDisposedError();
});
}
}
#observe(
result: BrowserDataResult<FileSelectionOutcome>,
): BrowserDataResult<FileSelectionOutcome> {
if (!result.ok) {
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "FAILED",
failureCode: result.error.code,
});
} else if (result.value.kind === "DISMISSED") {
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "DISMISSED",
});
} else {
const bytes = result.value.files.reduce(
(total, file) => total + file.sizeBytes,
0,
);
observeBrowserFile(this.#observer, {
operation: "FILE_SELECT",
outcome: "SUCCESS",
byteBucket: byteBucket(bytes),
});
}
return result;
/** One observation per terminal selection result, shared by both pickers. */
function observeSelection(
observer: BrowserFileObserver | undefined,
result: BrowserDataResult<FileSelectionOutcome>,
): BrowserDataResult<FileSelectionOutcome> {
if (!result.ok) {
observeBrowserFile(observer, {
operation: "FILE_SELECT",
outcome: "FAILED",
failureCode: result.error.code,
});
} else if (result.value.kind === "DISMISSED") {
observeBrowserFile(observer, {
operation: "FILE_SELECT",
outcome: "DISMISSED",
});
} else {
const bytes = result.value.files.reduce(
(total, file) => total + file.sizeBytes,
0,
);
observeBrowserFile(observer, {
operation: "FILE_SELECT",
outcome: "SUCCESS",
byteBucket: byteBucket(bytes),
});
}
return result;
}
function pickerAcceptValue(
@@ -14,6 +14,8 @@ import {
import {
assertFileInspectionPolicy,
assertFileSelectionPolicy,
EXACT_MEDIA_TYPE,
isPositiveSafeInteger,
sanitizeSuggestedFileName,
type RegisteredFileInspectionPolicy,
type RegisteredFileSelectionPolicy,
@@ -81,8 +83,6 @@ type SnapshotProfile = Readonly<{
}>;
const POLICY_TOKEN = /^[a-z0-9][a-z0-9._:-]{0,127}$/i;
const MEDIA_TYPE =
/^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
const ISSUED_POLICY_REFERENCES = new WeakSet<object>();
/**
@@ -417,7 +417,7 @@ function snapshotPreview(
hardMaxPreviewBytes: number,
): SnapshotProfile["preview"] {
if (
!positiveSafeInteger(input.maxPreviewBytes) ||
!isPositiveSafeInteger(input.maxPreviewBytes) ||
input.maxPreviewBytes > hardMaxPreviewBytes ||
!Array.isArray(input.allowedMediaTypes) ||
input.allowedMediaTypes.length < 1 ||
@@ -428,7 +428,7 @@ function snapshotPreview(
const allowedMediaTypes = new Set<string>();
for (const inputMediaType of input.allowedMediaTypes) {
const mediaType = inputMediaType.trim().toLowerCase();
if (!MEDIA_TYPE.test(mediaType)) {
if (!EXACT_MEDIA_TYPE.test(mediaType)) {
throw new TypeError("File preview media type is invalid.");
}
allowedMediaTypes.add(mediaType);
@@ -451,9 +451,9 @@ function snapshotDownload(
"PROMPT_AND_STREAM",
"BOUNDED_OBJECT_URL",
].includes(input.strategy) ||
!MEDIA_TYPE.test(mediaType) ||
!positiveSafeInteger(input.maxTransferBytes) ||
!positiveSafeInteger(input.maxBufferedBytes) ||
!EXACT_MEDIA_TYPE.test(mediaType) ||
!isPositiveSafeInteger(input.maxTransferBytes) ||
!isPositiveSafeInteger(input.maxBufferedBytes) ||
input.maxTransferBytes > hardLimits.maxTransferBytes ||
input.maxBufferedBytes > input.maxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
@@ -478,11 +478,11 @@ function assertHardLimits(
input: BrowserFilePolicyRegistryOptions["hardLimits"],
): void {
if (
!positiveSafeInteger(input.maxInspectionBytes) ||
!positiveSafeInteger(input.maxRetainedFileBytes) ||
!positiveSafeInteger(input.maxPreviewBytes) ||
!positiveSafeInteger(input.maxObjectUrlBytes) ||
!positiveSafeInteger(input.maxTransferBytes) ||
!isPositiveSafeInteger(input.maxInspectionBytes) ||
!isPositiveSafeInteger(input.maxRetainedFileBytes) ||
!isPositiveSafeInteger(input.maxPreviewBytes) ||
!isPositiveSafeInteger(input.maxObjectUrlBytes) ||
!isPositiveSafeInteger(input.maxTransferBytes) ||
input.maxObjectUrlBytes > input.maxTransferBytes
) {
throw new TypeError("Browser file policy hard limits are invalid.");
@@ -497,7 +497,7 @@ function reducedLimit(
if (requested === undefined) {
return browserDataSuccess(configured);
}
if (!positiveSafeInteger(requested)) {
if (!isPositiveSafeInteger(requested)) {
return browserDataFailure("INVALID_INPUT", operation);
}
if (requested > configured) {
@@ -520,7 +520,3 @@ function referenceKey(reference: FilePolicyReference): string {
reference.intention,
]);
}
function positiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
@@ -19,10 +19,16 @@ import {
browserDataSuccess,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
createAbortableOperation,
type AbortableOperation,
} from "../platform/abortable-operation.ts";
import {
assertFileInspectionPolicy,
assertFileSelectionPolicy,
findMatchingSignature,
isPositiveSafeInteger,
isSafeGeneratedToken,
matchesSelectionHint,
normalizedExtension,
signatureMetadataMatches,
@@ -119,7 +125,8 @@ export class BrowserFileVault
readonly #observer: BrowserFileObserver | undefined;
readonly #resolveInspection:
BrowserFilePolicyRegistry["resolveInspection"];
readonly #lifetime = new AbortController();
/** Open streams; dispose() closes each, which ends its pending read. */
readonly #streams = new Set<AbortableOperation>();
#disposed = false;
#retainedBytes = 0;
@@ -504,15 +511,12 @@ export class BrowserFileVault
signal: AbortSignal,
): AsyncIterable<BrowserDataResult<Uint8Array>> {
let transferred = 0;
const combined = combineAbortSignals(
signal,
vault.#lifetime.signal,
);
// Q-6.2-7. The kernel owner joins the caller signal and dispose().
const owner = createAbortableOperation({ signal });
if (vault.#disposed) owner.close();
else vault.#streams.add(owner);
try {
for await (const chunk of streamNativeFile(
file,
combined.signal,
)) {
for await (const chunk of streamNativeFile(file, owner)) {
transferred += chunk.byteLength;
yield browserDataSuccess(chunk);
}
@@ -533,7 +537,8 @@ export class BrowserFileVault
vault.#observeFailureResult(failure);
yield failure;
} finally {
combined.release();
vault.#streams.delete(owner);
owner.close();
}
},
});
@@ -620,7 +625,8 @@ export class BrowserFileVault
dispose(): void {
if (this.#disposed) return;
this.#disposed = true;
this.#lifetime.abort();
for (const stream of this.#streams) stream.close();
this.#streams.clear();
this.#verifications.clear();
this.#verificationReceiptsByRef.clear();
this.#records.clear();
@@ -681,7 +687,7 @@ export class BrowserFileVault
return browserDataFailure("LIMIT_EXCEEDED", "FILE_SELECT");
}
const refValue = this.#createReference();
if (!safeOpaqueValue(refValue)) {
if (!isSafeGeneratedToken(refValue)) {
return browserDataFailure("UNAVAILABLE", "FILE_SELECT");
}
const ref = refValue as LocalFileRef;
@@ -716,7 +722,7 @@ export class BrowserFileVault
#issueVerification(record: VerificationRecord):
BrowserDataResult<FileVerificationReceipt> {
const receiptValue = this.#createVerificationReceipt();
if (!safeOpaqueValue(receiptValue)) {
if (!isSafeGeneratedToken(receiptValue)) {
return browserDataFailure("UNAVAILABLE", "FILE_INSPECT");
}
const receipt = receiptValue as FileVerificationReceipt;
@@ -810,21 +816,20 @@ function snapshotSystemFileHandles(
async function* streamNativeFile(
file: File,
signal: AbortSignal,
owner: AbortableOperation,
): AsyncIterable<Uint8Array> {
if (signal.aborted) throw abortException();
if (owner.signal.aborted) throw abortException();
const reader = file.stream().getReader();
const abort = () => {
void reader.cancel(abortException()).catch(() => {});
};
signal.addEventListener("abort", abort, { once: true });
let transferred = 0;
let completed = false;
try {
while (true) {
if (signal.aborted) throw abortException();
const result = await reader.read();
if (signal.aborted) throw abortException();
const raced = await owner.race(reader.read());
if (raced.kind === "REJECTED") throw raced.reason;
if (raced.kind === "TERMINAL" || owner.signal.aborted) {
throw abortException();
}
const result = raced.value;
if (result.done) break;
const chunk = result.value;
if (!(chunk instanceof Uint8Array)) {
@@ -844,12 +849,16 @@ async function* streamNativeFile(
}
completed = true;
} finally {
signal.removeEventListener("abort", abort);
if (!completed) {
try {
await reader.cancel();
// An aborted read never waits on the source's own cancel algorithm.
if (owner.signal.aborted) {
void reader.cancel(abortException()).catch(() => {});
} else {
await reader.cancel();
}
} catch {
// The stream may already be errored or cancelled by AbortSignal.
// The stream may already be errored.
}
}
reader.releaseLock();
@@ -861,35 +870,6 @@ function normalizedMediaType(value: string): string | null {
return normalized.length > 0 ? normalized : null;
}
function isPositiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
function safeOpaqueValue(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
function combineAbortSignals(
caller: AbortSignal,
lifetime: AbortSignal,
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abort = (): void => controller.abort();
if (caller.aborted || lifetime.aborted) {
controller.abort();
} else {
caller.addEventListener("abort", abort, { once: true });
lifetime.addEventListener("abort", abort, { once: true });
}
return Object.freeze({
signal: controller.signal,
release(): void {
caller.removeEventListener("abort", abort);
lifetime.removeEventListener("abort", abort);
},
});
}
function abortException(): DOMException {
return new DOMException("Operation aborted", "AbortError");
}
@@ -24,6 +24,7 @@ import {
type DownloadDeliveryAdapterOptions,
} from "./download-delivery-adapter.ts";
import type { BrowserFileObserver } from "./file-observer.ts";
import { isPositiveSafeInteger } from "./file-policy.ts";
import {
BrowserTransientPreview,
ObjectUrlLeaseRegistry,
@@ -239,7 +240,3 @@ function resolveRuntimeLimits(
}
return resolved;
}
function isPositiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
@@ -1,5 +1,4 @@
import type {
BrowserManagedDownloadCapability,
BrowserManagedDownloadCapabilityResolver,
DownloadDeliveryPort,
DownloadOutcome,
@@ -12,7 +11,6 @@ import type {
TransferProgress,
} from "../../application/ports/browser-file-storage/shared.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
PresignedDownloadSourcePort,
} from "../../application/ports/browser-transfer/presigned-transfer.ts";
@@ -22,23 +20,31 @@ import {
browserDataSuccess,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
createAbortableOperation,
type AbortableOperation,
} from "../platform/abortable-operation.ts";
import {
byteBucket,
observeBrowserFile,
type BrowserFileObserver,
} from "./file-observer.ts";
import {
sanitizeSuggestedFileName,
type SuggestedFileNamePolicy,
} from "./file-policy.ts";
import {
ObjectUrlLeaseRegistry,
type ObjectUrlLease,
} from "./object-url-lease.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { isPositiveSafeInteger, isSafeGeneratedToken } from "./file-policy.ts";
import {
BrowserFilePolicyRegistry,
type ResolvedDownloadPolicy,
} from "./browser-file-policy-registry.ts";
activeDeliveryInput,
resolveBrowserManagedTarget,
validByteSource,
validPresignedByteSource,
validateBrowserManagedCapability,
validateDownloadInput,
type DeliveryInput,
type DeliveryRequest,
} from "./download-input-validation.ts";
export type BrowserDownloadHost = Readonly<{
handoff(href: string, suggestedFileName: string): void;
@@ -134,9 +140,6 @@ export type DownloadDeliveryAdapterOptions = Readonly<{
observer?: BrowserFileObserver;
}>;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
const SHA256 = /^[a-f0-9]{64}$/i;
/**
* Keeps a one-shot Blob URL alive across browser download scheduling and
* process handoff. Runtime dispose() still revokes every active lease
@@ -170,7 +173,8 @@ export function createDownloadDeliveryAdapter(
options.baseOrigin ?? globalThis.location?.origin ?? "https://localhost";
const userActivation =
options.userActivation ?? globalThis.navigator?.userActivation;
const lifetime = new AbortController();
// Every delivery in flight; dispose() closes each, which aborts its signal.
const liveOperations = new Set<AbortableOperation>();
let disposed = false;
if (
@@ -178,8 +182,8 @@ export function createDownloadDeliveryAdapter(
progressMinIntervalMs < 0 ||
!Number.isSafeInteger(releaseDelayMs) ||
releaseDelayMs < 0 ||
!isPositiveByteLimit(options.hardMaxObjectUrlBytes) ||
!isPositiveByteLimit(options.hardMaxTransferBytes) ||
!isPositiveSafeInteger(options.hardMaxObjectUrlBytes) ||
!isPositiveSafeInteger(options.hardMaxTransferBytes) ||
options.hardMaxObjectUrlBytes > options.hardMaxTransferBytes ||
typeof options.host?.handoff !== "function" ||
typeof options.policies?.resolveDownload !== "function" ||
@@ -224,8 +228,11 @@ export function createDownloadDeliveryAdapter(
: {}),
...(originalShowSaveFilePicker
? {
// Bound to undefined, not to options: `window.showSaveFilePicker`
// throws "Illegal invocation" for any other receiver, and Web IDL
// maps an undefined receiver to the global object.
showSaveFilePicker:
originalShowSaveFilePicker.bind(options),
originalShowSaveFilePicker.bind(undefined),
}
: {}),
...(originalIntegrityVerifier
@@ -263,19 +270,23 @@ export function createDownloadDeliveryAdapter(
dependencies.observer,
);
}
const combined = combineAbortSignals(
input.signal,
lifetime.signal,
);
// Q-6.2-7. One owner per delivery: caller abort and dispose() both end
// it, and a lease or writable that lands after that is compensated by the
// kernel race instead of a hand-written listener pair.
const owner = createAbortableOperation({ signal: input.signal });
liveOperations.add(owner);
try {
return await deliverActive({ ...input, signal: combined.signal });
return await deliverActive({ ...input, signal: owner.signal }, owner);
} finally {
combined.release();
liveOperations.delete(owner);
owner.close();
}
}
async function deliverActive(input: DeliveryRequest):
Promise<BrowserDataResult<DownloadOutcome>> {
async function deliverActive(
input: DeliveryRequest,
owner: AbortableOperation,
): Promise<BrowserDataResult<DownloadOutcome>> {
const resolvedPolicy = resolveDownloadPolicy(
input.policy,
{
@@ -312,17 +323,10 @@ export function createDownloadDeliveryAdapter(
dependencies.observer,
);
}
let suggestedFileName: string;
// Q-6.2-10. Validation already sanitized the name; it is not redone.
const suggestedFileName = validation.value;
let transferId: string;
try {
suggestedFileName = sanitizeSuggestedFileName(
activeInput.suggestedFileName,
{
safeExtension: activeInput.safeExtension,
maxUtf8Bytes:
dependencies.filenameMaxUtf8Bytes,
} satisfies SuggestedFileNamePolicy,
);
transferId = createTransferId();
} catch {
return observeResult(
@@ -330,7 +334,7 @@ export function createDownloadDeliveryAdapter(
dependencies.observer,
);
}
if (!safeGeneratedToken(transferId)) {
if (!isSafeGeneratedToken(transferId)) {
return observeResult(
browserDataFailure("UNAVAILABLE", "DOWNLOAD"),
dependencies.observer,
@@ -355,6 +359,7 @@ export function createDownloadDeliveryAdapter(
if (activeInput.strategy === "PROMPT_AND_STREAM") {
return promptAndStream({
input: activeInput,
owner,
suggestedFileName,
transferId,
options: dependencies,
@@ -364,6 +369,7 @@ export function createDownloadDeliveryAdapter(
return boundedObjectUrlHandoff({
input: activeInput,
owner,
suggestedFileName,
transferId,
options: dependencies,
@@ -379,7 +385,8 @@ export function createDownloadDeliveryAdapter(
dispose(): void {
if (disposed) return;
disposed = true;
lifetime.abort();
for (const operation of liveOperations) operation.close();
liveOperations.clear();
objectUrls.dispose();
},
});
@@ -479,6 +486,7 @@ function browserManagedHandoff(context: Readonly<{
async function promptAndStream(context: Readonly<{
input: DeliveryInput;
owner: AbortableOperation;
suggestedFileName: string;
transferId: string;
options: DownloadDeliveryAdapterOptions;
@@ -539,10 +547,7 @@ async function promptAndStream(context: Readonly<{
let handle: SaveFileHandle;
try {
handle = await awaitWithSignal(
handlePromise,
context.input.signal,
);
handle = await raceOwner(context.owner, handlePromise);
} catch (error) {
if (
error instanceof DOMException &&
@@ -573,7 +578,7 @@ async function promptAndStream(context: Readonly<{
try {
const sourceResult = await resolveByteSource(
context.input,
context.input.signal,
context.owner,
context.options,
sourceHolder,
);
@@ -592,9 +597,14 @@ async function promptAndStream(context: Readonly<{
);
}
context.progress.report("PREPARING", 0, source.byteLength, true);
const writable = await awaitWithSignal(
const writable = await raceOwner(
context.owner,
handle.createWritable(),
context.input.signal,
// A writable that opens after the abort keeps a browser swap file
// until it is aborted.
(late) => {
void late.abort().catch(() => undefined);
},
);
const writer = writable.getWriter();
let committed = false;
@@ -603,7 +613,7 @@ async function promptAndStream(context: Readonly<{
try {
for await (const chunkResult of abortableFileChunks(
source,
context.input.signal,
context.owner,
)) {
if (!chunkResult.ok) {
throw new ClosedFileStreamError(chunkResult.error);
@@ -619,15 +629,12 @@ async function promptAndStream(context: Readonly<{
throw limitException();
}
if (verifier) {
await awaitWithSignal(
await raceOwner(
context.owner,
Promise.resolve(verifier.update(chunk)),
context.input.signal,
);
}
await awaitWithSignal(
writer.write(chunk),
context.input.signal,
);
await raceOwner(context.owner, writer.write(chunk));
transferred = next;
context.progress.report(
"TRANSFERRING",
@@ -644,9 +651,9 @@ async function promptAndStream(context: Readonly<{
true,
);
if (verifier) {
const verified = await awaitWithSignal(
const verified = await raceOwner(
context.owner,
Promise.resolve(verifier.verify()),
context.input.signal,
);
if (!verified) throw integrityException();
}
@@ -713,6 +720,7 @@ async function promptAndStream(context: Readonly<{
async function boundedObjectUrlHandoff(context: Readonly<{
input: DeliveryInput;
owner: AbortableOperation;
suggestedFileName: string;
transferId: string;
options: DownloadDeliveryAdapterOptions;
@@ -731,38 +739,38 @@ async function boundedObjectUrlHandoff(context: Readonly<{
);
}
const sourceHolder = createSourceHolder();
const sourceResult = await resolveByteSource(
context.input,
context.input.signal,
context.options,
sourceHolder,
);
if (!sourceResult.ok) {
closeHeldSource(sourceHolder);
return observeResult(sourceResult, context.options.observer);
}
const source = sourceResult.value;
if (
source.byteLength !== null &&
(source.byteLength > context.input.maxBufferedBytes ||
source.byteLength > context.input.maxTransferBytes)
) {
closeHeldSource(sourceHolder);
return observeResult(
browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"),
context.options.observer,
source.byteLength,
);
}
const chunks: ArrayBuffer[] = [];
let transferred = 0;
let lease: ObjectUrlLease | undefined;
try {
// Inside the try: an open that throws or is aborted must still resolve to
// a Result and reach the finally that closes the held lease.
const sourceResult = await resolveByteSource(
context.input,
context.owner,
context.options,
sourceHolder,
);
if (!sourceResult.ok) {
return observeResult(sourceResult, context.options.observer);
}
const source = sourceResult.value;
if (
source.byteLength !== null &&
(source.byteLength > context.input.maxBufferedBytes ||
source.byteLength > context.input.maxTransferBytes)
) {
return observeResult(
browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD"),
context.options.observer,
source.byteLength,
);
}
context.progress.report("PREPARING", 0, source.byteLength, true);
for await (const chunkResult of abortableFileChunks(
source,
context.input.signal,
context.owner,
)) {
if (!chunkResult.ok) {
throw new ClosedFileStreamError(chunkResult.error);
@@ -779,9 +787,9 @@ async function boundedObjectUrlHandoff(context: Readonly<{
throw limitException();
}
if (verifier) {
await awaitWithSignal(
await raceOwner(
context.owner,
Promise.resolve(verifier.update(chunk)),
context.input.signal,
);
}
const copy = chunk.slice();
@@ -801,9 +809,9 @@ async function boundedObjectUrlHandoff(context: Readonly<{
true,
);
if (verifier) {
const verified = await awaitWithSignal(
const verified = await raceOwner(
context.owner,
Promise.resolve(verifier.verify()),
context.input.signal,
);
if (!verified) throw integrityException();
}
@@ -854,168 +862,14 @@ async function boundedObjectUrlHandoff(context: Readonly<{
}
}
type DeliveryRequest =
Parameters<DownloadDeliveryPort["deliver"]>[0];
type DeliveryInput = Readonly<
Omit<
DeliveryRequest,
"maxTransferBytes" | "maxBufferedBytes"
> &
ResolvedDownloadPolicy & {
expectedSha256?: string;
}
>;
function activeDeliveryInput(
input: DeliveryRequest,
policy: ResolvedDownloadPolicy,
): DeliveryInput {
const source = snapshotDownloadSource(input.source);
const expectedSha256 =
source.kind === "GENERATED"
? source.expectedSha256
: undefined;
return Object.freeze({
policy: input.policy,
source,
suggestedFileName: input.suggestedFileName,
signal: input.signal,
onProgress: input.onProgress,
...policy,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function snapshotDownloadSource(
source: DownloadSource,
): DownloadSource {
const kind = source.kind;
if (kind === "BROWSER_MANAGED_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capabilityReceipt: source.capabilityReceipt,
});
}
if (kind === "AUTHORIZED_STREAM_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capability: source.capability,
});
}
if (kind !== "GENERATED") {
throw new TypeError("Download source kind is invalid.");
}
const sourceBytes = source.bytes;
const stream = sourceBytes.stream;
const byteLength = sourceBytes.byteLength;
if (typeof stream !== "function") {
throw new TypeError("Download byte source is invalid.");
}
const bytes: FileByteSource = Object.freeze({
byteLength,
stream: stream.bind(sourceBytes),
});
const expectedSha256 = source.expectedSha256;
return Object.freeze({
kind,
bytes,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function validateDownloadInput(
input: DeliveryInput,
options: DownloadDeliveryAdapterOptions,
userActivation: Readonly<{ isActive: boolean }> | undefined,
): BrowserDataResult<true> {
if (
input.signal.aborted ||
input.suggestedFileName.length === 0 ||
!MEDIA_TYPE.test(input.mediaType) ||
!isValidByteLength(input.maxTransferBytes) ||
input.maxTransferBytes === 0 ||
!isValidByteLength(input.maxBufferedBytes) ||
input.maxBufferedBytes === 0 ||
(input.expectedSha256 !== undefined &&
!SHA256.test(input.expectedSha256)) ||
(input.source.kind === "AUTHORIZED_STREAM_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!validPresignedCapabilityForInput(
input.source.capability,
input.source.resourceId,
input.mediaType,
input.maxTransferBytes,
options.now?.() ?? Date.now(),
) ||
options.openAuthorizedSource === undefined)) ||
(input.source.kind === "BROWSER_MANAGED_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!safeOpaqueId(input.source.capabilityReceipt))) ||
(input.strategy === "PROMPT_AND_STREAM" &&
options.showSaveFilePicker === undefined)
) {
return browserDataFailure(
input.signal.aborted ? "ABORTED" : "INVALID_INPUT",
"DOWNLOAD",
);
}
if (
input.maxTransferBytes > options.hardMaxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
(input.maxBufferedBytes > options.hardMaxObjectUrlBytes ||
input.maxBufferedBytes > input.maxTransferBytes))
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
if (
(input.strategy === "BROWSER_MANAGED" &&
input.source.kind !== "BROWSER_MANAGED_RESOURCE") ||
(input.strategy !== "BROWSER_MANAGED" &&
input.source.kind === "BROWSER_MANAGED_RESOURCE") ||
(input.integrity === "REQUIRED" &&
input.source.kind === "GENERATED" &&
input.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (input.source.kind === "GENERATED") {
try {
if (!validByteSource(input.source.bytes)) {
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (
input.source.bytes.byteLength !== null &&
input.source.bytes.byteLength > input.maxTransferBytes
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
if (userActivation && !userActivation.isActive) {
return browserDataFailure("PERMISSION_DENIED", "DOWNLOAD");
}
try {
sanitizeSuggestedFileName(input.suggestedFileName, {
safeExtension: input.safeExtension,
maxUtf8Bytes: options.filenameMaxUtf8Bytes,
});
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
return browserDataSuccess(true);
}
/**
* TR-RR-04. A presigned byte source owns a fetch reader and a capability lease,
* and its port requires `close()`. The delivery consumer never called it, so
* every success, validation failure, writer failure and abort leaked both. The
* closeable subtype is lost in the `FileByteSource` projection, so the holder
* keeps it and the outermost boundary closes it exactly once.
* keeps it and the outermost boundary closes it exactly once. A lease that
* lands after the owner ended never reaches the holder; the owner's race
* compensates it instead.
*/
type CloseableSourceHolder = { source: FileByteSource | null; closed: boolean };
@@ -1023,32 +877,6 @@ function createSourceHolder(): CloseableSourceHolder {
return { source: null, closed: false };
}
/**
* TR-02. Closes a lease that fulfilled after the delivery already ended. The
* holder's own `closed` latch is the single close-once authority, so a lease
* the holder did adopt is never closed twice and a lease it never saw is still
* closed exactly once. A late rejection is observed and discarded.
*/
function compensateLateSource(
pending: Promise<BrowserDataResult<FileByteSource>>,
holder: CloseableSourceHolder | undefined,
): void {
if (!holder) return;
void pending.then(
(result) => {
if (!result.ok || !holder.closed) return;
// The holder was already closed, so this lease was never adopted.
if (!isVerifiedPresignedSource(result.value)) return;
try {
result.value.close();
} catch {
// Compensation is best effort and never changes the outcome.
}
},
() => undefined,
);
}
function closeHeldSource(holder: CloseableSourceHolder): void {
if (holder.closed) return;
holder.closed = true;
@@ -1064,12 +892,12 @@ function closeHeldSource(holder: CloseableSourceHolder): void {
async function resolveByteSource(
input: DeliveryInput,
signal: AbortSignal,
owner: AbortableOperation,
options: DownloadDeliveryAdapterOptions,
holder?: CloseableSourceHolder,
): Promise<BrowserDataResult<FileByteSource>> {
const source = input.source;
if (signal.aborted) {
if (owner.signal.aborted) {
return browserDataFailure("ABORTED", "DOWNLOAD");
}
if (source.kind === "GENERATED") {
@@ -1082,17 +910,22 @@ async function resolveByteSource(
}
const open = options.openAuthorizedSource;
if (!open) return browserDataFailure("UNSUPPORTED", "DOWNLOAD");
const pendingOpen = open({
resourceId: source.resourceId,
capability: source.capability,
signal,
});
// TR-02. A lease that arrives after the abort already ended the delivery
// never reaches the holder, so nothing would ever close it: the fetch reader
// and the capability lease outlived the terminal result. The compensator and
// the holder share one close-once latch, so exactly one of them closes it.
compensateLateSource(pendingOpen, holder);
const result = await awaitWithSignal(pendingOpen, signal);
// TR-02 / Q-6.2-7. A lease that arrives after the owner ended never reaches
// the holder, so the race closes it: exactly one of the two ever sees it,
// with no gap between the abort and the holder's own cleanup.
const result = await raceOwner(
owner,
open({
resourceId: source.resourceId,
capability: source.capability,
signal: owner.signal,
}),
(late) => {
if (late.ok && isVerifiedPresignedSource(late.value)) {
late.value.close();
}
},
);
if (!result.ok) {
return browserDataFailure(result.error.code, "DOWNLOAD", {
retryable: result.error.retryable,
@@ -1114,14 +947,6 @@ async function resolveByteSource(
: browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
function validByteSource(source: FileByteSource): boolean {
return (
typeof source.stream === "function" &&
(source.byteLength === null ||
isValidByteLength(source.byteLength))
);
}
function isVerifiedPresignedSource(
source: FileByteSource,
): source is PresignedDownloadByteSource {
@@ -1131,70 +956,16 @@ function isVerifiedPresignedSource(
);
}
function validPresignedByteSource(
source: PresignedDownloadByteSource,
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
return (
validByteSource(source) &&
source.capability === capability &&
source.integrity === "VERIFIED_ON_SUCCESSFUL_EXHAUSTION" &&
source.byteLength === capability.byteLength &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
}
function validPresignedCapabilityForInput(
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
try {
return (
Boolean(capability) &&
typeof capability === "object" &&
Object.isFrozen(capability) &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
isValidByteLength(capability.byteLength) &&
isPositiveByteLimit(capability.maxBytes) &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(capability.expiresAtEpochMs) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
} catch {
return false;
}
}
async function* abortableFileChunks(
source: FileByteSource,
signal: AbortSignal,
owner: AbortableOperation,
): AsyncIterable<BrowserDataResult<Uint8Array>> {
const signal = owner.signal;
const iterator = source.stream(signal)[Symbol.asyncIterator]();
let completed = false;
try {
while (true) {
const next = await awaitWithSignal(iterator.next(), signal);
const next = await raceOwner(owner, iterator.next());
if (next.done) {
completed = true;
return;
@@ -1267,116 +1038,6 @@ function mapDownloadException(
return mapBrowserDataException(error, "DOWNLOAD");
}
function validateBrowserManagedCapability(
capability: BrowserManagedDownloadCapability,
input: DeliveryInput,
nowEpochMs: number,
): BrowserDataResult<BrowserManagedDownloadCapability> {
if (
input.source.kind !== "BROWSER_MANAGED_RESOURCE" ||
!capability ||
typeof capability !== "object" ||
typeof capability.href !== "string" ||
capability.href.length === 0 ||
capability.capabilityReceipt !==
input.source.capabilityReceipt ||
capability.resourceId !== input.source.resourceId ||
capability.mediaType.trim().toLowerCase() !==
input.mediaType ||
capability.safeExtension.trim().toLowerCase() !==
input.safeExtension ||
!isPositiveByteLimit(capability.maxBytes) ||
capability.maxBytes > input.maxTransferBytes ||
!Number.isSafeInteger(capability.expiresAtEpochMs) ||
!Number.isSafeInteger(nowEpochMs) ||
(capability.expectedSha256 !== undefined &&
!SHA256.test(capability.expectedSha256)) ||
(input.integrity === "REQUIRED" &&
capability.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (capability.expiresAtEpochMs <= nowEpochMs) {
return browserDataFailure("EXPIRED_RESOURCE", "DOWNLOAD", {
recovery: "RETRY",
});
}
return browserDataSuccess(
Object.freeze({
capabilityReceipt: capability.capabilityReceipt,
href: capability.href,
resourceId: capability.resourceId,
mediaType: input.mediaType,
safeExtension: input.safeExtension,
maxBytes: capability.maxBytes,
...(capability.expectedSha256
? {
expectedSha256:
capability.expectedSha256.toLowerCase(),
}
: {}),
expiresAtEpochMs: capability.expiresAtEpochMs,
}),
);
}
type ResolvedBrowserManagedTarget = Readonly<{ absoluteHref: string }>;
/**
* STO-02. Parse once, canonicalize, then execute the canonical value.
*
* Returning a boolean and handing the raw href to the host let the browser
* re-resolve a relative target against `document.baseURI`, so a hostile
* `<base>` could send the navigation to a different origin than the one this
* policy just approved.
*/
function resolveBrowserManagedTarget(
href: string,
baseOrigin: string,
policy: Readonly<{
allowCrossOrigin: boolean;
allowQuery: boolean;
}>,
): BrowserDataResult<ResolvedBrowserManagedTarget> {
let base: URL;
let target: URL;
try {
base = new URL(baseOrigin);
target = new URL(href, base);
} catch {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (
!["http:", "https:"].includes(target.protocol) ||
target.username.length > 0 ||
target.password.length > 0 ||
(!policy.allowCrossOrigin && target.origin !== base.origin) ||
(!policy.allowQuery && target.search.length > 0) ||
target.hash.length > 0
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
return browserDataSuccess(
Object.freeze({ absoluteHref: target.href }),
);
}
function safeOpaqueId(value: unknown): value is string {
if (typeof value !== "string") return false;
if (value.length === 0 || value.length > 256) return false;
for (const character of value) {
const code = character.codePointAt(0);
if (code === undefined || code <= 0x20 || code === 0x7f) {
return false;
}
}
return true;
}
function safeGeneratedToken(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
type ProgressReporter = Readonly<{
report(
phase: TransferProgress["phase"],
@@ -1479,50 +1140,17 @@ class ClosedFileStreamError extends Error {
}
}
function combineAbortSignals(
caller: AbortSignal,
lifetime: AbortSignal,
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abort = (): void => controller.abort();
if (caller.aborted || lifetime.aborted) {
controller.abort();
} else {
caller.addEventListener("abort", abort, { once: true });
lifetime.addEventListener("abort", abort, { once: true });
}
return Object.freeze({
signal: controller.signal,
release(): void {
caller.removeEventListener("abort", abort);
lifetime.removeEventListener("abort", abort);
},
});
}
async function awaitWithSignal<Value>(
/**
* The owner's value, the task's own rejection, or an AbortError once the owner
* ended. `compensate` receives a value that lands after that.
*/
async function raceOwner<Value>(
owner: AbortableOperation,
pending: Promise<Value>,
signal: AbortSignal,
compensate?: (value: Value) => void,
): Promise<Value> {
if (signal.aborted) throw abortException();
return new Promise<Value>((resolve, reject) => {
let settled = false;
const finish = (callback: () => void): void => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
callback();
};
const onAbort = (): void =>
finish(() => reject(abortException()));
signal.addEventListener("abort", onAbort, { once: true });
pending.then(
(value) => finish(() => resolve(value)),
(error: unknown) => finish(() => reject(error)),
);
});
}
function isPositiveByteLimit(value: number): boolean {
return isValidByteLength(value) && value > 0;
const raced = await owner.race(pending, compensate);
if (raced.kind === "VALUE") return raced.value;
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
}
@@ -0,0 +1,367 @@
import type {
BrowserManagedDownloadCapability,
DownloadDeliveryPort,
DownloadSource,
FileByteSource,
} from "../../application/ports/browser-file-storage/file.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import type {
PresignedDownloadCapability,
PresignedDownloadByteSource,
} from "../../application/ports/browser-transfer/presigned-transfer.ts";
import { isValidByteLength } from "../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../browser-file-storage/result.ts";
import {
EXACT_MEDIA_TYPE,
isPositiveSafeInteger,
sanitizeSuggestedFileName,
type SuggestedFileNamePolicy,
} from "./file-policy.ts";
import type { ResolvedDownloadPolicy } from "./browser-file-policy-registry.ts";
/**
* Q-6.2-11. Input admission for download delivery: request snapshot, policy
* and limit checks, presigned and browser-managed capability validation, and
* canonical handoff target resolution. Moved verbatim out of the adapter.
*/
/** The adapter options that input validation reads. */
export type DownloadInputValidationOptions = Readonly<{
hardMaxObjectUrlBytes: number;
hardMaxTransferBytes: number;
openAuthorizedSource?: unknown;
showSaveFilePicker?: unknown;
filenameMaxUtf8Bytes?: number;
now?: () => number;
}>;
const SHA256 = /^[a-f0-9]{64}$/i;
export type DeliveryRequest =
Parameters<DownloadDeliveryPort["deliver"]>[0];
export type DeliveryInput = Readonly<
Omit<
DeliveryRequest,
"maxTransferBytes" | "maxBufferedBytes"
> &
ResolvedDownloadPolicy & {
expectedSha256?: string;
}
>;
export function activeDeliveryInput(
input: DeliveryRequest,
policy: ResolvedDownloadPolicy,
): DeliveryInput {
const source = snapshotDownloadSource(input.source);
const expectedSha256 =
source.kind === "GENERATED"
? source.expectedSha256
: undefined;
return Object.freeze({
policy: input.policy,
source,
suggestedFileName: input.suggestedFileName,
signal: input.signal,
onProgress: input.onProgress,
...policy,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
function snapshotDownloadSource(
source: DownloadSource,
): DownloadSource {
const kind = source.kind;
if (kind === "BROWSER_MANAGED_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capabilityReceipt: source.capabilityReceipt,
});
}
if (kind === "AUTHORIZED_STREAM_RESOURCE") {
return Object.freeze({
kind,
resourceId: source.resourceId,
capability: source.capability,
});
}
if (kind !== "GENERATED") {
throw new TypeError("Download source kind is invalid.");
}
const sourceBytes = source.bytes;
const stream = sourceBytes.stream;
const byteLength = sourceBytes.byteLength;
if (typeof stream !== "function") {
throw new TypeError("Download byte source is invalid.");
}
const bytes: FileByteSource = Object.freeze({
byteLength,
stream: stream.bind(sourceBytes),
});
const expectedSha256 = source.expectedSha256;
return Object.freeze({
kind,
bytes,
...(expectedSha256 !== undefined ? { expectedSha256 } : {}),
});
}
export function validateDownloadInput(
input: DeliveryInput,
options: DownloadInputValidationOptions,
userActivation: Readonly<{ isActive: boolean }> | undefined,
): BrowserDataResult<string> {
if (
input.signal.aborted ||
input.suggestedFileName.length === 0 ||
!EXACT_MEDIA_TYPE.test(input.mediaType) ||
!isValidByteLength(input.maxTransferBytes) ||
input.maxTransferBytes === 0 ||
!isValidByteLength(input.maxBufferedBytes) ||
input.maxBufferedBytes === 0 ||
(input.expectedSha256 !== undefined &&
!SHA256.test(input.expectedSha256)) ||
(input.source.kind === "AUTHORIZED_STREAM_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!validPresignedCapabilityForInput(
input.source.capability,
input.source.resourceId,
input.mediaType,
input.maxTransferBytes,
options.now?.() ?? Date.now(),
) ||
options.openAuthorizedSource === undefined)) ||
(input.source.kind === "BROWSER_MANAGED_RESOURCE" &&
(!safeOpaqueId(input.source.resourceId) ||
!safeOpaqueId(input.source.capabilityReceipt))) ||
(input.strategy === "PROMPT_AND_STREAM" &&
options.showSaveFilePicker === undefined)
) {
return browserDataFailure(
input.signal.aborted ? "ABORTED" : "INVALID_INPUT",
"DOWNLOAD",
);
}
if (
input.maxTransferBytes > options.hardMaxTransferBytes ||
(input.strategy === "BOUNDED_OBJECT_URL" &&
(input.maxBufferedBytes > options.hardMaxObjectUrlBytes ||
input.maxBufferedBytes > input.maxTransferBytes))
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
if (
(input.strategy === "BROWSER_MANAGED" &&
input.source.kind !== "BROWSER_MANAGED_RESOURCE") ||
(input.strategy !== "BROWSER_MANAGED" &&
input.source.kind === "BROWSER_MANAGED_RESOURCE") ||
(input.integrity === "REQUIRED" &&
input.source.kind === "GENERATED" &&
input.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (input.source.kind === "GENERATED") {
try {
if (!validByteSource(input.source.bytes)) {
return browserDataFailure("INTEGRITY_FAILED", "DOWNLOAD");
}
if (
input.source.bytes.byteLength !== null &&
input.source.bytes.byteLength > input.maxTransferBytes
) {
return browserDataFailure("LIMIT_EXCEEDED", "DOWNLOAD");
}
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
if (userActivation && !userActivation.isActive) {
return browserDataFailure("PERMISSION_DENIED", "DOWNLOAD");
}
try {
return browserDataSuccess(
sanitizeSuggestedFileName(input.suggestedFileName, {
safeExtension: input.safeExtension,
maxUtf8Bytes: options.filenameMaxUtf8Bytes,
} satisfies SuggestedFileNamePolicy),
);
} catch {
return browserDataFailure("INVALID_INPUT", "DOWNLOAD");
}
}
export function validByteSource(source: FileByteSource): boolean {
return (
typeof source.stream === "function" &&
(source.byteLength === null ||
isValidByteLength(source.byteLength))
);
}
export function validPresignedByteSource(
source: PresignedDownloadByteSource,
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
return (
validByteSource(source) &&
source.capability === capability &&
source.integrity === "VERIFIED_ON_SUCCESSFUL_EXHAUSTION" &&
source.byteLength === capability.byteLength &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
}
function validPresignedCapabilityForInput(
capability: PresignedDownloadCapability,
resourceId: string,
mediaType: string,
maxTransferBytes: number,
nowEpochMs: number,
): boolean {
try {
return (
Boolean(capability) &&
typeof capability === "object" &&
Object.isFrozen(capability) &&
capability.method === "GET" &&
capability.binding.kind === "DOWNLOAD" &&
capability.binding.resourceId === resourceId &&
capability.mediaType === mediaType &&
isValidByteLength(capability.byteLength) &&
isPositiveSafeInteger(capability.maxBytes) &&
capability.byteLength <= capability.maxBytes &&
capability.maxBytes <= maxTransferBytes &&
SHA256.test(capability.expectedSha256) &&
Number.isSafeInteger(capability.expiresAtEpochMs) &&
Number.isSafeInteger(nowEpochMs) &&
capability.expiresAtEpochMs > nowEpochMs
);
} catch {
return false;
}
}
export function validateBrowserManagedCapability(
capability: BrowserManagedDownloadCapability,
input: DeliveryInput,
nowEpochMs: number,
): BrowserDataResult<BrowserManagedDownloadCapability> {
if (
input.source.kind !== "BROWSER_MANAGED_RESOURCE" ||
!capability ||
typeof capability !== "object" ||
typeof capability.href !== "string" ||
capability.href.length === 0 ||
capability.capabilityReceipt !==
input.source.capabilityReceipt ||
capability.resourceId !== input.source.resourceId ||
capability.mediaType.trim().toLowerCase() !==
input.mediaType ||
capability.safeExtension.trim().toLowerCase() !==
input.safeExtension ||
!isPositiveSafeInteger(capability.maxBytes) ||
capability.maxBytes > input.maxTransferBytes ||
!Number.isSafeInteger(capability.expiresAtEpochMs) ||
!Number.isSafeInteger(nowEpochMs) ||
(capability.expectedSha256 !== undefined &&
!SHA256.test(capability.expectedSha256)) ||
(input.integrity === "REQUIRED" &&
capability.expectedSha256 === undefined)
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (capability.expiresAtEpochMs <= nowEpochMs) {
return browserDataFailure("EXPIRED_RESOURCE", "DOWNLOAD", {
recovery: "RETRY",
});
}
return browserDataSuccess(
Object.freeze({
capabilityReceipt: capability.capabilityReceipt,
href: capability.href,
resourceId: capability.resourceId,
mediaType: input.mediaType,
safeExtension: input.safeExtension,
maxBytes: capability.maxBytes,
...(capability.expectedSha256
? {
expectedSha256:
capability.expectedSha256.toLowerCase(),
}
: {}),
expiresAtEpochMs: capability.expiresAtEpochMs,
}),
);
}
export type ResolvedBrowserManagedTarget = Readonly<{ absoluteHref: string }>;
/**
* STO-02. Parse once, canonicalize, then execute the canonical value.
*
* Returning a boolean and handing the raw href to the host let the browser
* re-resolve a relative target against `document.baseURI`, so a hostile
* `<base>` could send the navigation to a different origin than the one this
* policy just approved.
*/
export function resolveBrowserManagedTarget(
href: string,
baseOrigin: string,
policy: Readonly<{
allowCrossOrigin: boolean;
allowQuery: boolean;
}>,
): BrowserDataResult<ResolvedBrowserManagedTarget> {
let base: URL;
let target: URL;
try {
base = new URL(baseOrigin);
target = new URL(href, base);
} catch {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
if (
!["http:", "https:"].includes(target.protocol) ||
target.username.length > 0 ||
target.password.length > 0 ||
(!policy.allowCrossOrigin && target.origin !== base.origin) ||
(!policy.allowQuery && target.search.length > 0) ||
target.hash.length > 0
) {
return browserDataFailure("POLICY_REJECTED", "DOWNLOAD");
}
return browserDataSuccess(
Object.freeze({ absoluteHref: target.href }),
);
}
function safeOpaqueId(value: unknown): value is string {
if (typeof value !== "string") return false;
if (value.length === 0 || value.length > 256) return false;
for (const character of value) {
const code = character.codePointAt(0);
if (code === undefined || code <= 0x20 || code === 0x7f) {
return false;
}
}
return true;
}
+2 -13
View File
@@ -6,6 +6,8 @@ import type {
} from "../../application/ports/browser-file-storage/shared.ts";
import { observeBrowserData } from "../browser-file-storage/result.ts";
export { browserDataByteBucket as byteBucket } from "../../application/ports/browser-file-storage/shared.ts";
type BrowserFileObservation = Readonly<{
operation: BrowserDataOperation;
outcome: "SUCCESS" | "DISMISSED" | "FAILED";
@@ -19,19 +21,6 @@ type BrowserFileObservation = Readonly<{
*/
export type BrowserFileObserver = BrowserDataObserver;
export function byteBucket(
byteLength: number | null,
): BrowserFileObservation["byteBucket"] | undefined {
if (byteLength === null || !Number.isSafeInteger(byteLength) || byteLength < 0) {
return undefined;
}
if (byteLength === 0) return "ZERO";
if (byteLength < 1_048_576) return "LT1MIB";
if (byteLength < 10_485_760) return "1_TO_9MIB";
if (byteLength < 104_857_600) return "10_TO_99MIB";
return "GTE100MIB";
}
export function observeBrowserFile(
observer: BrowserFileObserver | undefined,
observation: BrowserFileObservation,
+38 -14
View File
@@ -40,6 +40,20 @@ export type RegisteredFileInspectionPolicy = Readonly<{
}>;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/(?:[a-z0-9!#$&^_.+-]+|\*)$/i;
/**
* Q-6.2-12. The shared browser-file copies of three checks that used to be
* redefined per module: an exact `type/subtype` media type (no wildcard), a
* generated opaque token (file reference, receipt or transfer ID) and a
* positive safe integer limit.
*/
export const EXACT_MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
export function isSafeGeneratedToken(value: string): boolean {
return /^[a-z0-9][a-z0-9:_-]{0,127}$/i.test(value);
}
export { isPositiveSafeInteger } from "../../application/ports/browser-file-storage/shared.ts";
const EXTENSION =
/^\.[a-z0-9][a-z0-9+_-]{0,15}(?:\.[a-z0-9][a-z0-9+_-]{0,15})?$/i;
const POLICY_TOKEN = /^[a-z0-9][a-z0-9._:-]{0,127}$/i;
@@ -354,12 +368,7 @@ export function sanitizeSuggestedFileName(
base = fallbackBase.length > 0 ? fallbackBase : "download";
}
while (
base.length > 0 &&
utf8Length(`${base}${safeExtension}`) > maxUtf8Bytes
) {
base = Array.from(base).slice(0, -1).join("").trimEnd();
}
base = truncateUtf8(base, maxUtf8Bytes - utf8Length(safeExtension));
if (base.length === 0 || WINDOWS_RESERVED.test(base)) {
base = fallbackBase;
}
@@ -401,21 +410,36 @@ function utf8Length(value: string): number {
return new TextEncoder().encode(value).byteLength;
}
/**
* Q-6.2-10. The longest code-point prefix within `maxBytes` UTF-8 bytes, with
* trailing whitespace removed once it was cut; `value` itself when it fits.
* One pass: re-encoding the whole name per dropped code point was O(n^2).
*/
function truncateUtf8(value: string, maxBytes: number): string {
let bytes = 0;
let end = 0;
for (const character of value) {
const codePoint = character.codePointAt(0) ?? 0;
// A lone surrogate encodes as U+FFFD, three bytes, like any BMP point.
bytes +=
codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
if (bytes > maxBytes) return value.slice(0, end).trimEnd();
end += character.length;
}
return value;
}
function fitFallbackBaseName(
configured: string,
extension: string,
maxUtf8Bytes: number,
): string {
let fallback =
const fallback = truncateUtf8(
configured.length > 0 && !WINDOWS_RESERVED.test(configured)
? configured
: "download";
while (
fallback.length > 0 &&
utf8Length(`${fallback}${extension}`) > maxUtf8Bytes
) {
fallback = Array.from(fallback).slice(0, -1).join("").trimEnd();
}
: "download",
maxUtf8Bytes - utf8Length(extension),
);
return fallback.length > 0 && !WINDOWS_RESERVED.test(fallback)
? fallback
: "a";
+2 -13
View File
@@ -20,6 +20,7 @@ import {
type BrowserFileObserver,
} from "./file-observer.ts";
import { BrowserFilePolicyRegistry } from "./browser-file-policy-registry.ts";
import { EXACT_MEDIA_TYPE, isPositiveSafeInteger } from "./file-policy.ts";
export type ObjectUrlApi = Readonly<{
createObjectURL(blob: Blob): string;
@@ -109,13 +110,6 @@ export class ObjectUrlLeaseRegistry {
}
const url = this.#createObjectURL(blob);
if (typeof url !== "string" || url.length === 0) {
if (typeof url === "string" && url.length > 0) {
try {
this.#revokeObjectURL(url);
} catch {
// The invalid lease is rejected regardless of cleanup support.
}
}
throw new DOMException(
"Object URL allocation failed",
"InvalidStateError",
@@ -184,7 +178,6 @@ const DEFAULT_ACTIVE_CONTENT = new Set([
"text/html",
"text/xml",
]);
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/i;
export class BrowserTransientPreview implements TransientPreviewPort {
readonly #resolveVerifiedFile:
@@ -269,7 +262,7 @@ export class BrowserTransientPreview implements TransientPreviewPort {
}
const mediaType = resolved.value.mediaType.trim().toLowerCase();
if (
!MEDIA_TYPE.test(mediaType) ||
!EXACT_MEDIA_TYPE.test(mediaType) ||
!policy.allowedMediaTypes.has(mediaType) ||
this.#hardForbiddenMediaTypes.has(mediaType)
) {
@@ -333,7 +326,3 @@ export class BrowserTransientPreview implements TransientPreviewPort {
return result;
}
}
function isPositiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
+71 -63
View File
@@ -22,6 +22,7 @@ import {
import type { InstalledBoundaryMapper } from "../../contracts/boundary-mapper.ts";
import {
createFailure,
withFailureEffect,
type AppFailure,
type FailureKind,
} from "../../contracts/errors.ts";
@@ -292,6 +293,7 @@ async function executeUnary<Output>(
const { operation, profile, encoder, transport } = bound;
const linked = linkedAbortController(context.signal);
let attemptCount = 0;
let sent = false;
const finish = (
result: Result<Output, AppFailure>,
@@ -300,7 +302,11 @@ async function executeUnary<Output>(
// R-06. Listener and timer cleanup happens exactly once, on every exit.
linked.cleanup();
observe(dependencies, operation, outcome, attemptCount, result.ok ? 1 : 0);
return result;
// Q-6.3-9. Once a command reached the transport, no failure proves the
// server did not apply it, so it is never offered as a plain retry.
return !result.ok && sent && operation.semantics === "COMMAND"
? failureResult(withFailureEffect(result.error, "MAYBE_APPLIED"))
: result;
};
const generation = safeCapture(generationFence);
@@ -350,6 +356,21 @@ async function executeUnary<Output>(
}
for (let attempt = 0; attempt < profile.maxAttempts; attempt += 1) {
// Q-6.3-9. A retry never outlives the scope generation that started it,
// so a previous user's request is not sent again after a logout.
if (attempt > 0 && !safeIsCurrent(generationFence, generation)) {
return finish(
failureResult(
callFailure(
operation,
attempt - 1,
"SCOPE_GENERATION_CHANGED",
"RPC_SCOPE_GENERATION_CHANGED",
),
),
"ABORTED",
);
}
attemptCount = attempt + 1;
const attemptNow = safeNow(clock);
if (attemptNow === CLOCK_FAILURE) {
@@ -393,6 +414,7 @@ async function executeUnary<Output>(
? { idempotencyKey: context.idempotencyKey }
: {}),
});
sent = true;
const timed = await raceWithin(
Promise.resolve().then(() => transport.invokeUnary!(call)),
remainingMs,
@@ -549,10 +571,30 @@ async function* executeServerStream<Event>(
const deadlineAt = safeNowOrDeadline(clock, 0) + operation.totalDeadlineMs;
const linked = linkedAbortController(context.signal);
let iterator: AsyncIterator<BrowserRpcStreamFrame> | null = null;
let lease: BrowserRpcServerStreamLease | null = null;
let registered: ActiveStreamLease | null = null;
let observed = false;
let messageCount = 0;
// R-01 / RPC-RR-01. Runs once, when the stream's own signal aborts. The
// lease's `cancel` is what actually stops the physical stream, and the entry
// is removed only once the transport confirms the physical stream closed.
// Until then the operation stays DRAINING and admits nothing new — a bounded
// wait here would re-open the very hole this registry exists to close.
const releaseRegistered = () => {
const entry = registered;
if (!entry) return;
try {
entry.cancel("stream-closed");
} catch {
// A transport that refuses to cancel stays DRAINING below.
}
void entry.closed.then((confirmed) => {
if (confirmed && activeStreams.get(operation.operationId) === entry) {
activeStreams.delete(operation.operationId);
}
});
};
const finish = (outcome: BrowserRpcObservationOutcome) => {
if (observed) return;
observed = true;
@@ -662,21 +704,28 @@ async function* executeServerStream<Event>(
yield failureResult(protocolFailure(operation, 0));
return;
}
lease = decodedLease;
const lease = decodedLease;
// Registered at the moment the physical stream exists, not after a timeout.
activeStreams.set(
operation.operationId,
Object.freeze({
streamId: lease.streamId,
cancel: lease.cancel,
// RPC-01. Only a fulfilled, contract-shaped receipt is evidence that the
// physical stream closed. Absorbing a rejection, a synchronous throw or
// a non-promise into `undefined` forged that evidence, and the registry
// then admitted a second stream for the same operation while the first
// was still running against the server.
closed: confirmPhysicalClosure(lease),
}),
);
registered = Object.freeze({
streamId: lease.streamId,
cancel: lease.cancel,
// RPC-01. Only a fulfilled, contract-shaped receipt is evidence that the
// physical stream closed. Absorbing a rejection, a synchronous throw or
// a non-promise into `undefined` forged that evidence, and the registry
// then admitted a second stream for the same operation while the first
// was still running against the server.
closed: confirmPhysicalClosure(lease),
});
activeStreams.set(operation.operationId, registered);
// Q-6.3-9. A consumer that aborts and walks away without `return()` leaves
// this generator suspended at a `yield`, so `finally` never runs. The
// abort itself releases the physical stream.
if (linked.controller.signal.aborted) releaseRegistered();
else {
linked.controller.signal.addEventListener("abort", releaseRegistered, {
once: true,
});
}
try {
iterator = lease.frames[Symbol.asyncIterator]();
} catch {
@@ -842,38 +891,13 @@ async function* executeServerStream<Event>(
}
} finally {
// R-01 / RPC-RR-01. The commit/admission generation is fenced immediately
// and listeners are released without waiting for the transport.
// `iterator.return()` is a cleanup request, not a lifecycle authority, so
// the lease's own `cancel` is what actually stops the physical stream.
// and listeners are released without waiting for the transport. The abort
// runs `releaseRegistered` (cancel + positive-close subscription) unless
// an earlier abort already did. RPC-02: that happens before any fallible
// cleanup, so a throwing `return` accessor cannot strand the entry.
// `iterator.return()` is a cleanup request, not a lifecycle authority.
linked.controller.abort("stream-closed");
linked.cleanup();
const registered = lease
? activeStreams.get(operation.operationId)
: undefined;
if (registered && registered.streamId === lease?.streamId) {
try {
registered.cancel("stream-closed");
} catch {
// A transport that refuses to cancel stays DRAINING below.
}
}
if (registered && registered.streamId === lease?.streamId) {
// RPC-02. The positive-close subscription is installed before any
// fallible cleanup. Running cleanup first meant a throwing `return`
// accessor could skip it entirely and strand the registry entry.
// The entry is removed only once the transport confirms the physical
// stream closed. Until then the operation stays DRAINING and admits
// nothing new — a bounded wait here would re-open the very hole this
// registry exists to close.
void registered.closed.then((confirmed) => {
if (
confirmed &&
activeStreams.get(operation.operationId) === registered
) {
activeStreams.delete(operation.operationId);
}
});
}
const returnIterator = safeIteratorReturn(iterator);
if (returnIterator) {
const cleanup = Promise.resolve()
@@ -882,7 +906,7 @@ async function* executeServerStream<Event>(
.catch(() => undefined);
await boundedStreamCleanup(cleanup, clock, STREAM_CLEANUP_BOUND_MS);
}
if (registered && registered.streamId === lease?.streamId) {
if (registered) {
await boundedStreamCleanup(
registered.closed.then(() => undefined),
clock,
@@ -1465,22 +1489,6 @@ function decodeTransportFailure(
});
}
function validTransportFailure(
failure: unknown,
): failure is BrowserRpcTransportFailure {
if (!failure || typeof failure !== "object" || !("code" in failure)) {
return false;
}
const candidate = failure as BrowserRpcTransportFailure;
return (
TRANSPORT_FAILURE_CODES.has(candidate.code) &&
(candidate.retryAfterMs === undefined ||
(Number.isSafeInteger(candidate.retryAfterMs) &&
candidate.retryAfterMs >= 0 &&
candidate.retryAfterMs <= BROWSER_RPC_HARD_LIMITS.maxRetryAfterMs))
);
}
const TRANSPORT_FAILURE_CODES =
new Set<BrowserRpcTransportFailureCode>([
"NETWORK_UNREACHABLE",
@@ -133,7 +133,10 @@ and every CDN origin must differ from it. This is required because an
`anonymous` image request omits credentials only when it is cross-origin.
Private descriptors must be backend-signed, remain above the configured
minimum TTL at every resolve, and use an eager, non-low-priority
`PRIMARY_REQUIRED` preset. Digest and signature verification share one
`PRIMARY_REQUIRED` preset. A `PRIMARY_REQUIRED` preset must use `fit`
`cover`, `contain` or `fill`: the probe expects the exact primary pixel size,
and `inside`/`outside` keep the source ratio, so the registry rejects that
combination at composition time. Digest and signature verification share one
composition-owned deadline and race the caller's abort signal. The probe sends
no credentials, rejects any final URL other than the exact signed URL, and
requires the private response to declare the flag-only directive
@@ -7,11 +7,16 @@ import {
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
cancelBody,
cancelReader,
createAbortableOperation,
snapshotAbortTimers,
type AbortTimerSnapshot,
type AbortableOperation,
} from "../../platform/abortable-operation.ts";
import { parseStaticImageHeaderMetadata } from "./image-header-metadata.ts";
import {
isPositiveSafeInteger as positiveSafeInteger,
} from "../../../application/ports/browser-file-storage/shared.ts";
export type DecodedImageFacade = Readonly<{
width: number;
@@ -49,7 +54,10 @@ export function createBrowserImageProbe(
const createBitmap =
dependencies.createBitmap ??
(typeof createImageBitmap === "function"
? async (image: Blob) => createImageBitmap(image)
? // Q-6.1-8. The header parser reads pre-rotation dimensions, so the
// decode must not apply EXIF/irot orientation and swap them.
async (image: Blob) =>
createImageBitmap(image, { imageOrientation: "none" })
: undefined);
const timeoutMs = dependencies.timeoutMs ?? DEFAULT_TIMEOUT_MS;
const timers = snapshotAbortTimers(
@@ -100,11 +108,15 @@ export function createBrowserImageProbe(
return browserDataFailure("UNSUPPORTED", "IMAGE_RESOLVE");
}
const scope = createProbeAbortScope(
request.signal,
// X-AUDIT-02 / TR-RR-05. The probe is owned by the shared abort
// primitive: the caller listener and the deadline are installed
// together, so a throwing scheduler closes the probe instead of
// rejecting `probe()`.
const scope = createAbortableOperation({
signal: request.signal,
timeoutMs,
timers,
);
...timers,
});
let response: Response | undefined;
try {
if (scope.signal.aborted) {
@@ -124,8 +136,8 @@ export function createBrowserImageProbe(
signal: scope.signal,
}),
);
response = await scope.await(fetchTask, (lateResponse) => {
cancelResponseBody(lateResponse);
response = await awaitOwned(scope, fetchTask, (lateResponse) => {
cancelBody(lateResponse);
});
} catch {
return signalFailure(request.signal);
@@ -140,7 +152,7 @@ export function createBrowserImageProbe(
response.url !== url.href ||
!validResponseHeaders(response, request)
) {
cancelResponseBody(response);
cancelBody(response);
return browserDataFailure(
"POLICY_REJECTED",
"IMAGE_RESOLVE",
@@ -152,10 +164,10 @@ export function createBrowserImageProbe(
bytes = await readBoundedBody(
response,
request.maxEncodedBytes,
scope.signal,
scope,
);
} catch (error) {
if (request.signal.aborted || scope.timedOut()) {
if (request.signal.aborted || unanswered(scope)) {
return signalFailure(request.signal);
}
return error instanceof EncodedBodyLimitError
@@ -227,18 +239,12 @@ export function createBrowserImageProbe(
type: request.expectedMediaType,
}),
);
bitmap = await scope.await(decodeTask, closeBitmap);
bitmap = await awaitOwned(scope, decodeTask, closeBitmap);
if (
!positiveSafeInteger(bitmap.width) ||
!positiveSafeInteger(bitmap.height) ||
// The header dimensions are positive and already within the
// decode budget, so an exact match is the whole check.
bitmap.width !== metadata.width ||
bitmap.height !== metadata.height ||
!withinDecodeBudget(
bitmap.width,
bitmap.height,
request.maxDecodedPixels,
request.maxDecodedBytes,
)
bitmap.height !== metadata.height
) {
return browserDataFailure(
"INTEGRITY_FAILED",
@@ -255,7 +261,7 @@ export function createBrowserImageProbe(
}),
);
} catch {
return request.signal.aborted || scope.timedOut()
return request.signal.aborted || unanswered(scope)
? signalFailure(request.signal)
: browserDataFailure(
"INTEGRITY_FAILED",
@@ -265,7 +271,7 @@ export function createBrowserImageProbe(
if (bitmap) closeBitmap(bitmap);
}
} finally {
scope.release();
scope.close();
}
},
});
@@ -474,7 +480,7 @@ class EncodedBodyLimitError extends Error {}
async function readBoundedBody(
response: Response,
maximumBytes: number,
signal: AbortSignal,
scope: AbortableOperation,
): Promise<Uint8Array> {
if (!response.body) {
throw new TypeError("Image response body is unavailable.");
@@ -484,8 +490,9 @@ async function readBoundedBody(
let total = 0;
try {
while (true) {
if (signal.aborted) throw abortException();
const next = await readOrAbort(reader.read(), signal);
if (scope.signal.aborted) throw abortException();
// A late chunk is dropped: the bytes are only accumulated below.
const next = await awaitOwned(scope, reader.read(), () => undefined);
if (next.done) break;
if (!(next.value instanceof Uint8Array)) {
throw new TypeError("Image response chunk is invalid.");
@@ -515,90 +522,28 @@ async function readBoundedBody(
return bytes;
}
type ProbeAbortScope = Readonly<{
signal: AbortSignal;
/** True once a deadline, or a deadline that could not be installed, ended it. */
timedOut(): boolean;
/**
* Awaits `task` under this scope's ownership. A late value is compensated
* exactly once; a terminal owner raises the scope's abort exception.
*/
await<Value>(
task: Promise<Value>,
onLateValue: (value: Value) => void,
): Promise<Value>;
release(): void;
}>;
/**
* X-AUDIT-02 / TR-RR-05. The probe scope is the shared abort primitive with
* this subsystem's vocabulary on top. Owning a private copy meant the caller
* listener was attached before the timer was installed, so a scheduler that
* threw rejected the public `probe()` promise and left the listener behind.
* `CLOSED` here means the deadline could never be installed, so the probe was
* never bounded: operationally the same unanswered host as a deadline.
*/
function createProbeAbortScope(
externalSignal: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
): ProbeAbortScope {
const operation = createAbortableOperation({
signal: externalSignal,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
return Object.freeze({
signal: operation.signal,
// `CLOSED` here means the deadline could never be installed, so the probe
// was never bounded: operationally the same unanswered host as a deadline.
timedOut: () =>
operation.terminal() !== "CALLER_ABORT" && operation.terminal() !== null,
async await<Value>(
task: Promise<Value>,
onLateValue: (value: Value) => void,
): Promise<Value> {
const raced = await operation.race(task, onLateValue);
if (raced.kind === "VALUE") return raced.value;
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
},
release: () => operation.close(),
});
function unanswered(scope: AbortableOperation): boolean {
const terminal = scope.terminal();
return terminal !== null && terminal !== "CALLER_ABORT";
}
/**
* A single read raced against the probe's ownership. A late chunk is dropped:
* the bytes are only ever accumulated by the caller below.
* Awaits `task` under the probe's ownership. A late value is compensated
* exactly once; a terminal owner raises the probe's abort exception.
*/
function readOrAbort<Value>(
async function awaitOwned<Value>(
scope: AbortableOperation,
task: Promise<Value>,
signal: AbortSignal,
onLateValue: (value: Value) => void,
): Promise<Value> {
return new Promise<Value>((resolve, reject) => {
let settled = false;
const onAbort = () => {
if (settled) return;
settled = true;
reject(abortException());
};
signal.addEventListener("abort", onAbort, { once: true });
void task.then(
(value) => {
signal.removeEventListener("abort", onAbort);
if (!settled) {
settled = true;
resolve(value);
}
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
if (!settled) {
settled = true;
reject(error);
}
},
);
});
const raced = await scope.race(task, onLateValue);
if (raced.kind === "VALUE") return raced.value;
if (raced.kind === "REJECTED") throw raced.reason;
throw abortException();
}
function signalFailure(externalSignal: AbortSignal) {
@@ -612,25 +557,6 @@ function signalFailure(externalSignal: AbortSignal) {
});
}
function cancelResponseBody(response: Response): void {
try {
const cancellation = response.body?.cancel();
void cancellation?.catch(() => undefined);
} catch {
// Best-effort release cannot change the closed probe result.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => undefined);
} catch {
// Best-effort release cannot change the closed probe result.
}
}
function closeBitmap(bitmap: DecodedImageFacade): void {
try {
bitmap.close();
@@ -682,7 +608,3 @@ function isRasterMediaType(
"image/webp",
].includes(value);
}
function positiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
@@ -4,6 +4,11 @@ import type {
ImagePresetReference,
ImageRasterMediaType,
} from "../../../application/ports/browser-transfer/image-cdn.ts";
import {
isPositiveSafeInteger as positiveSafeInteger,
isNonNegativeSafeInteger as nonNegativeSafeInteger,
hasControlCharacter,
} from "../../../application/ports/browser-file-storage/shared.ts";
export type ImageCdnOriginPolicy = Readonly<{
originKey: string;
@@ -476,7 +481,7 @@ function snapshotPreset(
!positiveSafeInteger(input.quality) ||
input.quality > hardLimits.maxQuality ||
!SAFE_SIZES.test(input.sizes) ||
hasControlCharacters(input.sizes) ||
hasControlCharacter(input.sizes) ||
!["eager", "lazy"].includes(input.loading) ||
!["async", "sync"].includes(input.decoding) ||
!["high", "low", "auto"].includes(input.fetchPriority) ||
@@ -485,6 +490,10 @@ function snapshotPreset(
"strict-origin-when-cross-origin",
].includes(input.referrerPolicy) ||
!["NONE", "PRIMARY_REQUIRED"].includes(input.probeMode) ||
// Q-6.1-7 / D-12. The probe expects the exact primary pixel size, which
// only these fits produce; inside/outside keep the source ratio.
(input.probeMode === "PRIMARY_REQUIRED" &&
!["cover", "contain", "fill"].includes(input.fit)) ||
typeof input.allowUpscale !== "boolean" ||
!positiveSafeInteger(input.maxTransformedPixels) ||
input.maxTransformedPixels > hardLimits.maxTransformedPixels ||
@@ -722,14 +731,6 @@ function positiveDpr(value: number): boolean {
);
}
function positiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
function nonNegativeSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value >= 0;
}
function hasExactOwnKeys(
input: unknown,
keys: readonly string[],
@@ -744,10 +745,3 @@ function hasExactOwnKeys(
actual.every((key, index) => key === expected[index])
);
}
function hasControlCharacters(value: string): boolean {
return [...value].some((character) => {
const codePoint = character.codePointAt(0) ?? 0;
return codePoint < 0x20 || codePoint === 0x7f;
});
}
@@ -20,6 +20,11 @@ import {
browserDataSuccess,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
import {
createAbortableOperation,
snapshotAbortTimers,
type AbortableOperation,
} from "../../platform/abortable-operation.ts";
import {
IMAGE_FORMAT_MEDIA_TYPE,
type ImageCandidateGeometry,
@@ -71,6 +76,7 @@ type IssuedDescriptorSnapshot = BackendIssuedImageAsset;
const OPAQUE_TOKEN = /^[A-Za-z0-9_-]{8,128}$/u;
const SIGNATURE = /^[A-Za-z0-9_-]{16,512}$/u;
const SHA256_HEX = /^[a-f0-9]{64}$/u;
const REGISTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
const PUBLIC_DESCRIPTOR_KEYS = Object.freeze([
"kind",
"originKey",
@@ -145,19 +151,18 @@ export function createImageCdnRuntime(
dependencies.capabilityVerifier,
);
if (dependencies.capabilityVerifier) {
let covered = false;
try {
if (
!verifyCapability ||
!acceptsCapabilityKey ||
[...capabilityPolicy.acceptedKeyIds].some(
(keyId) => acceptsCapabilityKey(keyId) !== true,
)
) {
throw new TypeError(
"Image capability verifier registry does not cover policy keys.",
covered =
!!verifyCapability &&
!!acceptsCapabilityKey &&
[...capabilityPolicy.acceptedKeyIds].every(
(keyId) => acceptsCapabilityKey(keyId) === true,
);
}
} catch {
// A throwing registry covers nothing.
}
if (!covered) {
throw new TypeError(
"Image capability verifier registry does not cover policy keys.",
);
@@ -176,17 +181,34 @@ export function createImageCdnRuntime(
"Image capability verification timeout is invalid.",
);
}
const capabilityVerificationScheduler =
const capabilityVerificationTimers =
snapshotCapabilityVerificationScheduler(
dependencies.capabilityVerificationScheduler ??
defaultCapabilityVerificationScheduler(),
dependencies.capabilityVerificationScheduler ?? globalThis,
);
const probe =
dependencies.probe?.probe.bind(dependencies.probe);
const observer = snapshotObserver(dependencies.observer);
let acceptedAssets =
new WeakMap<ImageAssetReference, AssetSnapshot>();
const lifetime = new AbortController();
// Every in-flight operation, so `close()` ends the physical work too.
const lifetime = new Set<AbortableOperation>();
const openOperation = (
signal: AbortSignal | undefined,
timeoutMs?: number,
): AbortableOperation => {
const operation = createAbortableOperation({
signal,
timeoutMs,
...capabilityVerificationTimers,
});
if (closed) operation.close();
else lifetime.add(operation);
return operation;
};
const closeOperation = (operation: AbortableOperation): void => {
lifetime.delete(operation);
operation.close();
};
let activeCapabilityVerifications = 0;
let closed = false;
@@ -333,12 +355,11 @@ export function createImageCdnRuntime(
canonicalImageCapabilityPayload(snapshot);
let bindingDigest: string;
let verified: boolean;
let deadline: ImageCapabilityVerificationDeadline;
let deadline: AbortableOperation;
try {
deadline = createCapabilityVerificationDeadline(
[options.signal, lifetime.signal],
deadline = openOperation(
options.signal,
capabilityVerificationTimeoutMs,
capabilityVerificationScheduler,
);
} catch {
return browserDataFailure("UNAVAILABLE", "IMAGE_RESOLVE", {
@@ -352,10 +373,7 @@ export function createImageCdnRuntime(
}
const digestTask = sha256Hex(digest, canonicalPayload);
rawVerificationTasks.push(digestTask);
bindingDigest = await awaitImageRuntimeAbort(
digestTask,
deadline.signal,
);
bindingDigest = await raceImageRuntime(deadline, digestTask);
if (
!constantTimeHexEqual(
bindingDigest,
@@ -377,15 +395,12 @@ export function createImageCdnRuntime(
signatureBase64Url: snapshot.signature.valueBase64Url,
});
rawVerificationTasks.push(verifyTask);
verified = await awaitImageRuntimeAbort(
verifyTask,
deadline.signal,
);
verified = await raceImageRuntime(deadline, verifyTask);
} catch {
if (closed) return imageRuntimeClosedFailure();
return capabilityVerificationFailure(options.signal);
} finally {
deadline.release();
closeOperation(deadline);
}
if (closed) return imageRuntimeClosedFailure();
if (options.signal?.aborted) {
@@ -532,12 +547,10 @@ export function createImageCdnRuntime(
}
const primary = primaryCandidate(preset);
let probeResult: BrowserDataResult<ImageProbeReceipt>;
const probeScope = combineImageRuntimeAbortSignals([
request.signal,
lifetime.signal,
]);
const probeScope = openOperation(request.signal);
try {
probeResult = await awaitImageRuntimeAbort(
probeResult = await raceImageRuntime(
probeScope,
probe({
absoluteUrl: descriptor.src,
expectedMediaType: descriptor.fallbackMediaType,
@@ -552,7 +565,6 @@ export function createImageCdnRuntime(
referrerPolicy: descriptor.referrerPolicy,
signal: probeScope.signal,
}),
probeScope.signal,
);
} catch {
probeResult = closed
@@ -564,7 +576,7 @@ export function createImageCdnRuntime(
recovery: "RETRY",
});
} finally {
probeScope.release();
closeOperation(probeScope);
}
if (closed) probeResult = imageRuntimeClosedFailure();
observeImageTerminal(
@@ -629,7 +641,8 @@ export function createImageCdnRuntime(
close(): void {
if (closed) return;
closed = true;
lifetime.abort();
for (const operation of lifetime) operation.close();
lifetime.clear();
acceptedAssets =
new WeakMap<ImageAssetReference, AssetSnapshot>();
},
@@ -943,17 +956,11 @@ function snapshotIssuedDescriptor(
allowedPresetBindingIds.some(
(bindingId) =>
typeof bindingId !== "string" ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(
bindingId,
),
!REGISTRY_ID.test(bindingId),
) ||
snapshot.signature.algorithm !== "ECDSA_P256_SHA256" ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(
snapshot.issuer,
) ||
!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(
snapshot.signature.keyId,
) ||
!REGISTRY_ID.test(snapshot.issuer) ||
!REGISTRY_ID.test(snapshot.signature.keyId) ||
!SHA256_HEX.test(
snapshot.signature.capabilityBindingDigestHex,
) ||
@@ -1052,114 +1059,16 @@ function safeNow(now: () => number): number | null {
}
}
type ImageCapabilityVerificationDeadline = Readonly<{
signal: AbortSignal;
release(): void;
}>;
function createCapabilityVerificationDeadline(
signals: readonly (AbortSignal | undefined)[],
timeoutMs: number,
scheduler: ImageCapabilityVerificationScheduler,
): ImageCapabilityVerificationDeadline {
const controller = new AbortController();
let released = false;
const abortListeners = new Map<AbortSignal, () => void>();
const activeSignals = signals.filter(
(signal): signal is AbortSignal => signal !== undefined,
);
for (const signal of new Set(activeSignals)) {
const onAbort = () => controller.abort(signal.reason);
abortListeners.set(signal, onAbort);
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
}
let timeoutHandle: unknown;
try {
timeoutHandle = scheduler.setTimeout(() => {
if (released) return;
controller.abort(capabilityVerificationAbortException());
}, timeoutMs);
} catch (error) {
for (const [signal, onAbort] of abortListeners) {
signal.removeEventListener("abort", onAbort);
}
throw error;
}
return Object.freeze({
signal: controller.signal,
release() {
if (released) return;
released = true;
try {
scheduler.clearTimeout(timeoutHandle);
} catch {
// Scheduler cleanup cannot alter an already closed adapter result.
}
for (const [signal, onAbort] of abortListeners) {
signal.removeEventListener("abort", onAbort);
}
abortListeners.clear();
},
});
}
function awaitImageRuntimeAbort<Value>(
/** Settles with the task's own outcome, or rejects once the operation ends. */
async function raceImageRuntime<Value>(
operation: AbortableOperation,
task: Promise<Value>,
signal: AbortSignal,
): Promise<Value> {
return new Promise<Value>((resolve, reject) => {
let settled = false;
const onAbort = () => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
reject(capabilityVerificationAbortException());
};
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
void task.then(
(value) => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
resolve(value);
},
(error: unknown) => {
if (settled) return;
settled = true;
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function combineImageRuntimeAbortSignals(
signals: readonly AbortSignal[],
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abortListeners = new Map<AbortSignal, () => void>();
for (const signal of new Set(signals)) {
const onAbort = () => controller.abort(signal.reason);
abortListeners.set(signal, onAbort);
signal.addEventListener("abort", onAbort, { once: true });
if (signal.aborted) onAbort();
}
let released = false;
return Object.freeze({
signal: controller.signal,
release() {
if (released) return;
released = true;
for (const [signal, onAbort] of abortListeners) {
signal.removeEventListener("abort", onAbort);
}
abortListeners.clear();
},
});
const outcome = await operation.race(task);
if (outcome.kind === "VALUE") return outcome.value;
throw outcome.kind === "REJECTED"
? outcome.reason
: capabilityVerificationAbortException();
}
function capabilityVerificationFailure(
@@ -1187,35 +1096,14 @@ function capabilityVerificationAbortException(): DOMException {
function snapshotCapabilityVerificationScheduler(
scheduler: ImageCapabilityVerificationScheduler,
): ImageCapabilityVerificationScheduler {
if (
!scheduler ||
typeof scheduler.setTimeout !== "function" ||
typeof scheduler.clearTimeout !== "function"
) {
) {
try {
return snapshotAbortTimers(scheduler);
} catch {
throw new TypeError(
"Image capability verification scheduler is invalid.",
);
}
return Object.freeze({
setTimeout: scheduler.setTimeout.bind(scheduler),
clearTimeout: scheduler.clearTimeout.bind(scheduler),
});
}
function defaultCapabilityVerificationScheduler(): ImageCapabilityVerificationScheduler {
const schedule = globalThis.setTimeout.bind(globalThis);
const clear = globalThis.clearTimeout.bind(globalThis);
return Object.freeze({
setTimeout(callback: () => void, milliseconds: number) {
return schedule(callback, milliseconds);
},
clearTimeout(handle: unknown) {
clear(
handle as ReturnType<typeof globalThis.setTimeout>,
);
},
});
}
function createAssetReference(): ImageAssetReference {
@@ -73,8 +73,6 @@ function parsePng(
const interlace = bytes[payloadStart + 12];
if (
!dimensions ||
bitDepth === undefined ||
colorType === undefined ||
!validPngColorDepth(colorType, bitDepth) ||
compression !== 0 ||
filter !== 0 ||
@@ -144,7 +142,7 @@ function parseJpeg(
if (offset >= bytes.byteLength) return null;
const marker = bytes[offset];
offset += 1;
if (marker === undefined || marker === 0x00) return null;
if (marker === 0x00) return null;
if (marker === 0xd9) return null;
if (marker === 0xda) return dimensions;
if (
@@ -227,7 +225,6 @@ function parseWebp(
chunkIndex !== 0 ||
extendedHeaderSeen ||
length !== 10 ||
bytes[payloadStart] === undefined ||
(bytes[payloadStart] & 0xc3) !== 0
) {
return null;
@@ -260,15 +257,7 @@ function parseWebp(
const byte2 = bytes[payloadStart + 2];
const byte3 = bytes[payloadStart + 3];
const byte4 = bytes[payloadStart + 4];
if (
byte1 === undefined ||
byte2 === undefined ||
byte3 === undefined ||
byte4 === undefined ||
(byte4 & 0xe0) !== 0
) {
return null;
}
if ((byte4 & 0xe0) !== 0) return null;
candidate = validDimensions(
1 + byte1 + ((byte2 & 0x3f) << 8),
1 +
@@ -306,14 +295,8 @@ function parseAvif(
return null;
}
const fileType = boxes[0];
const fileTypeLength = fileType
? fileType.payloadEnd - fileType.payloadStart
: 0;
if (
!fileType ||
fileTypeLength < 8 ||
(fileTypeLength - 8) % 4 !== 0
) {
const fileTypeLength = fileType.payloadEnd - fileType.payloadStart;
if (fileTypeLength < 8 || (fileTypeLength - 8) % 4 !== 0) {
return null;
}
const brands: string[] = [
@@ -343,7 +326,6 @@ function parseAvif(
const metadataBox = metadataBoxes[0];
if (
metadataBoxes.length !== 1 ||
!metadataBox ||
metadataBox.payloadStart + 4 > metadataBox.payloadEnd ||
!zeroFullBoxFlags(bytes, metadataBox.payloadStart)
) {
@@ -413,9 +395,7 @@ function parseAvif(
const dimensions = state.properties.get(propertyIndex);
if (dimensions) associatedExtents.push(dimensions);
}
return associatedExtents.length === 1
? (associatedExtents[0] ?? null)
: null;
return associatedExtents.length === 1 ? associatedExtents[0] : null;
}
type IsoBox = Readonly<{
@@ -532,11 +512,7 @@ function parseAvifItemProperties(
(child) => child.type === "ipma",
);
const propertyContainer = propertyContainers[0];
if (
propertyContainers.length !== 1 ||
associationBoxes.length < 1 ||
!propertyContainer
) {
if (propertyContainers.length !== 1 || associationBoxes.length < 1) {
return false;
}
const properties = parseBoxes(
@@ -581,9 +557,7 @@ function parseAvifPropertyAssociations(
const version = bytes[start];
if (version !== 0 && version !== 1) return false;
const flags =
((bytes[start + 1] ?? 0) << 16) |
((bytes[start + 2] ?? 0) << 8) |
(bytes[start + 3] ?? 0);
(bytes[start + 1] << 16) | (bytes[start + 2] << 8) | bytes[start + 3];
if ((flags & ~1) !== 0) return false;
const wideAssociation = (flags & 1) === 1;
const view = dataView(bytes);
@@ -598,7 +572,6 @@ function parseAvifPropertyAssociations(
: view.getUint32(offset);
offset += itemIdBytes;
const associationCount = bytes[offset];
if (associationCount === undefined) return false;
offset += 1;
const propertyIndices: number[] = [];
for (
@@ -609,9 +582,7 @@ function parseAvifPropertyAssociations(
const associationBytes = wideAssociation ? 2 : 1;
if (offset + associationBytes > end) return false;
const encoded =
associationBytes === 2
? view.getUint16(offset)
: (bytes[offset] ?? 0);
associationBytes === 2 ? view.getUint16(offset) : bytes[offset];
const propertyIndex =
encoded & (wideAssociation ? 0x7fff : 0x7f);
offset += associationBytes;
@@ -694,35 +665,23 @@ function validDimensions(
: null;
}
/** Callers pass an offset whose three bytes lie inside a checked chunk. */
function readUint24LittleEndian(
bytes: Uint8Array,
offset: number,
): number {
const byte0 = bytes[offset];
const byte1 = bytes[offset + 1];
const byte2 = bytes[offset + 2];
if (
byte0 === undefined ||
byte1 === undefined ||
byte2 === undefined
) {
return Number.NaN;
}
return byte0 | (byte1 << 8) | (byte2 << 16);
return (
bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16)
);
}
/** Callers pass a range that the surrounding length checks keep in bounds. */
function ascii(
bytes: Uint8Array,
start: number,
end: number,
): string {
let value = "";
for (let offset = start; offset < end; offset += 1) {
const byte = bytes[offset];
if (byte === undefined) return "";
value += String.fromCharCode(byte);
}
return value;
return String.fromCharCode(...bytes.subarray(start, end));
}
function dataView(bytes: Uint8Array): DataView {
@@ -87,8 +87,7 @@ export function createP256ImageCapabilityVerifier(
return false;
}
try {
const signatureBytes = new Uint8Array(signature.byteLength);
signatureBytes.set(signature);
// `decodeBase64Url` already returns an owned, exactly sized buffer.
const payloadBytes = new Uint8Array(
request.canonicalPayload.byteLength,
);
@@ -96,7 +95,7 @@ export function createP256ImageCapabilityVerifier(
return await verify(
{ name: "ECDSA", hash: "SHA-256" },
key,
signatureBytes.buffer,
signature.buffer,
payloadBytes.buffer,
);
} catch {
@@ -106,7 +105,7 @@ export function createP256ImageCapabilityVerifier(
});
}
function decodeBase64Url(value: string): Uint8Array | null {
function decodeBase64Url(value: string): Uint8Array<ArrayBuffer> | null {
if (
!/^[A-Za-z0-9_-]+$/u.test(value) ||
value.length % 4 === 1
@@ -119,9 +118,8 @@ function decodeBase64Url(value: string): Uint8Array | null {
let accumulator = 0;
let bitCount = 0;
for (const character of value) {
const index = alphabet.indexOf(character);
if (index < 0) return null;
accumulator = (accumulator << 6) | index;
// The pattern above admits only alphabet characters.
accumulator = (accumulator << 6) | alphabet.indexOf(character);
bitCount += 6;
if (bitCount >= 8) {
bitCount -= 8;
@@ -0,0 +1,221 @@
import {
createAbortableOperation,
type AbortTimerSnapshot,
} from "../../platform/abortable-operation.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataOperation,
BrowserDataRecovery,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { browserDataByteBucket as byteBucket } from "../../../application/ports/browser-file-storage/shared.ts";
import type { Result } from "../../../contracts/result.ts";
import {
browserDataFailure,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
/**
* Q-6.1-9. HTTP mechanics shared by the presigned executor (object-store
* GET/PUT) and the capability provider (BFF issuance). They were two
* near-identical copies whose status table had already drifted apart.
*/
export { byteBucket };
/** BT-PRE-03. The scope ended before the task settled. */
export const SCOPE_ENDED = Symbol("presigned-scope-ended");
export type PresignedAbortScope = ReturnType<typeof createAbortScope>;
/**
* TR-RR-01 / TR-RR-05. A thin projection of the shared
* `createAbortableOperation` primitive into this subsystem's vocabulary.
*
* `abort()` exists, so `close()` on a download can actually stop a pending
* fetch instead of only dropping listeners; and additional ownership signals —
* a consumer's stream signal — are composed into the same operation *before*
* any I/O starts, so an already-aborted consumer never causes a fetch.
*/
export function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
consumer?: AbortSignal,
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
let release = () => {};
if (consumer?.aborted) operation.close();
else if (consumer) {
const onAbort = () => operation.close();
try {
consumer.addEventListener("abort", onAbort, { once: true });
release = () => {
try {
consumer.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
};
} catch {
// A signal that refuses a listener cannot bound this operation, so the
// operation closes rather than running unbounded.
operation.close();
}
}
const end = () => {
operation.close();
release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
/** Bounds a fetch that ignores its signal; a late response is cancelled. */
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(task, (value) => {
const body = (
value as { body?: { cancel(): Promise<void> } | null } | null
)?.body;
void body?.cancel().catch(() => undefined);
});
if (outcome.kind === "VALUE") return outcome.value;
// A collaborator's own rejection stays a rejection: the caller's existing
// catch classifies it, and it is never forged into a cancellation.
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
/** TR-RR-01. Ends the physical work, not just the bookkeeping. */
abort: end,
release: end,
});
}
export async function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) throw new DOMException("Aborted", "AbortError");
const operation = createAbortableOperation({ signal });
const outcome = await operation.race(reader.read());
operation.close();
if (outcome.kind === "VALUE") return outcome.value;
throw outcome.kind === "REJECTED"
? outcome.reason
: new DOMException("Aborted", "AbortError");
}
/**
* A plain decimal `Content-Length`. `Number()` alone accepted `"5e0"`,
* `"0x5"`, `"+5"` and `""`. An absent header is `null` unless the caller's
* binding allows an implicit zero.
*/
export function normalizedContentLength(
value: string | null,
allowImplicitZero = false,
): number | null {
if (value === null) return allowImplicitZero ? 0 : null;
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
/**
* One status table for both HTTP exchanges. Presigned capabilities are
* single-use, so every recoverable refusal — an expired or rejected signature
* (401/403), a conflict, a gone resource or a transient 429/5xx — is recovered
* by issuing a new capability, never by replaying the same one.
*/
export function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
export function transferFailure(
externalSignal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (externalSignal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{
retryable: true,
recovery: "REISSUE_CAPABILITY",
},
);
}
export function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
/**
* One terminal observation for presigned and resumable transfers. An absent or
* invalid byte length leaves `byteBucket` out rather than guessing one.
*/
export function observeTransferResult(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: Result<unknown, Readonly<{ code: BrowserDataFailureCode }>>,
byteLength?: number,
): void {
const bucket = byteBucket(byteLength);
observeBrowserData(observer, {
operation,
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
});
}
@@ -126,8 +126,8 @@ class Sha256Accumulator {
words[index] = view.getUint32(index * 4, false);
}
for (let index = 16; index < 64; index += 1) {
const previous15 = words[index - 15] ?? 0;
const previous2 = words[index - 2] ?? 0;
const previous15 = words[index - 15];
const previous2 = words[index - 2];
const sigma0 =
rotateRight(previous15, 7) ^
rotateRight(previous15, 18) ^
@@ -136,22 +136,18 @@ class Sha256Accumulator {
rotateRight(previous2, 17) ^
rotateRight(previous2, 19) ^
(previous2 >>> 10);
words[index] =
((words[index - 16] ?? 0) +
sigma0 +
(words[index - 7] ?? 0) +
sigma1) >>>
0;
// A Uint32Array store already reduces modulo 2^32.
words[index] = words[index - 16] + sigma0 + words[index - 7] + sigma1;
}
let a = this.#state[0] ?? 0;
let b = this.#state[1] ?? 0;
let c = this.#state[2] ?? 0;
let d = this.#state[3] ?? 0;
let e = this.#state[4] ?? 0;
let f = this.#state[5] ?? 0;
let g = this.#state[6] ?? 0;
let h = this.#state[7] ?? 0;
let a = this.#state[0];
let b = this.#state[1];
let c = this.#state[2];
let d = this.#state[3];
let e = this.#state[4];
let f = this.#state[5];
let g = this.#state[6];
let h = this.#state[7];
for (let index = 0; index < 64; index += 1) {
const sum1 =
@@ -161,8 +157,8 @@ class Sha256Accumulator {
(h +
sum1 +
choice +
(ROUND_CONSTANTS[index] ?? 0) +
(words[index] ?? 0)) >>>
ROUND_CONSTANTS[index] +
words[index]) >>>
0;
const sum0 =
rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
@@ -178,14 +174,15 @@ class Sha256Accumulator {
a = (temporary1 + temporary2) >>> 0;
}
this.#state[0] = ((this.#state[0] ?? 0) + a) >>> 0;
this.#state[1] = ((this.#state[1] ?? 0) + b) >>> 0;
this.#state[2] = ((this.#state[2] ?? 0) + c) >>> 0;
this.#state[3] = ((this.#state[3] ?? 0) + d) >>> 0;
this.#state[4] = ((this.#state[4] ?? 0) + e) >>> 0;
this.#state[5] = ((this.#state[5] ?? 0) + f) >>> 0;
this.#state[6] = ((this.#state[6] ?? 0) + g) >>> 0;
this.#state[7] = ((this.#state[7] ?? 0) + h) >>> 0;
const state = this.#state;
state[0] += a;
state[1] += b;
state[2] += c;
state[3] += d;
state[4] += e;
state[5] += f;
state[6] += g;
state[7] += h;
}
}
@@ -11,31 +11,40 @@ import type {
PresignedUploadPartCapabilityProvider,
} from "../../../application/ports/browser-transfer/presigned-transfer.ts";
import {
createAbortableOperation,
cancelBody,
cancelReader,
snapshotAbortTimers,
type AbortTimerSnapshot,
} from "../../platform/abortable-operation.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataFailureCode,
BrowserDataObserver,
BrowserDataRecovery,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
observeBrowserData,
} from "../../browser-file-storage/result.ts";
import type {
PresignedCapabilityRegistration,
PresignedCapabilityVault,
PresignedHeaderBinding,
} from "./presigned-capability-vault.ts";
import {
createAbortScope,
isAbortSignal,
normalizedContentLength,
observeTransferResult,
readWithSignal,
SCOPE_ENDED,
statusFailure,
transferFailure,
} from "./http-common.ts";
import {
SAFE_TRANSFER_ID,
SHA256_HEX as SHA256,
} from "../resumable-upload/checkpoint-schema.ts";
const SHA256 = /^[a-f0-9]{64}$/;
const MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
const OPAQUE_ID = /^[a-z0-9][a-z0-9._:-]{0,255}$/i;
const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
const QUERY_NAME = /^[A-Za-z0-9_.~-]{1,128}$/;
const FORBIDDEN_REQUEST_HEADERS = new Set([
@@ -170,15 +179,12 @@ export function createPresignedCapabilityHttpProvider(
result: BrowserDataResult<Capability>,
byteLength?: number,
): BrowserDataResult<Capability> {
const bucket = byteBucket(
observeTransferResult(
observer,
"PRESIGNED_TRANSFER",
result,
result.ok ? result.value.byteLength : byteLength,
);
observeBrowserData(observer, {
operation: "PRESIGNED_TRANSFER",
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
});
return result;
}
@@ -237,11 +243,11 @@ export function createPresignedCapabilityHttpProvider(
response.type === "opaqueredirect" ||
response.url !== endpoint
) {
cancelResponseBody(response);
cancelBody(response);
return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER");
}
if (!response.ok || response.status !== 200) {
cancelResponseBody(response);
cancelBody(response);
return statusFailure(response.status);
}
const contentType = response.headers.get("content-type") ?? "";
@@ -249,7 +255,7 @@ export function createPresignedCapabilityHttpProvider(
contentType.split(";", 1)[0]?.trim().toLowerCase() !==
"application/json"
) {
cancelResponseBody(response);
cancelBody(response);
return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER");
}
const payload = await readBoundedJson(
@@ -762,11 +768,11 @@ async function readBoundedJson(
if (declared !== null) {
declaredLength = normalizedContentLength(declared);
if (declaredLength === null) {
cancelResponseBody(response);
cancelBody(response);
throw new ResponseIntegrityError();
}
if (declaredLength > maxBytes) {
cancelResponseBody(response);
cancelBody(response);
throw new ResponseLimitError();
}
}
@@ -797,15 +803,7 @@ async function readBoundedJson(
text += decoder.decode();
return JSON.parse(text) as unknown;
} finally {
if (!completed) {
try {
void reader.cancel().catch(() => {
// Response cancellation is best effort after classification.
});
} catch {
// Response cleanup cannot alter the closed result.
}
}
if (!completed) cancelReader(reader);
try {
reader.releaseLock();
} catch {
@@ -814,223 +812,6 @@ async function readBoundedJson(
}
}
function cancelResponseBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Cancellation is best effort after the response is classified.
});
} catch {
// Response cleanup cannot alter the closed result.
}
}
function normalizedContentLength(value: string): number | null {
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () =>
reject(new DOMException("Aborted", "AbortError"));
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "RETRY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
recovery = "NONE";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
/** BT-PRE-03. The scope ended before the task settled. */
const SCOPE_ENDED = Symbol("presigned-capability-scope-ended");
/**
* TR-RR-01 / TR-RR-05. The abort scope is a thin projection of the shared
* `createAbortableOperation` primitive into this subsystem's vocabulary.
*
* Two things changed with the migration. `abort()` exists, so `close()` on a
* download can actually stop a pending fetch instead of only dropping
* listeners; and additional ownership signals — a consumer's stream signal —
* are composed into the same operation *before* any I/O starts, so an
* already-aborted consumer never causes a fetch.
*/
function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
additionalSignals: readonly AbortSignal[] = [],
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
const releases: (() => void)[] = [];
for (const extra of additionalSignals) {
if (!extra) continue;
if (extra.aborted) {
operation.close();
continue;
}
const onAbort = () => operation.close();
try {
extra.addEventListener("abort", onAbort, { once: true });
releases.push(() => {
try {
extra.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
});
} catch {
// A signal that refuses a listener cannot bound this operation, so the
// operation closes rather than running unbounded.
operation.close();
}
}
const releaseExtras = () => {
for (const release of releases.splice(0)) release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
/** Bounds a fetch that ignores its signal. */
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(
task,
(value) => compensateLateResponseValue(value),
);
if (outcome.kind === "VALUE") return outcome.value;
// A collaborator's own rejection stays a rejection: the caller's existing
// catch classifies it, and it is never forged into a cancellation.
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
/** TR-RR-01. Ends the physical work, not just the bookkeeping. */
abort() {
operation.close();
releaseExtras();
},
release() {
operation.close();
releaseExtras();
},
});
}
function compensateLateResponseValue(value: unknown): void {
const body = (value as { body?: { cancel(): Promise<void> } | null } | null)
?.body;
void body?.cancel().catch(() => undefined);
}
function transferFailure(
signal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (signal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{ retryable: true, recovery: "REISSUE_CAPABILITY" },
);
}
function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
function byteBucket(
byteLength: number | undefined,
):
| "ZERO"
| "LT1MIB"
| "1_TO_9MIB"
| "10_TO_99MIB"
| "GTE100MIB"
| undefined {
if (
byteLength === undefined ||
!Number.isSafeInteger(byteLength) ||
byteLength < 0
) {
return undefined;
}
if (byteLength === 0) return "ZERO";
if (byteLength < 1_048_576) return "LT1MIB";
if (byteLength < 10_485_760) return "1_TO_9MIB";
if (byteLength < 104_857_600) return "10_TO_99MIB";
return "GTE100MIB";
}
function strictRecord(
value: unknown,
keys: readonly string[],
@@ -1116,8 +897,8 @@ function normalizedSha256(value: unknown): string {
}
function snapshotOpaqueId(value: unknown, name: string): string {
const id = requiredString(value, 256);
if (!OPAQUE_ID.test(id)) throw new TypeError(`${name} is invalid.`);
const id = requiredString(value, 512);
if (!SAFE_TRANSFER_ID.test(id)) throw new TypeError(`${name} is invalid.`);
return id;
}
@@ -275,18 +275,14 @@ export function createPresignedCapabilityVault(options: Readonly<{
const invalid = validatePresignedCapabilityRegistration(snapshot);
if (invalid) return invalid;
pruneExpired();
if (
byReceipt.has(registration.capabilityReceipt) ||
byReceipt.size >= maxActiveCapabilities
) {
// Q-6.1-11. The duplicate check reads the snapshot too; the issuer's
// object is never read again once the snapshot exists.
const duplicate = byReceipt.has(snapshot.capabilityReceipt);
if (duplicate || byReceipt.size >= maxActiveCapabilities) {
return browserDataFailure(
byReceipt.has(registration.capabilityReceipt)
? "CONFLICT"
: "LIMIT_EXCEEDED",
duplicate ? "CONFLICT" : "LIMIT_EXCEEDED",
"PRESIGNED_TRANSFER",
byReceipt.has(registration.capabilityReceipt)
? { recovery: "REISSUE_CAPABILITY" }
: undefined,
duplicate ? { recovery: "REISSUE_CAPABILITY" } : undefined,
);
}
@@ -9,9 +9,9 @@ import type {
PresignedUploadPartPort,
} from "../../../application/ports/browser-transfer/presigned-transfer.ts";
import {
createAbortableOperation,
cancelBody,
cancelReader,
snapshotAbortTimers,
type AbortTimerSnapshot,
} from "../../platform/abortable-operation.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
@@ -34,9 +34,23 @@ import type {
PresignedCapabilityBinding,
PresignedCapabilityVault,
} from "./presigned-capability-vault.ts";
const SHA256 = /^[a-f0-9]{64}$/;
const RECEIPT_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/;
import {
byteBucket,
createAbortScope,
isAbortSignal,
normalizedContentLength,
observeTransferResult,
readWithSignal,
SCOPE_ENDED,
statusFailure,
transferFailure,
type PresignedAbortScope,
} from "./http-common.ts";
import {
isSafeUploadReceiptToken,
SAFE_TRANSFER_ID,
SHA256_HEX as SHA256,
} from "../resumable-upload/checkpoint-schema.ts";
type Scheduler = Readonly<{
setTimeout(callback: () => void, milliseconds: number): unknown;
@@ -185,7 +199,7 @@ export function createPresignedTransferExecutor(
signal,
timeoutMs,
timers,
consumerSignal ? [consumerSignal] : [],
consumerSignal,
),
recheckExpiry: () =>
validateExpiry(capability, minimumRemainingLifetimeMs, now()),
@@ -435,12 +449,12 @@ export function createPresignedTransferExecutor(
function createDownloadSource(input: Readonly<{
start: (
scope: ReturnType<typeof createAbortScope>,
scope: PresignedAbortScope,
) => Promise<Response>;
validateResponse: (response: Response) => BrowserDataResult<unknown>;
createScope: (
consumerSignal?: AbortSignal,
) => ReturnType<typeof createAbortScope>;
) => PresignedAbortScope;
recheckExpiry: () => BrowserDataResult<unknown>;
binding: PresignedCapabilityBinding;
capability: PresignedDownloadCapability;
@@ -453,7 +467,7 @@ function createDownloadSource(input: Readonly<{
}>): PresignedDownloadByteSource {
/** BT-PRE-01. One state machine shared by `stream()` and `close()`. */
let state: "READY" | "STREAMING" | "CLOSED" = "READY";
let activeScope: ReturnType<typeof createAbortScope> | undefined;
let activeScope: PresignedAbortScope | undefined;
let activeResponse: Response | undefined;
// TR-RR-01. Releasing the scope only dropped listeners and the timer, so a
@@ -783,8 +797,7 @@ function validateDownloadResponse(
const contentEncoding = response.headers.get("content-encoding");
if (
mediaType !== binding.mediaType ||
declaredLength === null ||
Number(declaredLength) !== binding.byteLength ||
normalizedContentLength(declaredLength) !== binding.byteLength ||
digestHeader === null ||
response.headers.get(digestHeader)?.trim().toLowerCase() !==
binding.expectedSha256 ||
@@ -928,17 +941,6 @@ function validateRequiredHeaders(
);
}
function normalizedContentLength(
value: string | null,
allowImplicitZero: boolean,
): number | null {
if (value === null) return allowImplicitZero ? 0 : null;
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
function headersFor(binding: PresignedCapabilityBinding): Headers {
const headers = new Headers();
for (const header of binding.requestHeaders) {
@@ -994,189 +996,6 @@ function validateExpiry(
);
}
function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
function transferFailure(
externalSignal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (externalSignal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{
retryable: true,
recovery: "REISSUE_CAPABILITY",
},
);
}
/** BT-PRE-03. The scope ended before the task settled. */
const SCOPE_ENDED = Symbol("presigned-scope-ended");
function compensateLateResponse(task: Promise<unknown>): void {
void task
.then(async (value) => {
const body = (value as { body?: { cancel(): Promise<void> } | null })
?.body;
await body?.cancel();
})
.catch(() => undefined);
}
/**
* TR-RR-01 / TR-RR-05. A projection of the shared `createAbortableOperation`
* primitive into this subsystem's vocabulary, replacing a second hand-written
* copy of the same mechanics.
*
* `additionalSignals` lets a consumer's stream signal join the operation's
* ownership before any I/O begins, and `abort()` ends the physical work rather
* than only releasing bookkeeping.
*/
function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
additionalSignals: readonly AbortSignal[] = [],
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
const releases: (() => void)[] = [];
for (const extra of additionalSignals) {
if (!extra) continue;
if (extra.aborted) {
operation.close();
continue;
}
const onAbort = () => operation.close();
try {
extra.addEventListener("abort", onAbort, { once: true });
releases.push(() => {
try {
extra.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
});
} catch {
operation.close();
}
}
const releaseExtras = () => {
for (const release of releases.splice(0)) release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(task, (value) => {
const body = (
value as { body?: { cancel(): Promise<void> } | null } | null
)?.body;
void body?.cancel().catch(() => undefined);
});
if (outcome.kind === "VALUE") return outcome.value;
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
abort() {
operation.close();
releaseExtras();
},
release() {
operation.close();
releaseExtras();
},
});
}
function cancelBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// A response already classified as failure/success is not reclassified by
// best-effort body cancellation.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// Reader cancellation cannot alter the terminal closed result.
}
}
function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () => {
reject(new DOMException("Aborted", "AbortError"));
};
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function normalizeReceiptToken(value: string | null): string | null {
if (!value) return null;
const trimmed = value.trim();
@@ -1186,9 +1005,7 @@ function normalizeReceiptToken(value: string | null): string | null {
trimmed.endsWith("\"")
? trimmed.slice(1, -1)
: trimmed;
return RECEIPT_TOKEN.test(unquoted) && !unquoted.includes("://")
? unquoted
: null;
return isSafeUploadReceiptToken(unquoted) ? unquoted : null;
}
function responseUrlMatches(
@@ -1211,12 +1028,7 @@ function normalizedSha256(value: unknown): string {
}
function opaqueId(value: unknown): string {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 256 ||
!/^[a-z0-9][a-z0-9._:-]*$/i.test(value)
) {
if (typeof value !== "string" || !SAFE_TRANSFER_ID.test(value)) {
throw new TypeError("Opaque identifier is invalid.");
}
return value;
@@ -1251,24 +1063,6 @@ async function digestSha256WithWebCrypto(
).join("");
}
function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
function safeInputByteLength(value: unknown): number | undefined {
try {
if (!value || typeof value !== "object") return undefined;
@@ -1304,41 +1098,3 @@ function safeInputByteLength(value: unknown): number | undefined {
}
return undefined;
}
function observeTransferResult(
observer: BrowserDataObserver | undefined,
operation: BrowserDataOperation,
result: BrowserDataResult<unknown>,
byteLength?: number,
): void {
const bucket = byteBucket(byteLength);
observeBrowserData(observer, {
operation,
outcome: result.ok ? "SUCCEEDED" : "FAILED",
...(!result.ok ? { failureCode: result.error.code } : {}),
...(bucket !== undefined ? { byteBucket: bucket } : {}),
});
}
function byteBucket(
byteLength: number | undefined,
):
| "ZERO"
| "LT1MIB"
| "1_TO_9MIB"
| "10_TO_99MIB"
| "GTE100MIB"
| undefined {
if (
byteLength === undefined ||
!Number.isSafeInteger(byteLength) ||
byteLength < 0
) {
return undefined;
}
if (byteLength === 0) return "ZERO";
if (byteLength < 1_048_576) return "LT1MIB";
if (byteLength < 10_485_760) return "1_TO_9MIB";
if (byteLength < 104_857_600) return "10_TO_99MIB";
return "GTE100MIB";
}
@@ -5,12 +5,23 @@ import type {
UploadPartReceipt,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import {
isPositiveSafeInteger as positiveSafeInteger,
isNonNegativeSafeInteger as nonNegativeSafeInteger,
} from "../../../application/ports/browser-file-storage/shared.ts";
export const SAFE_UPLOAD_KEY = /^[A-Za-z0-9][A-Za-z0-9._~:-]{7,127}$/u;
export const SAFE_REGISTRY_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
export const SAFE_OPAQUE_ID = /^[A-Za-z0-9_-]{8,512}$/u;
/**
* R-1.2. The one grammar the presigned layer applies to the IDs a capability
* binds (session, resource, idempotency key, capability receipt). A superset
* of SAFE_OPAQUE_ID, so an ID the control plane accepted is never refused
* later in the same transfer.
*/
export const SAFE_TRANSFER_ID = /^[A-Za-z0-9_-][A-Za-z0-9._:-]{0,511}$/u;
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
export const RECEIPT_TOKEN =
const RECEIPT_TOKEN =
/^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/u;
export const MEDIA_TYPE =
/^[a-z0-9!#$&^_.+-]{1,63}\/[a-z0-9!#$&^_.+-]{1,63}$/u;
@@ -60,7 +71,7 @@ export function isUploadFileFingerprint(
);
}
export function isUploadPartDescriptor(
function isUploadPartDescriptor(
value: unknown,
): value is UploadPartDescriptor {
if (!exactRecord(value, PART_KEYS)) return false;
@@ -131,7 +142,7 @@ export function isResumableUploadCheckpoint(
return true;
}
export function partMatchesFingerprint(
function partMatchesFingerprint(
part: UploadPartDescriptor,
fingerprint: UploadFileFingerprint,
): boolean {
@@ -161,7 +172,7 @@ export function samePart(
);
}
function exactRecord<const Keys extends readonly string[]>(
export function exactRecord<const Keys extends readonly string[]>(
value: unknown,
keys: Keys,
): value is Record<Keys[number], unknown> {
@@ -176,10 +187,17 @@ function exactRecord<const Keys extends readonly string[]>(
);
}
function positiveSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) > 0;
}
function nonNegativeSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) >= 0;
/**
* BT-UP-01. The structural guard must cover every method cleanup will call.
* Admitting a signal without `removeEventListener` turned a `finally` into a
* Promise rejection instead of the typed terminal result.
*/
export function isAbortSignal(value: unknown): value is AbortSignal {
return Boolean(
value &&
typeof value === "object" &&
typeof (value as AbortSignal).aborted === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
}
@@ -2,23 +2,27 @@ import type {
UploadProviderFailure,
UploadProviderResult,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataFailureCode,
BrowserDataRecovery,
import {
hasControlCharacter,
type BrowserDataFailureCode,
type BrowserDataRecovery,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
cancelBody,
cancelReader,
createAbortableOperation,
type AbortRace,
type AbortTerminalReason,
type AbortableOperation,
} from "../../platform/abortable-operation.ts";
import { parseRetryAfterDelay } from "../../platform/retry-after.ts";
import type {
ResumableUploadControlOperation,
ResumableUploadJsonTransport,
} from "./http-control-plane-adapter.ts";
import { isAbortSignal } from "./checkpoint-schema.ts";
export type ResumableUploadEndpointMap = Readonly<
Record<ResumableUploadControlOperation, string>
@@ -182,14 +186,17 @@ export function createResumableUploadFetchJsonTransport(
"NONE",
);
}
const attempt = createFetchAttempt(
// X-AUDIT-02 / TR-RR-05. The attempt is the shared abort primitive:
// the listener and the timer are installed together, so a throwing
// scheduler closes the attempt instead of rejecting `execute()`.
const attempt = createAbortableOperation({
signal,
timeoutMs,
setTimer,
clearTimer,
);
});
try {
if (attempt.terminalKind() !== null) {
if (attempt.terminal() !== null) {
// The attempt was closed before it could be bounded, so no request is
// ever put on the wire.
return attemptFailure(attempt, operation);
@@ -210,7 +217,7 @@ export function createResumableUploadFetchJsonTransport(
const raced = await attempt.race(
Promise.resolve(fetchPromise),
(late) => {
cancelResponseBody(late);
cancelBody(late);
},
);
if (raced.kind !== "VALUE") {
@@ -222,7 +229,7 @@ export function createResumableUploadFetchJsonTransport(
response.type === "opaqueredirect" ||
!sameUrl(response.url, endpoint)
) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"POLICY_REJECTED",
operation,
@@ -237,11 +244,11 @@ export function createResumableUploadFetchJsonTransport(
maxRetryAfterMs,
safeNowEpochMs(),
);
cancelResponseBody(response);
cancelBody(response);
return failed;
}
if (!jsonContentType(response.headers.get("content-type"))) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"CORRUPT_DATA",
operation,
@@ -261,7 +268,9 @@ export function createResumableUploadFetchJsonTransport(
} catch {
return attemptFailure(attempt, operation);
} finally {
attempt.release();
// BT-UP-01. Cleanup is best effort and never replaces the classified
// terminal result with a rejection.
attempt.close();
}
},
};
@@ -341,7 +350,7 @@ function snapshotHeaders(
seen.has(name) ||
typeof header.value !== "string" ||
header.value.length > 2048 ||
hasForbiddenHeaderValueCharacter(header.value)
hasControlCharacter(header.value)
) {
throw new TypeError("Upload request header is invalid.");
}
@@ -405,7 +414,7 @@ async function readBoundedJson(
response: Response,
maxBytes: number,
operation: ResumableUploadControlOperation,
attempt: FetchAttempt,
attempt: AbortableOperation,
): Promise<UploadProviderResult<unknown>> {
const contentLength = response.headers.get("content-length");
let declaredLength: number | null = null;
@@ -414,7 +423,7 @@ async function readBoundedJson(
(!/^(0|[1-9][0-9]*)$/u.test(contentLength) ||
Number(contentLength) > maxBytes)
) {
cancelResponseBody(response);
cancelBody(response);
return failure(
"LIMIT_EXCEEDED",
operation,
@@ -532,7 +541,7 @@ function statusFailure(
return failure("LIMIT_EXCEEDED", operation, false, "NONE");
}
if (response.status === 429) {
const retryAfterMs = parseRetryAfter(
const retryAfterMs = parseRetryAfterDelay(
response.headers.get("retry-after"),
nowEpochMs,
);
@@ -574,89 +583,15 @@ function failure(
return Object.freeze({ ok: false, error });
}
type FetchAttemptTerminalKind = "ABORT" | "TIMEOUT" | "CLOSED";
type FetchAttempt = Readonly<{
signal: AbortSignal;
terminalKind(): FetchAttemptTerminalKind | null;
race<Value>(
task: Promise<Value>,
compensate?: (value: Value) => void,
): Promise<AbortRace<Value>>;
release(): void;
}>;
/**
* X-AUDIT-02 / TR-RR-05. The attempt is the shared abort primitive with this
* subsystem's vocabulary on top. Owning a private copy meant the listener was
* attached before the timer was installed, so a scheduler that threw rejected
* the public `execute()` promise and left the listener on the caller's signal.
*/
function createFetchAttempt(
parent: AbortSignal,
timeoutMs: number,
setTimer: (callback: () => void, delayMs: number) => unknown,
clearTimer: (handle: unknown) => void,
): FetchAttempt {
const operation = createAbortableOperation({
signal: parent,
timeoutMs,
setTimer,
clearTimer,
});
const kindOf = (
reason: AbortTerminalReason | null,
): FetchAttemptTerminalKind | null => {
if (reason === null) return null;
if (reason === "CALLER_ABORT") return "ABORT";
return reason === "DEADLINE" ? "TIMEOUT" : "CLOSED";
};
return Object.freeze({
signal: operation.signal,
terminalKind: () => kindOf(operation.terminal()),
race: <Value,>(
task: Promise<Value>,
compensate?: (value: Value) => void,
) => operation.race(task, compensate),
release() {
// BT-UP-01. Cleanup is best effort and must never replace the already
// classified terminal result with a rejection.
operation.close();
},
});
}
function attemptFailure(
attempt: FetchAttempt,
attempt: AbortableOperation,
operation: ResumableUploadControlOperation,
): UploadProviderResult<never> {
return attempt.terminalKind() === "ABORT"
return attempt.terminal() === "CALLER_ABORT"
? failure("ABORTED", operation, false, "NONE")
: failure("UNAVAILABLE", operation, true, "RESUME");
}
function cancelResponseBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Response cancellation is best effort after closed classification.
});
} catch {
// A cancellation failure cannot change the already classified result.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => {
// Reader cancellation is best effort after closed classification.
});
} catch {
// A cancellation failure cannot change the already classified result.
}
}
function releaseReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
@@ -667,29 +602,6 @@ function releaseReader(
}
}
/**
* BT-UP-02. Both the delta-seconds and the HTTP-date branch resolve against the
* same captured `now`, so a fake clock makes boundary, rollback and invalid-date
* behaviour deterministic instead of depending on the global clock.
*/
function parseRetryAfter(
value: string | null,
nowEpochMs: number,
): number | null {
if (!value) return null;
if (/^(0|[1-9][0-9]*)$/u.test(value)) {
const seconds = Number(value);
const milliseconds = seconds * 1000;
return Number.isSafeInteger(milliseconds) ? milliseconds : null;
}
const timestamp = Date.parse(value);
if (!Number.isFinite(timestamp) || !Number.isSafeInteger(nowEpochMs)) {
return null;
}
// A clock that moved backwards yields zero, never a negative delay.
return Math.max(0, timestamp - nowEpochMs);
}
function jsonContentType(value: string | null): boolean {
return Boolean(
value &&
@@ -721,21 +633,6 @@ function boundedPositiveInteger(
return value;
}
/**
* BT-UP-01. The structural guard must cover every method cleanup will call.
* Admitting a signal without `removeEventListener` turned a `finally` into a
* Promise rejection instead of the typed terminal result.
*/
function isAbortSignal(value: unknown): value is AbortSignal {
return Boolean(
value &&
typeof value === "object" &&
typeof (value as AbortSignal).aborted === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
}
function isControlOperation(
value: unknown,
): value is ResumableUploadControlOperation {
@@ -766,13 +663,6 @@ function snapshotTransportRequest(
}
}
function hasForbiddenHeaderValueCharacter(value: string): boolean {
return [...value].some((character) => {
const codePoint = character.codePointAt(0);
return codePoint !== undefined && (codePoint <= 31 || codePoint === 127);
});
}
function isPlainRecord(
value: unknown,
): value is Readonly<Record<string, unknown>> {
@@ -30,6 +30,10 @@ import {
SAFE_UPLOAD_KEY,
SHA256_HEX,
} from "./checkpoint-schema.ts";
import {
isPositiveSafeInteger as positiveSafeInteger,
isNonNegativeSafeInteger as nonNegativeSafeInteger,
} from "../../../application/ports/browser-file-storage/shared.ts";
export type ResumableUploadControlOperation =
| "CREATE_SESSION"
@@ -679,11 +683,3 @@ function safeIdempotencyKey(value: string): boolean {
/^[A-Za-z0-9._~-]+$/u.test(value)
);
}
function positiveSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) > 0;
}
function nonNegativeSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) >= 0;
}
@@ -285,6 +285,35 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
}),
});
/**
* Every store operation reads the row it guards inside the same transaction
* it may then write in, so the guard and the write cannot interleave with
* another context.
*/
async function withCheckpointRow<Value>(
uploadKey: string,
mode: "readonly" | "readwrite",
signal: AbortSignal | undefined,
onRow: (
row: unknown,
store: IDBObjectStore,
context: CheckpointTransactionContext<Value>,
) => void,
): Promise<BrowserDataResult<Value>> {
const opened = await connection.acquire(signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<Value>(
opened.value,
mode,
signal,
(nativeStore, context) => {
const request = nativeStore.get(uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => onRow(request.result, nativeStore, context);
},
);
}
const storeValue: ResumableUploadCheckpointStore = {
async read(
uploadKey: string,
@@ -295,32 +324,22 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
if (!SAFE_UPLOAD_KEY.test(uploadKey)) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<
ResumableUploadCheckpoint | null
>(
opened.value,
return await withCheckpointRow<ResumableUploadCheckpoint | null>(
uploadKey,
"readonly",
signal,
(nativeStore, context) => {
const request = nativeStore.get(uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
if (request.result === undefined) {
context.succeed(null);
return;
}
if (!isResumableUploadCheckpoint(request.result)) {
context.fail(
checkpointFailure("CORRUPT_DATA", { recovery: "RECONCILE" }),
);
return;
}
context.succeed(
snapshotCheckpoint(request.result),
(row, _nativeStore, context) => {
if (row === undefined) {
context.succeed(null);
return;
}
if (!isResumableUploadCheckpoint(row)) {
context.fail(
checkpointFailure("CORRUPT_DATA", { recovery: "RECONCILE" }),
);
};
return;
}
context.succeed(snapshotCheckpoint(row));
},
);
},
@@ -345,32 +364,25 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(inputValue.signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<ResumableUploadCheckpoint>(
opened.value,
return await withCheckpointRow<ResumableUploadCheckpoint>(
checkpoint.uploadKey,
"readwrite",
inputValue.signal,
(nativeStore, context) => {
const request = nativeStore.get(checkpoint.uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
const current = request.result;
if (
(expectedRevision === null && current !== undefined) ||
(expectedRevision !== null &&
(!isResumableUploadCheckpoint(current) ||
current.revision !== expectedRevision))
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const put = nativeStore.put(checkpoint);
put.onerror = () => context.fail(mappedFailure(put.error));
put.onsuccess = () => context.succeed(checkpoint);
};
(current, nativeStore, context) => {
if (
(expectedRevision === null && current !== undefined) ||
(expectedRevision !== null &&
(!isResumableUploadCheckpoint(current) ||
current.revision !== expectedRevision))
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const put = nativeStore.put(checkpoint);
put.onerror = () => context.fail(mappedFailure(put.error));
put.onsuccess = () => context.succeed(checkpoint);
},
);
},
@@ -387,30 +399,51 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
const opened = await connection.acquire(inputValue.signal);
if (!opened.ok) return opened;
return await runCheckpointTransaction<void>(
opened.value,
return await withCheckpointRow<void>(
inputValue.uploadKey,
"readwrite",
inputValue.signal,
(nativeStore, context) => {
const request = nativeStore.get(inputValue.uploadKey);
request.onerror = () => context.fail(mappedFailure(request.error));
request.onsuccess = () => {
if (
!isResumableUploadCheckpoint(request.result) ||
request.result.revision !== inputValue.expectedRevision
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
const deletion = nativeStore.delete(inputValue.uploadKey);
deletion.onerror = () =>
context.fail(mappedFailure(deletion.error));
deletion.onsuccess = () => context.succeed(undefined);
};
(row, nativeStore, context) => {
if (
!isResumableUploadCheckpoint(row) ||
row.revision !== inputValue.expectedRevision
) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
deleteCheckpointRow(nativeStore, inputValue.uploadKey, context);
},
);
},
async removeUnreadable(
inputValue: Parameters<
NonNullable<ResumableUploadCheckpointStore["removeUnreadable"]>
>[0],
): Promise<BrowserDataResult<void>> {
if (!SAFE_UPLOAD_KEY.test(inputValue.uploadKey)) {
return browserDataFailure("INVALID_INPUT", OPERATION);
}
return await withCheckpointRow<void>(
inputValue.uploadKey,
"readwrite",
inputValue.signal,
(row, nativeStore, context) => {
// Checked in the same transaction as the delete, so a row another
// context rewrote as a valid checkpoint is never dropped.
if (row === undefined) {
context.succeed(undefined);
return;
}
if (isResumableUploadCheckpoint(row)) {
context.fail(
checkpointFailure("CONFLICT", { recovery: "RECONCILE" }),
);
return;
}
deleteCheckpointRow(nativeStore, inputValue.uploadKey, context);
},
);
},
@@ -477,6 +510,21 @@ export function createIndexedDbResumableUploadCheckpointRuntime(
return Object.freeze({ store, admin });
}
type CheckpointTransactionContext<Value> = Readonly<{
succeed(value: Value): void;
fail(failure: BrowserDataFailure): void;
}>;
function deleteCheckpointRow(
store: IDBObjectStore,
uploadKey: string,
context: CheckpointTransactionContext<void>,
): void {
const deletion = store.delete(uploadKey);
deletion.onerror = () => context.fail(mappedFailure(deletion.error));
deletion.onsuccess = () => context.succeed(undefined);
}
/**
* `durability` is deliberately `undefined` rather than `"default"`: that opens
* the transaction with no options bag at all, which is what checkpoint writes
@@ -494,10 +542,7 @@ async function runCheckpointTransaction<Value>(
signal: AbortSignal | undefined,
execute: (
store: IDBObjectStore,
context: Readonly<{
succeed(value: Value): void;
fail(failure: BrowserDataFailure): void;
}>,
context: CheckpointTransactionContext<Value>,
) => void,
): Promise<BrowserDataResult<Value>> {
return await runIndexedDbTransaction<Value, BrowserDataFailure>({
@@ -91,7 +91,9 @@ export function createPresignedUploadPartExecutor(
byteLength: input.part.byteLength,
checksumSha256: input.part.checksumSha256,
idempotencyKey: input.idempotencyKey,
bytes: Uint8Array.from(input.bytes),
// Q-6.1-3b. The presigned port snapshots `bytes` before any await,
// so a second copy here only doubled the per-part buffer.
bytes: input.bytes,
signal: input.signal,
});
} catch {
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,378 @@
import type {
ResumableUploadCheckpointStore,
ResumableUploadControlPlane,
UploadPartExecutor,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataObserver,
BrowserDataOperation,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import { createAbortableOperation } from "../../platform/abortable-operation.ts";
import { snapshotUploadCrypto, type UploadCrypto } from "./upload-byte-source.ts";
import {
resolveResumableUploadRuntimePolicy,
type ResumableUploadRuntimePolicy,
} from "./runtime-policy.ts";
import type { UploadCancellationChannel } from "./upload-cancellation-channel.ts";
import type { UploadMutationLock } from "./upload-mutation-lock.ts";
/**
* Q-6.1-10. The resumable upload runtime's injected collaborators. Each one is
* validated and its methods captured once at composition, so replacing a
* method afterwards cannot change what an upload in flight calls.
*/
export type ResumableUploadRuntimeDependencies<Capability> = Readonly<{
controlPlane: ResumableUploadControlPlane<Capability>;
partExecutor: UploadPartExecutor<Capability>;
checkpoints: ResumableUploadCheckpointStore;
mutationLock: UploadMutationLock;
/**
* Runtime-owned ephemeral BroadcastChannel coordination. When omitted,
* explicit abort is still correct but may wait for another context's lock.
*/
crossContextCancellation?: UploadCancellationChannel;
crypto: Crypto;
policy?: Partial<ResumableUploadRuntimePolicy>;
now?: () => number;
random?: () => number;
sleep?: (delayMs: number, signal: AbortSignal) => Promise<void>;
observer?: BrowserDataObserver;
}>;
export type RuntimeDependencies<Capability> = Readonly<{
controlPlane: ResumableUploadControlPlane<Capability>;
partExecutor: UploadPartExecutor<Capability>;
checkpoints: ResumableUploadCheckpointStore;
mutationLock: UploadMutationLock;
crossContextCancellation?: UploadCancellationChannel;
crypto: UploadCrypto;
policy: ResumableUploadRuntimePolicy;
now(): number;
random(): number;
sleep(delayMs: number, signal: AbortSignal): Promise<void>;
observer?: BrowserDataObserver;
/**
* TR-04. Every raw provider promise, from the moment the collaborator is
* called until it actually settles. The wrapper that bounds the attempt can
* settle long before the provider does, so the wrapper registry alone could
* report an empty set while physical work was still running.
*/
physicalTasks: Set<Promise<unknown>>;
}>;
export function snapshotDependencies<Capability>(
input: ResumableUploadRuntimeDependencies<Capability>,
physicalTasks: Set<Promise<unknown>>,
): RuntimeDependencies<Capability> {
const policy = resolveResumableUploadRuntimePolicy(input.policy);
const controlPlane = snapshotControlPlane(input.controlPlane);
const partExecutor = snapshotPartExecutor(input.partExecutor);
const checkpoints = snapshotCheckpointStore(input.checkpoints);
const mutationLock = snapshotMutationLock(input.mutationLock);
const crossContextCancellation = snapshotCancellationChannel(
input.crossContextCancellation,
);
const crypto = snapshotUploadCrypto(input.crypto);
const nowSource = input.now ?? Date.now;
const randomSource = input.random ?? Math.random;
const sleepSource = input.sleep ?? abortableSleep;
const observer = snapshotObserver(input.observer);
if (
typeof nowSource !== "function" ||
typeof randomSource !== "function" ||
typeof sleepSource !== "function"
) {
throw new TypeError("Upload runtime dependency is invalid.");
}
return Object.freeze({
physicalTasks,
controlPlane,
partExecutor,
checkpoints,
mutationLock,
...(crossContextCancellation
? { crossContextCancellation }
: {}),
crypto,
policy,
now: () => nowSource(),
random: () => randomSource(),
sleep: async (delayMs, signal) =>
await sleepSource(delayMs, signal),
...(observer ? { observer } : {}),
});
}
function snapshotCancellationChannel(
value: UploadCancellationChannel | undefined,
): UploadCancellationChannel | undefined {
if (!value) return undefined;
const publish = value.publish;
const subscribe = value.subscribe;
const close = value.close;
if (
typeof publish !== "function" ||
typeof subscribe !== "function" ||
typeof close !== "function"
) {
throw new TypeError(
"Upload cancellation channel is invalid.",
);
}
return Object.freeze({
publish(uploadKey: string): boolean {
try {
return publish.call(value, uploadKey) === true;
} catch {
return false;
}
},
subscribe(
listener: (uploadKey: string) => void,
): () => void {
const release = subscribe.call(value, listener);
if (typeof release !== "function") {
throw new TypeError(
"Upload cancellation subscription is invalid.",
);
}
let active = true;
return () => {
if (!active) return;
active = false;
try {
release();
} catch {
// Runtime close remains terminal.
}
};
},
close(): void {
try {
close.call(value);
} catch {
// Runtime close remains terminal.
}
},
});
}
function snapshotObserver(
value: BrowserDataObserver | undefined,
): BrowserDataObserver | undefined {
if (!value) return undefined;
const record = value.record;
if (typeof record !== "function") {
throw new TypeError("Upload observer is invalid.");
}
return Object.freeze({
record(
observation: Parameters<BrowserDataObserver["record"]>[0],
) {
record.call(value, Object.freeze({ ...observation }));
},
});
}
function snapshotControlPlane<Capability>(
value: ResumableUploadControlPlane<Capability>,
): ResumableUploadControlPlane<Capability> {
const createSession = value?.createSession;
const getStatus = value?.getStatus;
const issuePartCapability = value?.issuePartCapability;
const complete = value?.complete;
const abort = value?.abort;
if (
typeof createSession !== "function" ||
typeof getStatus !== "function" ||
typeof issuePartCapability !== "function" ||
typeof complete !== "function" ||
typeof abort !== "function"
) {
throw new TypeError("Upload control plane is invalid.");
}
const snapshot: ResumableUploadControlPlane<Capability> = {
async createSession(
input: Parameters<
ResumableUploadControlPlane<Capability>["createSession"]
>[0],
) {
return await createSession.call(value, input);
},
async getStatus(
input: Parameters<
ResumableUploadControlPlane<Capability>["getStatus"]
>[0],
) {
return await getStatus.call(value, input);
},
async issuePartCapability(
input: Parameters<
ResumableUploadControlPlane<Capability>["issuePartCapability"]
>[0],
) {
return await issuePartCapability.call(value, input);
},
async complete(
input: Parameters<
ResumableUploadControlPlane<Capability>["complete"]
>[0],
) {
return await complete.call(value, input);
},
async abort(
input: Parameters<
ResumableUploadControlPlane<Capability>["abort"]
>[0],
) {
return await abort.call(value, input);
},
};
return Object.freeze(snapshot);
}
function snapshotPartExecutor<Capability>(
value: UploadPartExecutor<Capability>,
): UploadPartExecutor<Capability> {
const uploadPart = value?.uploadPart;
if (typeof uploadPart !== "function") {
throw new TypeError("Upload part executor is invalid.");
}
const snapshot: UploadPartExecutor<Capability> = {
async uploadPart(
input: Parameters<UploadPartExecutor<Capability>["uploadPart"]>[0],
) {
return await uploadPart.call(value, input);
},
};
return Object.freeze(snapshot);
}
function snapshotCheckpointStore(
value: ResumableUploadCheckpointStore,
): ResumableUploadCheckpointStore {
const read = value?.read;
const compareAndSwap = value?.compareAndSwap;
const remove = value?.remove;
const removeUnreadable = value?.removeUnreadable;
const close = value?.close;
if (
typeof read !== "function" ||
typeof compareAndSwap !== "function" ||
typeof remove !== "function" ||
(removeUnreadable !== undefined &&
typeof removeUnreadable !== "function") ||
typeof close !== "function"
) {
throw new TypeError("Upload checkpoint store is invalid.");
}
const snapshot: ResumableUploadCheckpointStore = {
async read(
uploadKey: string,
signal?: AbortSignal,
) {
return await read.call(value, uploadKey, signal);
},
async compareAndSwap(
input: Parameters<
ResumableUploadCheckpointStore["compareAndSwap"]
>[0],
) {
return await compareAndSwap.call(value, input);
},
async remove(
input: Parameters<ResumableUploadCheckpointStore["remove"]>[0],
) {
return await remove.call(value, input);
},
...(removeUnreadable
? {
async removeUnreadable(
input: Parameters<typeof removeUnreadable>[0],
) {
return await removeUnreadable.call(value, input);
},
}
: {}),
close() {
close.call(value);
},
};
return Object.freeze(snapshot);
}
function snapshotMutationLock(value: UploadMutationLock): UploadMutationLock {
const run = value?.run;
if (typeof run !== "function") {
throw new TypeError("Upload mutation lock is invalid.");
}
return Object.freeze({
async run<Value>(
uploadKey: string,
signal: AbortSignal,
task: () => Promise<Value>,
): Promise<Value> {
return await (run.call(
value,
uploadKey,
signal,
task,
) as Promise<Value>);
},
});
}
export function safeNow<Capability>(
dependencies: RuntimeDependencies<Capability>,
operation: BrowserDataOperation,
): BrowserDataResult<number> {
try {
const value = dependencies.now();
return Number.isSafeInteger(value) && value >= 0
? browserDataSuccess(value)
: browserDataFailure("UNAVAILABLE", operation, {
recovery: "RESUME",
});
} catch {
return browserDataFailure("UNAVAILABLE", operation, {
recovery: "RESUME",
});
}
}
export function safeRandom<Capability>(
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<number> {
try {
const value = dependencies.random();
return Number.isFinite(value) && value >= 0 && value <= 1
? browserDataSuccess(value)
: browserDataFailure("UNAVAILABLE", "UPLOAD_RECONCILE", {
recovery: "RESUME",
});
} catch {
return browserDataFailure("UNAVAILABLE", "UPLOAD_RECONCILE", {
recovery: "RESUME",
});
}
}
async function abortableSleep(
delayMs: number,
signal: AbortSignal,
): Promise<void> {
// The kernel owns the timer and the abort listener; the sleep only waits
// for whichever of the two ends the operation first.
const sleep = createAbortableOperation({ signal, timeoutMs: delayMs });
const ended = await sleep.race(new Promise<never>(() => {}));
sleep.close();
if (ended.kind !== "TERMINAL" || ended.terminal !== "DEADLINE") {
throw new DOMException("The operation was aborted.", "AbortError");
}
}
@@ -1,3 +1,8 @@
import {
isPositiveSafeInteger as positiveSafeInteger,
isNonNegativeSafeInteger as nonNegativeSafeInteger,
} from "../../../application/ports/browser-file-storage/shared.ts";
export type ResumableUploadRuntimePolicy = Readonly<{
partSizeBytes: number;
maxFileBytes: number;
@@ -44,7 +49,9 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({
partSizeBytes: 5 * MIB,
maxFileBytes: 5 * GIB,
maxPartCount: 1_024,
maxConcurrency: 3,
// R-1.3. 5 MiB × 1 × copyFactor 4 fills the 20 MiB budget; raise both
// together to upload parts in parallel.
maxConcurrency: 1,
maxInFlightBytes: 20 * MIB,
partBufferCopyFactor: 4,
maxSourceChunkBytes: 8 * MIB,
@@ -80,7 +87,9 @@ export function resolveResumableUploadRuntimePolicy(
policy.partBufferCopyFactor >
ABSOLUTE_LIMITS.maxPartBufferCopyFactor ||
policy.maxInFlightBytes <
policy.partSizeBytes * policy.partBufferCopyFactor ||
policy.partSizeBytes *
policy.maxConcurrency *
policy.partBufferCopyFactor ||
!positiveSafeInteger(policy.maxSourceChunkBytes) ||
policy.maxSourceChunkBytes >
ABSOLUTE_LIMITS.maxSourceChunkBytes ||
@@ -112,11 +121,3 @@ export function resolveResumableUploadRuntimePolicy(
}
return policy;
}
function positiveSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
function nonNegativeSafeInteger(value: number): boolean {
return Number.isSafeInteger(value) && value >= 0;
}
@@ -13,6 +13,9 @@ import {
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import { samePart } from "./checkpoint-schema.ts";
import {
isPositiveSafeInteger as positiveSafeInteger,
} from "../../../application/ports/browser-file-storage/shared.ts";
export type UploadCrypto = Readonly<{
digestSha256(bytes: Uint8Array): Promise<ArrayBuffer>;
@@ -594,7 +597,3 @@ function remapFailure(
}),
});
}
function positiveSafeInteger(value: unknown): value is number {
return Number.isSafeInteger(value) && (value as number) > 0;
}
@@ -0,0 +1,296 @@
import type {
ActiveUploadStatus,
ResumableUploadCheckpoint,
UploadFileFingerprint,
UploadPartCapability,
UploadPartReceipt,
UploadSession,
UploadSessionStatus,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
BrowserDataOperation,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../browser-file-storage/result.ts";
import {
exactRecord,
isUploadFileFingerprint,
isUploadPartReceipt,
SAFE_OPAQUE_ID,
SHA256_HEX,
} from "./checkpoint-schema.ts";
import { safeNow, type RuntimeDependencies } from "./runtime-dependencies.ts";
import {
verifyPartAgainstManifest,
type UploadPartManifest,
} from "./upload-byte-source.ts";
/**
* Q-6.1-10. Strict decoders for what the control plane returns: a session, a
* status, a part capability and the accepted receipts. Every failure is closed
* with the recovery the runtime reports unchanged.
*/
export function validatePartCapability<Capability>(
value: UploadPartCapability<Capability>,
checkpoint: ResumableUploadCheckpoint,
uploadBindingSha256: string,
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<UploadPartCapability<Capability>> {
if (
!exactRecord(value, [
"capability",
"uploadBindingSha256",
"expiresAtEpochMs",
]) ||
value.uploadBindingSha256 !== uploadBindingSha256 ||
!SHA256_HEX.test(value.uploadBindingSha256) ||
!Number.isSafeInteger(value.expiresAtEpochMs)
) {
return browserDataFailure("CORRUPT_DATA", "UPLOAD_PART", {
recovery: "REISSUE_CAPABILITY",
});
}
const now = safeNow(dependencies, "UPLOAD_PART");
if (!now.ok) return now;
if (
value.expiresAtEpochMs <=
now.value + dependencies.policy.capabilityRefreshSkewMs
) {
return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_PART", {
retryable: true,
recovery: "REISSUE_CAPABILITY",
});
}
if (value.expiresAtEpochMs > checkpoint.sessionExpiresAtEpochMs) {
return browserDataFailure("POLICY_REJECTED", "UPLOAD_PART", {
recovery: "REISSUE_CAPABILITY",
});
}
return browserDataSuccess(value);
}
export function validateStatus<Capability>(
value: UploadSessionStatus,
checkpoint: ResumableUploadCheckpoint,
manifest: UploadPartManifest,
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<UploadSessionStatus> {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return browserDataFailure("CORRUPT_DATA", "UPLOAD_RECONCILE", {
recovery: "RECONCILE",
});
}
if (value.state === "ACTIVE") {
if (!exactRecord(value, ["state", "session", "acceptedParts"])) {
return browserDataFailure(
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
{ recovery: "RECONCILE" },
);
}
const session = validateSession(
value.session,
checkpoint.requestBindingSha256,
manifest.fingerprint,
dependencies,
true,
);
if (
!session.ok ||
session.value.sessionId !== checkpoint.sessionId ||
session.value.maxConcurrency !== checkpoint.sessionMaxConcurrency ||
session.value.expiresAtEpochMs !==
checkpoint.sessionExpiresAtEpochMs
) {
return browserDataFailure(
"INTEGRITY_FAILED",
"UPLOAD_RECONCILE",
{ recovery: "RECONCILE" },
);
}
const receipts = validateServerReceipts(
value,
manifest,
"UPLOAD_RECONCILE",
);
if (!receipts.ok) return receipts;
return browserDataSuccess(
Object.freeze({
state: "ACTIVE" as const,
session: session.value,
acceptedParts: receipts.value,
}),
);
}
if (value.state === "QUARANTINED") {
if (!exactRecord(value, ["state", "session", "resourceId"])) {
return browserDataFailure(
"CORRUPT_DATA",
"UPLOAD_RECONCILE",
{ recovery: "RECONCILE" },
);
}
const session = validateSession(
value.session,
checkpoint.requestBindingSha256,
manifest.fingerprint,
dependencies,
false,
);
if (
!session.ok ||
session.value.sessionId !== checkpoint.sessionId ||
session.value.maxConcurrency !== checkpoint.sessionMaxConcurrency ||
session.value.expiresAtEpochMs !==
checkpoint.sessionExpiresAtEpochMs ||
!SAFE_OPAQUE_ID.test(value.resourceId)
) {
return browserDataFailure(
"INTEGRITY_FAILED",
"UPLOAD_RECONCILE",
{ recovery: "RECONCILE" },
);
}
return browserDataSuccess(
Object.freeze({
state: "QUARANTINED" as const,
session: session.value,
resourceId: value.resourceId,
}),
);
}
if (
!["ABORTED", "EXPIRED", "NOT_FOUND"].includes(value.state) ||
!exactRecord(value, [
"state",
"protocol",
"sessionId",
"requestBindingSha256",
]) ||
value.protocol !== RESUMABLE_UPLOAD_PROTOCOL ||
value.sessionId !== checkpoint.sessionId ||
value.requestBindingSha256 !== checkpoint.requestBindingSha256
) {
return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_RECONCILE", {
recovery: "RECONCILE",
});
}
return browserDataSuccess(
Object.freeze({
state: value.state,
protocol: RESUMABLE_UPLOAD_PROTOCOL,
sessionId: value.sessionId,
requestBindingSha256: value.requestBindingSha256,
}),
);
}
export function validateSession<Capability>(
value: UploadSession,
requestBindingSha256: string,
fingerprint: UploadFileFingerprint,
dependencies: RuntimeDependencies<Capability>,
requireActiveExpiry = true,
): BrowserDataResult<UploadSession> {
if (
!exactRecord(value, [
"protocol",
"sessionId",
"requestBindingSha256",
"fingerprint",
"partSizeBytes",
"partCount",
"maxConcurrency",
"expiresAtEpochMs",
]) ||
value.protocol !== RESUMABLE_UPLOAD_PROTOCOL ||
!SAFE_OPAQUE_ID.test(value.sessionId) ||
value.requestBindingSha256 !== requestBindingSha256 ||
!SHA256_HEX.test(value.requestBindingSha256) ||
!isUploadFileFingerprint(value.fingerprint) ||
!sameFingerprint(value.fingerprint, fingerprint) ||
value.partSizeBytes !== fingerprint.partSizeBytes ||
value.partCount !== fingerprint.partCount ||
!Number.isSafeInteger(value.maxConcurrency) ||
value.maxConcurrency < 1 ||
value.maxConcurrency > dependencies.policy.maxConcurrency ||
!Number.isSafeInteger(value.expiresAtEpochMs)
) {
return browserDataFailure("INTEGRITY_FAILED", "UPLOAD_SESSION", {
recovery: "RECONCILE",
});
}
const now = safeNow(dependencies, "UPLOAD_SESSION");
if (!now.ok) return now;
if (
requireActiveExpiry &&
(value.expiresAtEpochMs <= now.value ||
value.expiresAtEpochMs - now.value >
dependencies.policy.maxSessionLifetimeMs)
) {
return browserDataFailure("EXPIRED_RESOURCE", "UPLOAD_SESSION", {
recovery: "RESTART",
});
}
return browserDataSuccess(
Object.freeze({
...value,
fingerprint: Object.freeze({ ...value.fingerprint }),
}),
);
}
function validateServerReceipts(
status: ActiveUploadStatus,
manifest: UploadPartManifest,
operation: BrowserDataOperation,
): BrowserDataResult<readonly UploadPartReceipt[]> {
if (
!Array.isArray(status.acceptedParts) ||
status.acceptedParts.length > manifest.parts.length
) {
return browserDataFailure("CORRUPT_DATA", operation, {
recovery: "RECONCILE",
});
}
let previousPart = 0;
for (const receipt of status.acceptedParts) {
if (
!isUploadPartReceipt(receipt) ||
receipt.partNumber <= previousPart ||
!verifyPartAgainstManifest(receipt, manifest)
) {
return browserDataFailure("INTEGRITY_FAILED", operation, {
recovery: "RECONCILE",
});
}
previousPart = receipt.partNumber;
}
return browserDataSuccess(snapshotReceipts(status.acceptedParts));
}
export function sameFingerprint(
left: UploadFileFingerprint,
right: UploadFileFingerprint,
): boolean {
return (
left.algorithm === right.algorithm &&
left.digestHex === right.digestHex &&
left.byteLength === right.byteLength &&
left.partSizeBytes === right.partSizeBytes &&
left.partCount === right.partCount
);
}
export function snapshotReceipts(
parts: readonly UploadPartReceipt[],
): readonly UploadPartReceipt[] {
return Object.freeze(
parts.map((part) => Object.freeze({ ...part })),
);
}
@@ -0,0 +1,656 @@
import type {
PublicCacheAsset,
PublicCacheHeader,
PublicCacheReleaseManifest,
} from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type {
BrowserDataFailure,
BrowserDataFailureCode,
BrowserDataOperation,
BrowserDataResult,
} from "../../application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
mapBrowserDataException,
} from "../browser-file-storage/result.ts";
import {
isAllowedPublicCacheOrigin,
type PublicCacheRuntimePolicy,
} from "./public-cache-policy.ts";
/**
* Q-6.2-11. Release manifest, marker and active-pointer codec for the public
* response cache: normalization, canonical digest input, bounded control JSON
* decoding, owned cache naming, and the mapping of a validation failure to a
* browser-data Result. Moved verbatim out of the adapter.
*/
export type PublicCacheCryptoFacade = Readonly<{
digestSha256(bytes: Uint8Array): Promise<ArrayBuffer>;
}>;
export type NormalizedAsset = Readonly<{
absoluteUrl: string;
expectedByteLength: number;
expectedContentType: string;
digestHex: string;
requestHeaders: readonly PublicCacheHeader[];
}>;
export type NormalizedReleaseManifest = Readonly<{
releaseRegistryId: string;
manifestDigestHex: string;
assets: readonly NormalizedAsset[];
}>;
export type ReleaseMarker = Readonly<{
schemaVersion: 1;
verified: true;
releaseRegistryId: string;
manifestDigestHex: string;
entryCount: number;
totalBytes: number;
stagedAtEpochMs: number;
assets: readonly NormalizedAsset[];
}>;
export type ActiveReleasePointer = Readonly<{
schemaVersion: 1;
releaseRegistryId: string;
manifestDigestHex: string;
candidateCacheName: string;
rollbackCandidateCacheNames: readonly string[];
activatedAtEpochMs: number;
}>;
export type BrowserFailureResult = Readonly<{
ok: false;
error: BrowserDataFailure;
}>;
export class CacheValidationFailure extends Error {
readonly code: BrowserDataFailureCode;
constructor(code: BrowserDataFailureCode) {
super("Public cache validation failed.");
this.name = "CacheValidationFailure";
this.code = code;
}
}
export async function normalizeAndVerifyManifest(
manifest: PublicCacheReleaseManifest,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
): Promise<NormalizedReleaseManifest> {
const snapshot = Object.freeze({
releaseRegistryId: manifest.releaseRegistryId,
manifestDigestHex: manifest.manifestDigestHex,
assets: normalizeAssets(manifest.assets, policy),
});
if (
!policy.isReleaseRegistryIdAllowed(snapshot.releaseRegistryId) ||
!SHA256_HEX.test(snapshot.manifestDigestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const actualDigest = await sha256Hex(
crypto,
new TextEncoder().encode(
canonicalManifest(snapshot.releaseRegistryId, snapshot.assets),
),
);
if (actualDigest !== snapshot.manifestDigestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return snapshot;
}
export function normalizeAssets(
assets: readonly PublicCacheAsset[],
policy: PublicCacheRuntimePolicy,
): readonly NormalizedAsset[] {
if (
!Array.isArray(assets) ||
assets.length < 1 ||
assets.length > policy.maxEntriesPerRelease
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const normalized = assets.map((asset) =>
normalizeAsset(asset, policy),
);
const keys = normalized.map(assetKey);
if (new Set(keys).size !== keys.length) {
throw new CacheValidationFailure("CONFLICT");
}
const declaredTotal = normalized.reduce(
(total, asset) => total + asset.expectedByteLength,
0,
);
if (
!Number.isSafeInteger(declaredTotal) ||
declaredTotal > policy.maxReleaseBytes
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
return Object.freeze(normalized);
}
export function normalizeAsset(
asset: PublicCacheAsset,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
if (
!asset ||
typeof asset !== "object" ||
!Number.isSafeInteger(asset.expectedByteLength) ||
asset.expectedByteLength < 0 ||
asset.expectedByteLength > policy.maxEntryBytes ||
asset.integrity?.algorithm !== "SHA-256" ||
!SHA256_HEX.test(asset.integrity.digestHex)
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
return Object.freeze({
absoluteUrl: normalizePublicUrl(asset.absoluteUrl, policy),
expectedByteLength: asset.expectedByteLength,
expectedContentType: normalizeContentType(
asset.expectedContentType,
policy,
),
digestHex: asset.integrity.digestHex,
requestHeaders: normalizeRequestHeaders(
asset.requestHeaders,
policy,
),
});
}
export function normalizeLookupRequest(
absoluteUrl: string,
requestHeaders: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): NormalizedAsset {
return {
absoluteUrl: normalizePublicUrl(absoluteUrl, policy),
expectedByteLength: 0,
expectedContentType: "",
digestHex: ZERO_SHA256,
requestHeaders: normalizeRequestHeaders(requestHeaders, policy),
};
}
export function normalizeContentType(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (
typeof input !== "string" ||
input.length < 1 ||
input.length > 256 ||
/[\r\n\0]/u.test(input) ||
!policy.isContentTypeAllowed(input)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return input
.split(";")
.map((part) => part.trim())
.filter((part) => part.length > 0)
.map((part, index) =>
index === 0 ? part.toLowerCase() : part,
)
.join("; ");
}
export function normalizePublicUrl(
input: string,
policy: PublicCacheRuntimePolicy,
): string {
if (typeof input !== "string" || input.length > 2_048) {
throw new CacheValidationFailure("INVALID_INPUT");
}
let url: URL;
try {
url = new URL(input);
} catch {
throw new CacheValidationFailure("INVALID_INPUT");
}
if (
url.origin !== policy.origin ||
!isAllowedPublicCacheOrigin(url) ||
url.username.length > 0 ||
url.password.length > 0 ||
url.hash.length > 0 ||
url.href === markerRequestUrl(policy) ||
url.href === activePointerRequestUrl(policy)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const forbidden = new Set(policy.forbiddenQueryParameterNames);
const allowed = new Set(policy.allowedQueryParameterNames);
const seenNames = new Set<string>();
for (const [rawName, value] of url.searchParams.entries()) {
const name = rawName.toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
seenNames.has(name) ||
!policy.isQueryParameterValueAllowed(name, value)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
seenNames.add(name);
}
return url.href;
}
export function normalizeRequestHeaders(
input: readonly PublicCacheHeader[] | undefined,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedRequestHeaderNames);
const forbidden = new Set([
"authorization",
"cookie",
"proxy-authorization",
"range",
]);
const headers = new Headers();
for (const pair of input ?? []) {
if (
!Array.isArray(pair) ||
pair.length !== 2 ||
typeof pair[0] !== "string" ||
typeof pair[1] !== "string"
) {
throw new CacheValidationFailure("INVALID_INPUT");
}
const name = pair[0].toLowerCase();
if (
forbidden.has(name) ||
!allowed.has(name) ||
pair[1].length > 1_024 ||
/[\r\n\0]/u.test(pair[1])
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
headers.append(name, pair[1].trim());
}
return Object.freeze(
[...headers.entries()]
.sort(([left], [right]) => left.localeCompare(right))
.map(
([name, value]) =>
Object.freeze([name, value]) as PublicCacheHeader,
),
);
}
export async function readBoundedJson(
response: Response,
maximumBytes: number,
): Promise<unknown> {
const contentLength = response.headers.get("content-length");
if (
!Number.isSafeInteger(maximumBytes) ||
maximumBytes <= 0 ||
(contentLength !== null &&
(!/^\d+$/u.test(contentLength) ||
Number(contentLength) > maximumBytes))
) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
if (!response.body) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const reader = response.body.getReader();
// Q-6.2-6. Chunks are kept as read; the budget is enforced on their total,
// never by preallocating it.
const chunks: Uint8Array[] = [];
let byteLength = 0;
let completelyRead = false;
try {
while (true) {
const chunk = await reader.read();
if (chunk.done) {
completelyRead = true;
break;
}
if (chunk.value.byteLength > maximumBytes - byteLength) {
throw new CacheValidationFailure("CORRUPT_DATA");
}
chunks.push(chunk.value);
byteLength += chunk.value.byteLength;
}
} catch (error) {
if (!completelyRead) {
cancelReaderSafely(
reader,
"Cache control JSON exceeded its read budget.",
);
}
throw error;
} finally {
reader.releaseLock();
}
const bytes = new Uint8Array(byteLength);
let offset = 0;
for (const chunk of chunks) {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
let text: string;
try {
text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
try {
return JSON.parse(text);
} catch {
throw new CacheValidationFailure("CORRUPT_DATA");
}
}
export function cancelReaderSafely(
reader: ReadableStreamDefaultReader<Uint8Array>,
reason: string,
): void {
try {
void reader.cancel(reason).catch(() => undefined);
} catch {
// Cancellation is best effort once the bounded consumer has stopped.
}
}
export function isReleaseMarker(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ReleaseMarker {
if (
!value ||
typeof value !== "object" ||
!("schemaVersion" in value) ||
value.schemaVersion !== 1 ||
!("verified" in value) ||
value.verified !== true ||
!("releaseRegistryId" in value) ||
typeof value.releaseRegistryId !== "string" ||
!policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) ||
!("manifestDigestHex" in value) ||
typeof value.manifestDigestHex !== "string" ||
!SHA256_HEX.test(value.manifestDigestHex) ||
!("entryCount" in value) ||
typeof value.entryCount !== "number" ||
!Number.isSafeInteger(value.entryCount) ||
!("totalBytes" in value) ||
typeof value.totalBytes !== "number" ||
!Number.isSafeInteger(value.totalBytes) ||
!("stagedAtEpochMs" in value) ||
typeof value.stagedAtEpochMs !== "number" ||
!Number.isSafeInteger(value.stagedAtEpochMs) ||
!("assets" in value) ||
!Array.isArray(value.assets) ||
value.assets.length > policy.maxEntriesPerRelease
) {
return false;
}
try {
const normalized = normalizeAssets(
value.assets.map((asset) => markerAssetToPublicAsset(asset)),
policy,
);
return stableJson(normalized) === stableJson(value.assets);
} catch {
return false;
}
}
export function markerAssetToPublicAsset(value: unknown): PublicCacheAsset {
if (!value || typeof value !== "object") {
throw new CacheValidationFailure("CORRUPT_DATA");
}
const asset = value as Partial<NormalizedAsset>;
return {
absoluteUrl: asset.absoluteUrl ?? "",
expectedByteLength: asset.expectedByteLength ?? -1,
expectedContentType: asset.expectedContentType ?? "",
integrity: {
algorithm: "SHA-256",
digestHex: asset.digestHex ?? "",
},
requestHeaders: asset.requestHeaders,
};
}
export function isActivePointer(
value: unknown,
policy: PublicCacheRuntimePolicy,
): value is ActiveReleasePointer {
return Boolean(
value &&
typeof value === "object" &&
"schemaVersion" in value &&
value.schemaVersion === 1 &&
"releaseRegistryId" in value &&
typeof value.releaseRegistryId === "string" &&
policy.isReleaseRegistryIdAllowed(value.releaseRegistryId) &&
"manifestDigestHex" in value &&
typeof value.manifestDigestHex === "string" &&
SHA256_HEX.test(value.manifestDigestHex) &&
"candidateCacheName" in value &&
typeof value.candidateCacheName === "string" &&
value.candidateCacheName ===
releaseCacheName(
policy,
value.releaseRegistryId,
value.manifestDigestHex,
) &&
"rollbackCandidateCacheNames" in value &&
Array.isArray(value.rollbackCandidateCacheNames) &&
value.rollbackCandidateCacheNames.length <=
policy.retainedPreviousReleaseCount &&
new Set(value.rollbackCandidateCacheNames).size ===
value.rollbackCandidateCacheNames.length &&
value.rollbackCandidateCacheNames.every(
(name) =>
typeof name === "string" &&
name !== value.candidateCacheName &&
isOwnedReleaseCacheName(name, policy),
) &&
"activatedAtEpochMs" in value &&
typeof value.activatedAtEpochMs === "number" &&
Number.isSafeInteger(value.activatedAtEpochMs),
);
}
export function isOwnedReleaseCacheName(
name: string,
policy: PublicCacheRuntimePolicy,
): boolean {
if (!name.startsWith(`${policy.ownedCachePrefix}release:`)) {
return false;
}
const remainder = name.slice(
`${policy.ownedCachePrefix}release:`.length,
);
const separator = remainder.lastIndexOf(":");
if (separator < 1) return false;
const releaseRegistryId = remainder.slice(0, separator);
const digestHex = remainder.slice(separator + 1);
return (
policy.isReleaseRegistryIdAllowed(releaseRegistryId) &&
SHA256_HEX.test(digestHex)
);
}
export function canonicalManifest(
releaseRegistryId: string,
assets: readonly NormalizedAsset[],
): string {
return [
"ca-public-cache-manifest-v1",
`release:${releaseRegistryId}`,
...[...assets]
.sort((left, right) => assetKey(left).localeCompare(assetKey(right)))
.map(
(asset) =>
`${assetKey(asset)}:${asset.expectedByteLength}:${JSON.stringify(asset.expectedContentType)}:${asset.digestHex}`,
),
"",
].join("\n");
}
export function assetKey(
asset: Pick<NormalizedAsset, "absoluteUrl" | "requestHeaders">,
): string {
return JSON.stringify([asset.absoluteUrl, asset.requestHeaders]);
}
export function markerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(markerRequestUrl(policy), { method: "GET" });
}
export function activePointerRequest(policy: PublicCacheRuntimePolicy): Request {
return new Request(activePointerRequestUrl(policy), { method: "GET" });
}
export function markerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/candidate`;
}
export function activePointerRequestUrl(policy: PublicCacheRuntimePolicy): string {
return `${policy.origin}/.well-known/ca-public-cache-v1/active`;
}
export function controlCacheName(policy: PublicCacheRuntimePolicy): string {
return `${policy.ownedCachePrefix}control`;
}
export function releaseCacheName(
policy: PublicCacheRuntimePolicy,
releaseRegistryId: string,
manifestDigestHex: string,
): string {
return `${policy.ownedCachePrefix}release:${releaseRegistryId}:${manifestDigestHex}`;
}
export function jsonResponse(value: unknown): Response {
return new Response(JSON.stringify(value), {
status: 200,
headers: {
"cache-control": "no-store",
"content-type": "application/json; charset=utf-8",
},
});
}
export function validationFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
return error instanceof CacheValidationFailure
? failureForCode(error.code, operation)
: asFailure(browserDataFailure("INVALID_INPUT", operation));
}
export function exceptionFailure(
error: unknown,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (error instanceof CacheValidationFailure) {
return failureForCode(error.code, operation);
}
const mapped = mapBrowserDataException(error, operation);
if (mapped.ok) {
return asFailure(
browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return mapped;
}
export function failureForCode(
code: BrowserDataFailureCode,
operation: BrowserDataOperation,
): BrowserFailureResult {
if (code === "ABORTED") {
return asFailure(browserDataFailure(code, operation));
}
if (code === "INTEGRITY_FAILED" || code === "CORRUPT_DATA") {
return asFailure(
browserDataFailure(code, operation, { recovery: "REHYDRATE" }),
);
}
if (code === "QUOTA_EXCEEDED") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "ONLINE_ONLY",
}),
);
}
if (code === "BLOCKED" || code === "UNAVAILABLE") {
return asFailure(
browserDataFailure(code, operation, {
retryable: true,
recovery: "RETRY",
}),
);
}
return asFailure(browserDataFailure(code, operation));
}
export function asFailure(
result: BrowserDataResult<never>,
): BrowserFailureResult {
if (result.ok) {
throw new TypeError("Expected a browser data failure.");
}
return result;
}
export async function sha256Hex(
crypto: PublicCacheCryptoFacade,
bytes: Uint8Array,
): Promise<string> {
const digest = await crypto.digestSha256(bytes);
let hex = "";
for (const byte of new Uint8Array(digest)) {
hex += byte.toString(16).padStart(2, "0");
}
return hex;
}
export function stableJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(stableJson).join(",")}]`;
}
if (typeof value === "object") {
const record = value as Record<string, unknown>;
return `{${Object.keys(record)
.sort()
.map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
.join(",")}}`;
}
throw new CacheValidationFailure("CORRUPT_DATA");
}
export const SHA256_HEX = /^[a-f0-9]{64}$/u;
export const ZERO_SHA256 = "0".repeat(64);
export const MAX_CONTROL_JSON_BYTES = 2 * 1024 * 1024;
@@ -137,6 +137,9 @@ export function assertPublicCachePolicy(
// rejected at composition instead of producing an unusable candidate.
(policy.allowedVaryHeaderNames.length > 0 &&
!policy.allowedResponseHeaderNames.includes("vary")) ||
// Activation re-validates the stored Content-Type, so stripping it would
// make every activation fail as INTEGRITY_FAILED.
!policy.allowedResponseHeaderNames.includes("content-type") ||
policy.forbiddenQueryParameterNames.some((name) => name.length === 0) ||
policy.allowedQueryParameterNames.some((name) =>
policy.forbiddenQueryParameterNames.includes(name),
@@ -0,0 +1,239 @@
import type { PublicCacheHeader } from "../../application/ports/browser-file-storage/cache-storage-ports.ts";
import type { BrowserDataResult } from "../../application/ports/browser-file-storage/shared.ts";
import { browserDataSuccess } from "../browser-file-storage/result.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
import {
CacheValidationFailure,
cancelReaderSafely,
exceptionFailure,
normalizeContentType,
sha256Hex,
type NormalizedAsset,
type PublicCacheCryptoFacade,
} from "./public-cache-codec.ts";
import type { PublicCacheRuntimePolicy } from "./public-cache-policy.ts";
/**
* Q-6.2-11. Admission of a network or cached response for one manifest asset:
* status, cache directives, content type, Vary, bounded body read and digest.
* Moved verbatim out of the adapter.
*/
export type CacheReadResult = Readonly<{
bytes: Uint8Array;
headers: readonly PublicCacheHeader[];
}>;
export async function readAndValidateResponse(
response: Response,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
crypto: PublicCacheCryptoFacade,
signal: AbortSignal | undefined,
): Promise<BrowserDataResult<CacheReadResult>> {
try {
if (
response.status !== 200 ||
!response.ok ||
response.redirected ||
response.type === "opaque" ||
response.type === "opaqueredirect" ||
response.type === "error" ||
(response.url.length > 0 &&
new URL(response.url).href !== asset.absoluteUrl)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const cacheControl = response.headers.get("cache-control") ?? "";
const directives = new Set(
cacheControl
.split(",")
.map((part) => part.trim().split("=", 1)[0]?.toLowerCase())
.filter((part): part is string => Boolean(part)),
);
if (
directives.has("private") ||
directives.has("no-store") ||
directives.has("no-cache") ||
(response.headers.get("pragma") ?? "")
.toLowerCase()
.includes("no-cache") ||
response.headers.has("set-cookie") ||
response.headers.has("set-cookie2") ||
response.headers.has("www-authenticate")
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
const contentType = response.headers.get("content-type");
if (!contentType || !policy.isContentTypeAllowed(contentType)) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
if (
normalizeContentType(contentType, policy) !==
asset.expectedContentType
) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
validateVary(response.headers.get("vary"), asset, policy);
const declaredLength = response.headers.get("content-length");
if (
declaredLength !== null &&
(!/^\d+$/u.test(declaredLength) ||
Number(declaredLength) > policy.maxEntryBytes)
) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
const bytes = await readBodyBounded(
response,
asset.expectedByteLength,
policy.maxEntryBytes,
signal,
);
const digestHex = await sha256Hex(crypto, bytes);
if (digestHex !== asset.digestHex) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const headers = sanitizedResponseHeaders(response.headers, policy);
return browserDataSuccess({ bytes, headers });
} catch (error) {
return exceptionFailure(error, "CACHE_STAGE");
}
}
export async function readBodyBounded(
response: Response,
expectedByteLength: number,
maxEntryBytes: number,
signal: AbortSignal | undefined,
): Promise<Uint8Array> {
if (expectedByteLength > maxEntryBytes) {
throw new CacheValidationFailure("LIMIT_EXCEEDED");
}
if (!response.body) {
if (expectedByteLength === 0) return new Uint8Array();
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
const output = new Uint8Array(expectedByteLength);
const reader = response.body.getReader();
let offset = 0;
// The kernel owner ends a pending read on abort instead of a listener pair.
const owner = createAbortableOperation({ signal });
const abortRead = (): CacheValidationFailure => {
cancelReaderSafely(reader, "Public cache body read was aborted.");
return new CacheValidationFailure("ABORTED");
};
try {
while (true) {
if (owner.signal.aborted) throw abortRead();
const raced = await owner.race(reader.read());
if (raced.kind === "REJECTED") throw raced.reason;
if (raced.kind === "TERMINAL" || owner.signal.aborted) {
throw abortRead();
}
const part = raced.value;
if (part.done) break;
if (
!(part.value instanceof Uint8Array) ||
offset + part.value.byteLength > expectedByteLength ||
offset + part.value.byteLength > maxEntryBytes
) {
cancelReaderSafely(
reader,
"Public cache body exceeded its read budget.",
);
throw new CacheValidationFailure(
offset + part.value.byteLength > maxEntryBytes
? "LIMIT_EXCEEDED"
: "INTEGRITY_FAILED",
);
}
output.set(part.value, offset);
offset += part.value.byteLength;
}
} finally {
owner.close();
reader.releaseLock();
}
if (offset !== expectedByteLength) {
throw new CacheValidationFailure("INTEGRITY_FAILED");
}
return output;
}
export function validateVary(
vary: string | null,
asset: NormalizedAsset,
policy: PublicCacheRuntimePolicy,
): void {
const expected = new Set(
asset.requestHeaders.map(([name]) => name.toLowerCase()),
);
const actual = new Set<string>();
if (!vary) {
if (expected.size > 0) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
return;
}
const allowed = new Set(policy.allowedVaryHeaderNames);
for (const item of vary.split(",")) {
const name = item.trim().toLowerCase();
// Browser-managed: Accept-Encoding is a forbidden request header, so no
// script-built Request carries it. Stored and lookup requests both lack it
// and Cache.match still matches exactly. nginx `gzip_vary` and most CDNs
// send it on every compressible asset.
if (name === "accept-encoding") continue;
if (
name === "*" ||
name === "authorization" ||
name === "cookie" ||
!allowed.has(name)
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
actual.add(name);
}
if (
actual.size !== expected.size ||
[...actual].some((name) => !expected.has(name))
) {
throw new CacheValidationFailure("POLICY_REJECTED");
}
}
export function sanitizedResponseHeaders(
headers: Headers,
policy: PublicCacheRuntimePolicy,
): readonly PublicCacheHeader[] {
const allowed = new Set(policy.allowedResponseHeaderNames);
const sanitized: PublicCacheHeader[] = [];
for (const [name, value] of headers.entries()) {
if (!allowed.has(name)) {
if (policy.unknownResponseHeaderAction === "REJECT") {
throw new CacheValidationFailure("POLICY_REJECTED");
}
continue;
}
sanitized.push(Object.freeze([name, value]));
}
return Object.freeze(sanitized);
}
export function createNativeRequest(
asset: NormalizedAsset,
signal?: AbortSignal,
): Request {
return new Request(asset.absoluteUrl, {
method: "GET",
headers: new Headers(
asset.requestHeaders.map(([name, value]) => [name, value]),
),
credentials: "omit",
cache: "no-store",
redirect: "error",
referrerPolicy: "no-referrer",
mode: "same-origin",
signal,
});
}
File diff suppressed because it is too large Load Diff
@@ -36,6 +36,20 @@ const CHANNEL_NAME = "ca-client-cache-invalidation-v1";
const STORAGE_PULSE_KEY =
STORAGE_REGISTRY.CACHE_INVALIDATION_PULSE.physicalKey;
/**
* Q-6.2-9. A release ID may hold any character (`1.2.3+sha.abc`, `feature/x`,
* `app@1.2.3`) and any length, but a cache epoch is an opaque identifier. The
* epoch is a stable 64-bit FNV-1a digest of the ID, so every tab of one release
* agrees on it and it always passes the wire rule.
*/
export function crossContextCacheEpochForRelease(releaseId: string): string {
let hash = 0xcbf29ce484222325n;
for (const byte of new TextEncoder().encode(releaseId)) {
hash = ((hash ^ BigInt(byte)) * 0x100000001b3n) & 0xffffffffffffffffn;
}
return `release.${hash.toString(16).padStart(16, "0")}`;
}
/**
* Captures native capabilities without allowing a SecurityError getter or a
* missing random source to fail application boot.
@@ -49,17 +63,38 @@ export function createBrowserCrossContextInvalidationFromHost(
const host =
dependencies.host ??
(globalThis as unknown as Record<string, unknown>);
// Q-6.2-9. Ending inactive is reported, so cross-tab invalidation is never
// switched off without a diagnostic.
const inactive = (
reason: "INVALID_CACHE_EPOCH" | "SECURE_RANDOM_UNAVAILABLE",
): undefined => {
try {
dependencies.observe?.(
Object.freeze({
operation: "OPEN" as const,
outcome: "FAILED" as const,
transport: "NONE" as const,
reason,
}),
);
} catch {
// Diagnostics cannot change the capability decision.
}
return undefined;
};
if (
!isCacheInvalidationOpaqueIdentifier(dependencies.cacheEpoch)
) {
return undefined;
return inactive("INVALID_CACHE_EPOCH");
}
const createOpaqueId = randomIdFactory(host);
if (!createOpaqueId) return undefined;
if (!createOpaqueId) return inactive("SECURE_RANDOM_UNAVAILABLE");
const sourceId = createOpaqueId("tab");
const sourceEpoch = createOpaqueId("page");
if (!sourceId || !sourceEpoch) return undefined;
if (!sourceId || !sourceEpoch) {
return inactive("SECURE_RANDOM_UNAVAILABLE");
}
const capturedLocalStorage = captureLocalStorage(host);
@@ -13,6 +13,12 @@ import {
export type CrossContextInvalidationStatus =
| "ACTIVE_BROADCAST"
| "ACTIVE_STORAGE_FALLBACK"
/**
* The browser has BroadcastChannel but this tab could not open it. Other
* tabs publish on BroadcastChannel only, so this tab misses their events
* while its own storage pulses still reach them.
*/
| "DEGRADED_STORAGE_FALLBACK"
| "DEGRADED_LOCAL_ONLY"
| "CLOSED";
@@ -37,9 +43,11 @@ export type CrossContextInvalidationObservationReason =
| "DELIVERED"
| "DUPLICATE"
| "HANDLER_FAILED"
| "INVALID_CACHE_EPOCH"
| "OPENED"
| "PUBLISHED"
| "SELF_ECHO"
| "SECURE_RANDOM_UNAVAILABLE"
| "SEQUENCE_EXHAUSTED"
| "STALE"
| "STORAGE_CLEANUP_FAILED"
@@ -145,10 +153,9 @@ export type BrowserCrossContextInvalidation = Readonly<{
}>;
type SeenEvent = Readonly<{ expiresAt: number }>;
type SourceHighWatermark = Readonly<{
sequence: number;
expiresAt: number;
}>;
// No TTL: a watermark must outlive its last event, or the next event after a
// quiet period reads as a GAP. `sourceCapacity` LRU bounds the memory.
type SourceHighWatermark = Readonly<{ sequence: number }>;
const DEFAULT_EVENT_TTL_MS = 60_000;
const DEFAULT_DEDUPE_CAPACITY = 1_024;
@@ -177,6 +184,10 @@ export function createBrowserCrossContextInvalidation(
let closed = false;
let sequence = 0;
let broadcast: BroadcastChannelFacade | undefined;
let broadcastOpenFailed = false;
// A failed postMessage moves publishing to storage but keeps the channel
// open, because other tabs keep publishing on it.
let broadcastPublishFailed = false;
let storageListenerInstalled = false;
let status: CrossContextInvalidationStatus = "DEGRADED_LOCAL_ONLY";
@@ -250,6 +261,7 @@ export function createBrowserCrossContextInvalidation(
// Opening still falls back when provider cleanup is rejected.
}
}
broadcastOpenFailed = true;
observe({
operation: "OPEN",
outcome: "DEGRADED",
@@ -262,14 +274,16 @@ export function createBrowserCrossContextInvalidation(
function refreshStatus(): void {
if (closed) {
status = "CLOSED";
} else if (broadcast) {
} else if (broadcast && !broadcastPublishFailed) {
status = "ACTIVE_BROADCAST";
} else if (
dependencies.storage &&
dependencies.storageEvents &&
storageListenerInstalled
) {
status = "ACTIVE_STORAGE_FALLBACK";
status = broadcastOpenFailed
? "DEGRADED_STORAGE_FALLBACK"
: "ACTIVE_STORAGE_FALLBACK";
} else {
status = "DEGRADED_LOCAL_ONLY";
}
@@ -323,7 +337,7 @@ export function createBrowserCrossContextInvalidation(
sequence = candidate.sequence;
pruneTracking(emittedAt);
if (broadcast) {
if (broadcast && !broadcastPublishFailed) {
try {
broadcast.postMessage(candidate);
observe({
@@ -343,7 +357,7 @@ export function createBrowserCrossContextInvalidation(
transport: "BROADCAST",
reason: "BROADCAST_PUBLISH_FAILED",
});
closeBroadcast();
broadcastPublishFailed = true;
refreshStatus();
}
}
@@ -414,7 +428,7 @@ export function createBrowserCrossContextInvalidation(
reason: "STORAGE_CLEANUP_FAILED",
});
}
status = "ACTIVE_STORAGE_FALLBACK";
refreshStatus();
observe({
operation: "PUBLISH",
outcome: "ACCEPTED",
@@ -497,10 +511,7 @@ export function createBrowserCrossContextInvalidation(
event.sequence > previous.sequence + 1)
? "GAP"
: "NEXT";
touchSource(sourceKey, {
sequence: event.sequence,
expiresAt: event.expiresAt,
});
touchSource(sourceKey, { sequence: event.sequence });
const delivery = Object.freeze({ event, ordering, transport });
for (const listener of [...listeners]) {
@@ -546,11 +557,6 @@ export function createBrowserCrossContextInvalidation(
for (const [eventId, entry] of seenEvents) {
if (entry.expiresAt <= currentTime) seenEvents.delete(eventId);
}
for (const [sourceKey, entry] of sourceHighWatermarks) {
if (entry.expiresAt <= currentTime) {
sourceHighWatermarks.delete(sourceKey);
}
}
}
function subscribe(
@@ -19,5 +19,6 @@ export {
} from "./browser-cross-context-invalidation.ts";
export {
createBrowserCrossContextInvalidationFromHost,
crossContextCacheEpochForRelease,
type BrowserCrossContextHostDependencies,
} from "./browser-cross-context-host.ts";
+48 -29
View File
@@ -7,6 +7,7 @@ import {
} from "../../contracts/errors.ts";
import { mapOperationPayload } from "./resource-mapper.ts";
import { retryDelay, shouldRetry } from "./retry-policy.ts";
import { parseRetryAfterDelay } from "../platform/retry-after.ts";
import {
validateEnvelope,
validateOperationPayload,
@@ -40,7 +41,7 @@ import type { ClockPort } from "../../application/ports/clock-port.ts";
import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.ts";
import type { TelemetryPort } from "../../application/ports/telemetry-port.ts";
import type { ApiOperation } from "../../contracts/api-operations.ts";
import type { ApiFailure } from "../../contracts/errors.ts";
import type { ApiFailure, FailureKind } from "../../contracts/errors.ts";
import type { OperationRequestInput } from "./request-builder.ts";
import { readBoundedJson } from "./bounded-json.ts";
import { admitCredentialHeaders } from "./http-contract-bridge.ts";
@@ -48,7 +49,7 @@ import type { MappingResult } from "../../contracts/boundary-mapper.ts";
import {
createRestProviderProfile,
resolveRestSecurityProfiles,
REST_AUTH_PROFILES,
INSTALLED_REST_AUTH_PROFILES,
REST_CSRF_PROFILES,
type RestAuthProfile,
type RestCsrfProfile,
@@ -336,12 +337,11 @@ export function createHttpClient(
);
}
// Q-6.3-11. Recovery is its own single replay, bounded by
// `recoveryUsed` and the deadline, not by the retry budget: a disabled
// or spent budget must not turn a recoverable 401 into a logout.
if (outcome.error.httpStatus === 401 && !recoveryUsed) {
recoveryUsed = true;
if (physicalAttemptCount >= maxRetryAttempts + 1) {
authSession.onUnauthenticated();
return finalize(outcome, "failed");
}
let recovered: SessionRecoveryOutcome;
// LEG-01. The recovery collaborator receives the request lifetime, and
// the transport races the same signal so a non-cooperative owner cannot
@@ -562,7 +562,7 @@ export function createHttpClient(
security = resolveRestSecurityProfiles(
operation,
provider,
dependencies.authProfiles ?? REST_AUTH_PROFILES,
dependencies.authProfiles ?? INSTALLED_REST_AUTH_PROFILES,
dependencies.csrfProfiles ?? REST_CSRF_PROFILES,
);
}
@@ -842,6 +842,17 @@ export function createHttpClient(
class LogicalDeadlineError extends Error {}
/**
* Q-6.3-3b. A gateway 5xx/408/425 with an HTML, empty or broken body is a
* server outage, not a contract breach: it keeps its status and the normal
* SERVER_FAILURE retry rule instead of a non-retryable body error.
*/
function gatewayFailureOr(status: number, kind: FailureKind): FailureKind {
return status >= 500 || status === 408 || status === 425
? "SERVER_FAILURE"
: kind;
}
async function parseResponse(
response: Response,
operation: ApiOperation,
@@ -853,6 +864,12 @@ async function parseResponse(
) => MappingResult<unknown>,
now: number,
): Promise<HttpResult> {
// R3-1. Retry-After is read only where the retry policy honors it; 502/504
// keep the local backoff.
const retryAfterMs = [408, 425, 429, 503].includes(response.status)
? (parseRetryAfterDelay(response.headers.get("retry-after"), now) ??
undefined)
: undefined;
const contentType = mediaType(response.headers.get("content-type"));
const acceptedMedia = operation.responseMediaTypes ?? ["application/json"];
if (!contentType || !acceptedMedia.includes(contentType)) {
@@ -862,10 +879,16 @@ async function parseResponse(
void response.body?.cancel().catch(() => {});
return {
ok: false,
error: failure("CONTENT_TYPE_MISMATCH", operation.operationId, attempt, {
code: "CONTENT_TYPE_MISMATCH",
httpStatus: response.status,
}),
error: failure(
gatewayFailureOr(response.status, "CONTENT_TYPE_MISMATCH"),
operation.operationId,
attempt,
{
code: "CONTENT_TYPE_MISMATCH",
httpStatus: response.status,
retryAfterMs,
},
),
};
}
@@ -876,10 +899,12 @@ async function parseResponse(
if (!decoded.ok) {
return {
ok: false,
error: failure(decoded.code, operation.operationId, attempt, {
code: decoded.code,
httpStatus: response.status,
}),
error: failure(
gatewayFailureOr(response.status, decoded.code),
operation.operationId,
attempt,
{ code: decoded.code, httpStatus: response.status, retryAfterMs },
),
};
}
const envelope = decoded.value;
@@ -889,12 +914,15 @@ async function parseResponse(
return {
ok: false,
error: failure(
response.ok ? "ENVELOPE_MISMATCH" : statusKind(response.status),
response.ok
? "ENVELOPE_MISMATCH"
: gatewayFailureOr(response.status, statusKind(response.status)),
operation.operationId,
attempt,
{
code: response.ok ? "ENVELOPE_MISMATCH" : "HTTP_FAILURE",
httpStatus: response.status,
retryAfterMs,
},
),
};
@@ -965,8 +993,9 @@ async function parseResponse(
};
}
const kind = statusKind(response.status);
const retryAfter = response.headers.get("retry-after");
// R3-1. V2 treats a 408/425 error envelope as the same server failure as a
// gateway body; the shared status map in contracts is not changed.
const kind = gatewayFailureOr(response.status, statusKind(response.status));
const backendError =
envelopeRecord.error && typeof envelopeRecord.error === "object"
? (envelopeRecord.error as Record<string, unknown>)
@@ -978,10 +1007,7 @@ async function parseResponse(
httpStatus: response.status,
requestId: safeMeta(envelopeRecord.meta).requestId,
traceId: safeMeta(envelopeRecord.meta).traceId,
retryAfterMs:
response.status === 429 && retryAfter
? parseRetryAfterHeader(retryAfter, now)
: undefined,
retryAfterMs,
validationIssues:
response.status === 422
? safeValidationIssues(backendError.details)
@@ -1065,13 +1091,6 @@ function safeMeta(meta: unknown): Record<string, string> {
};
}
function parseRetryAfterHeader(value: string, now: number): number | undefined {
const seconds = Number(value);
if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1_000;
const timestamp = Date.parse(value);
return Number.isFinite(timestamp) ? Math.max(0, timestamp - now) : undefined;
}
function safeIdentifier(
value: string,
property: "requestId" | "traceId",
+48 -4
View File
@@ -295,9 +295,26 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
): Result<Value, ApiFailure> {
// A throwing feature mapper is a mapping defect, not a transport failure: it
// must not reject and lose the effect the server already confirmed.
const mapperThrew = (
effect: FailureEffectCertainty,
httpStatus: number,
): Result<Value, ApiFailure> =>
failure(
"MAPPING_CONTRACT_VIOLATION",
operationId,
"MAPPING_CONTRACT_VIOLATION",
{ httpStatus, effect },
);
switch (outcome.kind) {
case "SUCCESS": {
const mapped = mapSuccess(outcome.value);
let mapped: MappingResult<Value>;
try {
mapped = mapSuccess(outcome.value);
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
return mapped.ok
? Object.freeze({ ok: true as const, value: mapped.value })
: failure(
@@ -308,7 +325,12 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
);
}
case "PROBLEM": {
const mapped = mapProblem?.(outcome.problem, outcome.metadata);
let mapped: FeatureHttpProblemMapping | undefined;
try {
mapped = mapProblem?.(outcome.problem, outcome.metadata);
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
return failure(
mapped?.kind ?? kindForStatus(outcome.metadata.status),
operationId,
@@ -353,16 +375,33 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
outcome.failure.kind,
{ effect: outcome.effect },
);
case "CONTRACT_VIOLATION":
case "CONTRACT_VIOLATION": {
const httpStatus = outcome.metadata?.status;
// R-3.3. A gateway 5xx/408/425 with an HTML or empty body is a server
// outage: keep its status and retryability instead of "contact support".
if (httpStatus !== undefined && isServerFailureStatus(httpStatus)) {
return failure("SERVER_FAILURE", operationId, outcome.violation.kind, {
httpStatus,
effect: outcome.effect,
});
}
return failure(
failureKindForViolation(outcome.violation.kind),
operationId,
outcome.violation.kind,
{ effect: outcome.effect },
{
...(httpStatus === undefined ? {} : { httpStatus }),
effect: outcome.effect,
},
);
}
}
}
function isServerFailureStatus(status: number): boolean {
return status >= 500 || status === 408 || status === 425;
}
function failureKindForViolation(
violation: Extract<
HttpExecutionOutcome<unknown, unknown>,
@@ -385,6 +424,11 @@ function failureKindForViolation(
case "PROBLEM_SCHEMA_INVALID":
case "VALIDATOR_RUNTIME_FAILURE":
return "SCHEMA_MISMATCH";
// Rejected before dispatch: the request, not the server answer, was wrong.
case "FINAL_REQUEST_INVARIANT_FAILED":
case "MISSING_IDEMPOTENCY_KEY":
case "UNEXPECTED_IDEMPOTENCY_KEY":
return "VALIDATION_REJECTED";
default:
return "ENVELOPE_MISMATCH";
}
+25 -4
View File
@@ -50,6 +50,13 @@ export type CredentialAdmissionOutcome =
const MAX_CREDENTIAL_HEADER_VALUE_BYTES = 8_192;
/**
* R-3.4. The one credential value rule for V2 and V3: a ByteString (every code
* unit one byte on the wire) with no C0/C1 control characters. Fetch rejects
* anything else only after the request counts as dispatched.
*/
const CREDENTIAL_HEADER_VALUE = /^[\x20-\x7E\xA0-\xFF]+$/;
/**
* §7.7. Admits a credential patch against the resolved profile before any
* header object is built. A rejection here guarantees `fetch()` is not called:
@@ -82,9 +89,8 @@ export function admitCredentialHeaders(
}
if (
typeof value !== "string" ||
value.length === 0 ||
/[\r\n]/.test(value) ||
encoder.encode(value).byteLength > MAX_CREDENTIAL_HEADER_VALUE_BYTES
!CREDENTIAL_HEADER_VALUE.test(value) ||
value.length > MAX_CREDENTIAL_HEADER_VALUE_BYTES
) {
return frozenAdmissionFailure("CREDENTIAL_HEADER_VALUE_INVALID");
}
@@ -189,7 +195,14 @@ function projectRequestChecked<Input, WireOutput, Problem>(
missing = true;
return "";
}
if (value.includes("/") || value.includes("\\")) {
// A dot segment survives encodeURIComponent and URL resolution would
// move the request to a parent path that still passes the base check.
if (
value.includes("/") ||
value.includes("\\") ||
value === "." ||
value === ".."
) {
invalid = true;
return "";
}
@@ -318,6 +331,7 @@ export type FinalInvariantFailure =
| "CREDENTIAL_HEADER_NOT_ALLOWED"
| "MISSING_REQUIRED_CREDENTIAL_HEADER"
| "FORBIDDEN_HEADER"
| "HEADER_VALUE_INVALID"
| "REQUEST_BODY_TOO_LARGE"
| "DEADLINE_EXPIRED"
| "SCOPE_FENCED";
@@ -376,6 +390,13 @@ export function checkFinalInvariants(
return "MISSING_REQUIRED_CREDENTIAL_HEADER";
}
}
// Fetch validates header values only once it is called; build them here so
// any value it would reject fails before dispatch, not as a network error.
try {
new Headers(input.headers);
} catch {
return "HEADER_VALUE_INVALID";
}
if (
input.request.bodyBytes &&
+99 -97
View File
@@ -134,6 +134,11 @@ export type HttpExecutionOutcome<Value, Problem> =
}>
| Readonly<{
kind: "UNAUTHENTICATED";
/**
* Present only when the server answered 401. Absent means no credential
* existed and nothing was sent; that is not a session verdict.
*/
metadata?: SafeResponseMetadata;
effect: "NOT_APPLICABLE" | "NOT_APPLIED" | "MAYBE_APPLIED";
}>
| Readonly<{
@@ -148,6 +153,11 @@ export type HttpExecutionOutcome<Value, Problem> =
| Readonly<{
kind: "CONTRACT_VIOLATION";
violation: HttpContractViolation;
/**
* Present when an error status arrived without a usable problem body.
* A 5xx/408/425 here is a server outage, not a contract breach (R-3.3).
*/
metadata?: SafeResponseMetadata;
effect: HttpEffectCertainty;
}>
| Readonly<{
@@ -300,9 +310,7 @@ function observationErrorKind(
function observationStatus(
outcome: HttpExecutionOutcome<unknown, unknown>,
): number | undefined {
return outcome.kind === "SUCCESS" || outcome.kind === "PROBLEM"
? outcome.metadata.status
: undefined;
return "metadata" in outcome ? outcome.metadata?.status : undefined;
}
export type ContractHttpExecutorDependencies = Readonly<{
@@ -496,6 +504,17 @@ export function createContractHttpExecutor(
kind: HttpTransportFailure["kind"],
): HttpExecutionOutcome<WireOutput, Problem> =>
transportFailure(kind, false, abandonedCertainty());
/**
* Q-6.3-7. What the attempts that were retried settled on. The logical
* accumulator above is raised at dispatch, before the attempt's own answer
* is known, so it cannot tell a rejected attempt from a lost one.
*/
let retriedCertainty: MutationEffectCertainty = "NOT_STARTED";
const rememberRetried = (settled: MutationEffectCertainty) => {
if (isCommand) {
retriedCertainty = joinMutationEffectCertainty(retriedCertainty, settled);
}
};
let terminalCancellation: CancellationOwner | null = null;
const lifetimeController = new AbortController();
const forwardCallerToLifetime = () => {
@@ -574,6 +593,31 @@ export function createContractHttpExecutor(
return outcome;
};
/**
* Q-6.3-6. The one classifier for a wait that a terminal owner ended. The
* caller cancels and the deadline times out. A scope fence during a `WAIT`
* (credentials, lease, dispatch, backoff) aborts the transport; during
* `ADMISSION` the response headers prove the request reached the server,
* so a stale generation stays the `SCOPE_FENCED` contract violation.
*/
const terminalOutcomeFor = (
phase: "WAIT" | "ADMISSION",
): HttpExecutionOutcome<WireOutput, Problem> => {
switch (terminalCancellation) {
case "CALLER":
return finish(cancelled(abandonedCertainty()), "CANCELLED");
case "SCOPE_FENCE":
return phase === "ADMISSION"
? finish(scopeFenced(abandonedCertainty()), "SCOPE_FENCED")
: finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
default:
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
}
};
try {
// §7.7. The installed registry is the only source of a profile. Composition
@@ -676,20 +720,7 @@ export function createContractHttpExecutor(
"AUTH_INTEGRATION_FAILURE",
);
}
if (patchResult === ABORTED) {
if (terminalCancellation === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
return terminalCancellation === "CALLER"
? finish(cancelled("NOT_STARTED"), "CANCELLED")
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (patchResult === ABORTED) return terminalOutcomeFor("WAIT");
// NS-01. The whole answer is decoded once, inside the auth boundary, before
// any field is used. Reading `kind` and `headers` off the raw object left
// the decode outside that boundary: a throwing getter escaped into the
@@ -810,16 +841,7 @@ export function createContractHttpExecutor(
"TRAFFIC_BUDGET_EXCEEDED",
);
}
if (terminalCancellation === "CALLER") {
return finish(cancelled(abandonedCertainty()), "CANCELLED");
}
if (terminalCancellation === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
return terminalOutcomeFor("WAIT");
}
try {
const controller = new AbortController();
@@ -911,22 +933,10 @@ export function createContractHttpExecutor(
} else {
clearTimeout(deadlineTimer);
lifetimeController.signal.removeEventListener("abort", forwardLifetime);
const owner = terminalCancellation;
if (owner === "CALLER") {
return finish(
cancelled(abandonedCertainty()),
"CANCELLED",
);
if (terminalCancellation !== null) {
return terminalOutcomeFor("WAIT");
}
if (owner === "SCOPE_FENCE") {
return finish(
abandonedTransportFailure("ABORTED_BY_SCOPE"),
"SCOPE_FENCED",
);
}
const kind = owner === "DEADLINE" ? "TIMEOUT" : "NETWORK_FAILURE";
if (
owner === null &&
canRetryTransport(contract.retrySemantics, attemptState) &&
retryIndex < retryCeiling &&
remaining() > 0
@@ -938,23 +948,14 @@ export function createContractHttpExecutor(
sleep(delay, lifetimeController.signal),
lifetimeController.signal,
);
if (slept === ABORTED) {
return terminalCancellation === "CALLER"
? finish(
cancelled(abandonedCertainty()),
"CANCELLED",
)
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (slept === ABORTED) return terminalOutcomeFor("WAIT");
rememberRetried(certaintyForAbandonedAttempt(attemptState, isCommand));
continue;
}
}
return finish(
abandonedTransportFailure(kind),
kind,
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
);
}
@@ -975,44 +976,28 @@ export function createContractHttpExecutor(
controller.signal,
() => cancelResponseBody(response),
);
// LIVE-04. Once response headers are in hand the request demonstrably
// reached the server, so a terminal owner that lands during admission
// keeps the dispatched classification: a stale generation stays the
// `SCOPE_FENCED` contract violation it has always been, and only the
// deadline and the caller reclassify the outcome.
const abandonAdmission = ():
| HttpExecutionOutcome<WireOutput, Problem>
| null => {
switch (terminalCancellation) {
case "DEADLINE":
return finish(abandonedTransportFailure("TIMEOUT"), "TIMEOUT");
case "CALLER":
return finish(cancelled(abandonedCertainty()), "CANCELLED");
case "SCOPE_FENCE":
return finish(
scopeFenced(abandonedCertainty()),
"SCOPE_FENCED",
);
default:
return null;
}
};
// LIVE-04. A terminal owner that lands during admission wins over the
// admitted answer.
if (admission.kind !== "VALUE") {
cancelResponseBody(response);
return (
abandonAdmission() ??
finish(
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
)
);
return terminalCancellation === null
? finish(
abandonedTransportFailure("NETWORK_FAILURE"),
"NETWORK_FAILURE",
)
: terminalOutcomeFor("ADMISSION");
}
const outcome = admission.value;
attemptState = "SETTLED";
const abandoned = abandonAdmission();
if (abandoned) return abandoned;
if (terminalCancellation !== null) {
return terminalOutcomeFor("ADMISSION");
}
if (
outcome.retryHint &&
// Q-6.3-7. An answer that says the command may already be applied
// is not replayed; reconciliation owns it from here.
outcome.certainty !== "MAYBE_APPLIED" &&
outcome.certainty !== "APPLIED_CONFIRMED" &&
retryIndex < retryCeiling &&
isRetryableSemantics(contract.retrySemantics)
) {
@@ -1028,21 +1013,28 @@ export function createContractHttpExecutor(
sleep(delay, lifetimeController.signal),
lifetimeController.signal,
);
if (slept === ABORTED) {
return terminalCancellation === "CALLER"
? finish(
cancelled(abandonedCertainty()),
"CANCELLED",
)
: finish(
abandonedTransportFailure("TIMEOUT"),
"TIMEOUT",
);
}
if (slept === ABORTED) return terminalOutcomeFor("WAIT");
rememberRetried(outcome.result.effect as MutationEffectCertainty);
continue;
}
}
return finish(outcome.result, outcome.certainty);
// Q-6.3-7. A retry never reports less than an earlier attempt of the
// same command already established.
const effect = isCommand
? joinMutationEffectCertainty(
retriedCertainty,
outcome.result.effect as MutationEffectCertainty,
)
: outcome.result.effect;
return finish(
effect === outcome.result.effect
? outcome.result
: (Object.freeze({
...outcome.result,
effect,
}) as HttpExecutionOutcome<WireOutput, Problem>),
outcome.certainty,
);
} finally {
clearTimeout(deadlineTimer);
lifetimeController.signal.removeEventListener("abort", forwardLifetime);
@@ -1158,6 +1150,7 @@ async function admitResponse<Input, WireOutput, Problem>(
unauthenticated(
certaintyForAbandonedAttempt(attemptState, isCommand),
isCommand,
metadata,
),
"UNAUTHENTICATED",
);
@@ -1490,6 +1483,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1502,6 +1496,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"CONTENT_TYPE_MISMATCH",
"RESPONSE",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1516,6 +1511,7 @@ async function admitProblem<Input, WireOutput, Problem>(
decoded.code,
"RESPONSE",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1534,6 +1530,7 @@ async function admitProblem<Input, WireOutput, Problem>(
"PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: false,
@@ -1550,6 +1547,7 @@ async function admitProblem<Input, WireOutput, Problem>(
: "PROBLEM_SCHEMA_INVALID",
"VALIDATION",
postDispatchEffect(isCommand),
metadata,
),
certainty: isCommand ? "MAYBE_APPLIED" : "NOT_STARTED",
retryHint: retryable,
@@ -1612,10 +1610,12 @@ function violation<Value, Problem>(
kind: HttpContractViolationKind,
operation: HttpContractViolation["operation"],
effect: HttpEffectCertainty,
metadata?: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "CONTRACT_VIOLATION" as const,
violation: Object.freeze({ kind, operation }),
...(metadata === undefined ? {} : { metadata }),
effect,
});
}
@@ -1652,9 +1652,11 @@ function postDispatchEffect(isCommand: boolean): HttpEffectCertainty {
function unauthenticated<Value, Problem>(
effect: string,
isCommand: boolean,
metadata?: SafeResponseMetadata,
): HttpExecutionOutcome<Value, Problem> {
return Object.freeze({
kind: "UNAUTHENTICATED" as const,
...(metadata === undefined ? {} : { metadata }),
effect: normalizeOptionalEffect(effect, isCommand),
});
}
+3 -1
View File
@@ -42,7 +42,9 @@ export type { CredentialPatchOutcome } from "./http-contract-bridge.ts";
*
* 이 템플릿은 V2의 오퍼레이션 레지스트리와 payload 매퍼를 비워서 출하한다.
* 제품이 `RuntimeHttpContract`(`src/bootstrap/runtime-adapters.ts`)의 네
* 슬롯을 주입해야 동작한다 — 주입 없이 V3에서 되돌리면 모든 요청이 실패한다.
* 슬롯을 주입해야 동작한다. V3의 롤백 경로는 아니다 — V2는
* `{ success, data, meta }` 봉투를, V3는 DTO 자체를 검증하므로 V2로 되돌리려면
* 슬롯 주입과 함께 서버 응답도 V2 봉투여야 한다.
*/
export {
createHttpClient,
+3
View File
@@ -73,6 +73,9 @@ export function buildRequestTarget(
if (
serialized.length === 0 ||
serialized.length > 512 ||
// Dot segments are not encoded and pathname assignment normalizes them.
serialized === "." ||
serialized === ".." ||
[...serialized].some((character) => {
const code = character.codePointAt(0) ?? 0;
return code < 32 || code === 127;
+4 -14
View File
@@ -1,3 +1,5 @@
import { parseRetryAfterDelay } from "../platform/retry-after.ts";
const retryKinds: ReadonlySet<string> = new Set([
"NETWORK_UNREACHABLE",
"REQUEST_TIMEOUT",
@@ -18,16 +20,7 @@ export function parseRetryAfter(
value: string | null | undefined,
now = Date.now(),
): number | null {
if (!value) return null;
const seconds = Number(value);
if (Number.isFinite(seconds)) {
return seconds < 0 ? null : seconds * 1_000;
}
const timestamp = Date.parse(value);
if (!Number.isFinite(timestamp)) return null;
return Math.max(0, timestamp - now);
return parseRetryAfterDelay(value, now);
}
export type RetryOperation = Readonly<{
@@ -54,12 +47,11 @@ export function shouldRetry(
if (
failure.kind === "SERVER_FAILURE" &&
failure.httpStatus !== undefined &&
![502, 503, 504].includes(failure.httpStatus)
![408, 425, 502, 503, 504].includes(failure.httpStatus)
) {
return false;
}
if (
failure.kind === "RATE_LIMITED" &&
typeof failure.retryAfterMs === "number" &&
failure.retryAfterMs > 30_000
) {
@@ -75,8 +67,6 @@ export function retryDelay(
now = Date.now(),
): number {
const localBackoff = calculateBackoff(retryIndex, random);
if (failure.kind !== "RATE_LIMITED") return localBackoff;
const retryAfterMs =
typeof failure.retryAfterMs === "number"
? failure.retryAfterMs
@@ -267,3 +267,49 @@ export function compensateLateHandle(
})
.catch(() => undefined);
}
/**
* Best-effort release of a response body whose result is already classified.
* Neither a synchronous throw nor a rejected cancellation can change that
* result.
*/
export function cancelBody(response: Response): void {
try {
void response.body?.cancel().catch(() => undefined);
} catch {
// The classified result wins over body cancellation.
}
}
/** `cancelBody` for a reader that already holds the body's lock. */
export function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => undefined);
} catch {
// The classified result wins over reader cancellation.
}
}
/** Aborts one signal when either input aborts; `release` only drops listeners. */
export function combineAbortSignals(
first: AbortSignal,
second: AbortSignal,
): Readonly<{ signal: AbortSignal; release(): void }> {
const controller = new AbortController();
const abort = () => controller.abort();
if (first.aborted || second.aborted) {
controller.abort();
} else {
first.addEventListener("abort", abort, { once: true });
second.addEventListener("abort", abort, { once: true });
}
return Object.freeze({
signal: controller.signal,
release() {
first.removeEventListener("abort", abort);
second.removeEventListener("abort", abort);
},
});
}
@@ -332,7 +332,9 @@ export function openIndexedDbDatabase<Failure>(
// A null `newVersion` means a delete is in progress, and no `upgrade`
// policy can be applied to a schema that is going away. It is reported
// before the callback runs so a caller never sees a half-open upgrade.
if (!transaction || newVersion === null || !input.upgrade) {
// Q-6.5-10. An open that already settled (caller abort, BLOCKED, close)
// must not commit a migration behind its caller's back either.
if (settled || !transaction || newVersion === null || !input.upgrade) {
upgradeRejection = { kind: "UPGRADE_REJECTED", oldVersion, newVersion };
abortUpgrade();
return;
@@ -26,7 +26,8 @@ export type IndexedDbDurability = "default" | "strict" | "relaxed";
*/
export type IndexedDbRequestSink<Failure> = Readonly<{
/**
* Records the failure and aborts the transaction. The first failure wins.
* Records the failure and aborts the transaction. The first failure wins,
* and it wins over an earlier `succeed`.
* This is `indexeddb-runtime.ts:1047-1054`'s `fail`.
*/
fail(failure: Failure): void;
@@ -266,7 +267,9 @@ export function runIndexedDbTransaction<Value, Failure>(
candidate ??= succeeded(value);
},
fail(failure) {
candidate ??= failed(failure);
// Q-6.5-10. A failure replaces an earlier `succeed`; only an earlier
// failure outranks it.
if (candidate?.ok !== false) candidate = failed(failure);
try {
transaction.abort();
} catch {
+38
View File
@@ -0,0 +1,38 @@
/**
* Parses an HTTP Retry-After value: delta-seconds (digits only, surrounding
* whitespace allowed) or an IMF-fixdate. Anything else — decimals, exponents,
* blank text, other date spellings — is `null`, never a guessed delay.
* No runtime ceiling is applied; callers reject a value above their budget.
*/
export function parseRetryAfterDelay(
value: string | null | undefined,
nowEpochMs: number,
): number | null {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 128 ||
!Number.isFinite(nowEpochMs)
) {
return null;
}
const normalized = value.trim();
if (/^\d+$/u.test(normalized)) {
const seconds = Number(normalized);
return Number.isSafeInteger(seconds) &&
seconds <= Math.floor(Number.MAX_SAFE_INTEGER / 1_000)
? seconds * 1_000
: null;
}
if (
!/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/u.test(
normalized,
)
) {
return null;
}
const timestamp = Date.parse(normalized);
return Number.isFinite(timestamp)
? Math.max(0, timestamp - nowEpochMs)
: null;
}
@@ -138,12 +138,11 @@ export function createConditionalValidatorStore(
function isSafeEntityTag(value: string): boolean {
if (value.length < 3 || value.length > 256) return false;
const opaque = value.startsWith('W/"')
? value.slice(3, -1)
: value.startsWith('"')
? value.slice(1, -1)
: null;
if (opaque === null || !value.endsWith('"')) return false;
const start = value.startsWith('W/"') ? 3 : value.startsWith('"') ? 1 : -1;
// Q-6.3-12. The closing quote must follow the opening one: a bare `W/"`
// ends with its opening quote and is unclosed.
if (start < 0 || value.length <= start || !value.endsWith('"')) return false;
const opaque = value.slice(start, -1);
return [...opaque].every((character) => {
const code = character.codePointAt(0) ?? 0;
return code === 0x21 || (code >= 0x23 && code <= 0x7e) ||
@@ -68,6 +68,7 @@ export function createCursorPaginationRuntime<Value>(dependencies: Readonly<{
return Object.freeze({
async loadAll(context) {
const items: Value[] = [];
let pageBytes = 0;
const cursors = new Set<string>();
let cursor: string | null = null;
let snapshot: string | null | undefined;
@@ -108,16 +109,21 @@ export function createCursorPaginationRuntime<Value>(dependencies: Readonly<{
"PAGINATION_SNAPSHOT_CHANGED",
);
}
items.push(...page.items);
// Q-6.3-12. Each page is measured once (the sum errs high by at most
// one byte per page) and appended item by item: re-serializing the
// accumulated items was O(pages × total), and `push(...items)`
// throws a RangeError for a large page.
pageBytes += estimatedBytes(page.items);
if (
items.length > profile.maxTotalItems ||
estimatedBytes(items) > profile.maxEstimatedBytes
items.length + page.items.length > profile.maxTotalItems ||
pageBytes > profile.maxEstimatedBytes
) {
return failure(
"RESULT_LIMIT_EXCEEDED",
"PAGINATION_RESULT_LIMIT",
);
}
for (const item of page.items) items.push(item);
if (!page.hasMore) return { ok: true, value: Object.freeze(items) };
const nextCursor: string | null = page.nextCursor;
if (!nextCursor || cursors.has(nextCursor)) {
@@ -24,7 +24,12 @@ export type ScopeResetParticipant = Readonly<{
}>;
export type ServerStateScopeDependencies = Readonly<{
session: Pick<AuthSessionPort, "subscribe">;
/**
* `getState`/`getSubject` let the runtime skip a notification that changes
* neither. Without `getState` every notification fences, as before.
*/
session: Pick<AuthSessionPort, "subscribe"> &
Partial<Pick<AuthSessionPort, "getState" | "getSubject">>;
queryInvalidation: Pick<QueryInvalidationCoordinator, "resetLocal">;
tokenFactory?: () => string;
participants?: readonly ScopeResetParticipant[];
@@ -49,6 +54,7 @@ export function createServerStateScopeRuntime(
let phase: ClientScopePhase = "READY";
let disposed = false;
let resetChain = Promise.resolve();
let sessionIdentity = readSessionIdentity(dependencies.session);
function createSnapshot(): CacheScopeSnapshot {
const capturedGeneration = generation;
@@ -89,6 +95,18 @@ export function createServerStateScopeRuntime(
const unsubscribe = dependencies.session.subscribe(() => {
if (disposed) return;
// §10.6 is for identity-affecting changes only. A notification that keeps
// (state, subject) — a token refresh, a repeated sign-out — must not abort
// requests and clear the cache. A FAILED scope still retries its reset.
const nextSessionIdentity = readSessionIdentity(dependencies.session);
if (
nextSessionIdentity !== null &&
nextSessionIdentity === sessionIdentity &&
phase !== "FAILED"
) {
return;
}
sessionIdentity = nextSessionIdentity;
const previousIdentities = identities;
const previousGeneration = generation;
@@ -185,6 +203,28 @@ export function createServerStateScopeRuntime(
});
}
/**
* `null` means the identity cannot be proven unchanged: no `getState`, a
* throwing owner, or an authenticated session without a non-empty subject.
* Those always fence, which keeps an account switch from reusing the previous
* cache.
*/
function readSessionIdentity(
session: ServerStateScopeDependencies["session"],
): string | null {
try {
const state = session.getState?.();
if (state === undefined) return null;
const subject = session.getSubject?.();
const knownSubject =
typeof subject === "string" && subject !== "" ? subject : null;
if (state === "authenticated" && knownSubject === null) return null;
return JSON.stringify([state, knownSubject]);
} catch {
return null;
}
}
function newIdentityRegistry(
tokenFactory: (() => string) | undefined,
): RuntimeIdentityRegistry {
@@ -76,16 +76,19 @@ export function createTanStackCacheCoordinator(
namespaces.set(queryNamespaceIdentityKey(namespace), namespace);
}
}
for (const namespace of namespaces.values()) {
try {
await dependencies.queryClient.invalidateQueries({
// Q-6.3-8. invalidateQueries resolves only after the active refetches
// finish, so the namespaces run side by side instead of one after another.
const results = await Promise.allSettled(
[...namespaces.values()].map(async (namespace) =>
dependencies.queryClient.invalidateQueries({
queryKey: createQueryInvalidationPrefix(namespace),
exact: false,
refetchType: "active",
});
} catch {
report("invalidate");
}
}),
),
);
for (const result of results) {
if (result.status === "rejected") report("invalidate");
}
}
+30 -11
View File
@@ -24,14 +24,16 @@ import {
} from "../../contracts/schema-registry.ts";
import {
hasDuplicateJsonMembers,
} from "./json-member-scanner.ts";
} from "../platform/json-member-scanner.ts";
export type ValidatedRealtimeEventDto = Readonly<{
envelope: RealtimeEventEnvelope;
wireBytes: number;
/**
* Adapter-private semantic identity used only by the bounded conflict
* detector. It must never be logged or projected into diagnostics.
* detector: a fixed-size hash of the canonical envelope, so dedupe memory
* does not grow with payload size. It must never be logged or projected
* into diagnostics.
*/
semanticFingerprint: string;
fingerprintBytes: number;
@@ -99,13 +101,13 @@ function decodeUnsafe(
if (typeof raw !== "string") {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (
raw.length > REALTIME_HARD_LIMITS.maxEventBytes ||
encoder.encode(raw).byteLength > REALTIME_HARD_LIMITS.maxEventBytes
) {
if (raw.length > REALTIME_HARD_LIMITS.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
const wireBytes = encoder.encode(raw).byteLength;
if (wireBytes > REALTIME_HARD_LIMITS.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
let input: unknown;
if (
@@ -186,11 +188,8 @@ function decodeUnsafe(
eventType,
payloadSnapshot,
);
const semanticFingerprint = canonicalJson(envelope);
const fingerprintBytes = encoder.encode(semanticFingerprint).byteLength;
if (fingerprintBytes > stream.limits.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
const semanticFingerprint = hash64(canonicalJson(envelope));
const fingerprintBytes = semanticFingerprint.length;
const dto = Object.freeze({
envelope,
@@ -367,6 +366,26 @@ function snapshotJson(
return visit(value, 0);
}
/**
* Two differently seeded 32-bit FNV-1a hashes as 16 hex characters.
* ponytail: not collision-proof against a hostile server; a collision only
* lets a conflicting redelivery pass as a duplicate. Use SHA-256 if the
* server is not trusted to keep event IDs unique.
*/
function hash64(text: string): string {
let first = 0x811c9dc5;
let second = 0x9e3779b9;
for (let index = 0; index < text.length; index += 1) {
const unit = text.charCodeAt(index);
first = Math.imul(first ^ unit, 0x01000193);
second = Math.imul(second ^ unit, 0x01000193);
}
return (
(first >>> 0).toString(16).padStart(8, "0") +
(second >>> 0).toString(16).padStart(8, "0")
);
}
function canonicalJson(value: unknown): string {
if (
value === null ||
+8
View File
@@ -178,6 +178,14 @@ function projectTransportOutcome(
streamId: StreamRegistrationId | null,
): RealtimeResult<RealtimeTransportEventOutcome> {
if (!accepted.ok) return accepted;
// A recovery with no barrier to confirm keeps the connection; handing it to
// the reconnect path would ask for a barrier the coordinator never set.
if (
accepted.value.outcome === "RECOVERED" &&
accepted.value.transportBarrierRequired === false
) {
return realtimeSuccess(REALTIME_TRANSPORT_CONTINUE);
}
if (
accepted.value.outcome === "RECOVERED" ||
accepted.value.outcome === "RECOVERY_BARRIER_REQUIRED"
@@ -7,6 +7,7 @@ import {
import { systemClock } from "../platform/system-clock.ts";
import {
isRealtimeResult,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
} from "./result.ts";
@@ -132,8 +133,6 @@ type InternalProbe<Value> = {
facade: LiveProbeLease<Value>;
readonly buffer: BufferedValue<Value>[];
bufferedBytes: number;
acceptedEvents: number;
acceptedBytes: number;
};
type QuiescenceOutcome = "QUIESCED" | "TIMER_FAILED" | "TIMED_OUT";
@@ -224,8 +223,6 @@ export function createLivePollHandoffCoordinator<Value>(
lease,
buffer: [],
bufferedBytes: 0,
acceptedEvents: 0,
acceptedBytes: 0,
facade: null as unknown as LiveProbeLease<Value>,
};
selected.facade = Object.freeze({
@@ -263,11 +260,11 @@ export function createLivePollHandoffCoordinator<Value>(
value: Value,
wireBytes: number,
): RealtimeResult<LivePollWriteReceipt> {
// Bounded by what is still buffered: activation drains the buffer while
// the probe keeps receiving.
if (
selected.acceptedEvents + 1 >
limits.maxProbeBufferedEvents ||
selected.acceptedBytes + wireBytes >
limits.maxProbeBufferedBytes
selected.buffer.length + 1 > limits.maxProbeBufferedEvents ||
selected.bufferedBytes + wireBytes > limits.maxProbeBufferedBytes
) {
if (transitioning) {
failClosed();
@@ -282,8 +279,6 @@ export function createLivePollHandoffCoordinator<Value>(
}
selected.buffer.push(Object.freeze({ value, wireBytes }));
selected.bufferedBytes += wireBytes;
selected.acceptedEvents += 1;
selected.acceptedBytes += wireBytes;
return realtimeSuccess(
Object.freeze({
kind: "BUFFERED" as const,
@@ -555,24 +550,6 @@ export function createLivePollHandoffCoordinator<Value>(
from: LivePollWriterKind,
candidate: InternalWriterLease<Value>,
): Promise<RealtimeResult<void>> {
const timer = new AbortController();
let releaseAbortGate = (): void => undefined;
const aborted = new Promise<
Readonly<{ kind: "ABORTED" }>
>((resolve) => {
const onAbort = () => resolve({ kind: "ABORTED" });
candidate.controller.signal.addEventListener(
"abort",
onAbort,
{ once: true },
);
releaseAbortGate = () =>
candidate.controller.signal.removeEventListener(
"abort",
onAbort,
);
if (candidate.controller.signal.aborted) onAbort();
});
const operation = Promise.resolve()
.then(() =>
dependencies.establishAuthoritativeCheckpoint(
@@ -585,59 +562,30 @@ export function createLivePollHandoffCoordinator<Value>(
isCheckpointCandidateCurrent(candidate),
}),
),
)
.then(
(value) => ({ kind: "VALUE" as const, value }),
() => ({ kind: "REJECTED" as const }),
);
// RT-RR-04. Registered at the moment the authority is called, and removed
// only when it settles, so `close()` cannot report quiescence over it.
checkpointTasks.add(operation);
void operation.finally(() => {
checkpointTasks.delete(operation);
const settled = operation.then(
() => undefined,
() => undefined,
);
checkpointTasks.add(settled);
void settled.then(() => {
checkpointTasks.delete(settled);
});
const timeout = Promise.resolve()
.then(async () => {
await clock.sleep(
limits.quiescenceTimeoutMs,
timer.signal,
);
return { kind: "TIMED_OUT" as const };
})
.catch(() => ({
kind: timer.signal.aborted
? ("CANCELED" as const)
: ("TIMER_FAILED" as const),
}));
const selected = await Promise.race([
operation,
timeout,
aborted,
]);
timer.abort();
releaseAbortGate();
const selected = await raceRealtimeTask(
() => operation,
candidate.controller.signal,
(signal) => clock.sleep(limits.quiescenceTimeoutMs, signal),
);
if (selected.kind === "ABORTED") {
return handoffFailure("ABORTED", "RECOVER");
}
if (selected.kind === "TIMED_OUT") {
if (selected.kind === "TIMEOUT") {
candidate.controller.abort();
return handoffFailure("IDLE_TIMEOUT", "RECOVER");
}
if (
selected.kind === "TIMER_FAILED" ||
selected.kind === "REJECTED"
) {
candidate.controller.abort();
return handoffFailure(
"PROVIDER_UNAVAILABLE",
"RECOVER",
true,
);
}
if (selected.kind === "CANCELED") {
return handoffFailure("ABORTED", "RECOVER");
}
if (selected.kind !== "VALUE") {
candidate.controller.abort();
return handoffFailure(
@@ -673,50 +621,22 @@ export function createLivePollHandoffCoordinator<Value>(
async function awaitTaskQuiescence(
task: Promise<unknown>,
): Promise<QuiescenceOutcome> {
const timer = new AbortController();
const settled = task.then(
() => "QUIESCED" as const,
() => "QUIESCED" as const,
const outcome = await raceRealtimeTask(
() => task,
undefined,
(signal) => clock.sleep(limits.quiescenceTimeoutMs, signal),
);
const timeout = Promise.resolve()
.then(async () => {
await clock.sleep(limits.quiescenceTimeoutMs, timer.signal);
return "TIMED_OUT" as const;
})
.catch(() =>
timer.signal.aborted
? ("QUIESCED" as const)
: ("TIMER_FAILED" as const),
);
const outcome = await Promise.race([settled, timeout]);
timer.abort();
return outcome;
return outcome.kind === "TIMEOUT"
? "TIMED_OUT"
: outcome.kind === "CLOCK_FAILED"
? "TIMER_FAILED"
: "QUIESCED";
}
async function awaitQuiescence(
function awaitQuiescence(
lease: InternalWriterLease<Value>,
): Promise<QuiescenceOutcome> {
const timer = new AbortController();
const settled = lease.tail.then(
() => "QUIESCED" as const,
() => "QUIESCED" as const,
);
const timeout = Promise.resolve()
.then(async () => {
await clock.sleep(
limits.quiescenceTimeoutMs,
timer.signal,
);
return "TIMED_OUT" as const;
})
.catch(() =>
timer.signal.aborted
? ("QUIESCED" as const)
: ("TIMER_FAILED" as const),
);
const outcome = await Promise.race([settled, timeout]);
timer.abort();
return outcome;
return awaitTaskQuiescence(lease.tail);
}
function close(): Promise<RealtimeResult<void>> {
@@ -13,8 +13,12 @@ import {
} from "../../../application/ports/realtime/shared.ts";
import { systemClock } from "../../platform/system-clock.ts";
import {
captureRealtimeDataSnapshot,
hasExactSnapshotKeys,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
type RealtimeRace,
} from "../result.ts";
/**
@@ -216,7 +220,7 @@ export function createBoundedPollCoordinator<Value>(
) {
return pollFailure("POLL_BUDGET_EXHAUSTED");
}
const cadenceOutcome = await awaitTaskOrAbort(
const cadenceOutcome = await raceRealtimeTask(
() => clock.sleep(nextDelayMs, controller.signal),
controller.signal,
);
@@ -231,7 +235,7 @@ export function createBoundedPollCoordinator<Value>(
);
return pollFailure(
afterSleepFailure ??
(cadenceOutcome.kind === "THREW"
(cadenceOutcome.kind === "REJECTED"
? "PROVIDER_UNAVAILABLE"
: "ABORTED"),
afterSleepFailure === "OFFLINE",
@@ -281,7 +285,7 @@ export function createBoundedPollCoordinator<Value>(
);
if (attemptOutcome.kind === "VALUE") {
result = attemptOutcome.value;
} else if (attemptOutcome.kind === "THREW") {
} else if (attemptOutcome.kind === "REJECTED") {
result = realtimeFailure(
controller.signal.aborted ? "ABORTED" : "OFFLINE",
"POLL",
@@ -341,13 +345,18 @@ export function createBoundedPollCoordinator<Value>(
}
result = parsedResult;
if (!result.ok) {
// A missing server hint falls back to policy backoff; an executor
// that requires one reports `retryable: false` instead.
if (
!result.error.retryable ||
!isPollRetryableFailureKind(result.error.kind) ||
(isPollRetryAfterFailureKind(result.error.kind) &&
result.error.retryAfterMs === undefined)
!isPollRetryableFailureKind(result.error.kind)
) {
return pollFailure(result.error.kind);
// OFFLINE (a thrown executor included) ends this lease but stays
// retryable, like every other OFFLINE here.
return pollFailure(
result.error.kind,
result.error.kind === "OFFLINE" && result.error.retryable,
);
}
consecutiveFailures += 1;
const failureDelay = retryDelay(
@@ -411,7 +420,7 @@ export function createBoundedPollCoordinator<Value>(
controller.signal,
() => stop("POLL_BUDGET_EXHAUSTED"),
);
if (applyOutcome.kind === "THREW") {
if (applyOutcome.kind === "REJECTED") {
return applyFailure();
}
if (applyOutcome.kind !== "VALUE") {
@@ -550,156 +559,24 @@ function currentFailure(
return null;
}
type TaskOutcome<Value> =
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "THREW" }>
| Readonly<{ kind: "ABORTED" }>;
type LeaseTaskOutcome<Value> =
| TaskOutcome<Value>
| Readonly<{ kind: "LEASE_EXPIRED" }>
| Readonly<{ kind: "CLOCK_FAILED" }>;
async function awaitTaskOrAbort<Value>(
task: () => Promise<Value>,
signal: AbortSignal,
): Promise<TaskOutcome<Value>> {
if (signal.aborted) return Object.freeze({ kind: "ABORTED" });
let removeAbortListener: () => void = () => undefined;
const aborted = new Promise<Readonly<{ kind: "ABORTED" }>>(
(resolve) => {
const onAbort = () => resolve(Object.freeze({ kind: "ABORTED" }));
signal.addEventListener("abort", onAbort, { once: true });
removeAbortListener = () =>
signal.removeEventListener("abort", onAbort);
if (signal.aborted) onAbort();
},
);
if (signal.aborted) {
removeAbortListener();
return Object.freeze({ kind: "ABORTED" });
}
let taskPromise: Promise<Value>;
try {
taskPromise = task();
} catch {
removeAbortListener();
return Object.freeze({ kind: "THREW" });
}
const completed = taskPromise.then<
TaskOutcome<Value>,
TaskOutcome<Value>
>(
(value) => Object.freeze({ kind: "VALUE", value }),
() => Object.freeze({ kind: "THREW" }),
);
try {
return await Promise.race([completed, aborted]);
} finally {
removeAbortListener();
}
}
const LEASE_EXPIRED = Object.freeze({ kind: "TIMEOUT" as const });
/** Bounds work by the lease's remaining time; expiry stops the whole run. */
async function awaitWithinLease<Value>(
task: () => Promise<Value>,
remainingMs: number,
clock: ClockPort,
signal: AbortSignal,
onLeaseExpired: () => void,
): Promise<LeaseTaskOutcome<Value>> {
if (!Number.isFinite(remainingMs) || remainingMs <= 0) {
onLeaseExpired();
return Object.freeze({ kind: "LEASE_EXPIRED" });
}
if (signal.aborted) return Object.freeze({ kind: "ABORTED" });
const deadlineController = new AbortController();
let resolveInterruption:
| ((outcome: LeaseTaskOutcome<Value>) => void)
| undefined;
let removeAbortListener: () => void = () => undefined;
let interruptionSettled = false;
const finishInterruption = (
outcome: LeaseTaskOutcome<Value>,
): boolean => {
if (interruptionSettled) return false;
interruptionSettled = true;
resolveInterruption?.(outcome);
return true;
};
const interrupted = new Promise<LeaseTaskOutcome<Value>>((resolve) => {
resolveInterruption = resolve;
const onAbort = () =>
finishInterruption(Object.freeze({ kind: "ABORTED" }));
signal.addEventListener("abort", onAbort, { once: true });
removeAbortListener = () =>
signal.removeEventListener("abort", onAbort);
if (signal.aborted) onAbort();
});
if (signal.aborted) {
removeAbortListener();
return Object.freeze({ kind: "ABORTED" });
}
let deadlineSleep: Promise<void>;
try {
deadlineSleep = clock.sleep(
remainingMs,
deadlineController.signal,
);
} catch {
removeAbortListener();
deadlineController.abort();
return Object.freeze({ kind: "CLOCK_FAILED" });
}
const deadline = deadlineSleep.then(
() => {
if (deadlineController.signal.aborted) return;
if (
finishInterruption(
Object.freeze({ kind: "LEASE_EXPIRED" }),
): Promise<RealtimeRace<Value>> {
const outcome =
Number.isFinite(remainingMs) && remainingMs > 0
? await raceRealtimeTask(task, signal, (lease) =>
clock.sleep(remainingMs, lease),
)
) {
onLeaseExpired();
}
},
() => {
if (!deadlineController.signal.aborted) {
finishInterruption(
Object.freeze({ kind: "CLOCK_FAILED" }),
);
}
},
);
if (signal.aborted) {
removeAbortListener();
deadlineController.abort();
void deadline;
return Object.freeze({ kind: "ABORTED" });
}
let taskPromise: Promise<Value>;
try {
taskPromise = task();
} catch {
taskPromise = Promise.reject(new Error("Task failed."));
}
const completed = taskPromise.then<
LeaseTaskOutcome<Value>,
LeaseTaskOutcome<Value>
>(
(value) => Object.freeze({ kind: "VALUE", value }),
() => Object.freeze({ kind: "THREW" }),
);
try {
const outcome = await Promise.race([completed, interrupted]);
void deadline;
return outcome;
} finally {
removeAbortListener();
deadlineController.abort();
}
: LEASE_EXPIRED;
if (outcome.kind === "TIMEOUT") onLeaseExpired();
return outcome;
}
function parseAttemptResult<Value>(
@@ -790,42 +667,10 @@ function snapshotDataRecord(
value: unknown,
allowedKeySets: readonly (readonly string[])[],
): Readonly<Record<string, unknown>> | null {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return null;
}
try {
if (Object.getPrototypeOf(value) !== Object.prototype) {
return null;
}
const keys = Reflect.ownKeys(value);
if (keys.some((key) => typeof key !== "string")) return null;
const sortedKeys = (keys as string[]).sort();
if (
!allowedKeySets.some((allowed) => {
const sortedAllowed = [...allowed].sort();
return (
sortedKeys.length === sortedAllowed.length &&
sortedKeys.every(
(key, index) => key === sortedAllowed[index],
)
);
})
) {
return null;
}
const descriptors = Object.getOwnPropertyDescriptors(value);
const snapshot: Record<string, unknown> = {};
for (const key of sortedKeys) {
const descriptor = descriptors[key];
if (!descriptor || !Object.hasOwn(descriptor, "value")) {
return null;
}
snapshot[key] = descriptor.value;
}
return Object.freeze(snapshot);
} catch {
return null;
}
const snapshot = captureRealtimeDataSnapshot(value);
return snapshot && hasExactSnapshotKeys(snapshot, ...allowedKeySets)
? snapshot.values
: null;
}
function retryDelay(
+102 -254
View File
@@ -16,9 +16,14 @@ import {
type ReconnectPolicy,
} from "./reconnect-policy.ts";
import {
captureRealtimeDataSnapshot,
hasExactSnapshotKeys,
isRealtimeResult,
isRealtimeTransportEventOutcome,
raceRealtimeTask,
realtimeFailure,
timerDeadline,
type RealtimeDataSnapshot,
} from "./result.ts";
type FailureResult = Extract<RealtimeResult<never>, { ok: false }>;
@@ -226,12 +231,6 @@ type ParsedCloseClassification =
directive: ParsedRecoveryDirective;
}>;
type DataSnapshot = Readonly<{
source: object;
keys: readonly string[];
values: Readonly<Record<string, unknown>>;
}>;
type ParsedRunInput = Readonly<{
signal: AbortSignal | undefined;
initialRecovery: ParsedRecoveryDirective | null;
@@ -590,6 +589,22 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
activeRecoveryGate = null;
}
};
/**
* Ends this attempt: settles its barrier gate when given a result,
* closes the opened session, and aborts and releases the phase.
*/
const endAttempt = (
gateResult: RealtimeResult<void> | null,
opened?: RealtimeReconnectSession<ClosedReceipt>,
) => {
if (gateResult) settleAttemptGate(gateResult);
if (opened) {
safelyClose(opened);
if (session === opened) session = null;
}
phase.controller.abort();
phase.dispose();
};
const isAttemptCurrent = () =>
state === "RUNNING" &&
generation === runGeneration &&
@@ -653,24 +668,19 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
continue;
}
const interrupted = currentFailure() ?? "ABORTED";
settleAttemptGate(recoveryFailure(interrupted));
phase.dispose();
endAttempt(recoveryFailure(interrupted));
return failure(interrupted);
}
const afterAttempt = currentFailure();
if (afterAttempt) {
closeLateSession(attempted);
settleAttemptGate(recoveryFailure(afterAttempt));
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(afterAttempt));
return failure(afterAttempt);
}
if (attemptOffline) {
closeLateSession(attempted);
settleAttemptGate(recoveryFailure("OFFLINE"));
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure("OFFLINE"));
retry = offlineRetry(
safeNow(clock) ?? beforeAttempt,
"CONNECT",
@@ -684,9 +694,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
"CONNECT",
pendingRecovery?.terminalFailure.result,
);
settleAttemptGate(nextRetry.result);
phase.controller.abort();
phase.dispose();
endAttempt(nextRetry.result);
retry = nextRetry;
continue;
}
@@ -696,33 +704,20 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
);
if (!opened) {
const mismatch = failure("PROTOCOL_MISMATCH");
settleAttemptGate(mismatch);
phase.controller.abort();
phase.dispose();
endAttempt(mismatch);
return mismatch;
}
const afterAttemptValidation = currentFailure();
if (afterAttemptValidation) {
if (opened.ok) safelyClose(opened.value.session);
settleAttemptGate(
recoveryFailure(afterAttemptValidation),
);
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(afterAttemptValidation));
return failure(afterAttemptValidation);
}
if (!opened.ok) {
settleAttemptGate(opened.failure.result);
phase.controller.abort();
phase.dispose();
if (
!reconnectable(
opened.failure,
opened.serverNotBeforeMs,
)
) {
endAttempt(opened.failure.result);
if (!reconnectable(opened.failure)) {
return opened.failure.result;
}
const failedAt = safeNow(clock);
@@ -748,21 +743,13 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
const mismatch = recoveryFailure(
"PROTOCOL_MISMATCH",
);
settleAttemptGate(mismatch);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(mismatch, active);
return mismatch;
}
const beforeConfirmation = currentFailure();
if (beforeConfirmation) {
settleAttemptGate(
recoveryFailure(beforeConfirmation),
);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(beforeConfirmation), active);
return failure(beforeConfirmation);
}
@@ -778,28 +765,17 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
const mismatch = recoveryFailure(
"PROTOCOL_MISMATCH",
);
settleAttemptGate(mismatch);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(mismatch, active);
return mismatch;
}
const afterConfirmation = currentFailure();
if (afterConfirmation) {
settleAttemptGate(
recoveryFailure(afterConfirmation),
);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(recoveryFailure(afterConfirmation), active);
return failure(afterConfirmation);
}
if (!confirmation.ok) {
settleAttemptGate(confirmation.failure.result);
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(confirmation.failure.result, active);
return confirmation.failure.result;
}
@@ -810,9 +786,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
} else {
settleAttemptGate(noPendingRecovery);
if (opened.value.hasRecoveryBarrier) {
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
return noPendingRecovery;
}
}
@@ -826,9 +800,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
openedAt,
) <= 0
) {
safelyClose(active);
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
return (
retry?.terminalResult ??
failure("PROVIDER_UNAVAILABLE")
@@ -846,10 +818,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
const afterWaitClosed = currentFailure();
if (afterWaitClosed) {
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
return failure(afterWaitClosed);
}
if (closed.kind === "INTERRUPTED") {
@@ -884,10 +853,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
}
if (closeOffline) {
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
retry = offlineRetry(
safeNow(clock) ?? openedAt,
"RECEIVE",
@@ -895,10 +861,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
continue;
}
if (closed.kind === "THREW") {
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
retry = providerRetry(
safeNow(clock) ?? openedAt,
"RECEIVE",
@@ -913,10 +876,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
rawClassification = null;
}
const afterClassification = currentFailure();
safelyClose(active);
session = null;
phase.controller.abort();
phase.dispose();
endAttempt(null, active);
if (afterClassification) {
return failure(afterClassification);
}
@@ -934,12 +894,7 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
if (classified.outcome.ok) {
return classified.outcome.result as RealtimeResult<void>;
}
if (
!reconnectable(
classified.outcome.failure,
classified.outcome.serverNotBeforeMs,
)
) {
if (!reconnectable(classified.outcome.failure)) {
return classified.outcome.failure.result;
}
@@ -1033,65 +988,31 @@ export function createRealtimeReconnectCoordinator<ClosedReceipt>(
});
}
const INTERRUPTED = Object.freeze({ kind: "INTERRUPTED" as const });
async function race<Value>(
task: Promise<Settled<Value>>,
signal: AbortSignal,
): Promise<AwaitedTask<Value>> {
if (signal.aborted) return Object.freeze({ kind: "INTERRUPTED" });
let cleanup: () => void = () => undefined;
const interrupted = new Promise<
Readonly<{ kind: "INTERRUPTED" }>
>((resolve) => {
const abort = () =>
resolve(Object.freeze({ kind: "INTERRUPTED" }));
signal.addEventListener("abort", abort, { once: true });
cleanup = () => signal.removeEventListener("abort", abort);
if (signal.aborted) abort();
});
try {
return await Promise.race([task, interrupted]);
} finally {
cleanup();
}
const raced = await raceRealtimeTask(() => task, signal);
return raced.kind === "VALUE" ? raced.value : INTERRUPTED;
}
async function drainWithinCeiling<Value>(
task: Promise<Settled<Value>>,
signal: AbortSignal,
): Promise<DrainedTask<Value>> {
if (signal.aborted) return Object.freeze({ kind: "INTERRUPTED" });
let timer: ReturnType<typeof setTimeout> | undefined;
let cleanup: () => void = () => undefined;
const boundary = new Promise<
| Readonly<{ kind: "INTERRUPTED" }>
| Readonly<{ kind: "TIMED_OUT" }>
>((resolve) => {
const abort = () =>
resolve(Object.freeze({ kind: "INTERRUPTED" }));
cleanup = () => safelyRemoveAbortListener(signal, abort);
try {
signal.addEventListener("abort", abort, { once: true });
timer = setTimeout(
() => resolve(Object.freeze({ kind: "TIMED_OUT" })),
REALTIME_RECONNECT_CEILINGS.drainTimeoutMs,
);
} catch {
resolve(Object.freeze({ kind: "TIMED_OUT" }));
}
if (signal.aborted) abort();
});
try {
return await Promise.race([task, boundary]);
} finally {
cleanup();
if (timer !== undefined) {
try {
clearTimeout(timer);
} catch {
// The generation remains fenced if host timer cleanup fails.
}
}
}
// A host timer, not the clock: a non-cooperative clock is one of the things
// this drain has to bound.
const raced = await raceRealtimeTask(
() => task,
signal,
timerDeadline(REALTIME_RECONNECT_CEILINGS.drainTimeoutMs),
);
if (raced.kind === "VALUE") return raced.value;
return raced.kind === "ABORTED"
? INTERRUPTED
: Object.freeze({ kind: "TIMED_OUT" });
}
function createBarrierGate(): BarrierGate {
@@ -1114,15 +1035,16 @@ function createBarrierGate(): BarrierGate {
}
function parseRunInput(value: unknown): ParsedRunInput | null {
const snapshot = captureDataSnapshot(value);
const snapshot = captureRealtimeDataSnapshot(value);
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
[],
["signal"],
["initialRecovery"],
["initialRecovery", "signal"],
])
)
) {
return null;
}
@@ -1140,7 +1062,7 @@ function parseRunInput(value: unknown): ParsedRunInput | null {
initialValue === undefined
? null
: parseRecoveryDirectiveSnapshot(
captureDataSnapshot(initialValue),
captureRealtimeDataSnapshot(initialValue),
);
if (initialValue !== undefined && !initialRecovery) return null;
return Object.freeze({
@@ -1153,28 +1075,29 @@ function parseAttemptOutcome<ClosedReceipt>(
value: unknown,
): ParsedOutcome<ParsedAttemptSuccess<ClosedReceipt>> | null {
return parseOutcomeSnapshot(
captureDataSnapshot(value),
captureRealtimeDataSnapshot(value),
(candidate) =>
parseAttemptSuccess<ClosedReceipt>(
captureDataSnapshot(candidate),
captureRealtimeDataSnapshot(candidate),
),
);
}
function parseAttemptSuccess<ClosedReceipt>(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): ParsedValue<ParsedAttemptSuccess<ClosedReceipt>> | null {
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
["session"],
["establishedRecoveryBarrier", "session"],
])
)
) {
return null;
}
const session = parseSession<ClosedReceipt>(
captureDataSnapshot(snapshot.values.session),
captureRealtimeDataSnapshot(snapshot.values.session),
);
if (!session) return null;
const hasRecoveryBarrier = snapshot.keys.includes(
@@ -1191,11 +1114,11 @@ function parseAttemptSuccess<ClosedReceipt>(
}
function parseSession<ClosedReceipt>(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): RealtimeReconnectSession<ClosedReceipt> | null {
if (
!snapshot ||
!hasExactKeys(snapshot, [
!hasExactSnapshotKeys(snapshot, [
"classifyClosed",
"close",
"waitClosed",
@@ -1231,7 +1154,7 @@ function parseSession<ClosedReceipt>(
function parseCloseClassification(
value: unknown,
): ParsedCloseClassification | null {
const snapshot = captureDataSnapshot(value);
const snapshot = captureRealtimeDataSnapshot(value);
if (!snapshot) return null;
if (snapshot.values.kind === "RECOVERY_RECONNECT") {
const directive = parseRecoveryDirectiveSnapshot(snapshot);
@@ -1255,11 +1178,12 @@ function parseCloseClassification(
}
function parseRecoveryDirectiveSnapshot(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): ParsedRecoveryDirective | null {
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
["kind", "recovery", "terminalResult"],
[
"kind",
@@ -1267,13 +1191,13 @@ function parseRecoveryDirectiveSnapshot(
"serverNotBeforeMs",
"terminalResult",
],
]) ||
) ||
snapshot.values.kind !== "RECOVERY_RECONNECT"
) {
return null;
}
const recovery = parseCommittedRecovery(
captureDataSnapshot(snapshot.values.recovery),
captureRealtimeDataSnapshot(snapshot.values.recovery),
);
const terminalFailure = parseFailureResult(
snapshot.values.terminalResult,
@@ -1296,32 +1220,32 @@ function parseRecoveryDirectiveSnapshot(
}
function parseCommittedRecovery(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): RealtimeCommittedRecovery | null {
if (
!snapshot ||
!hasExactKeys(snapshot, [
!hasExactSnapshotKeys(snapshot, [
"checkpoint",
"kind",
"streamId",
]) ||
snapshot.values.kind !== "RECOVERY_COMMITTED" ||
!safeFrozen(snapshot.source)
!snapshot.frozen
) {
return null;
}
const checkpoint = captureDataSnapshot(
const checkpoint = captureRealtimeDataSnapshot(
snapshot.values.checkpoint,
);
if (
!checkpoint ||
!hasExactKeys(checkpoint, [
!hasExactSnapshotKeys(checkpoint, [
"lastAppliedSequence",
"recoveryMode",
"resumeCursor",
"streamEpoch",
]) ||
!safeFrozen(checkpoint.source)
!checkpoint.frozen
) {
return null;
}
@@ -1357,22 +1281,23 @@ function parseVoidResult(
}
function parseOutcomeSnapshot<Value>(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
parseValue: (candidate: unknown) => ParsedValue<Value> | null,
): ParsedOutcome<Value> | null {
if (
!snapshot ||
!hasOneExactKeySet(snapshot, [
!hasExactSnapshotKeys(
snapshot,
["result"],
["result", "serverNotBeforeMs"],
])
)
) {
return null;
}
const result = parseResult(snapshot.values.result, parseValue);
if (!result) return null;
if (result.ok) {
return hasExactKeys(snapshot, ["result"])
return hasExactSnapshotKeys(snapshot, ["result"])
? Object.freeze({
ok: true,
result: result.result,
@@ -1395,11 +1320,11 @@ function parseResult<Value>(
value: unknown,
parseValue: (candidate: unknown) => ParsedValue<Value> | null,
): ParsedResult<Value> | null {
const snapshot = captureDataSnapshot(value);
if (!snapshot || !safeFrozen(snapshot.source)) return null;
const snapshot = captureRealtimeDataSnapshot(value);
if (!snapshot || !snapshot.frozen) return null;
if (snapshot.values.ok === true) {
if (!hasExactKeys(snapshot, ["ok", "value"])) return null;
if (!hasExactSnapshotKeys(snapshot, ["ok", "value"])) return null;
const parsedValue = parseValue(snapshot.values.value);
const canonical = Object.freeze({
ok: true,
@@ -1430,29 +1355,29 @@ function parseResult<Value>(
function parseFailureResult(
value: unknown,
): FailureSnapshot | null {
return parseFailureResultSnapshot(captureDataSnapshot(value));
return parseFailureResultSnapshot(captureRealtimeDataSnapshot(value));
}
function parseFailureResultSnapshot(
snapshot: DataSnapshot | null,
snapshot: RealtimeDataSnapshot | null,
): FailureSnapshot | null {
if (
!snapshot ||
!hasExactKeys(snapshot, ["error", "ok"]) ||
!hasExactSnapshotKeys(snapshot, ["error", "ok"]) ||
snapshot.values.ok !== false ||
!safeFrozen(snapshot.source)
!snapshot.frozen
) {
return null;
}
const error = captureDataSnapshot(snapshot.values.error);
const error = captureRealtimeDataSnapshot(snapshot.values.error);
if (
!error ||
!hasExactKeys(error, [
!hasExactSnapshotKeys(error, [
"kind",
"operation",
"retryable",
]) ||
!safeFrozen(error.source)
!error.frozen
) {
return null;
}
@@ -1482,69 +1407,6 @@ function parseFailureResultSnapshot(
});
}
function captureDataSnapshot(value: unknown): DataSnapshot | null {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return null;
}
try {
const prototype = Object.getPrototypeOf(value);
if (
prototype !== Object.prototype &&
prototype !== null
) {
return null;
}
const descriptors = Object.getOwnPropertyDescriptors(value);
const ownKeys = Reflect.ownKeys(descriptors);
if (ownKeys.some((key) => typeof key !== "string")) {
return null;
}
const keys = (ownKeys as string[]).sort();
const values = Object.create(null) as Record<string, unknown>;
for (const key of keys) {
const descriptor = descriptors[key];
if (
!descriptor ||
!("value" in descriptor) ||
descriptor.enumerable !== true
) {
return null;
}
Object.defineProperty(values, key, {
configurable: false,
enumerable: true,
value: descriptor.value,
writable: false,
});
}
return Object.freeze({
source: value,
keys: Object.freeze(keys),
values: Object.freeze(values),
});
} catch {
return null;
}
}
function hasOneExactKeySet(
snapshot: DataSnapshot,
expected: readonly (readonly string[])[],
): boolean {
return expected.some((keys) => hasExactKeys(snapshot, keys));
}
function hasExactKeys(
snapshot: DataSnapshot,
expected: readonly string[],
): boolean {
const sorted = [...expected].sort();
return (
snapshot.keys.length === sorted.length &&
snapshot.keys.every((key, index) => key === sorted[index])
);
}
function parseNotBefore(
value: unknown,
): number | null | undefined {
@@ -1658,17 +1520,11 @@ function providerRetry(
);
}
function reconnectable(
failureSnapshot: FailureSnapshot,
serverNotBeforeMs: number | null,
): boolean {
if (
serverNotBeforeMs === null &&
(failureSnapshot.kind === "RATE_LIMITED" ||
failureSnapshot.kind === "PROVIDER_UNAVAILABLE")
) {
return false;
}
/**
* A transport that needs a server hint and did not get one already reports
* `retryable: false`, so a missing hint alone never ends the loop.
*/
function reconnectable(failureSnapshot: FailureSnapshot): boolean {
return (
failureSnapshot.retryable &&
RETRYABLE_KINDS.includes(
@@ -1725,14 +1581,6 @@ function safeSignalAborted(
}
}
function safeFrozen(value: object): boolean {
try {
return Object.isFrozen(value);
} catch {
return false;
}
}
function safelyAddAbortListener(
signal: AbortSignal | undefined,
listener: () => void,
+9 -38
View File
@@ -1,3 +1,5 @@
export { parseRetryAfterDelay } from "../platform/retry-after.ts";
export const REALTIME_RECONNECT_CEILINGS = Object.freeze({
drainTimeoutMs: 2_000,
maxAttempts: 10,
@@ -126,57 +128,26 @@ export function reconnectBudgetRemaining(
return Math.max(0, policy.maxElapsedMs - (nowMs - startedAtMs));
}
/**
* A connection earns a fresh retry budget only when it both proved itself
* with a valid heartbeat/event and stayed open for `stableOpenMs`. Either
* alone lets a server that sends one comment and drops keep the budget at
* zero forever.
*/
export function isReconnectAttemptResetEligible(input: Readonly<{
policy: ReconnectPolicy;
openedAtMs: number;
nowMs: number;
observedValidHeartbeatOrEvent: boolean;
}>): boolean {
if (input.observedValidHeartbeatOrEvent) return true;
return (
input.observedValidHeartbeatOrEvent &&
Number.isFinite(input.openedAtMs) &&
Number.isFinite(input.nowMs) &&
input.nowMs - input.openedAtMs >= input.policy.stableOpenMs
);
}
/**
* Parses the HTTP Retry-After delay without applying a runtime ceiling.
* Callers must reject a value that exceeds their remaining/max-delay budget.
*/
export function parseRetryAfterDelay(
value: string | null | undefined,
nowEpochMs: number,
): number | null {
if (
typeof value !== "string" ||
value.length === 0 ||
value.length > 128 ||
!Number.isFinite(nowEpochMs)
) {
return null;
}
const normalized = value.trim();
if (/^\d+$/u.test(normalized)) {
const seconds = Number(normalized);
return Number.isSafeInteger(seconds) &&
seconds <= Math.floor(Number.MAX_SAFE_INTEGER / 1_000)
? seconds * 1_000
: null;
}
if (
!/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/u.test(
normalized,
)
) {
return null;
}
const timestamp = Date.parse(normalized);
return Number.isFinite(timestamp)
? Math.max(0, timestamp - nowEpochMs)
: null;
}
function positiveInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}
+108 -7
View File
@@ -16,6 +16,7 @@ import {
isRealtimeOpaqueIdentifier,
isRealtimeResumeCursor,
} from "../../contracts/realtime-events.ts";
import { createAbortableOperation } from "../platform/abortable-operation.ts";
export type {
RealtimeFailure,
@@ -35,6 +36,8 @@ const FAILURE_KINDS = new Set<unknown>(REALTIME_FAILURE_KINDS);
const OPERATIONS = new Set<unknown>(REALTIME_OPERATIONS);
export type RealtimeDataSnapshot = Readonly<{
/** The object that was read; never read its properties again. */
source: object;
keys: readonly string[];
values: Readonly<Record<string, unknown>>;
frozen: boolean;
@@ -67,6 +70,100 @@ export function isRealtimeFailure(
return parseRealtimeFailure(value, true) !== null;
}
export type RealtimeRace<Value> =
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "REJECTED" }>
| Readonly<{ kind: "ABORTED" }>
| Readonly<{ kind: "TIMEOUT" }>
| Readonly<{ kind: "CLOCK_FAILED" }>;
const REJECTED = Object.freeze({ kind: "REJECTED" as const });
const ABORTED = Object.freeze({ kind: "ABORTED" as const });
const TIMEOUT = Object.freeze({ kind: "TIMEOUT" as const });
const CLOCK_FAILED = Object.freeze({ kind: "CLOCK_FAILED" as const });
/**
* Realtime's one abort/deadline race, on the kernel abortable operation.
* Settles with whichever comes first: the task's value or rejection (a
* synchronous throw counts as one), `signal` aborting, or `deadline`
* resolving. A deadline that throws or rejects on its own is CLOCK_FAILED.
* Nothing starts when `signal` is already aborted.
*
* The task gets the operation signal, which aborts with `signal`, at the
* deadline and once the race is over. The deadline is armed before the task
* starts, so it wins a tie, but the task always starts (a cancel must not be
* skipped because the clock broke).
*/
export function raceRealtimeTask<Value>(
task: (signal: AbortSignal) => Value | PromiseLike<Value>,
signal?: AbortSignal,
deadline?: (signal: AbortSignal) => PromiseLike<unknown>,
): Promise<RealtimeRace<Value>> {
if (signal?.aborted) return Promise.resolve(ABORTED);
const timer = new AbortController();
const operation = createAbortableOperation({
signal,
...(deadline && {
timeoutMs: 0,
setTimer: (fire: () => void) =>
Promise.resolve(deadline(timer.signal)).then(fire, () =>
operation.close(),
),
clearTimer: () => timer.abort(),
}),
});
let running: Promise<Value>;
try {
running = Promise.resolve(task(operation.signal));
} catch (error) {
running = Promise.reject(error);
}
const raced = operation.race(running);
// Registered after the race, so the outcome is claimed first.
void running.then(operation.close, operation.close);
return raced.then((outcome) =>
outcome.kind === "VALUE"
? outcome
: outcome.kind === "REJECTED"
? REJECTED
: outcome.terminal === "CALLER_ABORT"
? ABORTED
: outcome.terminal === "DEADLINE"
? TIMEOUT
: CLOCK_FAILED,
);
}
/**
* A `raceRealtimeTask` deadline on a host timer instead of the injected
* clock, for bounds that must hold even when the clock itself hangs.
*/
export function timerDeadline(
delayMs: number,
schedule: (callback: () => void, delayMs: number) => unknown = (
callback,
delay,
) => setTimeout(callback, delay),
cancel: (handle: unknown) => void = (handle) =>
clearTimeout(handle as ReturnType<typeof setTimeout>),
): (signal: AbortSignal) => Promise<void> {
return (signal) =>
new Promise((resolve) => {
const handle = schedule(resolve, delayMs);
signal.addEventListener(
"abort",
() => {
try {
cancel(handle);
} catch {
// A broken scheduler cannot change the race outcome.
}
},
{ once: true },
);
});
}
/**
* Captures an external result through own data descriptors exactly once and
* returns a new canonical value. Callers that need to use the validated fields
@@ -186,6 +283,7 @@ export function captureRealtimeDataSnapshot(
descriptor.writable === false;
}
return Object.freeze({
source: value,
keys: Object.freeze(keys),
values: Object.freeze(values),
frozen,
@@ -266,13 +364,16 @@ function parseRealtimeFailure(
});
}
function hasExactSnapshotKeys(
/** True when the snapshot's keys are exactly one of the given key sets. */
export function hasExactSnapshotKeys(
snapshot: RealtimeDataSnapshot,
expectedKeys: readonly string[],
...keySets: readonly (readonly string[])[]
): boolean {
const expected = [...expectedKeys].sort();
return (
snapshot.keys.length === expected.length &&
snapshot.keys.every((key, index) => key === expected[index])
);
return keySets.some((keySet) => {
const expected = [...keySet].sort();
return (
snapshot.keys.length === expected.length &&
snapshot.keys.every((key, index) => key === expected[index])
);
});
}
+53 -143
View File
@@ -16,6 +16,7 @@ import { parseRetryAfterDelay } from "../reconnect-policy.ts";
import {
isRealtimeResult,
isRealtimeTransportEventOutcome,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
} from "../result.ts";
@@ -100,6 +101,7 @@ const MAX_CONNECT_TIMEOUT_MS = 30_000;
const MAX_IDLE_TIMEOUT_MS = 120_000;
const MAX_CURSOR_BYTES = 1_024;
const READER_CANCEL_TIMEOUT_MS = 2_000;
const encoder = new TextEncoder();
export function createFetchSseConnection(
dependencies: FetchSseConnectionDependencies,
@@ -162,30 +164,36 @@ export function createFetchSseConnection(
once: true,
});
if (input.signal?.aborted) onCallerAbort();
const timed = <Value>(
task: () => Value | PromiseLike<Value>,
timeoutMs: number,
) =>
raceRealtimeTask(task, controller.signal, (signal) =>
clock.sleep(timeoutMs, signal),
);
try {
const request = timed(
Promise.resolve().then(() =>
fetcher(endpoint.href, {
method: "GET",
credentials: "same-origin",
redirect: "error",
cache: "no-store",
referrerPolicy: "no-referrer",
headers: {
Accept: "text/event-stream",
...(input.resumeCursor === null
? {}
: { "Last-Event-ID": input.resumeCursor }),
},
signal: controller.signal,
}),
),
const responseResult = await timed(
// The fetcher starts on the next microtask, like other collaborators.
() =>
Promise.resolve().then(() =>
fetcher(endpoint.href, {
method: "GET",
credentials: "same-origin",
redirect: "error",
cache: "no-store",
referrerPolicy: "no-referrer",
headers: {
Accept: "text/event-stream",
...(input.resumeCursor === null
? {}
: { "Last-Event-ID": input.resumeCursor }),
},
signal: controller.signal,
}),
),
connectTimeoutMs,
clock,
controller.signal,
);
const responseResult = await request;
if (responseResult.kind === "CLOCK_FAILED") {
controller.abort();
return failed("PROVIDER_UNAVAILABLE", "CONNECT", true);
@@ -241,23 +249,11 @@ export function createFetchSseConnection(
const reader = response.body.getReader();
activeReader = reader;
let retryHintMs: number | null = null;
if (input.onOpen) {
let opening: Promise<RealtimeResult<void>>;
try {
opening = Promise.resolve(input.onOpen(controller.signal));
} catch {
await cancelReader(reader, clock, controller);
return failed(
"PROVIDER_UNAVAILABLE",
"CONNECT",
false,
);
}
const onOpen = input.onOpen;
if (onOpen) {
const opened = await timed(
opening,
() => onOpen(controller.signal),
connectTimeoutMs,
clock,
controller.signal,
);
if (opened.kind !== "VALUE") {
await cancelReader(reader, clock, controller);
@@ -305,7 +301,7 @@ export function createFetchSseConnection(
(!item.hasExplicitId ||
!item.id ||
!isRealtimeResumeCursor(item.id) ||
new TextEncoder().encode(item.id).byteLength >
encoder.encode(item.id).byteLength >
maxCursorBytes)
) {
await cancelReader(reader, clock, controller);
@@ -318,22 +314,9 @@ export function createFetchSseConnection(
await cancelReader(reader, clock, controller);
return failed("PROTOCOL_MISMATCH", "DECODE", false);
}
let handler: Promise<
RealtimeResult<SseInboundEventOutcome>
>;
try {
handler = Promise.resolve(
input.onEvent(item, controller.signal),
);
} catch {
await cancelReader(reader, clock, controller);
return failed("APPLY_FAILED", "APPLY", false);
}
const handled = await timed(
handler,
() => input.onEvent(item, controller.signal),
idleTimeoutMs,
clock,
controller.signal,
);
if (handled.kind === "ABORTED") {
await cancelReader(reader, clock, controller);
@@ -384,10 +367,8 @@ export function createFetchSseConnection(
while (true) {
const readResult = await timed(
reader.read(),
() => reader.read(),
idleTimeoutMs,
clock,
controller.signal,
);
if (readResult.kind === "ABORTED") {
await cancelReader(reader, clock, controller);
@@ -434,13 +415,20 @@ export function createFetchSseConnection(
await cancelReader(reader, clock, controller);
return failed("MALFORMED_EVENT", "DECODE", false);
}
const parsed = parser.push(readResult.value.value);
if (!parsed.ok) {
await cancelReader(reader, clock, controller);
return parsed;
// Items past the parser's per-call cap arrive through drain().
for (
let parsed = parser.push(readResult.value.value);
;
parsed = parser.drain()
) {
if (!parsed.ok) {
await cancelReader(reader, clock, controller);
return parsed;
}
if (parsed.value.length === 0) break;
const dispatchFailure = await handleParserItems(parsed.value);
if (dispatchFailure) return dispatchFailure;
}
const dispatchFailure = await handleParserItems(parsed.value);
if (dispatchFailure) return dispatchFailure;
}
} catch {
return failed(
@@ -532,7 +520,7 @@ function validResumeCursor(
return (
typeof cursor === "string" &&
isRealtimeResumeCursor(cursor) &&
new TextEncoder().encode(cursor).byteLength <= maxCursorBytes
encoder.encode(cursor).byteLength <= maxCursorBytes
);
}
@@ -591,66 +579,6 @@ function responseFailure(
return failed("PROTOCOL_MISMATCH", "CONNECT", false);
}
type TimedResult<Value> =
| Readonly<{ kind: "VALUE"; value: Value }>
| Readonly<{ kind: "REJECTED" }>
| Readonly<{ kind: "ABORTED" }>
| Readonly<{ kind: "CLOCK_FAILED" }>
| Readonly<{ kind: "TIMEOUT" }>;
async function timed<Value>(
operation: Promise<Value>,
timeoutMs: number,
clock: ClockPort,
signal: AbortSignal,
): Promise<TimedResult<Value>> {
if (signal.aborted) {
return Object.freeze({ kind: "ABORTED" });
}
const timer = new AbortController();
let abortListener: (() => void) | undefined;
const operationResult = operation.then<
TimedResult<Value>,
TimedResult<Value>
>(
(value) => Object.freeze({ kind: "VALUE", value }),
() => Object.freeze({ kind: "REJECTED" }),
);
let timeoutResult: Promise<TimedResult<Value>>;
try {
timeoutResult = clock.sleep(timeoutMs, timer.signal).then<
TimedResult<Value>,
TimedResult<Value>
>(
() => Object.freeze({ kind: "TIMEOUT" }),
() =>
Object.freeze({
kind: timer.signal.aborted
? ("ABORTED" as const)
: ("CLOCK_FAILED" as const),
}),
);
} catch {
return Object.freeze({ kind: "CLOCK_FAILED" });
}
const abortedResult = new Promise<TimedResult<Value>>((resolve) => {
abortListener = () =>
resolve(Object.freeze({ kind: "ABORTED" }));
signal.addEventListener("abort", abortListener, { once: true });
if (signal.aborted) abortListener();
});
const result = await Promise.race([
operationResult,
timeoutResult,
abortedResult,
]);
timer.abort();
if (abortListener) {
signal.removeEventListener("abort", abortListener);
}
return result;
}
function readClockNow(clock: ClockPort): number | null {
try {
const value = clock.now();
@@ -666,29 +594,11 @@ async function cancelReader(
generation?: AbortController,
): Promise<void> {
generation?.abort();
let cancellation: Promise<void>;
try {
cancellation = Promise.resolve(reader.cancel()).then(
() => undefined,
() => undefined,
);
} catch {
return;
}
const timeout = new AbortController();
let timeoutPromise: Promise<void>;
try {
timeoutPromise = clock
.sleep(READER_CANCEL_TIMEOUT_MS, timeout.signal)
.then(
() => undefined,
() => undefined,
);
} catch {
timeoutPromise = Promise.resolve();
}
await Promise.race([cancellation, timeoutPromise]);
timeout.abort();
await raceRealtimeTask(
() => reader.cancel(),
undefined,
(signal) => clock.sleep(READER_CANCEL_TIMEOUT_MS, signal),
);
}
function safelyNotify(
+158 -77
View File
@@ -13,6 +13,11 @@ export const SSE_PARSER_CEILINGS = Object.freeze({
maxRetryMs: 60_000,
});
const NO_ITEMS: readonly SseParserItem[] = Object.freeze([]);
const COMMENT_ITEMS: readonly SseParserItem[] = Object.freeze([
Object.freeze({ kind: "COMMENT" as const }),
]);
export type SseParserLimits = Readonly<{
maxLineBytes: number;
maxEventBytes: number;
@@ -45,7 +50,13 @@ export type SseParserFinish = Readonly<{
}>;
export type IncrementalSseParser = Readonly<{
/**
* Returns at most `maxItemsPerChunk` items. Bytes past that cap are kept
* and must be taken with `drain()` until it returns no items; pushing or
* finishing before then fails with QUEUE_OVERFLOW.
*/
push(chunk: Uint8Array): RealtimeResult<readonly SseParserItem[]>;
drain(): RealtimeResult<readonly SseParserItem[]>;
finish(): RealtimeResult<SseParserFinish>;
}>;
@@ -53,17 +64,23 @@ export function createIncrementalSseParser(
limits: Partial<SseParserLimits> = {},
): IncrementalSseParser {
const resolved = resolveLimits(limits);
// The decoder keeps U+FEFF; `append` drops the one leading BOM the stream
// grammar allows, so a BOM at the start of a later line stays text.
const decoder = new TextDecoder("utf-8", {
fatal: true,
ignoreBOM: false,
ignoreBOM: true,
});
const encoder = new TextEncoder();
let state: "OPEN" | "FAILED" | "FINISHED" = "OPEN";
let atStart = true;
let pendingCarriageReturn = false;
let atStreamStart = true;
let line = "";
// UTF-8 bytes of the decoded `line`. The bytes of a character the decoder
// still holds across reads (`held` of `heldNeed`) count once it completes.
let lineBytes = 0;
let held = 0;
let heldNeed = 0;
let undrained: Uint8Array | null = null;
let blockBytes = 0;
let dataLines: string[] = [];
let eventType = "";
@@ -82,35 +99,36 @@ export function createIncrementalSseParser(
if (chunk.byteLength > resolved.maxChunkBytes) {
return fail("EVENT_TOO_LARGE");
}
let text: string;
try {
text = decoder.decode(chunk, { stream: true });
} catch {
return fail("MALFORMED_EVENT");
if (undrained !== null) return fail("QUEUE_OVERFLOW");
return consumeBytes(chunk);
}
function drain(): RealtimeResult<readonly SseParserItem[]> {
if (state !== "OPEN") {
return realtimeFailure("CLOSED", "DECODE");
}
return consumeText(text);
const bytes = undrained ?? new Uint8Array();
undrained = null;
return consumeBytes(bytes);
}
function finish(): RealtimeResult<SseParserFinish> {
if (state !== "OPEN") {
return realtimeFailure("CLOSED", "DECODE");
}
let tail: string;
if (undrained !== null) return fail("QUEUE_OVERFLOW");
// Throws when the stream ends inside a character.
try {
tail = decoder.decode();
decoder.decode();
} catch {
return fail("MALFORMED_EVENT");
}
const consumed = consumeText(tail);
if (!consumed.ok) return consumed;
const items = [...consumed.value];
let items = NO_ITEMS;
if (pendingCarriageReturn) {
pendingCarriageReturn = false;
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
items = processed.value;
}
const incompleteEventDiscarded =
lineBytes > 0 ||
@@ -124,60 +142,132 @@ export function createIncrementalSseParser(
state = "FINISHED";
return success(
Object.freeze({
items: Object.freeze(items),
items,
incompleteEventDiscarded,
}),
);
}
function consumeText(
text: string,
/**
* Finds CR/LF on the raw bytes, so a line's byte length is known without
* re-encoding, and decodes each line once. CR and LF bytes never occur
* inside a multibyte UTF-8 character. Byte counts only grow within a line,
* so checking the limits per segment fails exactly where a per-character
* check would. Stops at `maxItemsPerChunk` items and keeps the rest for
* `drain()`.
*/
function consumeBytes(
bytes: Uint8Array,
): RealtimeResult<readonly SseParserItem[]> {
const items: SseParserItem[] = [];
for (const character of text) {
if (atStart) {
atStart = false;
if (character === "\uFEFF") continue;
}
let index = 0;
let nextLineFeed = -1;
let nextCarriageReturn = -1;
while (index < bytes.length) {
// Only part of a character is left: the decoder holds it, and a
// pending CR or the item cap waits for the character to complete.
const rest = bytes.length - index;
if (rest < 4 && heldAfter(bytes.subarray(index)) === held + rest) {
const appended = append(bytes.subarray(index), true);
if (!appended.ok) return appended;
break;
}
if (items.length >= resolved.maxItemsPerChunk) {
// A copy, so a caller reusing its buffer cannot change kept bytes.
undrained = bytes.slice(index);
break;
}
if (pendingCarriageReturn) {
pendingCarriageReturn = false;
const processed = processLine(character === "\n" ? 2 : 1);
const lineFeed = bytes[index] === 0x0a;
const processed = processLine(lineFeed ? 2 : 1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
if (character === "\n") continue;
items.push(...processed.value);
if (lineFeed) index += 1;
continue;
}
if (character === "\r") {
if (nextLineFeed < index) {
nextLineFeed = indexOrEnd(bytes, 0x0a, index);
}
if (nextCarriageReturn < index) {
nextCarriageReturn = indexOrEnd(bytes, 0x0d, index);
}
const lineBreak = Math.min(nextLineFeed, nextCarriageReturn);
const appended = append(
bytes.subarray(index, lineBreak),
lineBreak === bytes.length,
);
if (!appended.ok) return appended;
if (lineBreak === bytes.length) break;
index = lineBreak + 1;
if (bytes[lineBreak] === 0x0d) {
pendingCarriageReturn = true;
continue;
}
if (character === "\n") {
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
continue;
}
line += character;
lineBytes += encoder.encode(character).byteLength;
if (lineBytes > resolved.maxLineBytes) {
return fail("EVENT_TOO_LARGE");
}
if (
lineBytes + blockBytes >
resolved.maxIncompleteBufferBytes
) {
return fail("EVENT_TOO_LARGE");
}
const processed = processLine(1);
if (!processed.ok) return processed;
items.push(...processed.value);
}
return success(Object.freeze(items));
}
/**
* Decodes one line segment. `open` means the line continues in a later
* read, so the decoder may hold the bytes of an unfinished character.
*/
function append(
segment: Uint8Array,
open: boolean,
): RealtimeResult<null> {
let text = "";
if (segment.length > 0 || held > 0) {
try {
text = decoder.decode(segment, { stream: open });
} catch {
return fail("MALFORMED_EVENT");
}
}
const heldBefore = held;
held = open ? heldAfter(segment) : 0;
lineBytes += heldBefore + segment.length - held;
if (atStreamStart && (text.length > 0 || !open)) {
atStreamStart = false;
if (text.charCodeAt(0) === 0xfeff) {
text = text.slice(1);
lineBytes -= 3;
}
}
line += text;
if (
lineBytes > resolved.maxLineBytes ||
lineBytes + blockBytes > resolved.maxIncompleteBufferBytes
) {
return fail("EVENT_TOO_LARGE");
}
return success(null);
}
/**
* Bytes of the unfinished character at the end of a segment the decoder
* accepted in stream mode, so they form a valid UTF-8 prefix.
*/
function heldAfter(segment: Uint8Array): number {
const end = segment.length;
for (let index = end - 1; index >= 0 && index >= end - 4; index -= 1) {
const byte = segment[index]!;
if (byte < 0x80) return 0;
if (byte >= 0xc0) {
heldNeed = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : 2;
return end - index < heldNeed ? end - index : 0;
}
}
// Only continuation bytes: they extend the character already held.
return held + end < heldNeed ? held + end : 0;
}
function processLine(
terminatorBytes: number,
): RealtimeResult<readonly SseParserItem[]> {
@@ -203,13 +293,7 @@ export function createIncrementalSseParser(
return success(Object.freeze(items));
}
if (currentLine.startsWith(":")) {
return success(
Object.freeze([
Object.freeze({ kind: "COMMENT" as const }),
]),
);
}
if (currentLine.startsWith(":")) return success(COMMENT_ITEMS);
blockBytes += currentLineBytes + terminatorBytes;
if (blockBytes > resolved.maxEventBytes) {
@@ -230,18 +314,18 @@ export function createIncrementalSseParser(
if (field === "data") {
dataLines.push(value);
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "event") {
eventType = value;
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "id") {
if (!value.includes("\0")) {
lastEventId = value;
hasExplicitId = true;
}
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "retry" && /^\d+$/u.test(value)) {
const retryMs = Number(value);
@@ -256,7 +340,7 @@ export function createIncrementalSseParser(
);
}
}
return success(Object.freeze([]));
return success(NO_ITEMS);
}
function clearBlock(): void {
@@ -275,25 +359,13 @@ export function createIncrementalSseParser(
state = "FAILED";
line = "";
lineBytes = 0;
held = 0;
undrained = null;
clearBlock();
return realtimeFailure(kind, "DECODE");
}
function appendItems(
target: SseParserItem[],
additions: readonly SseParserItem[],
): boolean {
if (
target.length + additions.length >
resolved.maxItemsPerChunk
) {
return false;
}
target.push(...additions);
return true;
}
return Object.freeze({ push, finish });
return Object.freeze({ push, drain, finish });
}
function resolveLimits(
@@ -341,6 +413,15 @@ function success<Value>(value: Value): RealtimeResult<Value> {
return realtimeSuccess(value);
}
function indexOrEnd(
bytes: Uint8Array,
byte: number,
from: number,
): number {
const index = bytes.indexOf(byte, from);
return index === -1 ? bytes.length : index;
}
function positiveInteger(value: number): boolean {
return Number.isSafeInteger(value) && value > 0;
}

Some files were not shown because too many files have changed in this diff Show More