Files
clean-architecture-backend-…/docs/fileserver/http-contract.md
T
DongHyeonkaandClaude Opus 5.5 016597ac78 review-followup Wave 2: 정합성 수정 통합과 검증, 현황표·재개 프롬프트
13개 작업 묶음(P1–P13)의 W2 커밋을 합치고 전체 게이트로 검증했다.

- 묶음별 정합성 수정(notification dispatch·recovery, object storage staged
  publication, fileserver 복구·정리, gRPC 플랫폼, Redis 분류·lease TTL, JPA
  outbox claim 순서·durable operation HTTP, web 요청 id·category 필수, graphql
  에러 mapper, Mongo profile 바인딩, build 소스 보존 게이트·compose smoke info 확인)
- 통합 때 드러난 3건 수정: outbox claim 테스트 fixture의 가짜 envelope hash,
  sample scan이 새 operation controller를 등록하던 문제, SpotBugs aux classpath
  파일이 truncate되지 않아 로컬에서 ".jar.jar"로 실패하던 문제
- 현황표: 묶음 결과 반영, 소유자 결정 21–27, 후속 발견 결함 47행, 요약 갱신
- docs/capability-status.md 「제거된 코드」에 85행 추가
- 묶음 결과 파일·에이전트 지시·스크립트를 docs로 옮기고 desktop 재개 프롬프트 추가

검증: check, ci verifyDependencyLocks, mainCheck, architecture/public path/env
keys/config contract, bootstrap·sample integration/system, build-logic·build-tools
test, optional-platforms ci, qualificationBootJar 통과. integrationCheck는 이번
작업 전에도 실패하던 lane(Redis topology 모드 인자, httpclient failure
injection, AWS 보호 lane)만 실패.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-28 14:46:30 +09:00

4.5 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 application/problem+json with a stable code and its URN:

{
  "type": "urn:fileserver:problem:upload-offset-mismatch",
  "title": "Upload offset mismatch",
  "status": 409,
  "code": "UPLOAD_OFFSET_MISMATCH",
  "retryable": true,
  "ambiguous": false,
  "reconciliationRequired": false,
  "traceId": "..."
}

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.

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