Files
clean-architecture-backend-…/docs/fileserver/http-contract.md
DongHyeonka 377cf17653
pr / done (pull_request) Canceled after 0s
fix(http): 새 눈 리뷰가 찾은 계약 빈틈을 닫는다
PR 전 리뷰(계약·시험 렌즈, 구조 리뷰) 발견을 고친다.

- 상태만 아는 503·429(Spring이 던진 ResponseStatusException 등)가 SERVER_BUSY·
  RATE_LIMIT_EXCEEDED로 나가면서 Retry-After를 싣지 않았다. error dispatch는
  싣는데 handleExceptionInternal은 안 실었다. registry 값을 같은 advisor로 단다.
- virtual thread admission filter가 보안 chain 앞이라 cross-origin 거절 503에 CORS
  헤더가 없어 브라우저가 본문도 Retry-After도 못 읽었고, 인증 없는 요청도 permit을
  썼다. chain 바로 뒤(-99)로 옮겼다.
- permit을 한 번만 돌려주는 가드, onTimeout 뒤 onComplete, onStartAsync 재등록을
  지키는 시험이 없었다. 둘을 더했다.
- stream 위치 규칙이 writer와 WebStreamEvidence 두 곳에 있었다. 증거에
  requireNext를 두고 writer가 쓰기 전에 부른다.
- fileserver Retry-After가 좁히기 식을 복사했고 SERVER_BUSY 값을 두 번 적었다.
  ErrorResponseFactory.effectiveRetryable 하나를 같이 쓰고, 공용 이름의 code는
  RetryAfterAdvisor 값을 읽는다. 재시도 불가 code 전부가 헤더를 싣지 않는지 본다.
- batch 전체 성공의 results[]에 "error": null이 나갔다. 항목 record가 null을
  생략한다. batch 시험은 envelope wire 규칙을 실은 mapper로 키 집합을 본다.
- 알림 channel·locale 파싱이 두 controller에 있었다. NotificationVocabulary
  하나로 모으고, detail은 web 검증 어휘(INVALID)를 쓴다. 예외 이름을
  NotificationFieldRejectedException으로 바꿨다(THROWABLES_ARE_NAMED_EXCEPTION).
  template 게시의 거절 시험을 더했다.
- patch 전체 검증 설명에서 상태 전이 예를 뺐다. 검증 대상은 web 표현 DTO이고
  업무 규칙은 유스케이스의 것이다.
- web README의 RetryAfterHint 예시, upgrade 안내 행 넷(bulk 문구·null 키, stream
  역행 항목, 상태만 아는 503·429의 Retry-After, admission filter 순서)과 부분 실패의
  part 짚기(index)를 적었다.

Refs: RR9-03-01, RR9-03-02, RR9-03-06, RR9-03-13, RR9-03-15, RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-27
2026-11-13 05:09:45 +09:00

11 KiB

Fileserver HTTP 계약

모든 공개 endpoint를 여기 적는다. FileserverDocumentationCoverageTest가 controller를 훑어서 빠진 것이 있으면 실패하므로, 이 파일은 코드보다 조용히 뒤처질 수 없다.

공개 endpoint

Method Path 성공 비고
POST /v1/files 201 READY, 202 VERIFYING multipart 단일 업로드
POST /v1/files:raw 201, 202 요청 본문 전체가 파일이다
POST /v1/files:batch 200 공용 bulk envelope(docs/web/http-contract.md 1절). 명시적으로 원자적이지 않다
GET /v1/files/{fileId} 200 공개 metadata. content key나 경로는 절대 주지 않는다
GET /v1/files/{fileId}/content 200, 206, 304 다운로드
HEAD /v1/files/{fileId}/content 200, 304 같은 헤더, 본문 없음
DELETE /v1/files/{fileId} 202, 204 먼저 논리 삭제
POST /v1/files/{fileId}:copy 202 대상은 새로 만들기만 한다
POST /v1/files/{fileId}:move 200 namespace만 바뀌고 바이트는 그대로다. 파일의 할당량도 함께 옮긴다. 대상 namespace가 namespace-limit을 넘으면 413
OPTIONS /v1/uploads 204 tus capability 조회
POST /v1/uploads 201 tus 생성
HEAD /v1/uploads/{uploadId} 204 tus offset
PATCH /v1/uploads/{uploadId} 204 tus 이어 쓰기
DELETE /v1/uploads/{uploadId} 204 tus 종료
POST /v1/experimental/draft12/uploads 201 Experimental. 기본으로 꺼져 있다
PATCH /v1/experimental/draft12/uploads/{uploadId} 204 Experimental. 기본으로 꺼져 있다

관리 endpoint

app.fileserver-platform.enabled=true와 app.fileserver-platform.admin.enabled=true가 둘 다 있을 때만 닿는다. servlet chain에서 app.fileserver-platform.security.admin-roles로 막고, 공개 port가 아니라 관리 port에 두라고 만든 것이다.

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

상태 코드

상태 조건
200 metadata, 전체 GET, batch 결과, move
201 파일이나 업로드를 만들었다
202 검증이나 물리 정리를 미뤘다
204 이어 쓰기, 취소, 본문 없는 갱신
206 만족할 수 있는 Range
304 GET이나 HEAD에서 validator가 맞았다
400 헤더나 헤더 조합이 잘못됐다
401 인증하지 않았다
403 / 404 거부했거나, 존재를 숨기는 profile에서 숨겼다
409 상태, offset, lease 충돌
410 만료되거나 끝난(취소, 거부, 격리) 업로드 자원
411 require-content-length profile인데 길이가 없다
412 선행 조건 실패
413 크기나 할당량 정책 위반
415 업로드 media type을 받지 않는다
416 만족할 수 없는 Range. 실제 길이를 담는다
422 digest, 서명, 검사기 거부
429 전송 허가나 속도 제한
460 tus Upload-Checksum이 그 요청의 바이트와 맞지 않는다. 그 chunk는 버리고 offset은 움직이지 않는다
503 저장소나 검사기를 쓸 수 없다
504 하류 시간 초과
507 저장 용량이 없다

실패 본문

모든 실패는 애플리케이션의 오류 모양 하나인 Envelope(application/json)로 답한다. 안정된 code, 그 분류, 그 분류에 대한 공용 한국어 client 메시지, 그리고 error.details의 식별 값을 담는다.

{
  "success": false,
  "error": {
    "code": "UPLOAD_OFFSET_MISMATCH",
    "category": "CONFLICT",
    "message": "현재 상태에서는 요청을 처리할 수 없습니다.",
    "retryable": true,
    "details": {
      "uploadId": "...",
      "expectedOffset": 1024,
      "currentOffset": 2048
    }
  },
  "meta": { "requestId": "...", "traceId": "...", "correlationId": "..." }
}

details는 실패 context가 가진 것만 담는다: fileId, uploadId, expectedOffset, currentOffset, state, 그리고 참일 때만 ambiguous와 reconciliationRequired flag. 서버 쪽 예외 메시지는 절대 나오지 않는다. ambiguous는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다. retryable은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.

batch 업로드는 공용 bulk envelope다. 모든 part가 성공하면 success: true와 results[](part마다 clientPartId, status, fileId)다. 한 part라도 거부되면 success: false, error.code = BATCH_PARTIAL_FAILURE, error.details[]다. details[] 항목은 part 순서의 index, status(ok·error), 성공한 part의 id(fileId), 거부된 part의 code와 category 고정 문구 message다. 부분 실패에서 part는 요청에 보낸 순서의 index로 짚는다(clientPartId는 전부 성공한 results[]에만 있다). 성공한 part는 되돌리지 않는다.

Envelope 규칙의 프로토콜 예외

소유자 결정 2는 HTTP 오류 모양을 하나로 둔다. 아래 프로토콜 요소는 오류 어휘가 아니므로 프로토콜이 정한 대로 둔다(소유자 결정 12).

  • 성공이든 실패든 모든 tus 응답의 tus 프로토콜 헤더(Tus-Resumable, Upload-Offset, Upload-Length, …).
  • 실패 응답의 Retry-After와 만족하지 못한 range의 Content-Range(헤더 계약을 본다).
  • IETF resumable-upload draft의 offset 불일치 응답(Draft12UploadController#offsetMismatch): 409 application/problem+json, type = https://iana.org/assignments/http-problem-types#mismatching-upload-offset, expectedOffset과 providedOffset. Envelope가 아닌 실패 본문은 이것 하나뿐이다.

오류 코드

error.code는 FileserverErrorCode(application-fileserver)가 정한다. 아래 표가 그 전부이고, client는 이 값으로 분기한다. retryable은 그 code가 허락하는 최대치다. 실제 응답의 retryable은 그 발생에 대한 판단이라 true인 code도 false로 올 수 있다(위 「실패 본문」). Retry-After는 retryable인 발생에만 붙는다.

code status category retryable Retry-After 언제
BAD_REQUEST 400 VALIDATION false — 헤더나 헤더 조합이 잘못됐다
UNAUTHENTICATED 401 AUTH false — 인증하지 않았다
ACCESS_DENIED 403 AUTHZ false — 권한이 없다. 존재를 숨기는 profile에서는 FILE_NOT_FOUND로 온다
FILE_NOT_FOUND 404 NOT_FOUND false — 파일이 없거나 숨겼다
FILE_ALREADY_EXISTS 409 CONFLICT false — 대상 이름이 이미 있다(copy·move는 새로 만들기만 한다)
FILE_NOT_READY 409 CONFLICT true 2 검증이 끝나지 않아 아직 읽을 수 없다
UPLOAD_OFFSET_MISMATCH 409 CONFLICT true — 이어 쓰기 offset이 서버 offset과 다르다. details.currentOffset부터 다시 보낸다
CONCURRENT_MODIFICATION 409 CONFLICT true 1 같은 자원을 다른 요청이 바꾸는 중이다
UPLOAD_EXPIRED 410 CONFLICT false — 만료되거나 끝난(취소, 거부, 격리) 업로드다
CONTENT_LENGTH_REQUIRED 411 VALIDATION false — require-content-length profile인데 길이가 없다
PRECONDITION_FAILED 412 CONFLICT false — If-Match·If-Unmodified-Since가 맞지 않는다
FILE_TOO_LARGE 413 VALIDATION false — 파일 크기 정책을 넘었다
QUOTA_EXCEEDED 413 CONFLICT false — 저장 할당량을 넘었다
UNSUPPORTED_MEDIA_TYPE 415 VALIDATION false — 받지 않는 media type이다
RANGE_NOT_SATISFIABLE 416 VALIDATION false — Range를 만족할 수 없다. Content-Range: bytes */<길이>를 싣는다
INTEGRITY_MISMATCH 422 DATA_INTEGRITY false — 선언한 digest와 받은 바이트가 다르다
MALWARE_DETECTED 422 DATA_INTEGRITY false — 검사기가 거부했다
INVALID_PATH 422 VALIDATION false — 경로 형식이 틀렸다
PATH_OUTSIDE_NAMESPACE 422 VALIDATION false — 경로가 namespace 밖을 가리킨다
TRANSFER_ADMISSION_REJECTED 429 RATE_LIMIT true 1 호출자 자신의 동시 전송 permit이 찼다. 자기 전송이 끝나면 풀린다
CHECKSUM_MISMATCH 460 DATA_INTEGRITY false — tus Upload-Checksum이 그 요청의 바이트와 다르다. 그 chunk만 버린다
PARTIAL_WRITE 500 TRANSIENT_DEPENDENCY false — 쓰기가 중간에 끊겼다
AMBIGUOUS_COMPLETION 500 DATA_INTEGRITY false — 결과를 모른다. 이미 효과가 났을 수 있어 그대로 재시도하지 않는다
ATOMIC_PUBLISH_UNSUPPORTED 503 PERMANENT_DEPENDENCY false — 저장소가 원자적 게시를 지원하지 않는다(배포 설정 결함)
STORAGE_UNAVAILABLE 503 TRANSIENT_DEPENDENCY true 30 저장소나 검사기를 쓸 수 없다
SERVER_BUSY 503 TRANSIENT_DEPENDENCY true 1 instance 전체의 전송 permit이나 전송 worker pool이 찼다. 공용 서버 포화 코드와 같다
TRANSFER_TIMEOUT 504 TRANSIENT_DEPENDENCY true 5 전송이 시간 안에 끝나지 않았다
STORAGE_FULL 507 TRANSIENT_DEPENDENCY false — 저장 용량이 없다

헤더 계약

헤더 계약
Content-Type client 값은 주장일 뿐이다. 검증한 형식은 따로 저장한다
Content-Disposition 기본은 attachment. 스크립트가 될 수 있는 형식은 절대 inline이 아니다
Accept-Ranges bytes
Range 기본은 범위 하나. 여러 범위는 명시적 예산이 있을 때만
Content-Range 206에서는 실제 범위, 416에서는 만족하지 못한 형태
ETag SHA-256에서 만든 strong validator
Last-Modified metadata 게시 시각. 파일 시스템 timestamp가 아니다
Cache-Control 기본은 private, no-store
X-Content-Type-Options 다운로드에는 늘 nosniff
Retry-After 재시도할 수 있는 409, 429, 503, 504에 붙인다
X-Accel-Redirect 내부 전용. client에게 넘기지 않는다