Files
clean-architecture-frontend…/docs/architecture
DongHyeonka 471b001c40 fix(http): Fileserver 504 TRANSFER_TIMEOUT를 결과 불명으로 읽고 멱등 응답은 V3 표를 쓴다
문제: client는 504 TRANSFER_TIMEOUT을 NOT_APPLIED, retryable:true,
retryAfterMs 5000으로 준다. 매뉴얼대로면 기능이 5초 뒤 자동으로 다시
올린다. 근거로 든 "백엔드가 게시 전에 낸다"는 이 code에 맞지 않는다.
백엔드(45d2a478)는 업로드 작업을 전송 풀에 넘기고, 대기 스레드가
await-seconds가 지나면 작업 단계와 상관없이 future.cancel(true) 뒤
TRANSFER_TIMEOUT을 던진다(BlockingTransferExecutor). interrupt는 파일
복사는 멈추지만 게시 rename과 READY 커밋은 멈추지 않는다. 그래서 504 뒤에
파일이 READY가 될 수 있고, 백엔드가 멱등 키를 읽지 않으므로 다시 보내면
같은 파일이 둘 생긴다. 같은 client의 효과 표는 V3 표와도 갈라졌다. 503
IDEMPOTENCY_UNAVAILABLE을 client는 NOT_APPLIED, V3 표(backend-envelope.ts)와
매뉴얼 4절은 MAYBE_APPLIED로 본다. 계약 문서 6.1의 fileserver 행은 4xx를
MAYBE_APPLIED로 적는데 client는 NOT_APPLIED로 보고, 어느 쪽도 다른 쪽을
말하지 않는다. pin 대조도 이 표를 보지 않는다.

고른 방법:
- TRANSFER_TIMEOUT을 NOT_APPLIED_5XX_CODES에서 뺀다. 5xx 기본값대로
  MAYBE_APPLIED이고, createFailure가 retryable:false, action contact-support로
  만든다. 자동 재전송은 없다. 남은 NOT_APPLIED 5xx는 작업 스레드가 게시 전에
  내는 넷(PARTIAL_WRITE, ATOMIC_PUBLISH_UNSUPPORTED, STORAGE_UNAVAILABLE,
  STORAGE_FULL)이다.
- 멱등성 code(IDEMPOTENT_*, IDEMPOTENCY_* 접두)와 V3 표의 행(REFUSED_BEFORE_WRITE,
  MAYBE_APPLIED_ANSWERS의 status+code)은 client도 envelopeFailureEffect로
  판정한다(sharedAnswerEffect). 같은 백엔드 code의 판정이 이 repo에 하나다.
  503 IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED가 되고, 400
  IDEMPOTENCY_KEY_INVALID·422 IDEMPOTENT_REQUEST_MISMATCH는 그대로
  NOT_APPLIED, 409 IDEMPOTENT_IN_FLIGHT 등은 그대로 MAYBE_APPLIED다. 손으로 둔
  MAYBE_APPLIED_CODES 목록은 AMBIGUOUS_COMPLETION 비교 하나로 줄었다.
- pin 옆에 복사한 백엔드 답 표(config/contracts/backend-idempotency-answers.json)의
  행마다 client 결과의 effect가 V3 표와 같은지 통합 테스트가 본다. 그 표는
  tests/unit/backend-contract-pin.test.ts가 V3 표를 묶는 표와 같다. pin을
  옮기면 두 reader가 함께 다시 대조된다.
- Fileserver 4xx를 NOT_APPLIED로 보는 이유(업로드 use case가 취소)를 계약
  문서 6.1에 한 곳으로 적고, client 주석과 매뉴얼은 그곳을 가리킨다.
- client 주석·매뉴얼의 백엔드 SHA 표기를 bbe944bd에서 pin(45d2a478)으로
  맞췄다. 두 SHA 사이 Fileserver main 코드는 바뀌지 않았다(리뷰 2.1절).
버린 대안:
- client 효과 판정을 V3 표로 통째로 바꾼다: Fileserver 4xx가 모두 결과
  불명이 되어 413·415·422 파일 거절과 202 REJECTED 화면이 나빠진다. 단일
  업로드에서는 use case가 취소하므로 근거도 없다.
- TRANSFER_TIMEOUT 한 줄만 고친다: 위험한 줄은 없어지지만 세 표의 갈라짐과
  pin 밖 상태가 남는다.

위험·한계:
- 504 TRANSFER_TIMEOUT 뒤 화면이 "재시도"에서 "결과 불명"으로 바뀐다. 503
  IDEMPOTENCY_UNAVAILABLE도 같다. CHANGELOG [계약] 한 줄이 필요하다.
- 백엔드로 넘김: 백엔드는 TRANSFER_TIMEOUT을 retryable=true, ambiguous 없이
  보낸다(FileserverErrorCode, BlockingTransferExecutor). 요청 — (a) 작업이
  시작된 뒤의 대기 초과는 details.ambiguous=true, reconciliationRequired=true,
  retryable=false로 보내거나, (b) 작업 스레드가 게시 rename과 READY 커밋 전에
  interrupt를 확인해 504가 "READY 없음"을 보장하게 하고, 어느 쪽인지
  docs/fileserver/http-contract.md에 적는다. 백엔드가 (b)를 고르면 이 줄을
  되돌린다(재검토 조건).
- 백엔드로 넘김: POST /v1/files가 Idempotency-Key를 읽지 않는다
  (UploadFileApplicationUseCase NOT_IDEMPOTENT). 요청 — 업로드를 멱등성
  executor 뒤에 두거나, 키를 무시한다고 Fileserver 계약 문서에 적는다.
- 리뷰 최소 개선 방향 ④의 "drift 검사 대상에 docs/fileserver/http-contract.md
  추가"는 하지 않았다. scripts/check-backend-contract-drift.ts와 pin 모양은
  같은 라운드의 1105/07-01 수정이 다시 짠다. 같은 파일을 두 브랜치가 고치면
  충돌한다. 07-01과 함께 넣는 편이 낫다.
- Fileserver 자신의 code 표(NOT_APPLIED_5XX_CODES)는 여전히 손으로 읽은
  것이고 pin 대조 밖이다. 늦게 READY가 되는 경쟁은 재현하지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts
RED(이 커밋의 테스트 + 부모 src): Envelope failures 표의 "503
IDEMPOTENCY_UNAVAILABLE → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT → SERVER_FAILURE, MAYBE_APPLIED, retryable false",
"504 TRANSFER_TIMEOUT is an unknown result the client does not offer to
retry", pinned backend answer table의 "reads 503 IDEMPOTENCY_UNAVAILABLE as
the V3 Envelope table does"가 실패한다.

Refs: 1105/01-02
2026-11-05 22:11:17 +09:00
..