Files
clean-architecture-backend-…/docs/fileserver/http-contract.md
T
DongHyeonka 6583cc2e02 docs(fileserver): 파일서버 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/fileserver 아래 살아 있는 문서 8개가 영어였다(language 예외). 번역하며
본 주장 중 지금 코드와 다른 것이 있었다.
- design-deviations.md: 지운 `FileStateMachine`·`FileserverStorageConfiguration`·
  content-store SPI 넷(`AsyncContentStore` 등)을 지금 있는 것처럼 적었다. 고정 테스트로
  없는 `SampleApplicationContextTest`·`LocalOrphanScanAdapterTest`·
  `FileserverRoundTripContractTest`를 댔다. JPA 저장소가 persistence-jpa에 있다고 했지만
  지금은 persistence-fileserver의 `FileserverJpaPersistenceConfig` 조건 하나 뒤에 있다.
  지운 reactive transport가 아직 스트리밍한다고 했다.
- security.md: 「익명 읽기를 켜면」이라고 했지만 설정 스위치가 없다
  (`FileserverSecurityConfiguration`이 늘 false로 만든다). 이름 `ContentDispositionFactory`는
  지금 `HttpContentDispositionFactory`다.
- upgrade-guide.md: batch 실패를 `results[].problem`으로, 결과 모름을 problem document로
  읽으라고 했다. 지금은 `results[].error`와 Envelope `error.details.ambiguous`다. 확인 명령이
  Fileserver 테스트가 없는 `:app-bootstrap:test --tests '*Fileserver*'`와 fileserver 코드가 없는
  `:application-core:check`·`:adapter:inbound:web:check`를 돌렸다.
- operations.md: 「NFS 결과 모름」 신호를 problem document로 적었다(지금은 Envelope).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 지원 등급
이름(Stable, Beta, Limited, Compatibility, Experimental)은 표와 테스트가 읽는 꼬리표라
원문으로 둔다(messaging 지원 매트릭스와 같다). configuration.md의 절 제목은 테스트가 읽는
「… — `key`」 꼴을 지킨다. 위 불일치는 코드에 맞춰 고쳤다.

테스트: FileserverDocumentationCoverageTest가 runbook 제목 일곱과 「Explicitly not
claimed」를 영어 문자열로 단언했다. 같은 계약(runbook마다 제목이 있고, 주장하지 않는 것을
따로 밝힌다)을 한국어 제목 `## 저장소 가득 참` 등과 `## 주장하지 않는 것`으로 단언한다.
제목 앞에 `## `를 붙여 본문 어딘가에 낱말만 있어도 통과하던 것을 제목으로 좁혔다.
metric 이름·CI job·endpoint·설정 key 단언은 그대로다.

버린 대안: runbook 제목을 영어로 남기기. 살아 있는 문서를 한국어로 쓴다는 소유자 결정과
맞지 않는다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 예외 줄 0). 테스트의 단언을 같은 정규식으로
문서에 돌려 보았다(runbook 제목·job 존재·설정 key 44개가 번역 전과 같음).
2026-11-07 17:29:57 +09:00

129 lines
6.5 KiB
Markdown

# 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` | part별 결과를 순서대로 준다. 명시적으로 원자적이지 않다 |
| 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`의 식별 값을 담는다.
```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`는 실패 context가 가진 것만 담는다: `fileId`, `uploadId`, `expectedOffset`, `currentOffset`, `state`,
그리고 참일 때만 `ambiguous`와 `reconciliationRequired` flag. 서버 쪽 예외 메시지는 절대 나오지 않는다.
`ambiguous`는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
`retryable`은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객체(`code`, `category`, `message`,
`retryable`)를 담는다.
### 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가 아닌 실패 본문은 이것 하나뿐이다.
## 헤더 계약
| 헤더 | 계약 |
|---|---|
| `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에게 넘기지 않는다 |