fix(http)!: 계약 문서대로 patch·bulk·포화 오류를 답한다 #25

Closed
donghyeon.kang wants to merge 0 commits from claude/r9-c-contracts into main
Owner

무엇을, 왜

round9 리뷰 그룹 C의 계약·오류 코드 묶음(B11a web-advanced, B12 fileserver·notification HTTP, B13 전송 오류 코드)을 고친다. 계약 문서·registry와 코드가 갈린 곳을 약속한 응답으로 맞추고, 약속끼리 다른 곳은 리뷰 README 6절의 권하는 안(①②③)으로 정했다.

  • web-advanced(B11a): patch 형식 오류가 세 코드(400 PATCH_REJECTED / 400 BAD_PARAMETER / 403)와 500으로 갈렸다 → 모두 PATCH_REJECTED. 두 applier가 결과 전체를 Bean Validation으로 검증한다. stream writer가 위치 역행을 쓰기 전에 거절하고, commit 뒤 Failure 기록이 실패 자신의 코드(없으면 INTERNAL_ERROR)와 고정 문구를 싣는다. writer가 하지 않는 heartbeat·idle·버퍼·drain은 계약 문서를 실제대로 고쳤다. virtual thread admission guard가 bean만 있고 요청 경로에서 아무도 부르지 않았다 → VirtualThreadAdmissionFilter.
  • HTTP(B12): fileserver batch가 부분 실패에도 success:true였다 → 공용 bulk envelope. bulk 문구·null 키, Content-Range CORS 노출, 알림의 모르는 channel·slot·locale → VALIDATION_FAILED(필드 details), template 경로 /notificationTemplates, 전송 넷이 기본 파일 이름을 짓지 않음, EnvelopeWireShapeTest 빈틈.
  • 오류 코드(B13): 서버 포화가 전송마다 다른 코드였다 → 공용 SERVER_BUSY(503, retryable, Retry-After: 1) 하나. 상태만 아는 503은 SERVER_BUSY, async timeout만 REQUEST_TIMEOUT. fileserver 오류 code 표 전체, §4의 OPERATION_NOT_FOUND, Retry-After를 본문 retryable과 같은 규칙으로.

고른 방법과 버린 대안

  • 서버 포화는 새 공용 코드다. JOB_EXECUTOR_REJECTED 재사용은 백그라운드 job 이름이라 버렸다. fileserver는 같은 이름 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이 같은지 FileserverExceptionTest가 본다. 호출자 자신의 동시 전송 초과만 429다.
  • heartbeat를 writer에 넣는 안은 버렸다. 요청 thread의 동기 writer라 thread 모델을 바꿔야 한다. 문서가 누가 하는지(Registry·DrainCoordinator를 쓰는 서비스) 적는다.
  • /notification-templates를 별칭으로 남기는 안은 버렸다. 같은 자원의 경로가 둘이 된다.
  • admission filter는 보안 chain 바로 뒤(-99)다. 앞에 두면 cross-origin 거절에 CORS 헤더가 없어 브라우저가 503을 못 읽는다.

정한 기본값

  • 리뷰 README 6절 ① batch 부분 실패는 공용 B8, ② 서버 포화는 공용 코드 하나(호출자 빈도만 429), ③ PATCH 정본은 patch-contract. decisions 2.3에 행으로 남겼다. 소유자가 뒤집을 수 있다.
  • batch 부분 실패의 details[]는 공용 BulkItemResult 모양이라 part별 retryable·ambiguous·category가 없다. code로 안다. ①의 결과다.

위험과 영향(파생 서비스가 따라 할 일)

docs/upgrade/2026-11-round9-contracts.md 1~18행. 요점: patch applier 생성자에 Validator, patch·stream·포화 오류 코드가 바뀜, fileserver batch 응답 모양, 알림 template 경로, BulkItemResult.error(index, ApiErrorCode), 이름 없는 업로드 표시 이름 file, virtual thread 상한이 실제로 걸림. 커밋 ! 셋.

검증

desktop, --no-build-cache.

  • RED: 기준 + web-advanced 시험만 → 새 API가 없어 컴파일 실패(c1-red-webadv). 동작 RED는 각 시험이 옛 응답을 거절하는 단언(예: JSON이 아닌 본문 → 옛 코드에서 500).
  • GREEN: 바뀐 leaf 여덟의 check + :app-bootstrap:test·documentContractTest·repositoryContractTest 2209건 실패 0(트리 9b814124). 리뷰 수정 뒤 web 넷의 check + :app-bootstrap:architectureTest + :architectureCheck 1027건 실패 0.
  • scripts/verify.sh pr --no-cache: 첫 실행이 새 예외 이름 하나(THROWABLES_ARE_NAMED_EXCEPTION)로 실패해 고쳤다. 최종 head 재실행은 결과를 아래 댓글로 붙인다.
  • 노트북: check-docs.py·check-work-docs.py rc=0.
  • 새 눈 리뷰: reviewer(be-api-contract + be-testing) Medium 3·Low 8, arch-reviewer 통과(HARD-STOP 0)·Medium 1·Low 3 → 모두 377cf176에서 고침.

발견 ID 표

ID 판정 커밋
RR9-03-23 고침 18188f78, 377cf176
RR9-03-24 고침 18188f78, 377cf176
RR9-03-25 고침(위치 강제 + 계약 문서를 writer 동작대로) 18188f78, 377cf176
RR9-03-26 고침 18188f78
RR9-03-27 고침 18188f78, 377cf176
RR9-03-28 고침(결정 ③) 18188f78
RR9-03-01 고침(결정 ①) 7b5b4c69, 377cf176
RR9-03-02 고침 7b5b4c69
RR9-03-07 고침 697e62e8
RR9-03-09 고침 7b5b4c69
RR9-03-13 고침(201 Location은 읽는 endpoint가 없어 싣지 않고 manual 11에 그 경우를 적음) 7b5b4c69, 377cf176
RR9-03-15 고침 697e62e8, 377cf176
RR9-05-09 고침 7b5b4c69
RR9-03-06 고침(결정 ②) 697e62e8
RR9-03-11 고침 697e62e8
RR9-03-12 고침 697e62e8, 377cf176
RR9-03-16 고침 697e62e8
RR9-03-21 고침(같은 Envelope 계약이라 B16에서 옮김) 7b5b4c69
RR9-03-20 일부 고침(fileserver 포화 시험, 같은 파일이라 여기. graphql 부분은 그룹 C PR 2) 697e62e8

RR9-05-19(W2A-20)는 그룹 B 몫이라 이 PR에 없다.

관련

  • 리뷰 기록: PR #17 docs/reviews/2026-11-12-round9-review/.
  • 같은 그룹의 PR 2(시험·빌드·스크립트), PR 3(문서). PR 3은 이 PR 뒤에 병합한다.
## 무엇을, 왜 round9 리뷰 그룹 C의 계약·오류 코드 묶음(B11a web-advanced, B12 fileserver·notification HTTP, B13 전송 오류 코드)을 고친다. 계약 문서·registry와 코드가 갈린 곳을 약속한 응답으로 맞추고, 약속끼리 다른 곳은 리뷰 README 6절의 권하는 안(①②③)으로 정했다. - **web-advanced(B11a)**: patch 형식 오류가 세 코드(400 PATCH_REJECTED / 400 BAD_PARAMETER / 403)와 500으로 갈렸다 → 모두 `PATCH_REJECTED`. 두 applier가 결과 전체를 Bean Validation으로 검증한다. stream writer가 위치 역행을 쓰기 전에 거절하고, commit 뒤 `Failure` 기록이 실패 자신의 코드(없으면 `INTERNAL_ERROR`)와 고정 문구를 싣는다. writer가 하지 않는 heartbeat·idle·버퍼·drain은 계약 문서를 실제대로 고쳤다. virtual thread admission guard가 bean만 있고 요청 경로에서 아무도 부르지 않았다 → `VirtualThreadAdmissionFilter`. - **HTTP(B12)**: fileserver batch가 부분 실패에도 `success:true`였다 → 공용 bulk envelope. bulk 문구·null 키, `Content-Range` CORS 노출, 알림의 모르는 channel·slot·locale → `VALIDATION_FAILED`(필드 details), template 경로 `/notificationTemplates`, 전송 넷이 기본 파일 이름을 짓지 않음, `EnvelopeWireShapeTest` 빈틈. - **오류 코드(B13)**: 서버 포화가 전송마다 다른 코드였다 → 공용 `SERVER_BUSY`(503, retryable, `Retry-After: 1`) 하나. 상태만 아는 503은 `SERVER_BUSY`, async timeout만 `REQUEST_TIMEOUT`. fileserver 오류 code 표 전체, §4의 `OPERATION_NOT_FOUND`, Retry-After를 본문 retryable과 같은 규칙으로. ## 고른 방법과 버린 대안 - 서버 포화는 새 공용 코드다. `JOB_EXECUTOR_REJECTED` 재사용은 백그라운드 job 이름이라 버렸다. fileserver는 같은 이름 `FileserverErrorCode.SERVER_BUSY`를 두고, 이름이 같은 code의 뜻이 같은지 `FileserverExceptionTest`가 본다. 호출자 자신의 동시 전송 초과만 429다. - heartbeat를 writer에 넣는 안은 버렸다. 요청 thread의 동기 writer라 thread 모델을 바꿔야 한다. 문서가 누가 하는지(Registry·DrainCoordinator를 쓰는 서비스) 적는다. - `/notification-templates`를 별칭으로 남기는 안은 버렸다. 같은 자원의 경로가 둘이 된다. - admission filter는 보안 chain 바로 뒤(-99)다. 앞에 두면 cross-origin 거절에 CORS 헤더가 없어 브라우저가 503을 못 읽는다. ## 정한 기본값 - 리뷰 README 6절 ① batch 부분 실패는 공용 B8, ② 서버 포화는 공용 코드 하나(호출자 빈도만 429), ③ PATCH 정본은 patch-contract. decisions 2.3에 행으로 남겼다. 소유자가 뒤집을 수 있다. - batch 부분 실패의 `details[]`는 공용 `BulkItemResult` 모양이라 part별 `retryable`·`ambiguous`·`category`가 없다. `code`로 안다. ①의 결과다. ## 위험과 영향(파생 서비스가 따라 할 일) `docs/upgrade/2026-11-round9-contracts.md` 1~18행. 요점: patch applier 생성자에 `Validator`, patch·stream·포화 오류 코드가 바뀜, fileserver batch 응답 모양, 알림 template 경로, `BulkItemResult.error(index, ApiErrorCode)`, 이름 없는 업로드 표시 이름 `file`, virtual thread 상한이 실제로 걸림. 커밋 `!` 셋. ## 검증 desktop, `--no-build-cache`. - RED: 기준 + web-advanced 시험만 → 새 API가 없어 컴파일 실패(`c1-red-webadv`). 동작 RED는 각 시험이 옛 응답을 거절하는 단언(예: JSON이 아닌 본문 → 옛 코드에서 500). - GREEN: 바뀐 leaf 여덟의 `check` + `:app-bootstrap:test`·`documentContractTest`·`repositoryContractTest` 2209건 실패 0(트리 `9b814124`). 리뷰 수정 뒤 web 넷의 `check` + `:app-bootstrap:architectureTest` + `:architectureCheck` 1027건 실패 0. - `scripts/verify.sh pr --no-cache`: 첫 실행이 새 예외 이름 하나(`THROWABLES_ARE_NAMED_EXCEPTION`)로 실패해 고쳤다. 최종 head 재실행은 결과를 아래 댓글로 붙인다. - 노트북: `check-docs.py`·`check-work-docs.py` rc=0. - 새 눈 리뷰: reviewer(be-api-contract + be-testing) Medium 3·Low 8, arch-reviewer 통과(HARD-STOP 0)·Medium 1·Low 3 → 모두 `377cf176`에서 고침. ## 발견 ID 표 | ID | 판정 | 커밋 | | --- | --- | --- | | RR9-03-23 | 고침 | 18188f78, 377cf176 | | RR9-03-24 | 고침 | 18188f78, 377cf176 | | RR9-03-25 | 고침(위치 강제 + 계약 문서를 writer 동작대로) | 18188f78, 377cf176 | | RR9-03-26 | 고침 | 18188f78 | | RR9-03-27 | 고침 | 18188f78, 377cf176 | | RR9-03-28 | 고침(결정 ③) | 18188f78 | | RR9-03-01 | 고침(결정 ①) | 7b5b4c69, 377cf176 | | RR9-03-02 | 고침 | 7b5b4c69 | | RR9-03-07 | 고침 | 697e62e8 | | RR9-03-09 | 고침 | 7b5b4c69 | | RR9-03-13 | 고침(201 Location은 읽는 endpoint가 없어 싣지 않고 manual 11에 그 경우를 적음) | 7b5b4c69, 377cf176 | | RR9-03-15 | 고침 | 697e62e8, 377cf176 | | RR9-05-09 | 고침 | 7b5b4c69 | | RR9-03-06 | 고침(결정 ②) | 697e62e8 | | RR9-03-11 | 고침 | 697e62e8 | | RR9-03-12 | 고침 | 697e62e8, 377cf176 | | RR9-03-16 | 고침 | 697e62e8 | | RR9-03-21 | 고침(같은 Envelope 계약이라 B16에서 옮김) | 7b5b4c69 | | RR9-03-20 | 일부 고침(fileserver 포화 시험, 같은 파일이라 여기. graphql 부분은 그룹 C PR 2) | 697e62e8 | RR9-05-19(W2A-20)는 그룹 B 몫이라 이 PR에 없다. ## 관련 - 리뷰 기록: PR #17 `docs/reviews/2026-11-12-round9-review/`. - 같은 그룹의 PR 2(시험·빌드·스크립트), PR 3(문서). PR 3은 이 PR 뒤에 병합한다.
donghyeon.kang added 5 commits 2026-11-12 20:10:19 +00:00
문제: web-advanced의 계약 문서와 코드가 다섯 곳에서 갈렸다.
- patch 거부가 세 코드로 갈렸다. 형식 오류는 PATCH_REJECTED(400), 빈
  문서·연산 모양 오류·merge 깊이 초과는 IllegalArgumentException이라
  BAD_PARAMETER(400), 너무 깊은 pointer는 권한 거절 PATCH_PATH_FORBIDDEN(403)
  이었다. JSON이 아닌 본문과 결과가 대상 타입으로 읽히지 않는 patch는
  Jackson 예외로 catch-all에 닿아 500 INTERNAL_ERROR였다.
- patch-contract.md는 결과를 문서 전체로 검증한다고 했지만 두 applier는
  검증기를 받지 않았다.
- streaming-contract.md는 서버가 위치 증가를 강제하고 heartbeat·idle·max
  age·버퍼 상한·drain 재연결을 한다고 했다. MvcStreamWriter는 그 어느 것도
  하지 않았다.
- commit 뒤 Failure 기록이 어디에도 등록되지 않은 DEPENDENCY_FAILURE로
  고정이라, STREAM_ITEM_TOO_LARGE 같은 carrier 코드가 사라졌다.
- virtual thread profile은 503 + Retry-After를 약속했지만 admission guard는
  bean만 있었고 요청 경로에서 아무도 부르지 않았다.
- web AGENTS B2는 merge patch를 쓰지 않는다고 했고 patch-contract는 필드
  변경에 merge patch를 쓰라고 했다(정본 충돌).

고른 방법:
- 형식이 틀린 patch 문서는 모두 JsonPatchRejectedException(PATCH_REJECTED)
  이다. 본문 파싱과 결과 변환은 PatchBodies가 감싼다. 너무 깊은 pointer는
  권한 검사 앞에서 400으로 거절한다. 대상 타입이 객체가 아닌 것은 서버
  결함이라 IllegalStateException이다.
- 두 applier가 Bean Validation Validator를 받아 결과 객체 전체를 검증한다.
  위반은 @Valid 본문과 같은 ConstraintViolationException → VALIDATION_FAILED.
- writer는 위치가 앞 항목보다 크지 않으면 그 항목을 쓰지 않고 INTERNAL_ERROR
  Failure 기록으로 끝낸다. Failure 기록은 cause 사슬의 carrier 코드, 없으면
  INTERNAL_ERROR, 문구는 category 고정 문구다.
- writer가 할 수 없는 것(heartbeat, idle·max age, 버퍼, drain)은 계약
  문서를 고쳐 누가 하는지(WebStreamPolicy·Registry·DrainCoordinator를 쓰는
  서비스) 적었다. 요청 thread의 동기 writer라 heartbeat를 넣으려면 thread
  모델을 바꿔야 해서 버렸다.
- VirtualThreadAdmissionFilter가 모든 요청을 guard 아래 둔다(request-id
  filter 바로 뒤). async 요청은 async가 끝날 때 permit을 돌려준다. guard에
  Permit API를 더했다.
- 정본 충돌은 리뷰 README 6절 ③대로 patch-contract를 정본으로 두고 web
  AGENTS B2가 그쪽을 가리킨다.

위험·한계: patch를 쓰는 서비스는 applier 생성자에 Validator를 넘겨야
컴파일된다. client가 보는 patch·stream 오류 코드가 바뀐다. virtual thread
profile을 켠 배포는 처음으로 상한에 걸릴 수 있다(upgrade 안내 1~5).

BREAKING CHANGE: JsonMergePatchApplier·JsonPatchApplier 생성자가 Validator를
받는다. patch 거부는 모두 PATCH_REJECTED(400), 결과 제약 위반은
VALIDATION_FAILED, stream Failure 코드는 실패의 코드나 INTERNAL_ERROR다. 할
일은 docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-26, RR9-03-27, RR9-03-28
문제: fileserver·notification의 HTTP 표면이 공용 계약(web AGENTS B8,
http-contract §1, manual 11)과 달랐다.
- fileserver batch는 part가 실패해도 success:true였고 결과를 data.results에
  넣었다. fullySucceeded()를 아무도 부르지 않았다. 계약끼리도 달랐다(web B8의
  BATCH_PARTIAL_FAILURE vs fileserver 계약의 200 + results[].error).
- BulkEnvelope.partial의 error.message가 영어 고정 문구였고, BulkItemResult는
  호출자 문구를 그대로 실었으며 null 키를 남겼다(mix-in 없음).
- Content-Range가 CORS 노출 목록에 없어 브라우저가 다운로드를 이어 받지 못했다.
- 알림 제출·template 게시의 모르는 channel·slot·locale이 details 없는
  BAD_PARAMETER였고(주석은 validation error), template 경로가 lowerCamel이 아닌
  /notification-templates였다.
- 전송 넷(raw·multipart·draft-12·tus)이 이름 없는 업로드에 "upload.bin"을
  지어 넣었다. 앱 정책 OriginalFilenamePolicy의 기본값은 "file"이라 업무 규칙이
  두 곳에 있었다(HARD-STOP 4).
- EnvelopeWireShapeTest는 http-contract §1의 증거로 쓰이는데 data null 키 생략,
  String → Envelope, unsorted page의 sort:null, 부분 실패 문구를 보지 않았다.

고른 방법:
- 리뷰 README 6절 ①대로 fileserver batch도 공용 bulk envelope다. 모두 성공 →
  success:true + results, 하나라도 실패 → success:false + BATCH_PARTIAL_FAILURE +
  part별 details(index, status, id, code, message). 성공한 part는 되돌리지 않는다.
  BatchUploadResponse는 쓰는 곳이 없어져 지웠다.
- BulkEnvelope.partial과 BulkItemResult.error(index, ApiErrorCode)는 category
  고정 문구를 쓴다. BulkItemResult에 null 생략 mix-in을 더했다.
- 알림 controller는 NotificationFieldRejection(VALIDATION_FAILED carrier, 필드를
  짚는 details 하나, 거절한 값은 싣지 않음)을 던진다. template 경로는
  /notificationTemplates다. 읽는 endpoint가 없어 201에 Location을 싣지 않고,
  manual 11 규칙에 그 경우를 적었다.
- 전송은 이름이 없으면 빈 이름을 넘기고 OriginalFilenamePolicy가 정한다.
- EnvelopeWireShapeTest에 빠진 넷을 더했다. EnvelopeTest의 when 둘인 시험을
  둘로 나눴다.
버린 대안: /notification-templates를 별칭으로 남기기 — 같은 자원의 경로가 둘이
되고 인가·공개 경로 스냅숏이 둘을 따로 봐야 한다.

위험·한계: batch를 읽는 client, 알림 template 경로를 쓰는 client와 배포
스크립트, BulkItemResult.error(index, code, message)를 부르던 코드가 바뀐다
(upgrade 안내 6·7·10·11·12, 14).

BREAKING CHANGE: fileserver batch 응답이 공용 bulk envelope가 됐다. 알림
template 경로가 /notificationTemplates다. 알림의 모르는 vocabulary 값은
VALIDATION_FAILED다. BulkItemResult.error는 ApiErrorCode를 받는다. 이름 없는
업로드의 표시 이름이 "file"이다. 할 일은 docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-01, RR9-03-02, RR9-03-09, RR9-03-13, RR9-03-21, RR9-05-09
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. web-advanced는
ADMISSION_REFUSED(503), fileserver는 instance·전송 pool 포화까지
TRANSFER_ADMISSION_REJECTED(429 RATE_LIMIT), gRPC는 RATE_LIMIT_EXCEEDED
(RESOURCE_EXHAUSTED, "요청이 너무 잦습니다")였다. client는 자기 빈도 탓인지 서버
포화인지 가를 수 없었다. web은 상태만 아는 모든 503을 REQUEST_TIMEOUT으로 답했다
(§4는 비동기 시간 초과만). §4에 OPERATION_NOT_FOUND가 없었고, fileserver 오류
code 27개 중 23개가 계약 문서에 없었으며 예시가 "data": null을 실었다. fileserver는
Retry-After를 발생만 보고 붙여, 본문이 retryable=false로 좁힌 code에도 헤더가
나갔다. gRPC Javadoc과 graphql 스냅숏 머리말이 지운 이름(WORKLOG_NOT_FOUND, spi)을
적었다.

고른 방법(리뷰 README 6절 ②):
- 공용 OperationalError.SERVER_BUSY(503, TRANSIENT_DEPENDENCY, retryable,
  Retry-After 1)를 더했다. registry 행, RetryAfterAdvisor, runbook
  server-busy.md를 같이 둔다.
- web-advanced admission 거절, gRPC call admission(UNAVAILABLE), fileserver의
  instance permit·직접 다운로드 permit·전송 pool 포화가 이 코드다. fileserver는
  같은 이름의 FileserverErrorCode.SERVER_BUSY를 두고, 이름이 같은 code의 뜻이
  같은지 FileserverExceptionTest가 이미 본다. 호출자 자기 scope의 동시 전송
  초과만 TRANSFER_ADMISSION_REJECTED 429로 남는다.
- 상태만 아는 503은 SERVER_BUSY, AsyncRequestTimeoutException만
  REQUEST_TIMEOUT이다(HttpStatusErrorCodes.forException).
- fileserver Retry-After는 본문과 같은 규칙(code와 발생이 모두 retryable)으로
  붙인다. 재시도 불가 code인 ATOMIC_PUBLISH_UNSUPPORTED를 표에서 뺐다.
- docs/fileserver/http-contract.md에 오류 code 표 전체를 두고 예시의 data:null을
  지웠다. http-contract §4에 OPERATION_NOT_FOUND와 SERVER_BUSY를 적었다.
- decisions 2.3에 결정 ①②③ 행을 더했다.
- 포화 시험의 sleep(200)을 첫 거절 신호로 바꾸고, timeout 시험이 code까지
  본다(같은 파일이라 RR9-03-20의 그 부분을 여기서 고친다).
- web-advanced 파일의 spotless 정리(앞 커밋분)를 함께 싣는다.
버린 대안: JOB_EXECUTOR_REJECTED를 재사용 — 백그라운드 job 이름이라 요청 허가
거절을 읽는 client와 runbook을 잘못 이끈다.

위험·한계: 포화 거절로 분기하던 client와 재시도 정책, WebAdvancedError
.ADMISSION_REFUSED를 참조하던 코드, 모든 503을 REQUEST_TIMEOUT으로 보던 client가
바뀐다(upgrade 안내 8·9·13).

BREAKING CHANGE: 서버 포화 코드가 SERVER_BUSY 하나다(web-advanced
ADMISSION_REFUSED 삭제, fileserver instance·pool 포화 429 → 503, gRPC
RESOURCE_EXHAUSTED → UNAVAILABLE). 상태만 아는 503은 SERVER_BUSY다. 할 일은
docs/upgrade/2026-11-round9-contracts.md.

Refs: RR9-03-06, RR9-03-07, RR9-03-11, RR9-03-12, RR9-03-15, RR9-03-16, RR9-03-20
PR 전 리뷰(계약·시험 렌즈, 구조 리뷰) 발견을 고친다.

- 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)가 SERVER_BUSY·
  RATE_LIMIT_EXCEEDED로 나가면서 Retry-After를 싣지 않았다. error dispatch는
  싣는데 handleExceptionInternal은 안 실었다. registry 값을 같은 advisor로 단다.
- virtual thread admission filter가 보안 chain 앞이라 cross-origin 거절 503에 CORS
  헤더가 없어 브라우저가 본문도 Retry-After도 못 읽었고, 인증 없는 요청도 permit을
  썼다. chain 바로 뒤(-99)로 옮겼다.
- permit을 한 번만 돌려주는 가드, onTimeout 뒤 onComplete, onStartAsync 재등록을
  지키는 시험이 없었다. 둘을 더했다.
- stream 위치 규칙이 writer와 WebStreamEvidence 두 곳에 있었다. 증거에
  requireNext를 두고 writer가 쓰기 전에 부른다.
- fileserver Retry-After가 좁히기 식을 복사했고 SERVER_BUSY 값을 두 번 적었다.
  ErrorResponseFactory.effectiveRetryable 하나를 같이 쓰고, 공용 이름의 code는
  RetryAfterAdvisor 값을 읽는다. 재시도 불가 code 전부가 헤더를 싣지 않는지 본다.
- batch 전체 성공의 results[]에 "error": null이 나갔다. 항목 record가 null을
  생략한다. batch 시험은 envelope wire 규칙을 실은 mapper로 키 집합을 본다.
- 알림 channel·locale 파싱이 두 controller에 있었다. NotificationVocabulary
  하나로 모으고, detail은 web 검증 어휘(INVALID)를 쓴다. 예외 이름을
  NotificationFieldRejectedException으로 바꿨다(THROWABLES_ARE_NAMED_EXCEPTION).
  template 게시의 거절 시험을 더했다.
- patch 전체 검증 설명에서 상태 전이 예를 뺐다. 검증 대상은 web 표현 DTO이고
  업무 규칙은 유스케이스의 것이다.
- web README의 RetryAfterHint 예시, upgrade 안내 행 넷(bulk 문구·null 키, stream
  역행 항목, 상태만 아는 503·429의 Retry-After, admission filter 순서)과 부분 실패의
  part 짚기(index)를 적었다.

Refs: RR9-03-01, RR9-03-02, RR9-03-06, RR9-03-13, RR9-03-15, RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-27
Author
Owner

최종 head 377cf176(트리 a4fbf21f6d76)의 desktop scripts/verify.sh pr --no-cache: 6784건 실패 0, 건너뜀 35, rc=0, FROM-CACHE 0. 기준 d3a90479, 로그 desktop ~/claude-r9-c-contracts-logs/pr.log.

최종 head `377cf176`(트리 `a4fbf21f6d76`)의 desktop `scripts/verify.sh pr --no-cache`: 6784건 실패 0, 건너뜀 35, rc=0, `FROM-CACHE` 0. 기준 `d3a90479`, 로그 desktop `~/claude-r9-c-contracts-logs/pr.log`.
Author
Owner

#28로 병합됐다(main 3d31896a). 이 PR의 head 377cf176가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner pr / done이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).

#28로 병합됐다(main `3d31896a`). 이 PR의 head `377cf176`가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner `pr / done`이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).
donghyeon.kang closed this pull request 2026-11-12 23:28:33 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#25