Files
clean-architecture-frontend…/docs/reviews/adapters/INVENTORY.md
T
DongHyeonka f800549315 feat(http): 짝 백엔드 Fileserver의 multipart 한 번 업로드 client를 더한다
문제: 두 템플릿을 짝으로 쓰면 파일 업로드 경로가 없다. 프론트 업로드
레시피는 PRESIGNED_MULTIPART_V1 서버를 가정하는데 짝 백엔드는 그 코드를
지웠고, 짝 백엔드 Fileserver(POST /v1/files)를 부를 프론트 client는 없다.
src 전체에 multipart 요청을 만드는 코드가 없다.

고친 방법(리뷰 D1 (나-1)): src/adapters/http/fileserver-upload.ts에
createFileserverUploadClient를 둔다. 백엔드 bbe944bd 계약 그대로다.
- 입력은 FileContentPort.openSource가 주는 FileByteSource다. 바이트를 한
  번 읽어 multipart 본문(파트 이름 file, RFC 7578, 파일 이름은 HTML 폼
  인코더처럼 escape)을 직접 만든다. File·Blob은 이 adapter에 들어오지
  않는다(eslint browser-data 경계). 선언 크기가 maxFileBytes보다 크면 읽기
  전에 거절하고, 읽는 중에 넘어도 멈춘다. 선언 크기가 있으면 본문 버퍼
  하나에 바로 쓴다.
- 전송 규칙은 레시피와 V3 실행기와 같다. credentials는 인증 프로필이
  정하고, 자격 증명 헤더는 admitCredentialHeaders로 프로필에 맞춰 받는다.
  redirect "error", no-referrer, no-store, 응답 본문 상한, 바이트에 비례한
  deadline 하나, 호출자 abort(커널 createAbortableOperation).
- 성공: 201 READY / 202 그 밖의 state를 Envelope에서 읽는다. 201과 202의
  state가 맞지 않거나 size가 보낸 바이트와 다르면 SCHEMA_MISMATCH,
  APPLIED_CONFIRMED.
- 실패: backend-envelope.ts의 readFailureEnvelope와 envelopeFailureReading을
  그대로 쓴다. 효과 판정은 Fileserver 계약을 따른다. details.ambiguous,
  AMBIGUOUS_COMPLETION, IDEMPOTENT_IN_FLIGHT, IDEMPOTENCY_COMPLETION_UNKNOWN은
  MAYBE_APPLIED. 그 밖의 4xx는 NOT_APPLIED(백엔드 UploadFile use case가
  모호하지 않은 실패에서 업로드를 취소한다). 5xx는 이름 붙인 Fileserver
  code만 NOT_APPLIED이고 나머지는 MAYBE_APPLIED. 보낸 뒤 네트워크 실패·
  시간 초과·abort도 MAYBE_APPLIED. Envelope의 retryable:false와 상한(기본
  30초)을 넘는 Retry-After는 retryable을 false로 만든다(01-02와 같은 규칙).
- Idempotency-Key 헤더를 보낸다. client는 스스로 다시 보내지 않는다.

위치를 http adapter로 고른 이유: Envelope 해석(backend-envelope.ts), 자격
증명 admission(http-contract-bridge.ts), bounded reader를 adapter 안
import로 다시 쓴다. 새 adapter 사이 import 예외가 필요 없다. 바꾼 http
파일은 index.ts의 export 한 묶음뿐이다.
버린 대안:
- backend-envelope.ts를 커널(src/adapters/platform/)로 옮기고 client를
  browser-transfer에 둔다. 다른 작업이 지금 고치는 파일을 옮겨야 하고,
  커널은 제품 중립 primitive 자리인데 백엔드 짝 정책이 들어간다.
  file-transfer 레시피 예산 여유도 1.7KB뿐이고, 이 client는 presigned
  레시피와 무관한데 그 제거 드릴에 함께 지워진다.
- browser-transfer에 Envelope 파서를 하나 더 둔다. 갈라진 사본이다.
- V3 실행기에 multipart 본문을 더한다. 1,900줄짜리 실행기를 다른 작업과
  동시에 크게 고쳐야 한다.
- FormData와 Blob을 쓴다. http adapter는 File·Blob을 쓸 수 없고(eslint),
  기능은 Blob을 갖지 않는다.

조립: 제품이 product-composition.ts에서 client 재료
(FileserverUploadClientDependencies)를 capability로 넘기고, 기능 adapter가
createFileserverUploadClient를 부른다. 그래서 템플릿 boot 번들에는 들지
않는다. 매뉴얼 02 결정표 7절, patterns.md, 두 architecture 문서, 레시피
fallback이 이 경로를 가리킨다. adapter INVENTORY와 상세 리뷰 표에 행을
더했다(번호는 끝에 141로 붙였다).

위험·한계:
- 재개가 없다. 파일 전체를 메모리에 한 번 읽는다(maxFileBytes까지). tus
  client는 없다.
- 짝 백엔드 bbe944bd의 POST /v1/files는 멱등 키를 읽지 않는다
  (NOT_IDEMPOTENT). MAYBE_APPLIED 뒤 같은 키로 다시 보내도 파일이 두 개
  생길 수 있다. 매뉴얼에 적었다.
- 효과 판정 표(NOT_APPLIED_5XX_CODES, MAYBE_APPLIED_CODES)는 백엔드
  bbe944bd 기준이다. 어긋남을 알리는 검사는 없다(12-06과 같은 종류).
- 실제 짝 백엔드를 띄운 업로드는 하지 않았다. 테스트는 계약대로 답하는
  MSW다. 실제 브라우저(Playwright)에서도 돌리지 않았다.
- 템플릿 기본 product-composition.ts가 자격 증명 owner를 노출하지 않으므로,
  템플릿 세션(EXTERNAL_BEARER)으로 올리려면 제품이 자기 credential
  provider를 써야 한다.

검증:
- tests/integration/fileserver-upload.test.ts 48건 통과(201/202 본문,
  Envelope 실패 16종, 409 IDEMPOTENT_IN_FLIGHT + Retry-After 2, 상한 밖
  Retry-After, 보낸 뒤 네트워크 실패 뒤 같은 키 재전송, 시간 초과, abort,
  자격 증명 거절, 크기·입력 거절). multipart 본문은 undici FormData
  파서로 다시 읽어 확인했다.
- 변이 7건(4xx 판정, ambiguous 무시, 상한 무시, credentials 고정, 키 누락,
  201/202 state 검사 제거, Envelope retryable 무시) 모두 실패를 만들었다.
- check:types, lint(바꾼 파일), check:architecture, check:adapter-inventory,
  verify:documentation, check:registries, check:ci 통과
- check:bundle PASS: initial JS 201,921 / 204,800 gzip bytes. 빌드 산출물
  어디에도 client 코드가 없다(dist grep). check:optional-recipes:source PASS
  (file-transfer 56,082 / 57,800)

Refs: docs/reviews/2026-11-03-maturity-review/01-adapters-browser-transfer.md 01-01
2026-11-04 21:05:23 +09:00

16 KiB

Adapter 파일 전수 inventory

검토 기준: develop (2026-08-14 재검토 반영)

GOV-01. 이 표는 손으로 센 숫자가 아니라 corepack pnpm check:adapter-inventory가 git ls-files src/adapters와 정확히 대조하는 목록이다.

rg --files src/adapters | sort 결과 119개를 하나씩 고정한 coverage ledger다. 책임·의존성·finding·유지/변경 판정은 연결된 상세 리뷰의 파일별 표를 따른다.

# full path 상세 리뷰
1 src/adapters/auth/external-session-adapter.ts Network/state
2 src/adapters/auth/index.ts Network/state
3 src/adapters/browser-file-storage/index.ts Storage/files
4 src/adapters/browser-file-storage/result.ts Storage/files
5 src/adapters/browser-file-storage/storage-manager-adapter.ts Storage/files
6 src/adapters/browser-files/browser-file-picker.ts Storage/files
7 src/adapters/browser-files/browser-file-policy-registry.ts Storage/files
8 src/adapters/browser-files/browser-file-vault.ts Storage/files
9 src/adapters/browser-files/create-browser-file-runtime.ts Storage/files
10 src/adapters/browser-files/download-delivery-adapter.ts Storage/files
11 src/adapters/browser-files/download-input-validation.ts Storage/files
12 src/adapters/browser-files/file-observer.ts Storage/files
13 src/adapters/browser-files/file-policy.ts Storage/files
14 src/adapters/browser-files/index.ts Storage/files
15 src/adapters/browser-files/object-url-lease.ts Storage/files
16 src/adapters/browser-rpc/browser-rpc-runtime.ts Realtime/RPC
17 src/adapters/browser-rpc/index.ts Realtime/RPC
18 src/adapters/browser-rpc/transport.ts Realtime/RPC
19 src/adapters/browser-rpc/unavailable-browser-rpc-transport.ts Realtime/RPC
20 src/adapters/browser-transfer/image-cdn/README.md Browser transfer
21 src/adapters/browser-transfer/image-cdn/browser-image-probe.ts Browser transfer
22 src/adapters/browser-transfer/image-cdn/image-cdn-policy.ts Browser transfer
23 src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts Browser transfer
24 src/adapters/browser-transfer/image-cdn/image-header-metadata.ts Browser transfer
25 src/adapters/browser-transfer/image-cdn/index.ts Browser transfer
26 src/adapters/browser-transfer/image-cdn/p256-image-capability-verifier.ts Browser transfer
27 src/adapters/browser-transfer/index.ts Browser transfer
28 src/adapters/browser-transfer/presigned/http-common.ts Browser transfer
29 src/adapters/browser-transfer/presigned/incremental-sha256.ts Browser transfer
30 src/adapters/browser-transfer/presigned/index.ts Browser transfer
31 src/adapters/browser-transfer/presigned/presigned-capability-http-provider.ts Browser transfer
32 src/adapters/browser-transfer/presigned/presigned-capability-vault.ts Browser transfer
33 src/adapters/browser-transfer/presigned/presigned-transfer-executor.ts Browser transfer
34 src/adapters/browser-transfer/resumable-upload/checkpoint-schema.ts Browser transfer
35 src/adapters/browser-transfer/resumable-upload/fetch-json-transport.ts Browser transfer
36 src/adapters/browser-transfer/resumable-upload/http-control-plane-adapter.ts Browser transfer
37 src/adapters/browser-transfer/resumable-upload/index.ts Browser transfer
38 src/adapters/browser-transfer/resumable-upload/indexeddb-checkpoint-store.ts Browser transfer
39 src/adapters/browser-transfer/resumable-upload/presigned-upload-part-executor.ts Browser transfer
40 src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts Browser transfer
41 src/adapters/browser-transfer/resumable-upload/runtime-dependencies.ts Browser transfer
42 src/adapters/browser-transfer/resumable-upload/runtime-policy.ts Browser transfer
43 src/adapters/browser-transfer/resumable-upload/upload-byte-source.ts Browser transfer
44 src/adapters/browser-transfer/resumable-upload/upload-cancellation-channel.ts Browser transfer
45 src/adapters/browser-transfer/resumable-upload/upload-mutation-lock.ts Browser transfer
46 src/adapters/browser-transfer/resumable-upload/upload-response-validation.ts Browser transfer
47 src/adapters/cache-storage/index.ts Storage/files
48 src/adapters/cache-storage/public-cache-codec.ts Storage/files
49 src/adapters/cache-storage/public-cache-policy.ts Storage/files
50 src/adapters/cache-storage/public-cache-response-validation.ts Storage/files
51 src/adapters/cache-storage/public-response-cache-adapter.ts Storage/files
52 src/adapters/cross-context-invalidation/browser-cross-context-host.ts Network/state
53 src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts Network/state
54 src/adapters/cross-context-invalidation/index.ts Network/state
55 src/adapters/diagnostics/bounded-diagnostics.ts Network/state
56 src/adapters/diagnostics/index.ts Network/state
57 src/adapters/http/backend-envelope.ts Network/state
58 src/adapters/http/bounded-body-reader.ts Network/state
59 src/adapters/http/feature-http-binding.ts Network/state
60 src/adapters/http/http-contract-bridge.ts Network/state
61 src/adapters/http/http-effect-certainty.ts Network/state
62 src/adapters/http/http-execution-v3.ts Network/state
63 src/adapters/http/http-retry-lifecycle.ts Network/state
64 src/adapters/http/index.ts Network/state
65 src/adapters/http/platform-error-mapping.ts Network/state
66 src/adapters/platform/abortable-operation.ts Network/state
67 src/adapters/platform/bounded-capacity.ts Network/state
68 src/adapters/platform/browser-lifecycle.ts Network/state
69 src/adapters/platform/browser-mutation-intent-factory.ts Network/state
70 src/adapters/platform/index.ts Network/state
71 src/adapters/platform/indexeddb-connection.ts Network/state
72 src/adapters/platform/indexeddb-transaction.ts Network/state
73 src/adapters/platform/json-member-scanner.ts Network/state
74 src/adapters/platform/retry-after.ts Network/state
75 src/adapters/platform/system-clock.ts Network/state
76 src/adapters/query-cache/conditional-validator-store.ts Network/state
77 src/adapters/query-cache/cursor-pagination-contract.ts Network/state
78 src/adapters/query-cache/cursor-pagination-runtime.ts Network/state
79 src/adapters/query-cache/index.ts Network/state
80 src/adapters/query-cache/server-state-scope-runtime.ts Network/state
81 src/adapters/query-cache/tanstack-cache-coordinator.ts Network/state
82 src/adapters/query-cache/tanstack-query-cache.ts Network/state
83 src/adapters/realtime/event-codec.ts Realtime/RPC
84 src/adapters/realtime/event-consumer.ts Realtime/RPC
85 src/adapters/realtime/index.ts Realtime/RPC
86 src/adapters/realtime/live-poll-handoff-coordinator.ts Realtime/RPC
87 src/adapters/realtime/polling/bounded-poll-coordinator.ts Realtime/RPC
88 src/adapters/realtime/polling/index.ts Realtime/RPC
89 src/adapters/realtime/reconnect-coordinator.ts Realtime/RPC
90 src/adapters/realtime/reconnect-policy.ts Realtime/RPC
91 src/adapters/realtime/result.ts Realtime/RPC
92 src/adapters/realtime/sse/fetch-sse-connection.ts Realtime/RPC
93 src/adapters/realtime/sse/index.ts Realtime/RPC
94 src/adapters/realtime/sse/sse-parser.ts Realtime/RPC
95 src/adapters/realtime/stream-coordinator.ts Realtime/RPC
96 src/adapters/realtime/websocket/index.ts Realtime/RPC
97 src/adapters/realtime/websocket/websocket-connection.ts Realtime/RPC
98 src/adapters/realtime/websocket/websocket-protocol.ts Realtime/RPC
99 src/adapters/service-worker/index.ts Worker/push
100 src/adapters/service-worker/service-worker-entry.ts Worker/push
101 src/adapters/service-worker/service-worker-lifecycle.ts Worker/push
102 src/adapters/service-worker/service-worker-page-controller.ts Worker/push
103 src/adapters/service-worker/service-worker-protocol.ts Worker/push
104 src/adapters/service-worker/service-worker-removal.ts Worker/push
105 src/adapters/service-worker/service-worker-static-assets.ts Worker/push
106 src/adapters/storage/browser-storage-adapter.ts Storage/files
107 src/adapters/storage/browser-storage-codec.ts Storage/files
108 src/adapters/storage/index.ts Storage/files
109 src/adapters/storage/indexeddb/index.ts Storage/files
110 src/adapters/storage/indexeddb/indexeddb-governance.ts Storage/files
111 src/adapters/storage/indexeddb/indexeddb-maintenance.ts Storage/files
112 src/adapters/storage/indexeddb/indexeddb-migrations.ts Storage/files
113 src/adapters/storage/indexeddb/indexeddb-records.ts Storage/files
114 src/adapters/storage/indexeddb/indexeddb-runtime.ts Storage/files
115 src/adapters/storage/indexeddb/indexeddb-types.ts Storage/files
116 src/adapters/storage/opfs/browser-opfs-runtime.ts Storage/files
117 src/adapters/storage/opfs/index.ts Storage/files
118 src/adapters/storage/opfs/indexeddb-opfs-journal.ts Storage/files
119 src/adapters/storage/opfs/opfs-byte-store-adapter.ts Storage/files
120 src/adapters/storage/opfs/opfs-policy.ts Storage/files
121 src/adapters/storage/opfs/opfs-prepared-object.ts Storage/files
122 src/adapters/storage/opfs/opfs-worker-client.ts Storage/files
123 src/adapters/storage/opfs/opfs-worker-protocol.ts Storage/files
124 src/adapters/storage/opfs/opfs-worker-runtime.ts Storage/files
125 src/adapters/telemetry/best-effort-telemetry.ts Network/state
126 src/adapters/telemetry/feature-telemetry.ts Network/state
127 src/adapters/telemetry/index.ts Network/state
128 src/adapters/telemetry/telemetry-collector.ts Network/state
129 src/adapters/web-push/codec-primitives.ts Worker/push
130 src/adapters/web-push/inbound/notification-click-adapter.ts Worker/push
131 src/adapters/web-push/inbound/push-event-adapter.ts Worker/push
132 src/adapters/web-push/index.ts Worker/push
133 src/adapters/web-push/notification-registry.ts Worker/push
134 src/adapters/web-push/push-association-fence-store.ts Worker/push
135 src/adapters/web-push/push-codec.ts Worker/push
136 src/adapters/web-push/push-registration-gateway.ts Worker/push
137 src/adapters/web-push/push-subscription-adapter.ts Worker/push
138 src/adapters/web-push/runtime-support.ts Worker/push
139 src/adapters/web-push/service-worker-runtime.ts Worker/push
140 src/adapters/web-push/service-worker-scope-host.ts Worker/push
141 src/adapters/http/fileserver-upload.ts Network/state

합계: 141/141. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.