문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며 본 주장 중 지금 코드와 다른 것이 있었다. - design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`· content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로 없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`· `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만 지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다. 지운 reactive transport가 아직 스트리밍한다고 했다. - security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다 (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는 지금 `HttpContentDispositionFactory`다. - upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로 읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이 Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는 `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다. - operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope). 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 지원 등급 이름(Stable, Beta, Limited, Compatibility, Experimental)은 표와 테스트가 읽는 꼬리표라 원문으로 둔다(messaging 지원 매트릭스와 같다). configuration.md의 절 제목은 테스트가 읽는 「… — `key`」 꼴을 지킨다. 위 불일치는 코드에 맞춰 고쳤다. 테스트: FileserverDocumentationCoverageTest가 runbook 제목 일곱과 「Explicitly not claimed」를 영어 문자열로 단언했다. 같은 계약(runbook마다 제목이 있고, 주장하지 않는 것을 따로 밝힌다)을 한국어 제목 `## 저장소 가득 참` 등과 `## 주장하지 않는 것`으로 단언한다. 제목 앞에 `## `를 붙여 본문 어딘가에 낱말만 있어도 통과하던 것을 제목으로 좁혔다. metric 이름·CI job·endpoint·설정 key 단언은 그대로다. 버린 대안: runbook 제목을 영어로 남기기. 살아 있는 문서를 한국어로 쓴다는 소유자 결정과 맞지 않는다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로 문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
6.5 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 |
part별 결과를 순서대로 준다. 명시적으로 원자적이지 않다 |
| 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,
"data": null,
"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 업로드에서 거부된 part는 results[] 항목에 같은 error 객체(code, category, message,
retryable)를 담는다.
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가 아닌 실패 본문은 이것 하나뿐이다.
헤더 계약
| 헤더 | 계약 |
|---|---|
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에게 넘기지 않는다 |