refactor(browser-transfer): split validation and dependency snapshots out of the upload runtime (Q-6.1-10)

resumable-upload-runtime.ts carried the upload flow, retry/deadline, the
server response decoders and eight dependency snapshot wrappers in one
2.3k-line file. Moved without changing behavior:
- runtime-dependencies.ts: the dependency types, snapshotDependencies and
  its per-collaborator wrappers, safeNow/safeRandom and the default sleep.
- upload-response-validation.ts: validateSession, validateStatus,
  validatePartCapability, the receipt check and the small shared helpers
  (exactKeys, sameFingerprint, snapshotReceipts).
The runtime re-exports ResumableUploadRuntimeDependencies, so the public
surface is unchanged. The default sleep now waits on the kernel
createAbortableOperation instead of its own timer/listener pair, so the
moved file does not add a hand-rolled abort offender (ratchet stays 20/21).
INVENTORY and the detail review list the two files.

Verified: new characterization suite resumable-upload-runtime-contract
(invalid collaborators throw at composition, methods captured at
composition, frozen observer copies, throwing clock, default sleep retry
and abort, session/capability/status/receipt rejections) written and green
before the move, still green after + existing runtime suites + all gates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:33:05 +09:00
co-authored by Claude Opus 5.5
parent 1997ce4bbe
commit 7e610d1d05
6 changed files with 1177 additions and 749 deletions
+3 -1
View File
@@ -46,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` |
+102 -100
View File
@@ -47,105 +47,107 @@
| 37 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) |
| 38 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) |
| 39 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 45 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 46 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 47 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 48 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 49 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 50 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 51 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 52 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 82 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 83 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 99 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 100 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 106 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 107 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 126 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 127 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 128 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 129 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 130 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 40 | `src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts` | [Browser transfer](./04-browser-transfer.md) |
| 41 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) |
| 42 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) |
| 43 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) |
| 44 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) |
| 45 | `src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts` | [Browser transfer](./04-browser-transfer.md) |
| 46 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 47 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 48 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 49 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) |
| 50 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) |
| 51 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) |
| 52 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) |
| 53 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) |
| 54 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) |
| 55 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) |
| 56 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) |
| 57 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) |
| 58 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) |
| 59 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) |
| 60 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) |
| 61 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 62 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) |
| 63 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) |
| 64 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) |
| 65 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) |
| 66 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) |
| 67 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) |
| 68 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) |
| 69 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) |
| 70 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) |
| 71 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) |
| 72 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) |
| 73 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) |
| 74 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) |
| 75 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) |
| 76 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) |
| 77 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) |
| 78 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 79 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) |
| 80 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) |
| 81 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) |
| 82 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) |
| 83 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 84 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 85 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 86 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 87 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 88 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 89 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 90 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 91 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 92 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 93 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 94 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 95 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 96 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 97 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 98 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 99 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) |
| 100 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 101 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 102 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 103 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 104 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 105 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 106 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 107 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 108 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 109 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 110 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 111 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 112 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 128 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 129 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 130 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 131 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 132 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 133 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 134 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **138/138**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **140/140**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
@@ -1,21 +1,15 @@
import type {
ActiveUploadStatus,
QuarantinedUpload,
ResumableUploadCheckpoint,
ResumableUploadCheckpointStore,
ResumableUploadControlPlane,
ResumableUploadPort,
ResumableUploadRequest,
UploadAbortOutcome,
UploadFileFingerprint,
UploadPartCapability,
UploadPartDescriptor,
UploadPartExecutor,
UploadPartReceipt,
UploadProviderFailure,
UploadProviderResult,
UploadSession,
UploadSessionStatus,
} from "../../../application/ports/browser-transfer/resumable-upload.ts";
import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts";
import type {
@@ -33,14 +27,12 @@ import {
import { createAbortableOperation } from "../../platform/abortable-operation.ts";
import {
isResumableUploadCheckpoint,
isUploadFileFingerprint,
isUploadPartReceipt,
MEDIA_TYPE,
SAFE_OPAQUE_ID,
SAFE_REGISTRY_ID,
SAFE_UPLOAD_KEY,
samePart,
SHA256_HEX,
} from "./checkpoint-schema.ts";
import {
buildUploadPartManifest,
@@ -50,20 +42,29 @@ import {
findManifestPart,
iterateUploadParts,
readAndVerifyRangePart,
snapshotUploadCrypto,
snapshotUploadSource,
verifyPartAgainstManifest,
verifyUploadPartBytes,
type UploadCrypto,
type UploadPartManifest,
type UploadSourceSnapshot,
} from "./upload-byte-source.ts";
import type { ResumableUploadRuntimePolicy } from "./runtime-policy.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";
safeNow,
safeRandom,
snapshotDependencies,
type ResumableUploadRuntimeDependencies,
type RuntimeDependencies,
} from "./runtime-dependencies.ts";
import {
exactKeys,
sameFingerprint,
snapshotReceipts,
validatePartCapability,
validateSession,
validateStatus,
} from "./upload-response-validation.ts";
export type { ResumableUploadRuntimeDependencies } from "./runtime-dependencies.ts";
export type ResumableUploadRuntime = ResumableUploadPort &
Readonly<{
@@ -87,24 +88,6 @@ export type ResumableUploadRuntime = ResumableUploadPort &
lifecycle(): "OPEN" | "CLOSING" | "CLOSED";
}>;
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;
}>;
type UploadRequestSnapshot = Readonly<{
uploadKey: string;
purpose: string;
@@ -114,27 +97,6 @@ type UploadRequestSnapshot = Readonly<{
onProgress?: (progress: TransferProgress) => void;
}>;
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>>;
}>;
type ActiveResolution =
| Readonly<{
kind: "ACTIVE";
@@ -1444,245 +1406,6 @@ function canRetry(
);
}
function validatePartCapability<Capability>(
value: UploadPartCapability<Capability>,
checkpoint: ResumableUploadCheckpoint,
uploadBindingSha256: string,
dependencies: RuntimeDependencies<Capability>,
): BrowserDataResult<UploadPartCapability<Capability>> {
if (
!exactKeys(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);
}
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 (!exactKeys(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 (!exactKeys(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) ||
!exactKeys(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,
}),
);
}
function validateSession<Capability>(
value: UploadSession,
requestBindingSha256: string,
fingerprint: UploadFileFingerprint,
dependencies: RuntimeDependencies<Capability>,
requireActiveExpiry = true,
): BrowserDataResult<UploadSession> {
if (
!exactKeys(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));
}
function checkpointFrom(
input:
| Readonly<{
@@ -1787,268 +1510,6 @@ function snapshotRequest(
});
}
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>);
},
});
}
function normalizeProviderFailure(
input: UploadProviderFailure,
operation: BrowserDataOperation,
@@ -2129,77 +1590,6 @@ function remapResult<Value>(
});
}
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",
});
}
}
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",
});
}
}
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
);
}
function snapshotReceipts(
parts: readonly UploadPartReceipt[],
): readonly UploadPartReceipt[] {
return Object.freeze(
parts.map((part) => Object.freeze({ ...part })),
);
}
function exactKeys(
value: unknown,
keys: readonly string[],
): value is Record<string, unknown> {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return false;
}
const actual = Object.keys(value).sort();
const expected = [...keys].sort();
return (
actual.length === expected.length &&
actual.every((key, index) => key === expected[index])
);
}
function reportProgress(
request: UploadRequestSnapshot,
phase: TransferProgress["phase"],
@@ -2305,24 +1695,3 @@ function isAbortSignal(value: unknown): value is AbortSignal {
);
}
async function abortableSleep(
delayMs: number,
signal: AbortSignal,
): Promise<void> {
if (signal.aborted) {
throw new DOMException("The operation was aborted.", "AbortError");
}
await new Promise<void>((resolve, reject) => {
const timer = setTimeout(finish, delayMs);
function finish() {
signal.removeEventListener("abort", abort);
resolve();
}
function abort() {
clearTimeout(timer);
signal.removeEventListener("abort", abort);
reject(new DOMException("The operation was aborted.", "AbortError"));
}
signal.addEventListener("abort", abort, { once: true });
});
}
@@ -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");
}
}
@@ -0,0 +1,310 @@
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 {
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 (
!exactKeys(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 (!exactKeys(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 (!exactKeys(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) ||
!exactKeys(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 (
!exactKeys(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 })),
);
}
export function exactKeys(
value: unknown,
keys: readonly string[],
): value is Record<string, unknown> {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return false;
}
const actual = Object.keys(value).sort();
const expected = [...keys].sort();
return (
actual.length === expected.length &&
actual.every((key, index) => key === expected[index])
);
}
@@ -0,0 +1,367 @@
import { describe, expect, it } from "vitest";
import type { BrowserDataObservation } from "../../src/application/ports/browser-file-storage/shared.ts";
import {
browserDataFailure,
browserDataSuccess,
} from "../../src/adapters/browser-file-storage/result.ts";
import {
createResumableUploadRuntime,
type ResumableUploadRuntimeDependencies,
} from "../../src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts";
import {
activeSignal,
createControlHarness,
executorFor,
MemoryCheckpointStore,
noContentionLock,
rangeSource,
runtimePolicy,
type ControlHarness,
type TestCapability,
} from "./resumable-upload-runtime-fixture.ts";
/**
* Q-6.1-10. Characterization of the two blocks moved out of the runtime file:
* the dependency snapshot wrappers and the server response validators. The
* other runtime suites reach them only on their happy paths.
*/
function dependencies(
harness: ControlHarness,
overrides: Partial<ResumableUploadRuntimeDependencies<TestCapability>> = {},
): ResumableUploadRuntimeDependencies<TestCapability> {
return {
controlPlane: harness.control,
partExecutor: executorFor(harness),
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy(),
now: () => 1_000,
random: () => 0,
sleep: async () => {},
...overrides,
};
}
async function upload(
input: ResumableUploadRuntimeDependencies<TestCapability>,
) {
return await createResumableUploadRuntime(input).upload({
uploadKey: "upload_key_contract",
purpose: "attachment",
mediaType: "application/octet-stream",
source: rangeSource(new Uint8Array([1, 2, 3, 4, 5])),
signal: activeSignal,
});
}
describe("resumable upload runtime dependency snapshots", () => {
it("rejects an invalid collaborator at composition", () => {
const harness = createControlHarness();
const invalid: Partial<
ResumableUploadRuntimeDependencies<TestCapability>
>[] = [
{
controlPlane: {
...harness.control,
abort: undefined,
} as unknown as typeof harness.control,
},
{ partExecutor: {} as never },
{
checkpoints: {
read: async () => browserDataSuccess(null),
} as never,
},
{
checkpoints: Object.assign(new MemoryCheckpointStore(), {
removeUnreadable: "not a function",
}) as never,
},
{ mutationLock: {} as never },
{
crossContextCancellation: {
publish: () => true,
subscribe: () => () => {},
} as never,
},
{
crossContextCancellation: {
publish: () => true,
subscribe: () => "not a release",
close: () => {},
} as never,
},
{ observer: {} as never },
{ now: 1_000 as never },
{ random: "0" as never },
{ sleep: 1 as never },
];
for (const override of invalid) {
expect(
() => createResumableUploadRuntime(dependencies(harness, override)),
Object.keys(override).join(","),
).toThrow(TypeError);
}
});
it("captures collaborator methods once at composition", async () => {
const harness = createControlHarness();
const runtime = createResumableUploadRuntime(dependencies(harness));
harness.control.createSession = async () => {
throw new Error("replaced after composition");
};
await expect(
runtime.upload({
uploadKey: "upload_key_contract",
purpose: "attachment",
mediaType: "application/octet-stream",
source: rangeSource(new Uint8Array([1, 2, 3, 4, 5])),
signal: activeSignal,
}),
).resolves.toMatchObject({
ok: true,
value: { state: "QUARANTINED" },
});
});
it("hands the observer frozen copies and survives a throwing one", async () => {
const observations: BrowserDataObservation[] = [];
const harness = createControlHarness();
await expect(
upload(
dependencies(harness, {
observer: {
record(observation) {
observations.push(observation);
throw new Error("observer failure");
},
},
}),
),
).resolves.toMatchObject({ ok: true });
expect(observations.length).toBeGreaterThan(0);
expect(observations.every((value) => Object.isFrozen(value))).toBe(true);
});
it("sleeps between retries with the default timer when none is injected", async () => {
const harness = createControlHarness();
const create = harness.control.createSession.bind(harness.control);
let creates = 0;
harness.control.createSession = async (input) => {
creates += 1;
return creates === 1
? browserDataFailure("UNAVAILABLE", "UPLOAD_SESSION", {
retryable: true,
recovery: "RESUME",
})
: await create(input);
};
const { sleep: _injected, ...withoutSleep } = dependencies(harness);
await expect(upload(withoutSleep)).resolves.toMatchObject({
ok: true,
value: { state: "QUARANTINED" },
});
expect(creates).toBe(2);
});
it("ends the default retry sleep when the caller aborts", async () => {
const harness = createControlHarness();
let failed: () => void = () => {};
const firstFailure = new Promise<void>((resolve) => {
failed = resolve;
});
harness.control.createSession = async () => {
failed();
return browserDataFailure("UNAVAILABLE", "UPLOAD_SESSION", {
retryable: true,
recovery: "RESUME",
});
};
const { sleep: _injected, ...withoutSleep } = dependencies(harness, {
policy: runtimePolicy({
retryBaseDelayMs: 60_000,
retryMaxDelayMs: 60_000,
}),
});
const controller = new AbortController();
const uploading = createResumableUploadRuntime(withoutSleep).upload({
uploadKey: "upload_key_contract",
purpose: "attachment",
mediaType: "application/octet-stream",
source: rangeSource(new Uint8Array([1, 2, 3, 4, 5])),
signal: controller.signal,
});
await firstFailure;
controller.abort();
await expect(uploading).resolves.toMatchObject({
ok: false,
error: { code: "ABORTED" },
});
});
it("treats a throwing clock as UNAVAILABLE", async () => {
const harness = createControlHarness();
await expect(
upload(
dependencies(harness, {
now: () => {
throw new Error("clock");
},
}),
),
).resolves.toMatchObject({
ok: false,
error: { code: "UNAVAILABLE", operation: "UPLOAD_SESSION" },
});
});
});
describe("resumable upload runtime server response validation", () => {
it("rejects a created session with an unknown field", async () => {
const harness = createControlHarness();
const create = harness.control.createSession.bind(harness.control);
harness.control.createSession = async (input) => {
const created = await create(input);
return created.ok
? browserDataSuccess({
...created.value,
uploadUrl: "https://objects.invalid/secret",
})
: created;
};
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: {
code: "INTEGRITY_FAILED",
operation: "UPLOAD_SESSION",
recovery: "RECONCILE",
},
});
});
it("rejects a session concurrency above the local policy", async () => {
const harness = createControlHarness({ serverMaxConcurrency: 4 });
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_SESSION" },
});
});
it("restarts a session whose lifetime exceeds the policy ceiling", async () => {
const harness = createControlHarness();
const create = harness.control.createSession.bind(harness.control);
harness.control.createSession = async (input) => {
const created = await create(input);
return created.ok
? browserDataSuccess({
...created.value,
expiresAtEpochMs: 1_000 + 20_000,
})
: created;
};
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: {
code: "EXPIRED_RESOURCE",
operation: "UPLOAD_SESSION",
recovery: "RESTART",
},
});
});
it("rejects a part capability with an unknown field", async () => {
const harness = createControlHarness({
issueCapability: (input) =>
browserDataSuccess({
capability: Object.freeze({ id: "cap" }),
uploadBindingSha256: input.uploadBindingSha256,
expiresAtEpochMs: 1_000 + 4_000,
href: "https://objects.invalid/secret",
} as never),
});
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: {
code: "CORRUPT_DATA",
operation: "UPLOAD_PART",
recovery: "REISSUE_CAPABILITY",
},
});
});
it("rejects a part capability that outlives its session", async () => {
const harness = createControlHarness({
issueCapability: (input) =>
browserDataSuccess({
capability: Object.freeze({ id: "cap" }),
uploadBindingSha256: input.uploadBindingSha256,
expiresAtEpochMs: 1_000 + 5_000 + 1,
}),
});
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: {
code: "POLICY_REJECTED",
operation: "UPLOAD_PART",
recovery: "REISSUE_CAPABILITY",
},
});
});
it("rejects a status in a state outside the protocol", async () => {
const harness = createControlHarness();
harness.control.getStatus = async (input) =>
browserDataSuccess({
state: "PAUSED",
protocol: input.protocol,
sessionId: input.sessionId,
requestBindingSha256: input.requestBindingSha256,
} as never);
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: {
code: "INTEGRITY_FAILED",
operation: "UPLOAD_RECONCILE",
recovery: "RECONCILE",
},
});
});
it("rejects server receipts that are out of part order", async () => {
const harness = createControlHarness({
statusParts: (_session, accepted) =>
[...accepted.values()].sort(
(left, right) => right.partNumber - left.partNumber,
),
});
// The first status has no parts; once parts are accepted the reversed
// list is what the final reconcile reads.
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: false,
error: { code: "INTEGRITY_FAILED", operation: "UPLOAD_RECONCILE" },
});
});
it("treats a definitive not-found status as terminal and restarts", async () => {
const harness = createControlHarness({
sessionId: (index) => `session_0${index}`,
});
let statusCalls = 0;
const status = harness.control.getStatus.bind(harness.control);
harness.control.getStatus = async (input) => {
statusCalls += 1;
return statusCalls === 1
? browserDataFailure("NOT_FOUND", "UPLOAD_RECONCILE")
: await status(input);
};
await expect(upload(dependencies(harness))).resolves.toMatchObject({
ok: true,
value: { state: "QUARANTINED", replayed: false },
});
expect(harness.getSession()?.sessionId).toBe("session_02");
});
});