From 9e2c98272f983236510cc3a7be47626bbd69864a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 24 Sep 2026 13:18:23 +0900 Subject: [PATCH] fix(browser-transfer): share one presigned HTTP helper module (Q-6.1-9) The presigned executor and the capability provider each carried a copy of createAbortScope, readWithSignal, transferFailure, isAbortSignal, byteBucket, body/reader cancel, Content-Length parsing and statusFailure. They now import them from presigned/http-common.ts. Behavior changes: - statusFailure is one table. The provider used NONE for 401/403 and RETRY for 429/5xx; it now answers REISSUE_CAPABILITY like the executor. Retry decisions (retryable) are unchanged. Chosen because capabilities are single-use and the architecture doc (3.2) and BT-PRE-04 already say a refusal is recovered by a new capability. - The download check used Number(Content-Length), which let "5e0", "0x5", "+5" and "5.0" through; it now uses the strict decimal parser the upload path and the provider already had. - The executor's compensateLateResponse had no caller and is deleted. - The resumable runtime's invokeProviderAttempt now bounds each attempt with the kernel createAbortableOperation instead of its own listener/timer race; outcomes (ABORTED on caller abort, retryable UNAVAILABLE on the deadline) are unchanged. INVENTORY and the browser-transfer detail review list the new file. The hand-rolled abort ratchet drops to 20/21; the ceiling constant is left for the integration step so parallel lanes do not conflict on it. Verified: RED tests "rejects a download Content-Length that is not a plain decimal" (5e0 was accepted) and "maps capability endpoint statuses with the executor's recovery table" (401 was NONE); existing presigned and runtime suites cover the moved code + all gates. Co-Authored-By: Claude Opus 5.5 --- docs/reviews/adapters/04-browser-transfer.md | 1 + docs/reviews/adapters/INVENTORY.md | 225 +++++++-------- .../browser-transfer/presigned/http-common.ts | 254 +++++++++++++++++ .../presigned-capability-http-provider.ts | 257 ++--------------- .../presigned/presigned-transfer-executor.ts | 263 ++---------------- .../resumable-upload-runtime.ts | 37 +-- tests/unit/presigned-transfer.test.ts | 61 ++++ 7 files changed, 479 insertions(+), 619 deletions(-) create mode 100644 src/adapters/browser-transfer/presigned/http-common.ts diff --git a/docs/reviews/adapters/04-browser-transfer.md b/docs/reviews/adapters/04-browser-transfer.md index 262f0e5c..03278401 100644 --- a/docs/reviews/adapters/04-browser-transfer.md +++ b/docs/reviews/adapters/04-browser-transfer.md @@ -35,6 +35,7 @@ | --- | --- | --- | --- | | `browser-transfer/index.ts` | 하위 capability export | KEEP | public export 증가는 각 capability 계획에서만 수행 | | `presigned/index.ts` | presigned public surface | KEEP | `BT-PRE-04`에서 vault issuer 노출만 축소 검토 | +| `presigned/http-common.ts` | executor·provider 공용 HTTP 메커니즘(abort scope, status 표, Content-Length 파싱, body 취소) | KEEP | Q-6.1-9. 두 벌이던 사본을 합쳤다. status 표는 여기 한 벌만 둔다 | | `presigned/incremental-sha256.ts` | streaming SHA-256 | KEEP | WebCrypto `digest()`로 바꾸면 전체 buffering이 되므로 교체 금지 | | `presigned/presigned-capability-http-provider.ts` | BFF capability 발급, strict decode | CONTRACT_GAP | `BT-PRE-02`, `BT-PRE-03`, `BT-X-01` | | `presigned/presigned-capability-vault.ts` | identity capability 보관/폐기 | REFACTOR | `BT-PRE-04` | diff --git a/docs/reviews/adapters/INVENTORY.md b/docs/reviews/adapters/INVENTORY.md index 39868d1d..deceac2b 100644 --- a/docs/reviews/adapters/INVENTORY.md +++ b/docs/reviews/adapters/INVENTORY.md @@ -34,117 +34,118 @@ | 24 | `src/adapters/browser-transfer/image-cdn/index.ts` | [Browser transfer](./04-browser-transfer.md) | | 25 | `src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts` | [Browser transfer](./04-browser-transfer.md) | | 26 | `src/adapters/browser-transfer/index.ts` | [Browser transfer](./04-browser-transfer.md) | -| 27 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) | -| 28 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) | -| 29 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) | -| 30 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) | -| 31 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) | -| 32 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) | -| 33 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) | -| 34 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) | -| 35 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) | -| 36 | `src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts` | [Browser transfer](./04-browser-transfer.md) | -| 37 | `src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts` | [Browser transfer](./04-browser-transfer.md) | -| 38 | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | [Browser transfer](./04-browser-transfer.md) | -| 39 | `src/adapters/browser-transfer/resumable-upload/runtime-policy.ts` | [Browser transfer](./04-browser-transfer.md) | -| 40 | `src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts` | [Browser transfer](./04-browser-transfer.md) | -| 41 | `src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts` | [Browser transfer](./04-browser-transfer.md) | -| 42 | `src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts` | [Browser transfer](./04-browser-transfer.md) | -| 43 | `src/adapters/cache-storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 44 | `src/adapters/cache-storage/public-cache-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 45 | `src/adapters/cache-storage/public-response-cache-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 46 | `src/adapters/cross-context-invalidation/browser-cross-context-host.ts` | [Network/state](./01-network-and-state.md) | -| 47 | `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` | [Network/state](./01-network-and-state.md) | -| 48 | `src/adapters/cross-context-invalidation/index.ts` | [Network/state](./01-network-and-state.md) | -| 49 | `src/adapters/diagnostics/bounded-diagnostics.ts` | [Network/state](./01-network-and-state.md) | -| 50 | `src/adapters/diagnostics/index.ts` | [Network/state](./01-network-and-state.md) | -| 51 | `src/adapters/http/bounded-body-reader.ts` | [Network/state](./01-network-and-state.md) | -| 52 | `src/adapters/http/bounded-json.ts` | [Network/state](./01-network-and-state.md) | -| 53 | `src/adapters/http/client.ts` | [Network/state](./01-network-and-state.md) | -| 54 | `src/adapters/http/feature-http-binding.ts` | [Network/state](./01-network-and-state.md) | -| 55 | `src/adapters/http/http-contract-bridge.ts` | [Network/state](./01-network-and-state.md) | -| 56 | `src/adapters/http/http-effect-certainty.ts` | [Network/state](./01-network-and-state.md) | -| 57 | `src/adapters/http/http-execution-v3.ts` | [Network/state](./01-network-and-state.md) | -| 58 | `src/adapters/http/http-retry-lifecycle.ts` | [Network/state](./01-network-and-state.md) | -| 59 | `src/adapters/http/index.ts` | [Network/state](./01-network-and-state.md) | -| 60 | `src/adapters/http/platform-error-mapping.ts` | [Network/state](./01-network-and-state.md) | -| 61 | `src/adapters/http/request-builder.ts` | [Network/state](./01-network-and-state.md) | -| 62 | `src/adapters/http/resource-mapper.ts` | [Network/state](./01-network-and-state.md) | -| 63 | `src/adapters/http/retry-policy.ts` | [Network/state](./01-network-and-state.md) | -| 64 | `src/adapters/http/schema-registry.ts` | [Network/state](./01-network-and-state.md) | -| 65 | `src/adapters/platform/abortable-operation.ts` | [Network/state](./01-network-and-state.md) | -| 66 | `src/adapters/platform/bounded-capacity.ts` | [Network/state](./01-network-and-state.md) | -| 67 | `src/adapters/platform/browser-lifecycle.ts` | [Network/state](./01-network-and-state.md) | -| 68 | `src/adapters/platform/browser-mutation-intent-factory.ts` | [Network/state](./01-network-and-state.md) | -| 69 | `src/adapters/platform/index.ts` | [Network/state](./01-network-and-state.md) | -| 70 | `src/adapters/platform/indexeddb-connection.ts` | [Network/state](./01-network-and-state.md) | -| 71 | `src/adapters/platform/indexeddb-transaction.ts` | [Network/state](./01-network-and-state.md) | -| 72 | `src/adapters/platform/system-clock.ts` | [Network/state](./01-network-and-state.md) | -| 73 | `src/adapters/query-cache/conditional-validator-store.ts` | [Network/state](./01-network-and-state.md) | -| 74 | `src/adapters/query-cache/cursor-pagination-contract.ts` | [Network/state](./01-network-and-state.md) | -| 75 | `src/adapters/query-cache/cursor-pagination-runtime.ts` | [Network/state](./01-network-and-state.md) | -| 76 | `src/adapters/query-cache/index.ts` | [Network/state](./01-network-and-state.md) | -| 77 | `src/adapters/query-cache/server-state-scope-runtime.ts` | [Network/state](./01-network-and-state.md) | -| 78 | `src/adapters/query-cache/tanstack-cache-coordinator.ts` | [Network/state](./01-network-and-state.md) | -| 79 | `src/adapters/query-cache/tanstack-query-cache.ts` | [Network/state](./01-network-and-state.md) | -| 80 | `src/adapters/realtime/event-codec.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 81 | `src/adapters/realtime/event-consumer.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 82 | `src/adapters/realtime/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 83 | `src/adapters/realtime/json-member-scanner.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 84 | `src/adapters/realtime/live-poll-handoff-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 85 | `src/adapters/realtime/polling/bounded-poll-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 86 | `src/adapters/realtime/polling/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 87 | `src/adapters/realtime/reconnect-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 88 | `src/adapters/realtime/reconnect-policy.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 89 | `src/adapters/realtime/result.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 90 | `src/adapters/realtime/sse/fetch-sse-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 91 | `src/adapters/realtime/sse/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 92 | `src/adapters/realtime/sse/sse-parser.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 93 | `src/adapters/realtime/stream-coordinator.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 94 | `src/adapters/realtime/websocket/index.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 95 | `src/adapters/realtime/websocket/websocket-connection.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 96 | `src/adapters/realtime/websocket/websocket-protocol.ts` | [Realtime/RPC](./02-realtime-and-browser-rpc.md) | -| 97 | `src/adapters/service-worker/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 98 | `src/adapters/service-worker/service-worker-entry.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 99 | `src/adapters/service-worker/service-worker-lifecycle.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 100 | `src/adapters/service-worker/service-worker-page-controller.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 101 | `src/adapters/service-worker/service-worker-protocol.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 102 | `src/adapters/service-worker/service-worker-removal.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 103 | `src/adapters/service-worker/service-worker-static-assets.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 104 | `src/adapters/storage/browser-storage-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 105 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 106 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 107 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 108 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 109 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 110 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 111 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 112 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 113 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 114 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 115 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 116 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 117 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 118 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 119 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 120 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 121 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 122 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 123 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) | -| 124 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) | -| 125 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) | -| 126 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) | -| 127 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 128 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 129 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 130 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 131 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 132 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 133 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 134 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 135 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 136 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) | -| 137 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) | +| 27 | `src/adapters/browser-transfer/presigned/http-common.ts` | [Browser transfer](./04-browser-transfer.md) | +| 28 | `src/adapters/browser-transfer/presigned/incremental-sha256.ts` | [Browser transfer](./04-browser-transfer.md) | +| 29 | `src/adapters/browser-transfer/presigned/index.ts` | [Browser transfer](./04-browser-transfer.md) | +| 30 | `src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts` | [Browser transfer](./04-browser-transfer.md) | +| 31 | `src/adapters/browser-transfer/presigned/presigned-capability-vault.ts` | [Browser transfer](./04-browser-transfer.md) | +| 32 | `src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts` | [Browser transfer](./04-browser-transfer.md) | +| 33 | `src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts` | [Browser transfer](./04-browser-transfer.md) | +| 34 | `src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts` | [Browser transfer](./04-browser-transfer.md) | +| 35 | `src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts` | [Browser transfer](./04-browser-transfer.md) | +| 36 | `src/adapters/browser-transfer/resumable-upload/index.ts` | [Browser transfer](./04-browser-transfer.md) | +| 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) | -합계: **137/137**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. +합계: **138/138**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다. diff --git a/src/adapters/browser-transfer/presigned/http-common.ts b/src/adapters/browser-transfer/presigned/http-common.ts new file mode 100644 index 00000000..6c55ffbd --- /dev/null +++ b/src/adapters/browser-transfer/presigned/http-common.ts @@ -0,0 +1,254 @@ +import { + createAbortableOperation, + type AbortTimerSnapshot, +} from "../../platform/abortable-operation.ts"; +import type { + BrowserDataFailureCode, + BrowserDataRecovery, + BrowserDataResult, +} from "../../../application/ports/browser-file-storage/shared.ts"; +import { browserDataFailure } from "../../browser-file-storage/result.ts"; + +/** + * Q-6.1-9. HTTP mechanics shared by the presigned executor (object-store + * GET/PUT) and the capability provider (BFF issuance). They were two + * near-identical copies whose status table had already drifted apart. + */ + +/** BT-PRE-03. The scope ended before the task settled. */ +export const SCOPE_ENDED = Symbol("presigned-scope-ended"); + +export type PresignedAbortScope = ReturnType; + +/** + * TR-RR-01 / TR-RR-05. A thin projection of the shared + * `createAbortableOperation` primitive into this subsystem's vocabulary. + * + * `abort()` exists, so `close()` on a download can actually stop a pending + * fetch instead of only dropping listeners; and additional ownership signals — + * a consumer's stream signal — are composed into the same operation *before* + * any I/O starts, so an already-aborted consumer never causes a fetch. + */ +export function createAbortScope( + external: AbortSignal, + timeoutMs: number, + timers: AbortTimerSnapshot, + additionalSignals: readonly AbortSignal[] = [], +) { + const operation = createAbortableOperation({ + signal: external, + timeoutMs, + setTimer: timers.setTimer, + clearTimer: timers.clearTimer, + }); + const releases: (() => void)[] = []; + for (const extra of additionalSignals) { + if (!extra) continue; + if (extra.aborted) { + operation.close(); + continue; + } + const onAbort = () => operation.close(); + try { + extra.addEventListener("abort", onAbort, { once: true }); + releases.push(() => { + try { + extra.removeEventListener("abort", onAbort); + } catch { + // A hostile signal facade cannot block the rest of cleanup. + } + }); + } catch { + // A signal that refuses a listener cannot bound this operation, so the + // operation closes rather than running unbounded. + operation.close(); + } + } + const end = () => { + operation.close(); + for (const release of releases.splice(0)) release(); + }; + return Object.freeze({ + signal: operation.signal, + timedOut: () => operation.terminal() === "DEADLINE", + /** Bounds a fetch that ignores its signal; a late response is cancelled. */ + async race(task: Promise): Promise { + const outcome = await operation.race(task, (value) => { + const body = ( + value as { body?: { cancel(): Promise } | null } | null + )?.body; + void body?.cancel().catch(() => undefined); + }); + if (outcome.kind === "VALUE") return outcome.value; + // A collaborator's own rejection stays a rejection: the caller's existing + // catch classifies it, and it is never forged into a cancellation. + if (outcome.kind === "REJECTED") throw outcome.reason; + return SCOPE_ENDED; + }, + /** TR-RR-01. Ends the physical work, not just the bookkeeping. */ + abort: end, + release: end, + }); +} + +export function readWithSignal( + reader: ReadableStreamDefaultReader, + signal: AbortSignal, +): Promise> { + if (signal.aborted) { + return Promise.reject(new DOMException("Aborted", "AbortError")); + } + return new Promise((resolve, reject) => { + const onAbort = () => { + reject(new DOMException("Aborted", "AbortError")); + }; + signal.addEventListener("abort", onAbort, { once: true }); + reader.read().then( + (result) => { + signal.removeEventListener("abort", onAbort); + resolve(result); + }, + (error: unknown) => { + signal.removeEventListener("abort", onAbort); + reject(error); + }, + ); + }); +} + +export function cancelBody(response: Response): void { + try { + void response.body?.cancel().catch(() => { + // Cancellation is best effort after the result is classified. + }); + } catch { + // A response already classified as failure/success is not reclassified by + // best-effort body cancellation. + } +} + +export function cancelReader( + reader: ReadableStreamDefaultReader, +): void { + try { + void reader.cancel().catch(() => { + // Cancellation is best effort after the result is classified. + }); + } catch { + // Reader cancellation cannot alter the terminal closed result. + } +} + +/** + * A plain decimal `Content-Length`. `Number()` alone accepted `"5e0"`, + * `"0x5"`, `"+5"` and `""`. An absent header is `null` unless the caller's + * binding allows an implicit zero. + */ +export function normalizedContentLength( + value: string | null, + allowImplicitZero = false, +): number | null { + if (value === null) return allowImplicitZero ? 0 : null; + const trimmed = value.trim(); + if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null; + const length = Number(trimmed); + return Number.isSafeInteger(length) ? length : null; +} + +/** + * One status table for both HTTP exchanges. Presigned capabilities are + * single-use, so every recoverable refusal — an expired or rejected signature + * (401/403), a conflict, a gone resource or a transient 429/5xx — is recovered + * by issuing a new capability, never by replaying the same one. + */ +export function statusFailure( + status: number, +): BrowserDataResult { + let code: BrowserDataFailureCode = "UNAVAILABLE"; + let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY"; + let retryable = status === 429 || status >= 500; + if (status === 401 || status === 403) { + code = "PERMISSION_DENIED"; + retryable = false; + } else if (status === 404) { + code = "NOT_FOUND"; + recovery = "NONE"; + retryable = false; + } else if (status === 409) { + code = "CONFLICT"; + retryable = false; + } else if (status === 410) { + code = "EXPIRED_RESOURCE"; + retryable = false; + } else if (status === 413) { + code = "LIMIT_EXCEEDED"; + recovery = "NONE"; + retryable = false; + } else if (status >= 400 && status < 500 && status !== 429) { + code = "POLICY_REJECTED"; + recovery = "NONE"; + retryable = false; + } + return browserDataFailure(code, "PRESIGNED_TRANSFER", { + retryable, + recovery, + }); +} + +export function transferFailure( + externalSignal: AbortSignal, + timedOut: boolean, +): BrowserDataResult { + if (externalSignal.aborted) { + return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER"); + } + return browserDataFailure( + timedOut ? "UNAVAILABLE" : "NOT_READABLE", + "PRESIGNED_TRANSFER", + { + retryable: true, + recovery: "REISSUE_CAPABILITY", + }, + ); +} + +export function isAbortSignal(value: unknown): value is AbortSignal { + try { + if (!value || typeof value !== "object") return false; + const abortedGetter = Object.getOwnPropertyDescriptor( + AbortSignal.prototype, + "aborted", + )?.get; + return Boolean( + abortedGetter && + typeof abortedGetter.call(value) === "boolean" && + typeof (value as AbortSignal).addEventListener === "function" && + typeof (value as AbortSignal).removeEventListener === "function", + ); + } catch { + return false; + } +} + +export function byteBucket( + byteLength: number | undefined, +): + | "ZERO" + | "LT1MIB" + | "1_TO_9MIB" + | "10_TO_99MIB" + | "GTE100MIB" + | undefined { + if ( + byteLength === undefined || + !Number.isSafeInteger(byteLength) || + byteLength < 0 + ) { + return undefined; + } + if (byteLength === 0) return "ZERO"; + if (byteLength < 1_048_576) return "LT1MIB"; + if (byteLength < 10_485_760) return "1_TO_9MIB"; + if (byteLength < 104_857_600) return "10_TO_99MIB"; + return "GTE100MIB"; +} diff --git a/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts b/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts index 1f62832b..d7b5a920 100644 --- a/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts +++ b/src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts @@ -10,16 +10,10 @@ import type { PresignedUploadPartCapability, PresignedUploadPartCapabilityProvider, } from "../../../application/ports/browser-transfer/presigned-transfer.ts"; -import { - createAbortableOperation, - snapshotAbortTimers, - type AbortTimerSnapshot, -} from "../../platform/abortable-operation.ts"; +import { snapshotAbortTimers } from "../../platform/abortable-operation.ts"; import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts"; import type { - BrowserDataFailureCode, BrowserDataObserver, - BrowserDataRecovery, BrowserDataResult, } from "../../../application/ports/browser-file-storage/shared.ts"; import { @@ -32,6 +26,18 @@ import type { PresignedCapabilityVault, PresignedHeaderBinding, } from "./presigned-capability-vault.ts"; +import { + byteBucket, + cancelBody, + cancelReader, + createAbortScope, + isAbortSignal, + normalizedContentLength, + readWithSignal, + SCOPE_ENDED, + statusFailure, + transferFailure, +} from "./http-common.ts"; import { SAFE_TRANSFER_ID } from "../resumable-upload/checkpoint-schema.ts"; const SHA256 = /^[a-f0-9]{64}$/; @@ -237,11 +243,11 @@ export function createPresignedCapabilityHttpProvider( response.type === "opaqueredirect" || response.url !== endpoint ) { - cancelResponseBody(response); + cancelBody(response); return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER"); } if (!response.ok || response.status !== 200) { - cancelResponseBody(response); + cancelBody(response); return statusFailure(response.status); } const contentType = response.headers.get("content-type") ?? ""; @@ -249,7 +255,7 @@ export function createPresignedCapabilityHttpProvider( contentType.split(";", 1)[0]?.trim().toLowerCase() !== "application/json" ) { - cancelResponseBody(response); + cancelBody(response); return browserDataFailure("POLICY_REJECTED", "PRESIGNED_TRANSFER"); } const payload = await readBoundedJson( @@ -762,11 +768,11 @@ async function readBoundedJson( if (declared !== null) { declaredLength = normalizedContentLength(declared); if (declaredLength === null) { - cancelResponseBody(response); + cancelBody(response); throw new ResponseIntegrityError(); } if (declaredLength > maxBytes) { - cancelResponseBody(response); + cancelBody(response); throw new ResponseLimitError(); } } @@ -797,15 +803,7 @@ async function readBoundedJson( text += decoder.decode(); return JSON.parse(text) as unknown; } finally { - if (!completed) { - try { - void reader.cancel().catch(() => { - // Response cancellation is best effort after classification. - }); - } catch { - // Response cleanup cannot alter the closed result. - } - } + if (!completed) cancelReader(reader); try { reader.releaseLock(); } catch { @@ -814,223 +812,6 @@ async function readBoundedJson( } } -function cancelResponseBody(response: Response): void { - try { - void response.body?.cancel().catch(() => { - // Cancellation is best effort after the response is classified. - }); - } catch { - // Response cleanup cannot alter the closed result. - } -} - -function normalizedContentLength(value: string): number | null { - const trimmed = value.trim(); - if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null; - const length = Number(trimmed); - return Number.isSafeInteger(length) ? length : null; -} - -function readWithSignal( - reader: ReadableStreamDefaultReader, - signal: AbortSignal, -): Promise> { - if (signal.aborted) { - return Promise.reject(new DOMException("Aborted", "AbortError")); - } - return new Promise((resolve, reject) => { - const onAbort = () => - reject(new DOMException("Aborted", "AbortError")); - signal.addEventListener("abort", onAbort, { once: true }); - reader.read().then( - (result) => { - signal.removeEventListener("abort", onAbort); - resolve(result); - }, - (error: unknown) => { - signal.removeEventListener("abort", onAbort); - reject(error); - }, - ); - }); -} - -function statusFailure( - status: number, -): BrowserDataResult { - let code: BrowserDataFailureCode = "UNAVAILABLE"; - let recovery: BrowserDataRecovery = "RETRY"; - let retryable = status === 429 || status >= 500; - if (status === 401 || status === 403) { - code = "PERMISSION_DENIED"; - recovery = "NONE"; - retryable = false; - } else if (status === 404) { - code = "NOT_FOUND"; - recovery = "NONE"; - retryable = false; - } else if (status === 409) { - code = "CONFLICT"; - recovery = "REISSUE_CAPABILITY"; - retryable = false; - } else if (status === 410) { - code = "EXPIRED_RESOURCE"; - recovery = "REISSUE_CAPABILITY"; - retryable = false; - } else if (status === 413) { - code = "LIMIT_EXCEEDED"; - recovery = "NONE"; - retryable = false; - } else if (status >= 400 && status < 500 && status !== 429) { - code = "POLICY_REJECTED"; - recovery = "NONE"; - retryable = false; - } - return browserDataFailure(code, "PRESIGNED_TRANSFER", { - retryable, - recovery, - }); -} - -/** BT-PRE-03. The scope ended before the task settled. */ -const SCOPE_ENDED = Symbol("presigned-capability-scope-ended"); - -/** - * TR-RR-01 / TR-RR-05. The abort scope is a thin projection of the shared - * `createAbortableOperation` primitive into this subsystem's vocabulary. - * - * Two things changed with the migration. `abort()` exists, so `close()` on a - * download can actually stop a pending fetch instead of only dropping - * listeners; and additional ownership signals — a consumer's stream signal — - * are composed into the same operation *before* any I/O starts, so an - * already-aborted consumer never causes a fetch. - */ -function createAbortScope( - external: AbortSignal, - timeoutMs: number, - timers: AbortTimerSnapshot, - additionalSignals: readonly AbortSignal[] = [], -) { - const operation = createAbortableOperation({ - signal: external, - timeoutMs, - setTimer: timers.setTimer, - clearTimer: timers.clearTimer, - }); - const releases: (() => void)[] = []; - for (const extra of additionalSignals) { - if (!extra) continue; - if (extra.aborted) { - operation.close(); - continue; - } - const onAbort = () => operation.close(); - try { - extra.addEventListener("abort", onAbort, { once: true }); - releases.push(() => { - try { - extra.removeEventListener("abort", onAbort); - } catch { - // A hostile signal facade cannot block the rest of cleanup. - } - }); - } catch { - // A signal that refuses a listener cannot bound this operation, so the - // operation closes rather than running unbounded. - operation.close(); - } - } - const releaseExtras = () => { - for (const release of releases.splice(0)) release(); - }; - return Object.freeze({ - signal: operation.signal, - timedOut: () => operation.terminal() === "DEADLINE", - /** Bounds a fetch that ignores its signal. */ - async race(task: Promise): Promise { - const outcome = await operation.race( - task, - (value) => compensateLateResponseValue(value), - ); - if (outcome.kind === "VALUE") return outcome.value; - // A collaborator's own rejection stays a rejection: the caller's existing - // catch classifies it, and it is never forged into a cancellation. - if (outcome.kind === "REJECTED") throw outcome.reason; - return SCOPE_ENDED; - }, - /** TR-RR-01. Ends the physical work, not just the bookkeeping. */ - abort() { - operation.close(); - releaseExtras(); - }, - release() { - operation.close(); - releaseExtras(); - }, - }); -} - -function compensateLateResponseValue(value: unknown): void { - const body = (value as { body?: { cancel(): Promise } | null } | null) - ?.body; - void body?.cancel().catch(() => undefined); -} - -function transferFailure( - signal: AbortSignal, - timedOut: boolean, -): BrowserDataResult { - if (signal.aborted) { - return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER"); - } - return browserDataFailure( - timedOut ? "UNAVAILABLE" : "NOT_READABLE", - "PRESIGNED_TRANSFER", - { retryable: true, recovery: "REISSUE_CAPABILITY" }, - ); -} - -function isAbortSignal(value: unknown): value is AbortSignal { - try { - if (!value || typeof value !== "object") return false; - const abortedGetter = Object.getOwnPropertyDescriptor( - AbortSignal.prototype, - "aborted", - )?.get; - return Boolean( - abortedGetter && - typeof abortedGetter.call(value) === "boolean" && - typeof (value as AbortSignal).addEventListener === "function" && - typeof (value as AbortSignal).removeEventListener === "function", - ); - } catch { - return false; - } -} - -function byteBucket( - byteLength: number | undefined, -): - | "ZERO" - | "LT1MIB" - | "1_TO_9MIB" - | "10_TO_99MIB" - | "GTE100MIB" - | undefined { - if ( - byteLength === undefined || - !Number.isSafeInteger(byteLength) || - byteLength < 0 - ) { - return undefined; - } - if (byteLength === 0) return "ZERO"; - if (byteLength < 1_048_576) return "LT1MIB"; - if (byteLength < 10_485_760) return "1_TO_9MIB"; - if (byteLength < 104_857_600) return "10_TO_99MIB"; - return "GTE100MIB"; -} - function strictRecord( value: unknown, keys: readonly string[], diff --git a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts index 2ddfdd34..afbf8b3c 100644 --- a/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts +++ b/src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts @@ -8,11 +8,7 @@ import type { PresignedUploadPartOutcome, PresignedUploadPartPort, } from "../../../application/ports/browser-transfer/presigned-transfer.ts"; -import { - createAbortableOperation, - snapshotAbortTimers, - type AbortTimerSnapshot, -} from "../../platform/abortable-operation.ts"; +import { snapshotAbortTimers } from "../../platform/abortable-operation.ts"; import { RESUMABLE_UPLOAD_PROTOCOL } from "../../../application/ports/browser-transfer/resumable-upload.ts"; import type { BrowserDataFailureCode, @@ -34,6 +30,19 @@ import type { PresignedCapabilityBinding, PresignedCapabilityVault, } from "./presigned-capability-vault.ts"; +import { + byteBucket, + cancelBody, + cancelReader, + createAbortScope, + isAbortSignal, + normalizedContentLength, + readWithSignal, + SCOPE_ENDED, + statusFailure, + transferFailure, + type PresignedAbortScope, +} from "./http-common.ts"; import { SAFE_TRANSFER_ID } from "../resumable-upload/checkpoint-schema.ts"; const SHA256 = /^[a-f0-9]{64}$/; @@ -436,12 +445,12 @@ export function createPresignedTransferExecutor( function createDownloadSource(input: Readonly<{ start: ( - scope: ReturnType, + scope: PresignedAbortScope, ) => Promise; validateResponse: (response: Response) => BrowserDataResult; createScope: ( consumerSignal?: AbortSignal, - ) => ReturnType; + ) => PresignedAbortScope; recheckExpiry: () => BrowserDataResult; binding: PresignedCapabilityBinding; capability: PresignedDownloadCapability; @@ -454,7 +463,7 @@ function createDownloadSource(input: Readonly<{ }>): PresignedDownloadByteSource { /** BT-PRE-01. One state machine shared by `stream()` and `close()`. */ let state: "READY" | "STREAMING" | "CLOSED" = "READY"; - let activeScope: ReturnType | undefined; + let activeScope: PresignedAbortScope | undefined; let activeResponse: Response | undefined; // TR-RR-01. Releasing the scope only dropped listeners and the timer, so a @@ -784,8 +793,7 @@ function validateDownloadResponse( const contentEncoding = response.headers.get("content-encoding"); if ( mediaType !== binding.mediaType || - declaredLength === null || - Number(declaredLength) !== binding.byteLength || + normalizedContentLength(declaredLength) !== binding.byteLength || digestHeader === null || response.headers.get(digestHeader)?.trim().toLowerCase() !== binding.expectedSha256 || @@ -929,17 +937,6 @@ function validateRequiredHeaders( ); } -function normalizedContentLength( - value: string | null, - allowImplicitZero: boolean, -): number | null { - if (value === null) return allowImplicitZero ? 0 : null; - const trimmed = value.trim(); - if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null; - const length = Number(trimmed); - return Number.isSafeInteger(length) ? length : null; -} - function headersFor(binding: PresignedCapabilityBinding): Headers { const headers = new Headers(); for (const header of binding.requestHeaders) { @@ -995,189 +992,6 @@ function validateExpiry( ); } -function statusFailure( - status: number, -): BrowserDataResult { - let code: BrowserDataFailureCode = "UNAVAILABLE"; - let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY"; - let retryable = status === 429 || status >= 500; - if (status === 401 || status === 403) { - code = "PERMISSION_DENIED"; - recovery = "REISSUE_CAPABILITY"; - retryable = false; - } else if (status === 404) { - code = "NOT_FOUND"; - recovery = "NONE"; - retryable = false; - } else if (status === 409) { - code = "CONFLICT"; - retryable = false; - } else if (status === 410) { - code = "EXPIRED_RESOURCE"; - retryable = false; - } else if (status === 413) { - code = "LIMIT_EXCEEDED"; - recovery = "NONE"; - retryable = false; - } else if (status >= 400 && status < 500 && status !== 429) { - code = "POLICY_REJECTED"; - recovery = "NONE"; - retryable = false; - } - return browserDataFailure(code, "PRESIGNED_TRANSFER", { - retryable, - recovery, - }); -} - -function transferFailure( - externalSignal: AbortSignal, - timedOut: boolean, -): BrowserDataResult { - if (externalSignal.aborted) { - return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER"); - } - return browserDataFailure( - timedOut ? "UNAVAILABLE" : "NOT_READABLE", - "PRESIGNED_TRANSFER", - { - retryable: true, - recovery: "REISSUE_CAPABILITY", - }, - ); -} - -/** BT-PRE-03. The scope ended before the task settled. */ -const SCOPE_ENDED = Symbol("presigned-scope-ended"); - -function compensateLateResponse(task: Promise): void { - void task - .then(async (value) => { - const body = (value as { body?: { cancel(): Promise } | null }) - ?.body; - await body?.cancel(); - }) - .catch(() => undefined); -} - -/** - * TR-RR-01 / TR-RR-05. A projection of the shared `createAbortableOperation` - * primitive into this subsystem's vocabulary, replacing a second hand-written - * copy of the same mechanics. - * - * `additionalSignals` lets a consumer's stream signal join the operation's - * ownership before any I/O begins, and `abort()` ends the physical work rather - * than only releasing bookkeeping. - */ -function createAbortScope( - external: AbortSignal, - timeoutMs: number, - timers: AbortTimerSnapshot, - additionalSignals: readonly AbortSignal[] = [], -) { - const operation = createAbortableOperation({ - signal: external, - timeoutMs, - setTimer: timers.setTimer, - clearTimer: timers.clearTimer, - }); - const releases: (() => void)[] = []; - for (const extra of additionalSignals) { - if (!extra) continue; - if (extra.aborted) { - operation.close(); - continue; - } - const onAbort = () => operation.close(); - try { - extra.addEventListener("abort", onAbort, { once: true }); - releases.push(() => { - try { - extra.removeEventListener("abort", onAbort); - } catch { - // A hostile signal facade cannot block the rest of cleanup. - } - }); - } catch { - operation.close(); - } - } - const releaseExtras = () => { - for (const release of releases.splice(0)) release(); - }; - return Object.freeze({ - signal: operation.signal, - timedOut: () => operation.terminal() === "DEADLINE", - async race(task: Promise): Promise { - const outcome = await operation.race(task, (value) => { - const body = ( - value as { body?: { cancel(): Promise } | null } | null - )?.body; - void body?.cancel().catch(() => undefined); - }); - if (outcome.kind === "VALUE") return outcome.value; - if (outcome.kind === "REJECTED") throw outcome.reason; - return SCOPE_ENDED; - }, - abort() { - operation.close(); - releaseExtras(); - }, - release() { - operation.close(); - releaseExtras(); - }, - }); -} - -function cancelBody(response: Response): void { - try { - void response.body?.cancel().catch(() => { - // Cancellation is best effort after the result is classified. - }); - } catch { - // A response already classified as failure/success is not reclassified by - // best-effort body cancellation. - } -} - -function cancelReader( - reader: ReadableStreamDefaultReader, -): void { - try { - void reader.cancel().catch(() => { - // Cancellation is best effort after the result is classified. - }); - } catch { - // Reader cancellation cannot alter the terminal closed result. - } -} - -function readWithSignal( - reader: ReadableStreamDefaultReader, - signal: AbortSignal, -): Promise> { - if (signal.aborted) { - return Promise.reject(new DOMException("Aborted", "AbortError")); - } - return new Promise((resolve, reject) => { - const onAbort = () => { - reject(new DOMException("Aborted", "AbortError")); - }; - signal.addEventListener("abort", onAbort, { once: true }); - reader.read().then( - (result) => { - signal.removeEventListener("abort", onAbort); - resolve(result); - }, - (error: unknown) => { - signal.removeEventListener("abort", onAbort); - reject(error); - }, - ); - }); -} - function normalizeReceiptToken(value: string | null): string | null { if (!value) return null; const trimmed = value.trim(); @@ -1247,24 +1061,6 @@ async function digestSha256WithWebCrypto( ).join(""); } -function isAbortSignal(value: unknown): value is AbortSignal { - try { - if (!value || typeof value !== "object") return false; - const abortedGetter = Object.getOwnPropertyDescriptor( - AbortSignal.prototype, - "aborted", - )?.get; - return Boolean( - abortedGetter && - typeof abortedGetter.call(value) === "boolean" && - typeof (value as AbortSignal).addEventListener === "function" && - typeof (value as AbortSignal).removeEventListener === "function", - ); - } catch { - return false; - } -} - function safeInputByteLength(value: unknown): number | undefined { try { if (!value || typeof value !== "object") return undefined; @@ -1315,26 +1111,3 @@ function observeTransferResult( ...(bucket !== undefined ? { byteBucket: bucket } : {}), }); } - -function byteBucket( - byteLength: number | undefined, -): - | "ZERO" - | "LT1MIB" - | "1_TO_9MIB" - | "10_TO_99MIB" - | "GTE100MIB" - | undefined { - if ( - byteLength === undefined || - !Number.isSafeInteger(byteLength) || - byteLength < 0 - ) { - return undefined; - } - if (byteLength === 0) return "ZERO"; - if (byteLength < 1_048_576) return "LT1MIB"; - if (byteLength < 10_485_760) return "1_TO_9MIB"; - if (byteLength < 104_857_600) return "10_TO_99MIB"; - return "GTE100MIB"; -} 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 315b9626..935672b0 100644 --- a/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts +++ b/src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts @@ -30,6 +30,7 @@ import { browserDataFailure, browserDataSuccess, } from "../../browser-file-storage/result.ts"; +import { createAbortableOperation } from "../../platform/abortable-operation.ts"; import { isResumableUploadCheckpoint, isUploadFileFingerprint, @@ -1343,23 +1344,11 @@ async function invokeProviderAttempt( if (parentSignal.aborted) { return providerFailure("ABORTED", operation, false, "NONE"); } - const controller = new AbortController(); - let timer: ReturnType | undefined; - let releaseAbort = () => {}; - const deadline = new Promise>((resolve) => { - const abort = () => { - controller.abort(); - resolve(providerFailure("ABORTED", operation, false, "NONE")); - }; - parentSignal.addEventListener("abort", abort, { once: true }); - releaseAbort = () => - parentSignal.removeEventListener("abort", abort); - timer = setTimeout(() => { - controller.abort(); - resolve( - providerFailure("UNAVAILABLE", operation, true, "RESUME"), - ); - }, dependencies.policy.providerAttemptTimeoutMs); + // Q-6.1-9. The caller signal and the attempt deadline are the kernel's + // abortable operation, not a second hand-written race. + const attempt = createAbortableOperation({ + signal: parentSignal, + timeoutMs: dependencies.policy.providerAttemptTimeoutMs, }); try { // TR-04. The raw promise enters the physical registry the moment the @@ -1367,20 +1356,20 @@ async function invokeProviderAttempt( // against a deadline let the bounded wrapper settle first and leave the // set empty, so `dispose()` reported a drained runtime while the provider // was still running. - const raw = action(controller.signal); + const raw = action(attempt.signal); const tracked = Promise.resolve(raw).then( () => undefined, () => undefined, ); dependencies.physicalTasks.add(tracked); void tracked.finally(() => dependencies.physicalTasks.delete(tracked)); - return await Promise.race([ - invokeProvider(operation, () => raw), - deadline, - ]); + const outcome = await attempt.race(invokeProvider(operation, () => raw)); + if (outcome.kind === "VALUE") return outcome.value; + return outcome.kind === "TERMINAL" && outcome.terminal === "CALLER_ABORT" + ? providerFailure("ABORTED", operation, false, "NONE") + : providerFailure("UNAVAILABLE", operation, true, "RESUME"); } finally { - if (timer) clearTimeout(timer); - releaseAbort(); + attempt.close(); } } diff --git a/tests/unit/presigned-transfer.test.ts b/tests/unit/presigned-transfer.test.ts index ab260fc1..4eeb3cf5 100644 --- a/tests/unit/presigned-transfer.test.ts +++ b/tests/unit/presigned-transfer.test.ts @@ -565,6 +565,67 @@ describe("presigned transfer capability issuance and admission", () => { }); }); + // Q-6.1-9. `Number(declaredLength)` accepted "5e0", "0x5" and "+5" as 5. + it("rejects a download Content-Length that is not a plain decimal", async () => { + const bytes = new Uint8Array([1, 2, 3, 4, 5]); + const payload = downloadCapabilityPayload(bytes); + for (const declared of ["5e0", "0x5", "+5", "5.0"]) { + const fetcher = vi.fn(async (input: RequestInfo | URL) => + String(input) === CONTROL_ENDPOINT + ? jsonResponse(payload) + : downloadResponse(bytes.slice().buffer, payload, { + "Content-Length": declared, + }), + ) as unknown as typeof fetch; + const harness = createHarness({ fetcher }); + const issued = await harness.provider.issueDownload({ + resourceId: "resource-1", + signal: new AbortController().signal, + }); + expect(issued.ok).toBe(true); + if (!issued.ok) return; + await expect( + firstStreamResult( + await harness.executor.downloadSources.open({ + resourceId: "resource-1", + capability: issued.value, + signal: new AbortController().signal, + }), + ), + declared, + ).resolves.toMatchObject({ + ok: false, + error: { code: "INTEGRITY_FAILED" }, + }); + } + }); + + // Q-6.1-9. The provider and the executor share one status table: a refused + // or failed capability HTTP exchange is recovered by a new capability. + it("maps capability endpoint statuses with the executor's recovery table", async () => { + for (const [status, code, retryable] of [ + [401, "PERMISSION_DENIED", false], + [403, "PERMISSION_DENIED", false], + [503, "UNAVAILABLE", true], + [429, "UNAVAILABLE", true], + ] as const) { + const fetcher = vi.fn(async () => + responseWithUrl(new Response(null, { status }), CONTROL_ENDPOINT), + ) as unknown as typeof fetch; + const { provider } = createHarness({ fetcher }); + expect( + await provider.issueDownload({ + resourceId: "resource-1", + signal: new AbortController().signal, + }), + String(status), + ).toMatchObject({ + ok: false, + error: { code, retryable, recovery: "REISSUE_CAPABILITY" }, + }); + } + }); + it("accepts a valid opaque UTF-8 path segment", async () => { const bytes = new Uint8Array([1, 2, 3]); // BT-PRE-05. Canonical uppercase percent-hex for a real UTF-8 segment.