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:
@@ -9,7 +9,7 @@
|
||||
|---|---|---|---|
|
||||
| POST | `/v1/files` | `201` READY, `202` VERIFYING | multipart 단일 업로드 |
|
||||
| POST | `/v1/files:raw` | `201`, `202` | 요청 본문 전체가 파일이다 |
|
||||
| POST | `/v1/files:batch` | `200` | part별 결과를 순서대로 준다. 명시적으로 원자적이지 않다 |
|
||||
| POST | `/v1/files:batch` | `200` | 공용 bulk envelope(`docs/web/http-contract.md` 1절). 명시적으로 원자적이지 않다 |
|
||||
| GET | `/v1/files/{fileId}` | `200` | 공개 metadata. content key나 경로는 절대 주지 않는다 |
|
||||
| GET | `/v1/files/{fileId}/content` | `200`, `206`, `304` | 다운로드 |
|
||||
| HEAD | `/v1/files/{fileId}/content` | `200`, `304` | 같은 헤더, 본문 없음 |
|
||||
@@ -76,7 +76,6 @@ servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고,
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "UPLOAD_OFFSET_MISMATCH",
|
||||
"category": "CONFLICT",
|
||||
@@ -97,8 +96,10 @@ servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고,
|
||||
`ambiguous`는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
|
||||
`retryable`은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
|
||||
|
||||
batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객체(`code`, `category`, `message`,
|
||||
`retryable`)를 담는다.
|
||||
batch 업로드는 공용 bulk envelope다. 모든 part가 성공하면 `success: true`와 `results[]`(part마다 `clientPartId`,
|
||||
`status`, `fileId`)다. 한 part라도 거부되면 `success: false`, `error.code = BATCH_PARTIAL_FAILURE`, `error.details[]`다.
|
||||
`details[]` 항목은 part 순서의 `index`, `status`(`ok`·`error`), 성공한 part의 `id`(fileId), 거부된 part의 `code`와
|
||||
category 고정 문구 `message`다. 성공한 part는 되돌리지 않는다.
|
||||
|
||||
### Envelope 규칙의 프로토콜 예외
|
||||
|
||||
@@ -111,6 +112,43 @@ batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객
|
||||
`409 application/problem+json`, `type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset`,
|
||||
`expectedOffset`과 `providedOffset`. Envelope가 아닌 실패 본문은 이것 하나뿐이다.
|
||||
|
||||
## 오류 코드
|
||||
|
||||
`error.code`는 `FileserverErrorCode`(application-fileserver)가 정한다. 아래 표가 그 전부이고, client는 이 값으로
|
||||
분기한다. `retryable`은 그 code가 허락하는 최대치다. 실제 응답의 `retryable`은 그 발생에 대한 판단이라 `true`인
|
||||
code도 `false`로 올 수 있다(위 「실패 본문」). `Retry-After`는 retryable인 발생에만 붙는다.
|
||||
|
||||
| code | status | category | retryable | `Retry-After` | 언제 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `BAD_REQUEST` | 400 | `VALIDATION` | false | — | 헤더나 헤더 조합이 잘못됐다 |
|
||||
| `UNAUTHENTICATED` | 401 | `AUTH` | false | — | 인증하지 않았다 |
|
||||
| `ACCESS_DENIED` | 403 | `AUTHZ` | false | — | 권한이 없다. 존재를 숨기는 profile에서는 `FILE_NOT_FOUND`로 온다 |
|
||||
| `FILE_NOT_FOUND` | 404 | `NOT_FOUND` | false | — | 파일이 없거나 숨겼다 |
|
||||
| `FILE_ALREADY_EXISTS` | 409 | `CONFLICT` | false | — | 대상 이름이 이미 있다(copy·move는 새로 만들기만 한다) |
|
||||
| `FILE_NOT_READY` | 409 | `CONFLICT` | true | 2 | 검증이 끝나지 않아 아직 읽을 수 없다 |
|
||||
| `UPLOAD_OFFSET_MISMATCH` | 409 | `CONFLICT` | true | — | 이어 쓰기 offset이 서버 offset과 다르다. `details.currentOffset`부터 다시 보낸다 |
|
||||
| `CONCURRENT_MODIFICATION` | 409 | `CONFLICT` | true | 1 | 같은 자원을 다른 요청이 바꾸는 중이다 |
|
||||
| `UPLOAD_EXPIRED` | 410 | `CONFLICT` | false | — | 만료되거나 끝난(취소, 거부, 격리) 업로드다 |
|
||||
| `CONTENT_LENGTH_REQUIRED` | 411 | `VALIDATION` | false | — | `require-content-length` profile인데 길이가 없다 |
|
||||
| `PRECONDITION_FAILED` | 412 | `CONFLICT` | false | — | `If-Match`·`If-Unmodified-Since`가 맞지 않는다 |
|
||||
| `FILE_TOO_LARGE` | 413 | `VALIDATION` | false | — | 파일 크기 정책을 넘었다 |
|
||||
| `QUOTA_EXCEEDED` | 413 | `CONFLICT` | false | — | 저장 할당량을 넘었다 |
|
||||
| `UNSUPPORTED_MEDIA_TYPE` | 415 | `VALIDATION` | false | — | 받지 않는 media type이다 |
|
||||
| `RANGE_NOT_SATISFIABLE` | 416 | `VALIDATION` | false | — | Range를 만족할 수 없다. `Content-Range: bytes */<길이>`를 싣는다 |
|
||||
| `INTEGRITY_MISMATCH` | 422 | `DATA_INTEGRITY` | false | — | 선언한 digest와 받은 바이트가 다르다 |
|
||||
| `MALWARE_DETECTED` | 422 | `DATA_INTEGRITY` | false | — | 검사기가 거부했다 |
|
||||
| `INVALID_PATH` | 422 | `VALIDATION` | false | — | 경로 형식이 틀렸다 |
|
||||
| `PATH_OUTSIDE_NAMESPACE` | 422 | `VALIDATION` | false | — | 경로가 namespace 밖을 가리킨다 |
|
||||
| `TRANSFER_ADMISSION_REJECTED` | 429 | `RATE_LIMIT` | true | 1 | 호출자 자신의 동시 전송 permit이 찼다. 자기 전송이 끝나면 풀린다 |
|
||||
| `CHECKSUM_MISMATCH` | 460 | `DATA_INTEGRITY` | false | — | tus `Upload-Checksum`이 그 요청의 바이트와 다르다. 그 chunk만 버린다 |
|
||||
| `PARTIAL_WRITE` | 500 | `TRANSIENT_DEPENDENCY` | false | — | 쓰기가 중간에 끊겼다 |
|
||||
| `AMBIGUOUS_COMPLETION` | 500 | `DATA_INTEGRITY` | false | — | 결과를 모른다. 이미 효과가 났을 수 있어 그대로 재시도하지 않는다 |
|
||||
| `ATOMIC_PUBLISH_UNSUPPORTED` | 503 | `PERMANENT_DEPENDENCY` | false | — | 저장소가 원자적 게시를 지원하지 않는다(배포 설정 결함) |
|
||||
| `STORAGE_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | true | 30 | 저장소나 검사기를 쓸 수 없다 |
|
||||
| `SERVER_BUSY` | 503 | `TRANSIENT_DEPENDENCY` | true | 1 | instance 전체의 전송 permit이나 전송 worker pool이 찼다. 공용 서버 포화 코드와 같다 |
|
||||
| `TRANSFER_TIMEOUT` | 504 | `TRANSIENT_DEPENDENCY` | true | 5 | 전송이 시간 안에 끝나지 않았다 |
|
||||
| `STORAGE_FULL` | 507 | `TRANSIENT_DEPENDENCY` | false | — | 저장 용량이 없다 |
|
||||
|
||||
## 헤더 계약
|
||||
|
||||
| 헤더 | 계약 |
|
||||
|
||||
Reference in New Issue
Block a user