fix(errors)!: 서버 포화는 모든 전송이 공용 SERVER_BUSY 하나로 답한다
문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. 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
This commit is contained in:
@@ -116,6 +116,9 @@
|
||||
| GraphQL 인자 변환 실패 | Spring GraphQL 인자 binder의 `BindException`(`@Argument` 값이 파라미터 타입으로 바뀌지 않음)은 `BAD_PARAMETER`(`REQUEST`)로 답하고, WARN 한 줄(예외 타입만, 입력값 없음)을 남긴다. web이 바뀌지 않는 경로 변수에 답하는 것과 같다 | 소유자 | 2026-11-07 같은 전달, r8-f1 보고 「범위 밖」 2 |
|
||||
| 약속한 응답으로 맞추기 | 레지스트리·`docs/web/http-contract.md`·Javadoc이 이미 약속한 응답으로 코드를 맞추는 것은 결함 수정이다. 고치기 전에 묻지 않고, 응답이 바뀌니 업그레이드 안내 행은 적는다. 약속한 곳끼리 다르면 묻는다 | 소유자(2026-11-07, 기본값 확인) | `docs/work/improve.md` 7절, `docs/work/evidence.md` 11절 |
|
||||
| STOMP 필수 header 누락 | 필수 header·destination 변수가 없을 때 Spring이 던지는 `MessageHandlingException`은 ERROR 그대로 둔다. 메시지에 입력값이 없고, Spring이 같은 타입으로 서버 실패(handler의 `Error` 등)도 감싸서 타입만으로는 클라이언트 탓을 가를 수 없다 | 기본값(2026-11-07) | 2026-11-07 총괄 지시, r8-f1 보고 「범위 밖」 3 |
|
||||
| 서버 포화 코드 | 서버 쪽 상한(요청 허가, 꽉 찬 work pool)이 찬 거절은 모든 전송이 공용 `SERVER_BUSY`(503, `TRANSIENT_DEPENDENCY`, retryable, `Retry-After: 1`) 하나다. 호출자 자신의 빈도·동시성 초과만 429(`RATE_LIMIT_EXCEEDED`, fileserver `TRANSFER_ADMISSION_REJECTED`)다. 상태만 아는 503도 `SERVER_BUSY`이고, 비동기 요청 시간 초과만 `REQUEST_TIMEOUT`이다 | 기본값(2026-11-12, 소유자가 뒤집을 수 있다) | 2026-11-12 전체 리뷰 기록 README 6절 ② |
|
||||
| batch 부분 실패 | fileserver batch도 공용 bulk envelope(web AGENTS B8)다. 하나라도 실패하면 `success:false` + `BATCH_PARTIAL_FAILURE` + 항목별 `details` | 기본값(2026-11-12) | 같은 README 6절 ① |
|
||||
| PATCH 정본 | `docs/web/patch-contract.md`가 merge patch·JSON Patch의 정본이다. web AGENTS B2는 `application/json` PATCH DTO만 다루고 그쪽을 가리킨다 | 기본값(2026-11-12) | 같은 README 6절 ③ |
|
||||
|
||||
### 2.4 멱등성
|
||||
|
||||
|
||||
Reference in New Issue
Block a user