문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
6.1 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 |
namespace change only, bytes stay; the file's quota moves with it, and a target namespace past its namespace-limit is 413 |
| 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 |