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
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는 요청에 보낸 순서의 index로 짚는다(clientPartId는 전부 성공한 results[]에만 있다). 성공한 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에게 넘기지 않는다 |