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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:32:56 +09:00
co-authored by Claude Opus 5.5
parent 9e387b7ec3
commit 9e2c98272f
7 changed files with 479 additions and 619 deletions
@@ -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` |
+113 -112
View File
@@ -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를 같은 변경에서 갱신한다.
@@ -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<typeof createAbortScope>;
/**
* TR-RR-01 / TR-RR-05. A thin projection of the shared
* `createAbortableOperation` primitive into this subsystem's vocabulary.
*
* `abort()` exists, so `close()` on a download can actually stop a pending
* fetch instead of only dropping listeners; and additional ownership signals —
* a consumer's stream signal — are composed into the same operation *before*
* any I/O starts, so an already-aborted consumer never causes a fetch.
*/
export function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
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<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(task, (value) => {
const body = (
value as { body?: { cancel(): Promise<void> } | null } | null
)?.body;
void body?.cancel().catch(() => undefined);
});
if (outcome.kind === "VALUE") return outcome.value;
// A collaborator's own rejection stays a rejection: the caller's existing
// catch classifies it, and it is never forged into a cancellation.
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
/** TR-RR-01. Ends the physical work, not just the bookkeeping. */
abort: end,
release: end,
});
}
export function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () => {
reject(new DOMException("Aborted", "AbortError"));
};
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
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<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// Reader cancellation cannot alter the terminal closed result.
}
}
/**
* A plain decimal `Content-Length`. `Number()` alone accepted `"5e0"`,
* `"0x5"`, `"+5"` and `""`. An absent header is `null` unless the caller's
* binding allows an implicit zero.
*/
export function normalizedContentLength(
value: string | null,
allowImplicitZero = false,
): number | null {
if (value === null) return allowImplicitZero ? 0 : null;
const trimmed = value.trim();
if (!/^(?:0|[1-9][0-9]{0,15})$/.test(trimmed)) return null;
const length = Number(trimmed);
return Number.isSafeInteger(length) ? length : null;
}
/**
* One status table for both HTTP exchanges. Presigned capabilities are
* single-use, so every recoverable refusal — an expired or rejected signature
* (401/403), a conflict, a gone resource or a transient 429/5xx — is recovered
* by issuing a new capability, never by replaying the same one.
*/
export function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
export function transferFailure(
externalSignal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (externalSignal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{
retryable: true,
recovery: "REISSUE_CAPABILITY",
},
);
}
export function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
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";
}
@@ -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<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () =>
reject(new DOMException("Aborted", "AbortError"));
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function statusFailure(
status: number,
): BrowserDataResult<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "RETRY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
recovery = "NONE";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
/** BT-PRE-03. The scope ended before the task settled. */
const SCOPE_ENDED = Symbol("presigned-capability-scope-ended");
/**
* TR-RR-01 / TR-RR-05. The abort scope is a thin projection of the shared
* `createAbortableOperation` primitive into this subsystem's vocabulary.
*
* Two things changed with the migration. `abort()` exists, so `close()` on a
* download can actually stop a pending fetch instead of only dropping
* listeners; and additional ownership signals — a consumer's stream signal —
* are composed into the same operation *before* any I/O starts, so an
* already-aborted consumer never causes a fetch.
*/
function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
additionalSignals: readonly AbortSignal[] = [],
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
const releases: (() => void)[] = [];
for (const extra of additionalSignals) {
if (!extra) continue;
if (extra.aborted) {
operation.close();
continue;
}
const onAbort = () => operation.close();
try {
extra.addEventListener("abort", onAbort, { once: true });
releases.push(() => {
try {
extra.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
});
} catch {
// A signal that refuses a listener cannot bound this operation, so the
// operation closes rather than running unbounded.
operation.close();
}
}
const releaseExtras = () => {
for (const release of releases.splice(0)) release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
/** Bounds a fetch that ignores its signal. */
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(
task,
(value) => compensateLateResponseValue(value),
);
if (outcome.kind === "VALUE") return outcome.value;
// A collaborator's own rejection stays a rejection: the caller's existing
// catch classifies it, and it is never forged into a cancellation.
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
/** TR-RR-01. Ends the physical work, not just the bookkeeping. */
abort() {
operation.close();
releaseExtras();
},
release() {
operation.close();
releaseExtras();
},
});
}
function compensateLateResponseValue(value: unknown): void {
const body = (value as { body?: { cancel(): Promise<void> } | null } | null)
?.body;
void body?.cancel().catch(() => undefined);
}
function transferFailure(
signal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (signal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{ retryable: true, recovery: "REISSUE_CAPABILITY" },
);
}
function isAbortSignal(value: unknown): value is AbortSignal {
try {
if (!value || typeof value !== "object") return false;
const abortedGetter = Object.getOwnPropertyDescriptor(
AbortSignal.prototype,
"aborted",
)?.get;
return Boolean(
abortedGetter &&
typeof abortedGetter.call(value) === "boolean" &&
typeof (value as AbortSignal).addEventListener === "function" &&
typeof (value as AbortSignal).removeEventListener === "function",
);
} catch {
return false;
}
}
function byteBucket(
byteLength: number | undefined,
):
| "ZERO"
| "LT1MIB"
| "1_TO_9MIB"
| "10_TO_99MIB"
| "GTE100MIB"
| undefined {
if (
byteLength === undefined ||
!Number.isSafeInteger(byteLength) ||
byteLength < 0
) {
return undefined;
}
if (byteLength === 0) return "ZERO";
if (byteLength < 1_048_576) return "LT1MIB";
if (byteLength < 10_485_760) return "1_TO_9MIB";
if (byteLength < 104_857_600) return "10_TO_99MIB";
return "GTE100MIB";
}
function strictRecord(
value: unknown,
keys: readonly string[],
@@ -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<typeof createAbortScope>,
scope: PresignedAbortScope,
) => Promise<Response>;
validateResponse: (response: Response) => BrowserDataResult<unknown>;
createScope: (
consumerSignal?: AbortSignal,
) => ReturnType<typeof createAbortScope>;
) => PresignedAbortScope;
recheckExpiry: () => BrowserDataResult<unknown>;
binding: PresignedCapabilityBinding;
capability: PresignedDownloadCapability;
@@ -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<typeof createAbortScope> | undefined;
let activeScope: PresignedAbortScope | undefined;
let activeResponse: Response | undefined;
// TR-RR-01. Releasing the scope only dropped listeners and the timer, so a
@@ -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<never> {
let code: BrowserDataFailureCode = "UNAVAILABLE";
let recovery: BrowserDataRecovery = "REISSUE_CAPABILITY";
let retryable = status === 429 || status >= 500;
if (status === 401 || status === 403) {
code = "PERMISSION_DENIED";
recovery = "REISSUE_CAPABILITY";
retryable = false;
} else if (status === 404) {
code = "NOT_FOUND";
recovery = "NONE";
retryable = false;
} else if (status === 409) {
code = "CONFLICT";
retryable = false;
} else if (status === 410) {
code = "EXPIRED_RESOURCE";
retryable = false;
} else if (status === 413) {
code = "LIMIT_EXCEEDED";
recovery = "NONE";
retryable = false;
} else if (status >= 400 && status < 500 && status !== 429) {
code = "POLICY_REJECTED";
recovery = "NONE";
retryable = false;
}
return browserDataFailure(code, "PRESIGNED_TRANSFER", {
retryable,
recovery,
});
}
function transferFailure(
externalSignal: AbortSignal,
timedOut: boolean,
): BrowserDataResult<never> {
if (externalSignal.aborted) {
return browserDataFailure("ABORTED", "PRESIGNED_TRANSFER");
}
return browserDataFailure(
timedOut ? "UNAVAILABLE" : "NOT_READABLE",
"PRESIGNED_TRANSFER",
{
retryable: true,
recovery: "REISSUE_CAPABILITY",
},
);
}
/** BT-PRE-03. The scope ended before the task settled. */
const SCOPE_ENDED = Symbol("presigned-scope-ended");
function compensateLateResponse(task: Promise<unknown>): void {
void task
.then(async (value) => {
const body = (value as { body?: { cancel(): Promise<void> } | null })
?.body;
await body?.cancel();
})
.catch(() => undefined);
}
/**
* TR-RR-01 / TR-RR-05. A projection of the shared `createAbortableOperation`
* primitive into this subsystem's vocabulary, replacing a second hand-written
* copy of the same mechanics.
*
* `additionalSignals` lets a consumer's stream signal join the operation's
* ownership before any I/O begins, and `abort()` ends the physical work rather
* than only releasing bookkeeping.
*/
function createAbortScope(
external: AbortSignal,
timeoutMs: number,
timers: AbortTimerSnapshot,
additionalSignals: readonly AbortSignal[] = [],
) {
const operation = createAbortableOperation({
signal: external,
timeoutMs,
setTimer: timers.setTimer,
clearTimer: timers.clearTimer,
});
const releases: (() => void)[] = [];
for (const extra of additionalSignals) {
if (!extra) continue;
if (extra.aborted) {
operation.close();
continue;
}
const onAbort = () => operation.close();
try {
extra.addEventListener("abort", onAbort, { once: true });
releases.push(() => {
try {
extra.removeEventListener("abort", onAbort);
} catch {
// A hostile signal facade cannot block the rest of cleanup.
}
});
} catch {
operation.close();
}
}
const releaseExtras = () => {
for (const release of releases.splice(0)) release();
};
return Object.freeze({
signal: operation.signal,
timedOut: () => operation.terminal() === "DEADLINE",
async race<Value>(task: Promise<Value>): Promise<Value | typeof SCOPE_ENDED> {
const outcome = await operation.race(task, (value) => {
const body = (
value as { body?: { cancel(): Promise<void> } | null } | null
)?.body;
void body?.cancel().catch(() => undefined);
});
if (outcome.kind === "VALUE") return outcome.value;
if (outcome.kind === "REJECTED") throw outcome.reason;
return SCOPE_ENDED;
},
abort() {
operation.close();
releaseExtras();
},
release() {
operation.close();
releaseExtras();
},
});
}
function cancelBody(response: Response): void {
try {
void response.body?.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// A response already classified as failure/success is not reclassified by
// best-effort body cancellation.
}
}
function cancelReader(
reader: ReadableStreamDefaultReader<Uint8Array>,
): void {
try {
void reader.cancel().catch(() => {
// Cancellation is best effort after the result is classified.
});
} catch {
// Reader cancellation cannot alter the terminal closed result.
}
}
function readWithSignal(
reader: ReadableStreamDefaultReader<Uint8Array>,
signal: AbortSignal,
): Promise<ReadableStreamReadResult<Uint8Array>> {
if (signal.aborted) {
return Promise.reject(new DOMException("Aborted", "AbortError"));
}
return new Promise((resolve, reject) => {
const onAbort = () => {
reject(new DOMException("Aborted", "AbortError"));
};
signal.addEventListener("abort", onAbort, { once: true });
reader.read().then(
(result) => {
signal.removeEventListener("abort", onAbort);
resolve(result);
},
(error: unknown) => {
signal.removeEventListener("abort", onAbort);
reject(error);
},
);
});
}
function normalizeReceiptToken(value: string | null): string | null {
if (!value) return null;
const trimmed = value.trim();
@@ -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";
}
@@ -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<Capability, Value>(
if (parentSignal.aborted) {
return providerFailure("ABORTED", operation, false, "NONE");
}
const controller = new AbortController();
let timer: ReturnType<typeof setTimeout> | undefined;
let releaseAbort = () => {};
const deadline = new Promise<UploadProviderResult<Value>>((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<Capability, Value>(
// 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();
}
}
+61
View File
@@ -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.