- HTTP 에러는 Envelope 하나(결정 2): fileserver problem+json 제거, tus 헤더만 유지, Draft-12 offset 문서는 프로토콜 예외(결정 12) - shared-contract `ClientErrorMessages`(Category별 한국어, 결정 11), shared 예외 `ApiErrorCarrier`, web 일반 carrier 분기 - GraphQL: category switch 3개 → 표 하나, 요청 단계·body-limit·DataLoader 코드가 mapper 경유, 등록된 코드만 노출(결정 25) - gRPC trailer `retryable`, STOMP carrier 코드 보존, IAE는 모든 전송 400 계열, JpaPersistenceException → PersistenceFailureException - sample 이벤트 JSON escape를 `EventJson` 하나로 - 통합 충돌 3건(gRPC 인터셉터 import, sample 409 핸들러·테스트를 새 문구 표 방식으로), P14 GraphQL 테스트 import 경로 수정 검증: ./gradlew check architectureCheck verifyPublicPathSnapshot verifyDependencyLocks --continue 통과(598 task) Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
6.0 KiB
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:
{
"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-Afterand the unsatisfied-rangeContent-Rangeon a failure (see the header contract).- The IETF resumable-upload draft's offset-mismatch response
(
Draft12UploadController#offsetMismatch):409 application/problem+jsonwithtype = https://iana.org/assignments/http-problem-types#mismatching-upload-offset,expectedOffsetandprovidedOffset. 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 |