# Fileserver HTTP contract Every public endpoint is listed here. `FileserverDocumentationCoverageTest` scans the controllers and fails if one is missing, so this file cannot silently fall behind the code. ## Public endpoints | Method | Path | Success | Notes | |---|---|---|---| | POST | `/v1/files` | `201` READY, `202` VERIFYING | multipart single upload | | POST | `/v1/files:raw` | `201`, `202` | the whole request body is the file | | POST | `/v1/files:batch` | `200` | ordered per-part results; explicitly non-atomic | | GET | `/v1/files/{fileId}` | `200` | public metadata; never a content key or path | | GET | `/v1/files/{fileId}/content` | `200`, `206`, `304` | download | | HEAD | `/v1/files/{fileId}/content` | `200`, `304` | identical headers, no body | | DELETE | `/v1/files/{fileId}` | `202`, `204` | logical delete first | | POST | `/v1/files/{fileId}:copy` | `202` | create-only target | | POST | `/v1/files/{fileId}:move` | `200` | logical namespace change only | | OPTIONS | `/v1/uploads` | `204` | tus capability discovery | | POST | `/v1/uploads` | `201` | tus creation | | HEAD | `/v1/uploads/{uploadId}` | `204` | tus offset | | PATCH | `/v1/uploads/{uploadId}` | `204` | tus append | | DELETE | `/v1/uploads/{uploadId}` | `204` | tus termination | | POST | `/v1/experimental/draft12/uploads` | `201` | Experimental; off by default | | PATCH | `/v1/experimental/draft12/uploads/{uploadId}` | `204` | Experimental; off by default | ## Management endpoints Reachable only where both `app.fileserver-platform.enabled=true` and `app.fileserver-platform.admin.enabled=true`, gated at the servlet chain on `app.fileserver-platform.security.admin-roles`, and intended for a management port rather than the public one. | 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` | ## Status codes | Status | Condition | |---:|---| | `200` | metadata, full GET, batch result, move | | `201` | file or upload created | | `202` | verification or physical cleanup deferred | | `204` | append, cancel, bodyless update | | `206` | satisfiable Range | | `304` | validator matched on GET or HEAD | | `400` | malformed header or header combination | | `401` | unauthenticated | | `403` / `404` | denied, or hidden under the existence-hiding profile | | `409` | state, offset, or lease conflict | | `410` | expired or ended (cancelled, rejected, quarantined) upload resource | | `411` | `require-content-length` profile with no length | | `412` | precondition failed | | `413` | size or quota policy violation | | `415` | upload media type not accepted | | `416` | unsatisfiable Range; carries the real length | | `422` | digest, signature, or scanner rejection | | `429` | transfer admission or rate limit | | `460` | tus `Upload-Checksum` does not match that request's bytes; the chunk is discarded and the offset does not move | | `503` | storage or scanner unavailable | | `504` | downstream timeout | | `507` | out of storage capacity | ## Failure body Every failure answers the application's one error shape, the `Envelope` (`application/json`), with the stable code, its category, the shared Korean client message for that category and the identifying values in `error.details`: ```json { "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` carries only what the failure context holds: `fileId`, `uploadId`, `expectedOffset`, `currentOffset`, `state`, and the flags `ambiguous` and `reconciliationRequired` when they are true. The server-side exception message never appears. `ambiguous` is the field a client must read before retrying: an ambiguous failure may already have taken effect. `retryable` is this occurrence's decision and is never wider than the code allows. A batch upload part that is rejected carries the same `error` object (`code`, `category`, `message`, `retryable`) in its `results[]` entry. ### Protocol exceptions to the Envelope rule Owner decision 2 keeps one HTTP error shape; the protocol pieces below are not error vocabulary and stay as the protocol defines them (owner decision 12): - tus protocol headers (`Tus-Resumable`, `Upload-Offset`, `Upload-Length`, …) on every tus response, success or failure. - `Retry-After` and the unsatisfied-range `Content-Range` on a failure (see the header contract). - The IETF resumable-upload draft's offset-mismatch response (`Draft12UploadController#offsetMismatch`): `409 application/problem+json` with `type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset`, `expectedOffset` and `providedOffset`. It is the only non-Envelope failure body. ## Header contract | Header | Contract | |---|---| | `Content-Type` | client value is a claim; the verified type is stored separately | | `Content-Disposition` | `attachment` by default; scriptable types are never inline | | `Accept-Ranges` | `bytes` | | `Range` | single range by default; multi-range only under an explicit budget | | `Content-Range` | actual range on `206`; the unsatisfied form on `416` | | `ETag` | strong validator derived from the SHA-256 | | `Last-Modified` | metadata publication instant, never a filesystem timestamp | | `Cache-Control` | `private, no-store` by default | | `X-Content-Type-Options` | always `nosniff` on a download | | `Retry-After` | on retryable `409`, `429`, `503`, and `504` | | `X-Accel-Redirect` | internal only; never forwarded to a client |