From 7e610d1d05ef73ac0f1db5fb4d8c350c53987285 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:27:51 +0900 Subject: [PATCH] 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 --- docs/reviews/adapters/04-browser-transfer.md | 4 +- docs/reviews/adapters/INVENTORY.md | 202 +++--- .../resumable-upload-runtime.ts | 665 +----------------- .../resumable-upload/runtime-dependencies.ts | 378 ++++++++++ .../upload-response-validation.ts | 310 ++++++++ .../resumable-upload-runtime-contract.test.ts | 367 ++++++++++ 6 files changed, 1177 insertions(+), 749 deletions(-) create mode 100644 src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts create mode 100644 src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts create mode 100644 tests/unit/resumable-upload-runtime-contract.test.ts diff --git a/docs/reviews/adapters/04-browser-transfer.md b/docs/reviews/adapters/04-browser-transfer.md index 03278401..6ac58ca4 100644 --- a/docs/reviews/adapters/04-browser-transfer.md +++ b/docs/reviews/adapters/04-browser-transfer.md @@ -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` | diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index deceac2b..a92ead9f 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -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를 같은 변경에서 갱신한다. diff --git a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts index 935672b0..bf8dfe87 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -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 = Readonly<{ - controlPlane: ResumableUploadControlPlane; - partExecutor: UploadPartExecutor; - 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; - now?: () => number; - random?: () => number; - sleep?: (delayMs: number, signal: AbortSignal) => Promise; - observer?: BrowserDataObserver; -}>; - type UploadRequestSnapshot = Readonly<{ uploadKey: string; purpose: string; @@ -114,27 +97,6 @@ type UploadRequestSnapshot = Readonly<{ onProgress?: (progress: TransferProgress) => void; }>; -type RuntimeDependencies = Readonly<{ - controlPlane: ResumableUploadControlPlane; - partExecutor: UploadPartExecutor; - checkpoints: ResumableUploadCheckpointStore; - mutationLock: UploadMutationLock; - crossContextCancellation?: UploadCancellationChannel; - crypto: UploadCrypto; - policy: ResumableUploadRuntimePolicy; - now(): number; - random(): number; - sleep(delayMs: number, signal: AbortSignal): Promise; - 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>; -}>; - type ActiveResolution = | Readonly<{ kind: "ACTIVE"; @@ -1444,245 +1406,6 @@ function canRetry( ); } -function validatePartCapability( - value: UploadPartCapability, - checkpoint: ResumableUploadCheckpoint, - uploadBindingSha256: string, - dependencies: RuntimeDependencies, -): BrowserDataResult> { - 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( - value: UploadSessionStatus, - checkpoint: ResumableUploadCheckpoint, - manifest: UploadPartManifest, - dependencies: RuntimeDependencies, -): BrowserDataResult { - 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( - value: UploadSession, - requestBindingSha256: string, - fingerprint: UploadFileFingerprint, - dependencies: RuntimeDependencies, - requireActiveExpiry = true, -): BrowserDataResult { - 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 { - 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( - input: ResumableUploadRuntimeDependencies, - physicalTasks: Set>, -): RuntimeDependencies { - 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[0], - ) { - record.call(value, Object.freeze({ ...observation })); - }, - }); -} - -function snapshotControlPlane( - value: ResumableUploadControlPlane, -): ResumableUploadControlPlane { - 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 = { - async createSession( - input: Parameters< - ResumableUploadControlPlane["createSession"] - >[0], - ) { - return await createSession.call(value, input); - }, - async getStatus( - input: Parameters< - ResumableUploadControlPlane["getStatus"] - >[0], - ) { - return await getStatus.call(value, input); - }, - async issuePartCapability( - input: Parameters< - ResumableUploadControlPlane["issuePartCapability"] - >[0], - ) { - return await issuePartCapability.call(value, input); - }, - async complete( - input: Parameters< - ResumableUploadControlPlane["complete"] - >[0], - ) { - return await complete.call(value, input); - }, - async abort( - input: Parameters< - ResumableUploadControlPlane["abort"] - >[0], - ) { - return await abort.call(value, input); - }, - }; - return Object.freeze(snapshot); -} - -function snapshotPartExecutor( - value: UploadPartExecutor, -): UploadPartExecutor { - const uploadPart = value?.uploadPart; - if (typeof uploadPart !== "function") { - throw new TypeError("Upload part executor is invalid."); - } - const snapshot: UploadPartExecutor = { - async uploadPart( - input: Parameters["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[0], - ) { - return await remove.call(value, input); - }, - ...(removeUnreadable - ? { - async removeUnreadable( - input: Parameters[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( - uploadKey: string, - signal: AbortSignal, - task: () => Promise, - ): Promise { - return await (run.call( - value, - uploadKey, - signal, - task, - ) as Promise); - }, - }); -} - function normalizeProviderFailure( input: UploadProviderFailure, operation: BrowserDataOperation, @@ -2129,77 +1590,6 @@ function remapResult( }); } -function safeNow( - dependencies: RuntimeDependencies, - operation: BrowserDataOperation, -): BrowserDataResult { - 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( - dependencies: RuntimeDependencies, -): BrowserDataResult { - 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 { - 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 { - if (signal.aborted) { - throw new DOMException("The operation was aborted.", "AbortError"); - } - await new Promise((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 }); - }); -} diff --git a/src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts b/src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts new file mode 100644 index 00000000..5b1537e5 --- /dev/null +++ b/src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts @@ -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 = Readonly<{ + controlPlane: ResumableUploadControlPlane; + partExecutor: UploadPartExecutor; + 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; + now?: () => number; + random?: () => number; + sleep?: (delayMs: number, signal: AbortSignal) => Promise; + observer?: BrowserDataObserver; +}>; + +export type RuntimeDependencies = Readonly<{ + controlPlane: ResumableUploadControlPlane; + partExecutor: UploadPartExecutor; + checkpoints: ResumableUploadCheckpointStore; + mutationLock: UploadMutationLock; + crossContextCancellation?: UploadCancellationChannel; + crypto: UploadCrypto; + policy: ResumableUploadRuntimePolicy; + now(): number; + random(): number; + sleep(delayMs: number, signal: AbortSignal): Promise; + 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>; +}>; + +export function snapshotDependencies( + input: ResumableUploadRuntimeDependencies, + physicalTasks: Set>, +): RuntimeDependencies { + 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[0], + ) { + record.call(value, Object.freeze({ ...observation })); + }, + }); +} + +function snapshotControlPlane( + value: ResumableUploadControlPlane, +): ResumableUploadControlPlane { + 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 = { + async createSession( + input: Parameters< + ResumableUploadControlPlane["createSession"] + >[0], + ) { + return await createSession.call(value, input); + }, + async getStatus( + input: Parameters< + ResumableUploadControlPlane["getStatus"] + >[0], + ) { + return await getStatus.call(value, input); + }, + async issuePartCapability( + input: Parameters< + ResumableUploadControlPlane["issuePartCapability"] + >[0], + ) { + return await issuePartCapability.call(value, input); + }, + async complete( + input: Parameters< + ResumableUploadControlPlane["complete"] + >[0], + ) { + return await complete.call(value, input); + }, + async abort( + input: Parameters< + ResumableUploadControlPlane["abort"] + >[0], + ) { + return await abort.call(value, input); + }, + }; + return Object.freeze(snapshot); +} + +function snapshotPartExecutor( + value: UploadPartExecutor, +): UploadPartExecutor { + const uploadPart = value?.uploadPart; + if (typeof uploadPart !== "function") { + throw new TypeError("Upload part executor is invalid."); + } + const snapshot: UploadPartExecutor = { + async uploadPart( + input: Parameters["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[0], + ) { + return await remove.call(value, input); + }, + ...(removeUnreadable + ? { + async removeUnreadable( + input: Parameters[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( + uploadKey: string, + signal: AbortSignal, + task: () => Promise, + ): Promise { + return await (run.call( + value, + uploadKey, + signal, + task, + ) as Promise); + }, + }); +} + +export function safeNow( + dependencies: RuntimeDependencies, + operation: BrowserDataOperation, +): BrowserDataResult { + 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( + dependencies: RuntimeDependencies, +): BrowserDataResult { + 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 { + // 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(() => {})); + sleep.close(); + if (ended.kind !== "TERMINAL" || ended.terminal !== "DEADLINE") { + throw new DOMException("The operation was aborted.", "AbortError"); + } +} diff --git a/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts new file mode 100644 index 00000000..adc87087 --- /dev/null +++ b/src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts @@ -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( + value: UploadPartCapability, + checkpoint: ResumableUploadCheckpoint, + uploadBindingSha256: string, + dependencies: RuntimeDependencies, +): BrowserDataResult> { + 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( + value: UploadSessionStatus, + checkpoint: ResumableUploadCheckpoint, + manifest: UploadPartManifest, + dependencies: RuntimeDependencies, +): BrowserDataResult { + 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( + value: UploadSession, + requestBindingSha256: string, + fingerprint: UploadFileFingerprint, + dependencies: RuntimeDependencies, + requireActiveExpiry = true, +): BrowserDataResult { + 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 { + 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 { + 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]) + ); +} diff --git a/tests/unit/resumable-upload-runtime-contract.test.ts b/tests/unit/resumable-upload-runtime-contract.test.ts new file mode 100644 index 00000000..8d20d545 --- /dev/null +++ b/tests/unit/resumable-upload-runtime-contract.test.ts @@ -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 { + 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, +) { + 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 + >[] = [ + { + 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((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"); + }); +});