문제: 서버 쪽 상한이 찬 거절이 전송마다 다른 코드였다. 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
11 KiB
Fileserver HTTP 계약
모든 공개 endpoint를 여기 적는다. FileserverDocumentationCoverageTest가 controller를 훑어서 빠진 것이 있으면
실패하므로, 이 파일은 코드보다 조용히 뒤처질 수 없다.
공개 endpoint
| Method | Path | 성공 | 비고 |
|---|---|---|---|
| POST | /v1/files |
201 READY, 202 VERIFYING |
multipart 단일 업로드 |
| POST | /v1/files:raw |
201, 202 |
요청 본문 전체가 파일이다 |
| 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 |
같은 헤더, 본문 없음 |
| DELETE | /v1/files/{fileId} |
202, 204 |
먼저 논리 삭제 |
| POST | /v1/files/{fileId}:copy |
202 |
대상은 새로 만들기만 한다 |
| POST | /v1/files/{fileId}:move |
200 |
namespace만 바뀌고 바이트는 그대로다. 파일의 할당량도 함께 옮긴다. 대상 namespace가 namespace-limit을 넘으면 413 |
| OPTIONS | /v1/uploads |
204 |
tus capability 조회 |
| POST | /v1/uploads |
201 |
tus 생성 |
| HEAD | /v1/uploads/{uploadId} |
204 |
tus offset |
| PATCH | /v1/uploads/{uploadId} |
204 |
tus 이어 쓰기 |
| DELETE | /v1/uploads/{uploadId} |
204 |
tus 종료 |
| POST | /v1/experimental/draft12/uploads |
201 |
Experimental. 기본으로 꺼져 있다 |
| PATCH | /v1/experimental/draft12/uploads/{uploadId} |
204 |
Experimental. 기본으로 꺼져 있다 |
관리 endpoint
app.fileserver-platform.enabled=true와 app.fileserver-platform.admin.enabled=true가 둘 다 있을 때만 닿는다.
servlet chain에서 app.fileserver-platform.security.admin-roles로 막고, 공개 port가 아니라 관리 port에 두라고
만든 것이다.
| Method | Path |
|---|---|
| GET | /internal/fileserver/storage-health |
| GET | /internal/fileserver/capabilities |
| GET | /internal/fileserver/orphans |
| POST | /internal/fileserver/orphans:reconcile |
| POST | /internal/fileserver/files/{fileId}:reverify |
| POST | /internal/fileserver/files/{fileId}:force-delete |
| GET | /internal/fileserver/uploads/incomplete |
| POST | /internal/fileserver/uploads:cleanup |
상태 코드
| 상태 | 조건 |
|---|---|
200 |
metadata, 전체 GET, batch 결과, move |
201 |
파일이나 업로드를 만들었다 |
202 |
검증이나 물리 정리를 미뤘다 |
204 |
이어 쓰기, 취소, 본문 없는 갱신 |
206 |
만족할 수 있는 Range |
304 |
GET이나 HEAD에서 validator가 맞았다 |
400 |
헤더나 헤더 조합이 잘못됐다 |
401 |
인증하지 않았다 |
403 / 404 |
거부했거나, 존재를 숨기는 profile에서 숨겼다 |
409 |
상태, offset, lease 충돌 |
410 |
만료되거나 끝난(취소, 거부, 격리) 업로드 자원 |
411 |
require-content-length profile인데 길이가 없다 |
412 |
선행 조건 실패 |
413 |
크기나 할당량 정책 위반 |
415 |
업로드 media type을 받지 않는다 |
416 |
만족할 수 없는 Range. 실제 길이를 담는다 |
422 |
digest, 서명, 검사기 거부 |
429 |
전송 허가나 속도 제한 |
460 |
tus Upload-Checksum이 그 요청의 바이트와 맞지 않는다. 그 chunk는 버리고 offset은 움직이지 않는다 |
503 |
저장소나 검사기를 쓸 수 없다 |
504 |
하류 시간 초과 |
507 |
저장 용량이 없다 |
실패 본문
모든 실패는 애플리케이션의 오류 모양 하나인 Envelope(application/json)로 답한다. 안정된 code, 그 분류,
그 분류에 대한 공용 한국어 client 메시지, 그리고 error.details의 식별 값을 담는다.
{
"success": false,
"error": {
"code": "UPLOAD_OFFSET_MISMATCH",
"category": "CONFLICT",
"message": "현재 상태에서는 요청을 처리할 수 없습니다.",
"retryable": true,
"details": {
"uploadId": "...",
"expectedOffset": 1024,
"currentOffset": 2048
}
},
"meta": { "requestId": "...", "traceId": "...", "correlationId": "..." }
}
details는 실패 context가 가진 것만 담는다: fileId, uploadId, expectedOffset, currentOffset, state,
그리고 참일 때만 ambiguous와 reconciliationRequired flag. 서버 쪽 예외 메시지는 절대 나오지 않는다.
ambiguous는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
retryable은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
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 규칙의 프로토콜 예외
소유자 결정 2는 HTTP 오류 모양을 하나로 둔다. 아래 프로토콜 요소는 오류 어휘가 아니므로 프로토콜이 정한 대로 둔다(소유자 결정 12).
- 성공이든 실패든 모든 tus 응답의 tus 프로토콜 헤더(
Tus-Resumable,Upload-Offset,Upload-Length, …). - 실패 응답의
Retry-After와 만족하지 못한 range의Content-Range(헤더 계약을 본다). - IETF resumable-upload draft의 offset 불일치 응답(
Draft12UploadController#offsetMismatch):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 | — | 저장 용량이 없다 |
헤더 계약
| 헤더 | 계약 |
|---|---|
Content-Type |
client 값은 주장일 뿐이다. 검증한 형식은 따로 저장한다 |
Content-Disposition |
기본은 attachment. 스크립트가 될 수 있는 형식은 절대 inline이 아니다 |
Accept-Ranges |
bytes |
Range |
기본은 범위 하나. 여러 범위는 명시적 예산이 있을 때만 |
Content-Range |
206에서는 실제 범위, 416에서는 만족하지 못한 형태 |
ETag |
SHA-256에서 만든 strong validator |
Last-Modified |
metadata 게시 시각. 파일 시스템 timestamp가 아니다 |
Cache-Control |
기본은 private, no-store |
X-Content-Type-Options |
다운로드에는 늘 nosniff |
Retry-After |
재시도할 수 있는 409, 429, 503, 504에 붙인다 |
X-Accel-Redirect |
내부 전용. client에게 넘기지 않는다 |