Commit Graph
5 Commits
Author SHA1 Message Date
DongHyeonka c05f41a63e fix(http): KEYED 명령이 백엔드의 실행 전 거절에 같은 키로 다시 보낸다
문제
V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로
끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본
(2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response
status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는
network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과
어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝
백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로
나중에 다시 보낸다"로 정한다(http-contract.md §2).

고른 방법
- backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE.
- Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면
  AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget·
  MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을
  다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고
  키를 지킨다.

버린 대안
- V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이
  응답 없는 실패 뒤 재시도를 금지한다.
- 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자
  재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시
  보내지 않았다.

위험·한계
- retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다.
- Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다.

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on
  the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고
  PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과.
- GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다.
- check:types, lint, check:architecture, test:unit 2,568, test:integration 117,
  test:component 245, tests/features 99 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
2026-11-03 22:22:35 +09:00
DongHyeonka 048f490ada refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
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으로 실행한다.
2026-11-03 21:12:34 +09:00
DongHyeonka 326120867c fix(http): 거절의 적용 여부를 백엔드 기준 표 하나로 V2·V3가 판정한다
문제
계약 문서 6.1절(ed0e4b1, 백엔드 5786126c 코드 기준)은 400·409·422 code마다
쓰기 전 거절인지를 정했다. 쓰기 전이라 적용 안 됨인 것은 400
VALIDATION_FAILED(details 모양과 상관없음), 400 IDEMPOTENCY_KEY_INVALID,
422 IDEMPOTENT_REQUEST_MISMATCH뿐이고, 표에 없는 400·409·422는 쓰기 뒤에도
나올 수 있어 결과 불명이다. 지금 판정은 이 표와 세 곳이 다르다.
- V2: 필드 목록 없는 400 VALIDATION_FAILED({cause}, details 없음,
  {field, code})에 effect가 없다. 결과 불명으로 붙들려 다시 저장할 수 없다.
- V2: 422는 code와 상관없이 적용 안 됨이다. fileserver의 422
  INTEGRITY_MISMATCH·MALWARE_DETECTED는 레코드를 쓴 뒤 던진다.
- V3 Envelope operation(7db32e1): 위 V2 규칙을 같이 쓰고, 표 밖 400·409·422는
  classifyProblem에 맡긴다. 400·422를 모두 적용 안 됨으로 보는 분류기면
  BAD_PARAMETER·도메인 400이 틀린다.

고른 방법
- backend-envelope.ts에 표 REFUSED_BEFORE_WRITE(code → status, 진단
  reason)를 하나 두고 V2 client.ts, V3 실행기가 envelopeFailureEffect로
  같이 읽는다. 표에 있으면 NOT_APPLIED, 그 밖의 400·409·422와 503
  IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED, 나머지 status는 undefined
  (V2는 effect 없음, V3는 classifyProblem)다. 진단 reason도 같은 표에서
  읽는다.
- kind와 validationIssues 판정(isFieldValidationFailure)은 그대로 둔다.
  필드 목록 없는 400 VALIDATION_FAILED는 UNKNOWN_CLIENT_FAILURE, 422는
  VALIDATION_REJECTED다. 적용 여부만 바뀐다.
- V3 Envelope operation에서는 400·409·422를 표가 정하고 classifyProblem이
  바꾸지 못한다.

버린 대안
- V2와 V3에 표를 따로 두기: 7db32e1 전처럼 두 벌이 갈라진다.
- 표 밖 400·409·422를 classifyProblem에 맡기기: 6.1절이 표 밖은
  MAYBE_APPLIED로 정했고, 적용 안 됨을 잘못 내면 다음 저장이 새 키를 써
  같은 작업이 두 번 적용된다. 잘못된 MAYBE_APPLIED는 결과 불명 화면만 남긴다.
- 422 전부를 필드 검증(적용 안 됨)으로 남기기: 짝 백엔드는 필드 검증을
  400으로 보내고, fileserver 422는 쓴 뒤 던진다.
- V3 참조 기능 분류기 고치기: 참조 기능은 Envelope operation이 아니고
  fixture가 problem details라 이 표의 대상이 아니다. 고치지 않았다.

위험·한계
- 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에
  폼에서 다시 저장할 수 없다(결과 불명). 프론트 계약 문서 4.2절의 "422
  field validation" 행과 어긋난다. 그 문서는 이 커밋에서 고치지 않았다.
- 표는 백엔드 5786126c 기준이다. 백엔드가 쓰기 전 거절 code를 새로 만들면
  6.1절과 이 표를 함께 고쳐야 한다. 두 repo를 비교하는 검사는 없다.
- 6.1절의 남은 위험: 백엔드가 use case 안에서 VALIDATION_FAILED를 내게 되면
  적용 안 됨 판정이 틀린다.

검증
- RED: 바뀐 행 8건 실패. tests/integration/http-client.test.ts 필드 목록
  없는 400 VALIDATION_FAILED 3모양의 effect, http-diagnostics.test.ts의
  "unrelated 422"(effect NOT_APPLIED), http-execution-v3-envelope.test.ts의
  고정 판정 2건(VALIDATION_FAILED 3모양 NOT_APPLIED, BAD_PARAMETER·도메인
  409·fileserver 422 MAYBE_APPLIED), form-foundation.test.tsx 2건({cause}
  실패 뒤 다시 저장, 422 뒤 저장 버튼 꺼짐).
- GREEN: 위 4개 파일 128건 통과. V2와 V3에 같은 응답 11가지를 보내 판정을
  비교하는 행이 모두 같다.
- check:types, lint, check:architecture, check:diagnostics, check:ci,
  check:registries, check:adapter-inventory 통과. test:unit 2,604,
  test:integration 209, test:component 245, tests/features·tests/contract
  124건 통과. check:bundle 203,354 / 204,800 B.

Refs: docs/architecture/backend-api-and-server-state-contract.md 6.1 (ed0e4b1),
docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
2026-11-03 20:26:28 +09:00
DongHyeonka bd83b496cc fix(http): V3 Envelope 진단이 V2와 같은 멱등성 거절 reason을 싣는다
문제
V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400
IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로
남긴다(93782b0). V3 실행기의 진단에는 백엔드 code가 없다(리뷰 README
14.4). Problem 타입이 계약 패키지 소유라 실행기가 code를 몰랐기 때문이다.
7db32e1 뒤로 responseEnvelope: "ENVELOPE_V1" operation의 실행기는
Envelope error.code를 읽는다.

고른 방법
- Envelope operation의 실패에서 backend-envelope.ts의
  idempotencyRefusalReason(code, status)를 불러 V2와 같은 두 값을
  HttpDiagnosticReason으로 싣는다. projector(runtime-adapters.ts)는 이미
  diagnosticReason을 reason으로 옮기므로 bootstrap은 바꾸지 않았다.
- 표의 reason 타입을 IdempotencyRefusalReason으로 좁혀 두 값이 닫힌
  목록임을 타입으로 둔다.

버린 대안
- 백엔드 code를 reason에 그대로 넣기: reason은 이 repo가 소유한 닫힌
  목록(taxonomy)이고, 서버 code를 그대로 넣지 않는다는 93782b0 결정과
  어긋난다. V2도 넣지 않는다.
- 새 진단 키(problem_code) 추가: src/contracts/diagnostics.ts 허용 목록과
  bootstrap projector를 함께 바꿔야 하고 cardinality 등급을 새로 정해야
  한다. 이 변경 범위를 넘는다.

위험·한계
- 그 밖의 백엔드 code는 진단에 없다. 실패의 AppFailure.code에만 있다.
- DTO 모드 operation(참조 기능)의 진단에는 여전히 code가 없다.
- classifyProblem이 던져 CLASSIFIER_FAILED가 되는 경우는 Envelope 판정이
  있으면 분류기를 부르지 않으므로 둘이 겹치지 않는다.

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts의 "V3 Envelope
  diagnostics name what V2 names" 4행 중 2행 실패(422·400에서 V3 reason
  undefined). 409 두 행은 처음부터 통과(reason 없음 고정).
- GREEN: 같은 파일 29건 통과. 같은 응답의 V2 진단 기록과 V3 진단 기록의
  reason을 비교한다.
- check:types, lint, check:architecture, check:diagnostics 통과.
  test:unit 2,604, test:integration 204, test:component 244,
  tests/features·tests/contract 124건 통과.
- check:bundle 통과(203,352 / 204,800 B, 7db32e1 대비 +31 B).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
2026-11-03 20:13:02 +09:00
DongHyeonka 7db32e1343 fix(http): V3 실행기가 짝 백엔드 Envelope를 operation 단위로 읽는다
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.

고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
  둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
  같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
  프레임을 확인한다. outputValidator는 data(키가 없으면 null),
  problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
  새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
  min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
  backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
  읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
  409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
  classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
  같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
  스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
  <base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
  답한다.

버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
  참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
  모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
  Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
  멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.

위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
  exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
  정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
  불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
  KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
  예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
  모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
  돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
  실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
  조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
  고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
  httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
  비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
  check:registries, check:diagnostics, check:i18n, check:ci 통과.
  test:unit 2,604, test:component 244, test:integration 200 통과.
  tests/features·tests/contract 124건 통과.
  test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
  Envelope로 답하는 목록 화면 테스트 3건 포함).
  test:sample-removal 23개 검사 통과.
  check:bundle 통과(203,321 / 204,800 B).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
2026-11-03 20:10:51 +09:00