문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(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·의존 없음이어야 한다.
134 lines
6.1 KiB
Markdown
134 lines
6.1 KiB
Markdown
# 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`:
|
|
|
|
```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 |
|