문제: 짝 백엔드 Fileserver는 검증기가 거절한 업로드를 202 성공
Envelope(state REJECTED)로 답한다. client는 이 답을 FILE_REJECTED
실패로 바꾸는데, readSuccessEnvelope가 meta.traceId를 버려서 실패에
traceId가 없다. 같은 client의 Envelope 실패는 traceId를 싣는다
(1105/01-03). 서버가 정상으로 답해 trace 값이 손에 있는데도, 지원
담당이 이 거절을 서버 로그나 REJECTED 레코드와 잇지 못한다.
고른 방법: readSuccessEnvelope가 readFailureEnvelope처럼 meta.traceId가
있으면 traceId로 함께 돌려준다. Fileserver client는 202 REJECTED
실패에 그 값을 싣는다. V3 실행기는 value와 page만 읽으므로 동작이
같다. 매뉴얼 7절 결과 읽기 줄에 적었다.
버린 대안: fileserver-upload가 successEnvelopeSchema를 직접 파싱하면
Envelope 읽기가 backend-envelope.ts 밖으로 갈라진다. traceId만 읽는
함수를 따로 두면 같은 답을 두 번 파싱한다.
반환 칸이 늘어 readSuccessEnvelope 결과를 toEqual로 보는 테스트 두
곳(tests/runtime-schema/http-schema.test.ts,
tests/unit/a11y-api-answers.test.ts)의 기대값에 traceId를 더했다.
기대를 넓힌 것이 아니라 새 칸의 값까지 고정한 것이다.
위험·한계: 거절 이유는 여전히 없다. 프론트로는 고칠 수 없어
백엔드로 넘긴다.
- 사실(백엔드 45d2a478): FinalizeUploadApplicationUseCase
#applyNonAcceptVerdict는 REJECT 판정의 code(FILE_TOO_LARGE,
DIGEST_MALFORMED, 제품 검증기 code 등)를 FileRecordMutation.failure로
레코드의 lastErrorCode에만 쓴다. FileUploadController#created는
UploadedFileResponse 7칸(fileId, state, filename, mediaType, size,
sha256, etag)을 202로 답한다. 이유 칸이 없다.
- 요청: REJECT를 실패 Envelope(422, error.code = 판정 code,
retryable false)로 답하거나, 202 REJECTED 응답에 판정 code 칸을
더한다. 앞의 것이면 프론트의 기존 422 경로가 code와 traceId를
그대로 싣고 NOT_APPLIED로 읽는다. 그때 FILE_REJECTED 분기는 지운다.
- CHANGELOG의 "백엔드로 넘김" 목록에 이 항목을 더하는 일은 CHANGELOG
담당에게 남긴다.
실제 배포 응답의 성공 meta에 traceId가 있는지는 백엔드 문서
(docs/web/http-contract.md §1 meta 키)와 EnvelopeBodyAdvice 코드로만
확인했다. backend-envelope.ts는 초기 번들에 있어 초기 JS가 수십 B
늘 수 있다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts tests/runtime-schema/http-schema.test.ts tests/unit/a11y-api-answers.test.ts
RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused
file, not as a broken answer"가 traceId "trace-1"이 없어 실패한다.
"reads data, and a dropped data key as null"과 "answers an Envelope
list read with an empty list inside the Envelope"는 결과에 traceId
칸이 없어 실패한다.
Refs: 1106/01-01
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.