# 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`의 식별 값을 담는다. ```json { "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에게 넘기지 않는다 |