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개가 번역 전과 같음).
This commit is contained in:
DongHyeonka
2026-11-07 17:29:57 +09:00
parent 24eb1be36d
commit 6583cc2e02
10 changed files with 594 additions and 648 deletions
+138 -145
View File
@@ -1,209 +1,202 @@
# Fileserver configuration
# Fileserver 설정
Every key below lives under `app.fileserver-platform` (environment form
`APP_FILESERVER_PLATFORM_*`).
아래 key는 모두 `app.fileserver-platform` 아래에 있다(환경 변수 형태는 `APP_FILESERVER_PLATFORM_*`).
While `app.fileserver-platform.enabled` is false none of these keys is bound at all — the
auto-configuration that binds them is not processed — so a malformed value in a block nobody
enabled cannot fail a startup. Once enabled, binding is strict: an unknown key under the prefix is
refused rather than ignored. The defaults are the conservative ones: the
admin plane is off, background reclamation is on (leaving it off is what fills the volume), copies
and moves may only target the default namespace, and there is no permissive authorization fallback. Turning the capability on is a deliberate act, and so is every surface it
exposes.
`app.fileserver-platform.enabled`가 false인 동안에는 이 key들을 아예 바인딩하지 않는다. 바인딩하는
auto-configuration이 처리되지 않기 때문이다. 그래서 아무도 켜지 않은 블록의 잘못된 값이 시작을 실패시키지
않는다. 켜면 바인딩은 엄격하다. 접두사 아래의 모르는 key는 무시하지 않고 거부한다. 기본값은 보수적인 쪽이다.
## Minimum to start
- admin plane은 꺼져 있다.
- 백그라운드 회수는 켜져 있다(꺼 두면 volume이 찬다).
- copy와 move는 기본 namespace로만 쓸 수 있다.
- 권한을 느슨하게 풀어 주는 대체 경로는 없다.
capability를 켜는 것은 의도한 행동이고, 그것이 여는 면 하나하나도 그렇다.
## 시작에 필요한 최소 설정
```yaml
app:
fileserver-platform:
enabled: true
instance-id: ${HOSTNAME} # writer-lease owner; must be unique per node
instance-id: ${HOSTNAME} # writer lease 소유자. 노드마다 달라야 한다
storage:
root: /var/lib/backend/files # absolute, outside any webroot or config dir
root: /var/lib/backend/files # 절대 경로. webroot·설정 폴더 밖
security:
access-policy: role-based # or supply your own FileAccessPolicyPort bean
access-policy: role-based # 또는 직접 만든 FileAccessPolicyPort bean
observability:
fingerprint-key: ${FILESERVER_FINGERPRINT_KEY}
```
Startup fails, rather than degrading, when any of these is missing or unsafe:
아래 중 하나라도 빠지거나 안전하지 않으면 기능을 줄여 돌지 않고 시작이 실패한다.
| Condition | Why it is fatal |
| 조건 | 왜 치명적인가 |
| --- | --- |
| `security.access-policy` left at `required` with no `FileAccessPolicyPort` bean | a file capability that authorizes by default is worse than one that refuses to start |
| `observability.fingerprint-key` unset while metrics are on | an unkeyed digest of an enumerable identifier is reversible |
| the storage root fails a mandatory capability probe | a volume that cannot create atomically, keep staging and content on one FileStore, or refuse symlinks is unsafe, not degraded |
| `storage.publish-mode: atomic-move-required` on a volume where the probe could not prove an atomic move | the configured guarantee cannot be delivered |
| `security.access-policy: unenforced` under a `prod` profile | a value that was convenient in development must not survive promotion |
| `security.access-policy`가 `required`로 남았는데 `FileAccessPolicyPort` bean이 없다 | 기본으로 허락하는 파일 capability는 시작을 거부하는 것보다 나쁘다 |
| metric이 켜졌는데 `observability.fingerprint-key`가 없다 | 셀 수 있는 식별자를 key 없이 digest하면 되돌릴 수 있다 |
| 저장 루트가 필수 capability probe를 통과하지 못한다 | 원자적으로 만들지 못하거나, staging과 content를 한 FileStore에 두지 못하거나, symlink를 거부하지 못하는 volume은 기능이 줄어든 것이 아니라 안전하지 않은 것이다 |
| probe가 원자적 move를 증명하지 못한 volume에 `storage.publish-mode: atomic-move-required` | 설정한 보장을 지킬 수 없다 |
| `prod` profile에서 `security.access-policy: unenforced` | 개발 때 편했던 값이 승격까지 살아남으면 안 된다 |
## Authorization — `security`
## 권한 — `security`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `access-policy` | `required` | `required` (supply your own bean), `role-based`, or `unenforced` |
| `read-roles` | `ROLE_FILE_READ` | grants metadata read and download |
| `write-roles` | `ROLE_FILE_WRITE` | grants create, append, finalize, delete, copy, move |
| `admin-roles` | `ROLE_FILE_ADMIN` | grants reverify and force-delete, and gates `/internal/fileserver/**` at the servlet chain |
| `access-policy` | `required` | `required`(bean을 직접 준다), `role-based`, `unenforced` |
| `read-roles` | `ROLE_FILE_READ` | metadata 읽기와 다운로드를 허락한다 |
| `write-roles` | `ROLE_FILE_WRITE` | create, append, finalize, delete, copy, move를 허락한다 |
| `admin-roles` | `ROLE_FILE_ADMIN` | reverify와 force-delete를 허락하고, servlet chain에서 `/internal/fileserver/**`를 막는다 |
These roles decide the tier inside each operation. In front of it, every operation's use case
carries a `file:*` permission that the web adapter's method security checks against
`app.authz.role-permissions`; `security.yml` grants `file:read` to `ROLE_FILE_READ`,
`file:upload`, `file:delete`, `file:copy` and `file:move` to `ROLE_FILE_WRITE`, and `file:admin` to
`ROLE_FILE_ADMIN`. Renaming a tier role here means mapping the new name there as well, or the
caller is refused before the tier is consulted (`docs/fileserver/design-deviations.md` §5).
이 role들은 각 연산 안에서 등급(tier)을 정한다. 그 앞에서는 연산마다 use case가 `file:*` 권한을 가지고,
web 어댑터의 method security가 그 권한을 `app.authz.role-permissions`와 대조한다. `security.yml`은
`file:read`를 `ROLE_FILE_READ`에, `file:upload`·`file:delete`·`file:copy`·`file:move`를 `ROLE_FILE_WRITE`에,
`file:admin`을 `ROLE_FILE_ADMIN`에 준다. 여기서 등급 role의 이름을 바꾸면 거기서도 새 이름을 대응시켜야
한다. 아니면 등급을 보기도 전에 호출자가 거부된다(`docs/fileserver/design-deviations.md` §5).
There is no anonymous-read switch. Every Fileserver route is authenticated by the servlet chain
before any application policy is consulted, so such a setting could only ever have described a
permission the transport had already refused — a configuration that reads as if it grants access
and does not.
익명 읽기 스위치는 없다. 모든 Fileserver 경로는 애플리케이션 정책을 보기 전에 servlet chain이 인증한다.
그래서 그런 설정은 transport가 이미 거부한 권한을 설명할 수밖에 없다. 접근을 허락하는 것처럼 읽히지만
허락하지 않는 설정이 된다.
The three tiers do not inherit. An admin role cannot delete through the data plane, and a write role
cannot reach the management plane — a role model where "can delete" implied "can force-delete" would
make the audited plane reachable through the unaudited one.
세 등급은 서로 물려받지 않는다. admin role은 data plane으로 삭제할 수 없고, write role은 management plane에
닿을 수 없다. 「삭제할 수 있으면 강제 삭제도 할 수 있다」는 role 모델이면 감사하지 않는 plane을 거쳐 감사하는
plane에 닿게 된다.
`unenforced` authorizes everything and exists so a developer can exercise upload and download before
deciding on a role model. It is refused under a production profile.
`unenforced`는 모든 것을 허락한다. 개발자가 role 모델을 정하기 전에 업로드와 다운로드를 시험해 보라고 있는
값이다. 운영 profile에서는 거부한다.
## Storage — `storage`
## 저장소 — `storage`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `root` | `/var/lib/backend/files` | absolute path; the only place a path exists |
| `root` | `/var/lib/backend/files` | 절대 경로. 경로가 존재하는 유일한 곳 |
| `publish-mode` | `atomic-move-preferred` | `atomic-move-required`, `atomic-move-preferred`, `metadata-pointer` |
| `buffer-size` | `128KB` | bounds every transfer allocation; memory never scales with file size |
| `forbidden-root-ancestors` | `/app,/etc,/usr/share/nginx/html` | roots the storage root must not live under (webroot, config dirs) |
| `buffer-size` | `128KB` | 모든 전송 할당의 상한. 메모리는 파일 크기에 따라 늘지 않는다 |
| `forbidden-root-ancestors` | `/app,/etc,/usr/share/nginx/html` | 저장 루트가 그 아래 있으면 안 되는 root(webroot, 설정 폴더) |
`root` must be absolute. A relative root resolves against the process working directory, which is
one path in a container and another in a test, so it is refused at binding time.
`root`는 절대 경로여야 한다. 상대 경로는 프로세스 작업 폴더를 기준으로 풀리고, 그 폴더는 container와
테스트에서 다르다. 그래서 바인딩할 때 거부한다.
Three former keys are gone, pinned as constants instead: staging and content share one FileStore,
symbolic links are never followed, and the object and its directory are synced before READY. Each
is an invariant the atomic publish and the namespace boundary are built on — a deployment that
could switch one off would be running a different capability under the same name and the same
tests.
예전 key 셋은 없어지고 상수로 고정됐다: staging과 content는 FileStore 하나를 같이 쓴다, symbolic link는
절대 따라가지 않는다, 객체와 그 폴더는 READY 전에 sync한다. 셋 다 원자적 게시와 namespace 경계가 기대는
불변식이다. 그중 하나를 끌 수 있는 배포는 같은 이름과 같은 테스트로 다른 capability를 돌리는 셈이다.
The storage provider has no selector either. There is exactly one implementation, and a `type` key
with one legal value is a promise of pluggability that nothing keeps.
저장소 provider를 고르는 key도 없다. 구현이 정확히 하나이고, 허용 값이 하나뿐인 `type` key는 아무도
지키지 않는 교체 가능성의 약속이다.
## Upload, download, transfer
## 업로드, 다운로드, 전송
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `upload.max-file-size` | `100MB` | hard ceiling; also drives `spring.servlet.multipart.max-file-size` |
| `upload.max-request-size` | `110MB` | request envelope; must be at least `max-file-size` |
| `upload.initial-reservation` | `8MB` | quota reserved when the length is unknown |
| `upload.ttl` | `1h` | how long a resumable upload stays claimable |
| `upload.reservation-ttl` | `24h` | how long an unsettled quota reservation survives |
| `upload.lease-duration` | `30s` | writer lease; renewed at one third of this |
| `upload.max-parts` | `16` | multipart part ceiling |
| `upload.require-content-length` | `false` | refuse chunked raw uploads |
| `download.cache-control` | `private, no-store` | emitted on every content response |
| `download.inline-allowed` | `false` | scriptable content is always an attachment regardless |
| `download.max-ranges` | `1` | multi-range responses are opt-in |
| `download.max-range-bytes` | `100MB` | total bytes one ranged response may cover |
| `download.zero-copy-enabled` | `true` | hand large plaintext responses to the kernel |
| `download.zero-copy-minimum-bytes` | `16MB` | below this the syscall setup costs more than it saves |
| `transfer.core-size` / `max-size` / `queue-capacity` | `8` / `32` / `64` | blocking transfer pool bounds |
| `transfer.await-seconds` | `300` | how long a transfer may occupy a pool thread |
| `upload.max-file-size` | `100MB` | 넘을 수 없는 상한. `spring.servlet.multipart.max-file-size`도 이 값으로 정한다 |
| `upload.max-request-size` | `110MB` | 요청 전체 크기. `max-file-size` 이상이어야 한다 |
| `upload.initial-reservation` | `8MB` | 길이를 모를 때 예약하는 할당량 |
| `upload.ttl` | `1h` | 이어 올리기 업로드를 다시 잡을 수 있는 기간 |
| `upload.reservation-ttl` | `24h` | 정산하지 않은 할당량 예약이 남는 기간 |
| `upload.lease-duration` | `30s` | writer lease. 이 값의 1/3마다 갱신한다 |
| `upload.max-parts` | `16` | multipart part 개수 상한 |
| `upload.require-content-length` | `false` | chunked raw 업로드를 거부한다 |
| `download.cache-control` | `private, no-store` | 모든 content 응답에 붙인다 |
| `download.inline-allowed` | `false` | 스크립트가 될 수 있는 content는 이 값과 상관없이 늘 첨부 파일이다 |
| `download.max-ranges` | `1` | 여러 범위 응답은 켜야 생긴다 |
| `download.max-range-bytes` | `100MB` | 범위 응답 하나가 덮을 수 있는 총 바이트 |
| `download.zero-copy-enabled` | `true` | 큰 평문 응답을 kernel에 넘긴다 |
| `download.zero-copy-minimum-bytes` | `16MB` | 이보다 작으면 syscall 준비 비용이 아끼는 것보다 크다 |
| `transfer.core-size` / `max-size` / `queue-capacity` | `8` / `32` / `64` | blocking 전송 pool의 상한 |
| `transfer.await-seconds` | `300` | 전송 하나가 pool 스레드를 잡을 수 있는 시간 |
Zero copy changes no header and no status. When storage declines it — an unreadable region, an
unsupported backend — the response is streamed instead and is byte-identical.
zero copy는 헤더도 상태 코드도 바꾸지 않는다. 저장소가 거절하면(읽을 수 없는 영역, 지원하지 않는 backend)
응답을 스트리밍으로 보내고, 바이트는 똑같다.
## Verification — `verification`
## 검증 — `verification`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `timeout` | `5s` | per-verifier ceiling |
| `require-media-type-verdict` | `false` | refuse a file whose type could not be determined |
| `inline-safe-profile` | `false` | accept scriptable content instead of quarantining it |
| `timeout` | `5s` | 검증기 하나의 상한 |
| `require-media-type-verdict` | `false` | 형식을 정하지 못한 파일을 거부한다 |
| `inline-safe-profile` | `false` | 스크립트가 될 수 있는 content를 격리하지 않고 받는다 |
Set `inline-safe-profile: true` only when downloads are never served inline from a trusted origin.
`inline-safe-profile: true`는 다운로드를 믿을 수 있는 origin에서 inline으로 절대 내보내지 않을 때만 쓴다.
## Quota and admission — `quota`
## 할당량과 허가 — `quota`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `instance-upload-permits` | `16` | concurrent uploads this node admits |
| `scope-upload-permits` | `4` | concurrent uploads one caller (principal) admits; over it is a retryable `429` |
| `direct-download-permits` | `64` | concurrent non-delegated downloads |
| `soft-high-water` | `0.70` | storage fraction at which pressure is reported |
| `hard-high-water` | `0.85` | storage fraction at which uploads and copies are refused |
| `namespace-limit` | unset (unlimited) | most bytes one namespace may hold, live reservations plus committed usage; a create, copy or move that would pass it is refused with `QUOTA_EXCEEDED` (413) before any record, byte or namespace changes |
| `instance-upload-permits` | `16` | 이 노드가 받는 동시 업로드 수 |
| `scope-upload-permits` | `4` | 호출자(principal) 하나가 받는 동시 업로드 수. 넘으면 재시도할 수 있는 `429` |
| `direct-download-permits` | `64` | 위임하지 않은 동시 다운로드 수 |
| `soft-high-water` | `0.70` | 압박을 보고하기 시작하는 저장소 사용 비율 |
| `hard-high-water` | `0.85` | 업로드와 copy를 거부하는 저장소 사용 비율 |
| `namespace-limit` | 없음(제한 없음) | namespace 하나가 가질 수 있는 최대 바이트. 살아 있는 예약과 확정 사용량의 합이다. 이를 넘길 create, copy, move는 기록·바이트·namespace가 바뀌기 전에 `QUOTA_EXCEEDED`(413)로 거부한다 |
`namespace-limit` is checked against the usage the quota ledger reports and then reserved, in one
transaction but without a per-namespace lock: reservations admitted at the same moment can overshoot
the limit by at most their own size, and the next one is refused. A service that needs an exact cap
adds that lock in its persistence adapter.
`namespace-limit`은 할당량 ledger가 보고한 사용량과 비교한 뒤 예약한다. transaction 하나 안에서 하지만
namespace별 lock은 없다. 그래서 같은 순간에 허가된 예약들은 자기 크기만큼까지 한도를 넘을 수 있고, 그다음
예약은 거부된다. 정확한 상한이 필요한 서비스는 자기 persistence 어댑터에 그 lock을 더한다.
A move to another namespace carries the file's bytes in the ledger: in the transaction that relocates
the record it checks the target's limit, books the bytes as committed usage there and reclaims them
from the source. A refused move leaves the file, and both namespaces' usage, as they were.
다른 namespace로의 move는 ledger에서 파일의 바이트를 함께 옮긴다. 기록을 옮기는 transaction 안에서 대상의
한도를 확인하고, 대상 쪽에 확정 사용량으로 올리고, 원래 쪽에서 회수한다. 거부된 move는 파일과 두
namespace의 사용량을 그대로 둔다.
When the storage fraction cannot be read, admission treats it as unknown and does not apply the
high-water rule — a synthetic `0` would silently disable the guard, and a synthetic `1` would take
the capability down over a failed syscall.
저장소 사용 비율을 읽지 못하면 허가 단계는 그것을 모름으로 보고 high-water 규칙을 적용하지 않는다. 지어낸
`0`은 보호 장치를 조용히 끄고, 지어낸 `1`은 syscall 하나 실패로 capability를 내린다.
## Background reclamation — `cleanup`
## 백그라운드 회수 — `cleanup`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `enabled` | `true` | run the cleanup worker on this node; `false` logs a startup warning |
| `interval` | `60s` | fixed delay between batches, not fixed rate |
| `max-items` | `100` | items one batch may claim |
| `max-bytes` | `1GB` | bytes one batch may reclaim |
| `retry-backoff` | `5m` | how long a failed item waits before it is due again |
| `enabled` | `true` | 이 노드에서 cleanup worker를 돌린다. `false`면 시작할 때 경고를 남긴다 |
| `interval` | `60s` | batch 사이의 고정 지연. 고정 주기가 아니다 |
| `max-items` | `100` | batch 하나가 가져갈 수 있는 항목 수 |
| `max-bytes` | `1GB` | batch 하나가 회수할 수 있는 바이트 |
| `retry-backoff` | `5m` | 실패한 항목이 다시 차례가 될 때까지 기다리는 시간 |
The worker is on by default: it deletes only what the cleanup queue names, and without it cancelled
and expired staging, rejected and deleted content stay on the volume until the hard high-water mark
stops every upload. A node may turn it off — for instance when another node runs it — and startup
then logs a `WARN` naming `app.fileserver-platform.cleanup.enabled=false`. A node without it still
queues cleanup items; another node or an operator reclaims them. (A required "reason" key was
considered instead of the warning and rejected: it would be a setting whose only effect is to
silence startup, carried by every non-worker node.) An item that fails
eight times is abandoned rather than retried forever — it stays visible to an operator, parked
rather than discarded.
worker는 기본으로 켜져 있다. cleanup 큐가 이름 댄 것만 지운다. worker가 없으면 취소·만료된 staging, 거부·
삭제된 content가 hard high-water가 모든 업로드를 막을 때까지 volume에 남는다. 노드 하나가 worker를 끌 수
있다(예: 다른 노드가 돌릴 때). 그러면 시작할 때 `app.fileserver-platform.cleanup.enabled=false`를 이름 댄
`WARN`을 남긴다. worker가 없는 노드도 cleanup 항목을 큐에 넣는다. 다른 노드나 운영자가 회수한다. (경고 대신
필수 「이유」 key를 두는 안도 검토했지만 버렸다. 시작 경고를 끄는 것 말고는 효과가 없는 설정을 worker 아닌
모든 노드가 들고 다니게 된다.) 여덟 번 실패한 항목은 영원히 재시도하지 않고 내려놓는다. 버리지 않고 세워
두므로 운영자에게는 계속 보인다.
Each pass also expires uploads whose `expiresAt` has passed (the record becomes `EXPIRED` and its
staged bytes are queued), purges orphans the admin plane retired to quarantine, and runs
reconciliation over stale `UPLOADED`/`VERIFYING`/`FAILED` records, so an ambiguous publish settles
without an operator.
매 회차는 이런 일도 한다.
## Copy and move targets
- `expiresAt`이 지난 업로드를 만료시킨다(기록은 `EXPIRED`가 되고 staging 바이트는 큐에 들어간다).
- admin plane이 격리로 내린 고아 객체를 지운다.
- 오래된 `UPLOADED`/`VERIFYING`/`FAILED` 기록에 대해 맞춰 보기를 돌린다. 그래서 결과를 모르는 게시가 운영자
없이 정리된다.
`app.fileserver-platform.target-namespaces` (`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, a comma
list, empty by default) names the namespaces copy and move may write into besides
`default-namespace`, which is always allowed. The target namespace of a copy or a move comes from the request body, and a namespace is also the
quota grouping. Any other target is refused with `ACCESS_DENIED` before a byte moves or a
reservation is taken.
## Copy와 move 대상
`app.fileserver-platform.target-namespaces`(`APP_FILESERVER_PLATFORM_TARGET_NAMESPACES`, 쉼표 목록, 기본은
비어 있음)는 늘 허용되는 `default-namespace` 말고 copy와 move가 쓸 수 있는 namespace를 적는다. copy나 move의
대상 namespace는 요청 본문에서 오고, namespace는 할당량을 묶는 단위이기도 하다. 그 밖의 대상은 바이트가
움직이거나 예약을 잡기 전에 `ACCESS_DENIED`로 거부한다.
## Management plane — `admin`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `enabled` | `false` | expose `/internal/fileserver/**` |
| `orphan-minimum-age` | `1h` | how long an unreferenced object must exist before a scan may name it |
| `enabled` | `false` | `/internal/fileserver/**`를 연다 |
| `orphan-minimum-age` | `1h` | 참조 없는 객체가 scan에 이름이 오르기 전에 존재해야 하는 시간 |
Publishing content and committing its record are two steps. Anything younger than
`orphan-minimum-age` is assumed to be mid-commit rather than abandoned; shortening this makes
concurrent uploads look like orphans.
content를 게시하는 것과 그 기록을 확정하는 것은 두 단계다. `orphan-minimum-age`보다 어린 것은 버려진 것이
아니라 확정 중인 것으로 본다. 이 값을 줄이면 동시 업로드가 고아처럼 보인다.
## Front-proxy delegation — `nginx`
## 프런트 프록시 위임 — `nginx`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `enabled` | `false` | emit `X-Accel-Redirect` instead of a body |
| `internal-prefix` | `/__files/` | must be an `internal` location resolving to the content root |
| `object-suffix` | `.bin` | layout suffix the proxy appends |
| `minimum-size` | `16MB` | below this the application serves the transfer itself |
| `enabled` | `false` | 본문 대신 `X-Accel-Redirect`를 내보낸다 |
| `internal-prefix` | `/__files/` | content root로 풀리는 `internal` location이어야 한다 |
| `object-suffix` | `.bin` | 프록시가 붙이는 배치 접미사 |
| `minimum-size` | `16MB` | 이보다 작으면 애플리케이션이 직접 전송한다 |
Delegation is decided only after authorization and the READY gate, so an internal redirect can only
ever name content the caller was already allowed to read.
위임은 권한 확인과 READY 관문을 지난 뒤에만 정한다. 그래서 내부 redirect는 호출자가 이미 읽어도 되는
content만 가리킬 수 있다.
## Protocols — `tus`
## 프로토콜 — `tus`
| Key | Default | Meaning |
| Key | 기본값 | 뜻 |
| --- | --- | --- |
| `enabled` | `false` | expose the tus 1.0 endpoints |
| `enabled` | `false` | tus 1.0 endpoint를 연다 |
The HTTPbis resumable-upload draft-12 surface is experimental and documented in
[support-matrix.md](support-matrix.md).
HTTPbis resumable-upload draft-12 면은 실험 단계이고 [support-matrix.md](support-matrix.md)에 적었다.
+133 -148
View File
@@ -1,216 +1,201 @@
# Fileserver — deviations from the design
# Fileserver — 설계와 다른 곳
The design specification and the implementation plan are frozen documents. Where implementation
found them under-specified or self-contradicting, the resolution is recorded here rather than by
editing the specification, and every entry names the test that pins the decision.
설계 명세와 구현 계획서는 고정된 문서다. 구현하다 보니 명세가 덜 정해졌거나 스스로 모순인 곳이 있었다.
그 해결은 명세를 고치지 않고 여기 적는다. 항목마다 그 결정을 고정하는 테스트를 적는다.
## Resolved inconsistencies in the state machine and contracts
## 상태 기계와 계약에서 해결한 모순
### 1. `CREATED → FAILED` has no edge in the transition table
### 1. 전이 표에 `CREATED → FAILED` edge가 없다
A create that fails after the record exists must end in `FAILED`, but the table has no direct edge.
The record therefore walks `CREATED → UPLOADING → FAILED`, which is also the honest reading: the
upload had been admitted before it failed.
기록이 생긴 뒤 실패한 create는 `FAILED`로 끝나야 하는데, 표에 바로 가는 edge가 없다. 그래서 기록은
`CREATED → UPLOADING → FAILED`로 간다. 이것이 정직한 읽기이기도 하다. 업로드는 실패하기 전에 이미 허가됐다.
Pinned by `ResumableUploadUseCasesTest` (application-fileserver).
고정하는 테스트: `ResumableUploadUseCasesTest`(application-fileserver).
### 2. `ContentKey`'s alphabet admits a leading separator
### 2. `ContentKey`의 글자 집합이 맨 앞 구분자를 허락한다
The design's key pattern `[a-z0-9/_-]{16,200}` matches `/etc/passwd/...`. Rejecting an absolute path
at the value type would change a design-fixed contract, so the stricter shape check lives in
`PhysicalPathResolver`, per §12.2 rule 1 — the only place that turns an identifier into a path.
설계의 key 패턴 `[a-z0-9/_-]{16,200}`은 `/etc/passwd/...`에 맞는다. 값 타입에서 절대 경로를 거부하면 설계가
고정한 계약이 바뀐다. 그래서 더 엄격한 모양 검사는 §12.2 규칙 1에 따라 `PhysicalPathResolver`에 둔다.
식별자를 경로로 바꾸는 유일한 곳이다.
Pinned by `PhysicalPathResolverTest`.
고정하는 테스트: `PhysicalPathResolverTest`.
### 3. `VERIFYING → DELETING` has no edge
### 3. `VERIFYING → DELETING` edge가 없다
Deleting a file that is mid-verification has no legal transition. The lifecycle service refuses it
with `409 FILE_NOT_READY` rather than inventing an edge, which matches the allowed-state list the
JPA `markDeleting` statement already enforced.
검증 중인 파일을 지우는 합법적 전이가 없다. lifecycle 서비스는 edge를 지어내지 않고 `409 FILE_NOT_READY`로
거부한다. JPA `markDeleting` 문이 이미 강제하던 허용 상태 목록과 같다.
Pinned by `FileLifecycleUseCasesTest`.
고정하는 테스트: `FileLifecycleUseCasesTest`.
### 4. `If-Match` is specified as an ETag but the lifecycle was designed around the row version
### 4. `If-Match`는 ETag로 정해졌는데 lifecycle은 행 version을 기준으로 설계됐다
The HTTP contract sends an entity tag; the metadata store guards on a numeric version. The service
takes `Optional<String> expectedEtag` and compares against the record's strong validator, so the
precondition a client sends is the precondition that is checked.
HTTP 계약은 entity tag를 보내고, metadata 저장소는 숫자 version으로 막는다. 서비스는
`Optional<String> expectedEtag`를 받아 기록의 strong validator와 비교한다. 그래서 client가 보낸 선행 조건이
곧 검사하는 선행 조건이다.
Pinned by `FileLifecycleUseCasesTest`.
고정하는 테스트: `FileLifecycleUseCasesTest`.
### 5. The filename policy left `:` intact
### 5. 파일 이름 정책이 `:`를 남겼다
`C:\Windows\system.ini` sanitized to `C:Windowssystem.ini` — a drive-qualified name surviving into
display text and headers. `:` joined the structural strip set.
`C:\Windows\system.ini`가 `C:Windowssystem.ini`로 정리됐다. 드라이브가 붙은 이름이 표시 문자열과 헤더까지
살아남았다. `:`를 구조 문자 제거 집합에 넣었다.
Pinned by `FileserverHardeningContractTest` and `AmbiguousFilesystemOperationDetectorTest`.
고정하는 테스트: `FileserverHardeningContractTest`, `AmbiguousFilesystemOperationDetectorTest`.
## Additions the design implies but does not specify
## 설계가 암시하지만 정하지 않은 추가
### 6. `fs_recovery_item`
§10.2 lists five core tables and none of them can hold the recovery queue, yet §29.3 requires one:
reconciliation reports files whose bytes and metadata disagree, and holding that list in memory
would lose exactly the cases a restart interrupted. Added in
`V2__fileserver_recovery_and_staging_cleanup.sql` with one open item per file, so repeated sweeps
update a worklist rather than accumulating a log.
§10.2는 핵심 테이블 다섯을 나열하는데 그중 어느 것도 복구 큐를 담을 수 없다. 그런데 §29.3은 복구 큐를
요구한다. 맞춰 보기는 바이트와 metadata가 어긋나는 파일을 보고하는데, 그 목록을 메모리에 두면 재시작이 끊은
바로 그 경우를 잃는다. `V2__fileserver_recovery_and_staging_cleanup.sql`에서 더했다. 파일마다 열린 항목은
하나다. 그래서 같은 정리를 반복해도 로그가 쌓이지 않고 작업 목록이 갱신된다.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest`.
고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`.
### 7. `fs_cleanup_item.upload_id`
A staging object is addressed by upload, not by file. Without this column a queued staging cleanup
could name only already-published content, so a cancelled or expired upload left bytes nothing could
find. Added in the same migration, with a check constraint that an item names exactly one target.
staging 객체는 파일이 아니라 업로드로 가리킨다. 이 열이 없으면 큐에 넣은 staging 정리가 이미 게시된
content만 가리킬 수 있어서, 취소·만료된 업로드는 아무도 찾지 못하는 바이트를 남겼다. 같은 마이그레이션에서
더했고, 항목이 대상 정확히 하나를 가리키는지 check 제약을 둔다.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest`.
고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`.
### 8. `ContentReferenceLedgerPort` and `StagingUploadLocatorPort`
### 8. `ContentReferenceLedgerPort`와 `StagingUploadLocatorPort`
The orphan scan must ask whether a record still claims a physical object, and reconciliation must
map a file back to the upload that last staged it. Neither question is answerable through the
design's `FileMetadataPort` or `UploadSessionPort` as written. Rather than widen those
design-fixed interfaces, both are narrow single-method ports.
고아 scan은 어떤 기록이 아직 물리 객체를 가리키는지 물어야 하고, 맞춰 보기는 파일을 마지막으로 staging한
업로드로 되짚어야 한다. 설계에 적힌 그대로의 `FileMetadataPort`나 `UploadSessionPort`로는 어느 질문에도
답할 수 없다. 설계가 고정한 interface를 넓히지 않고, 둘 다 메서드 하나짜리 좁은 port로 만들었다.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest` and `LocalOrphanScanAdapterTest`.
고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`, `LocalOrphanScanTest`.
## Interpretations
## 해석
### 9. Quota settlement is FIFO within a scope
### 9. 할당량 정산은 범위 안에서 FIFO다
Nothing links a reservation row to the upload that took it, and the design deliberately reclaims
stragglers by TTL and the `STALE_QUOTA_RESERVATION` cleanup type rather than threading a reservation
id through the upload session. `QuotaCommitPort` therefore settles the oldest live reservation in
the file's namespace.
예약 행과 그것을 잡은 업로드를 잇는 것이 없다. 그리고 설계는 upload session에 예약 id를 끼워 넣지 않고
TTL과 `STALE_QUOTA_RESERVATION` cleanup 유형으로 남은 것을 회수한다. 그래서 `QuotaCommitPort`는 그 파일의
namespace에서 가장 오래된 살아 있는 예약을 정산한다.
Which row closes does not change any quota decision: enforcement sums reserved and committed bytes
per scope and never reads an individual row. Concurrent uploads of different sizes can leave the
reserved total transiently high or low, and it converges as each settles. Durable usage with no live
reservation behind it — an upload that outlived its TTL — is still recorded, because a ledger that
silently under-counts is worse than one that is briefly imprecise.
어느 행이 닫히는지는 할당량 판단을 바꾸지 않는다. 강제는 범위별로 예약·확정 바이트를 합하고 행 하나하나는
읽지 않는다. 크기가 다른 동시 업로드는 예약 합계를 잠깐 높거나 낮게 남길 수 있고, 각각 정산되면서 맞춰진다.
뒤에 살아 있는 예약이 없는 확정 사용량(TTL보다 오래 걸린 업로드)도 기록한다. 조용히 덜 세는 ledger는 잠깐
부정확한 ledger보다 나쁘다.
Pinned by `PostgreSqlFileserverReclamationIntegrationTest`.
고정하는 테스트: `PostgreSqlFileserverReclamationIntegrationTest`.
### 10. Zero copy is a channel transfer, not a file handoff
### 10. Zero copy는 파일 넘기기가 아니라 channel 전송이다
Task 22 asks for zero copy on local files; §19 forbids a `Path` leaving the storage adapter, and §5
of the plan forbids adding `Path` to the content store. WebFlux's zero-copy API takes a `Path`, so
that route is closed.
계획서 Task 22는 로컬 파일에 zero copy를 요구한다. 그런데 §19는 `Path`가 저장소 어댑터를 떠나는 것을 금하고,
계획서 §5는 content store에 `Path`를 더하는 것을 금한다. WebFlux의 zero-copy API는 `Path`를 받으므로 그 길은
닫혀 있다.
The servlet path takes the other one: `ZeroCopyDownloadPort` receives a `WritableByteChannel` from
the transport and the storage adapter performs `FileChannel.transferTo` into it. That is a genuine
kernel-level transfer with no filesystem concept leaving storage. The reactive path continues to
stream with bounded demand.
servlet 경로는 다른 길을 쓴다. `ZeroCopyDownloadPort`는 transport에서 `WritableByteChannel`을 받고, 저장소
어댑터가 그 안으로 `FileChannel.transferTo`를 한다. 파일 시스템 개념이 저장소를 떠나지 않는 진짜 kernel 수준
전송이다. reactive transport는 2026-09-25에 지웠다([support-matrix.md](support-matrix.md)).
Zero copy is an optimization with no observable difference: when storage declines, the response is
streamed and is byte-identical.
zero copy는 관측 가능한 차이가 없는 최적화다. 저장소가 거절하면 응답은 스트리밍되고 바이트는 똑같다.
Pinned by `LocalStorageGatewayContractTest` and `ZeroCopyEligibilityTest`.
고정하는 테스트: `LocalStorageGatewayContractTest`, `ZeroCopyEligibilityTest`.
### 11. The Fileserver JPA stores are gated on the capability switch
### 11. Fileserver JPA 저장소는 capability 스위치 뒤에 있다
The metadata store, session store, quota service, queues, ledger, and staging locator carry
`@ConditionalOnProperty(app.fileserver-platform.enabled)` even though the rest of
`adapter:outbound:persistence-jpa` is unconditional.
metadata 저장소, session 저장소, 할당량 서비스, 큐, ledger, staging locator는 `adapter:outbound:persistence-fileserver`
leaf에 있다. 그 leaf의 auto-configuration root `FileserverJpaPersistenceConfig`가
`@ConditionalOnProperty(app.fileserver-platform.enabled)` 하나로 entity 스캔, Spring Data repository, 저장소
bean을 모두 가린다.
게이트가 없으면 persistence 모듈을 포함한 조립 루트는 Fileserver를 쓰지 않아도 이 bean들을 만들고, 그 bean마다
Fileserver 설정만 주는 협력 객체가 필요하다. That is the same rule the design states for the transport
surface, applied to persistence: no surface appears merely because the dependency is present.
이 관문이 없으면 persistence 모듈을 포함한 조립 루트는 Fileserver를 쓰지 않아도 이 bean들을 만들고, 그
bean마다 Fileserver 설정만 주는 협력 객체가 필요하다. 설계가 transport 면에 대해 말한 규칙을 persistence에
적용한 것이다: 의존성이 있다는 이유만으로 면이 나타나지 않는다.
`FileStateMachine` is bound alongside them, in `FileserverStorageConfiguration`. It had no
production binding at all before, which made the metadata store unconstructible in any
component-scanned context.
예전의 `FileStateMachine` bean은 지웠다. 상태 전이 검사는 `FileState.canTransitionTo`가 한다
(`docs/capability-status.md` 「제거된 코드」).
Pinned by `SampleApplicationContextTest` (the capability off) and
`FileserverRuntimeAssemblyTest` (the capability on).
고정하는 테스트: `FileserverPersistenceActivationTest`(스캔이 스위치 뒤에 있음),
`FileserverRuntimeAssemblyTest`(capability를 켬), `FileStateTransitionTest`(전이 표).
### 12. Transaction boundaries are owned by the application services, and are deliberately narrow
### 12. Transaction 경계는 애플리케이션 서비스가 갖고, 일부러 좁다
The design does not say where a transaction begins. The repository does:
`adapter:outbound:persistence-jpa` forbids a repository adapter from owning a `@Transactional`
boundary, and `application-core` owns them through `TransactionPort`. The Fileserver follows that
rule — every `Jpa*` store here declares no `@Transactional` of its own.
설계는 transaction이 어디서 시작하는지 말하지 않는다. 저장소가 말한다. `adapter:outbound:persistence-jpa`는
repository 어댑터가 `@Transactional` 경계를 갖는 것을 금하고, `application-core`가 `TransactionPort`로 경계를
가진다. Fileserver도 이 규칙을 따른다. 여기 있는 `Jpa*` 저장소는 자기 `@Transactional`을 선언하지 않는다.
What is specific to this capability is how narrow the boundaries are. A boundary covers a contiguous
run of metadata writes and **stops before every storage call**, because a filesystem operation
inside a database transaction would hold a connection for the length of a byte transfer. The upload
path therefore has three boundaries, not one: acquire the lease, transfer the bytes, commit the
offset.
이 capability에 특별한 것은 경계가 얼마나 좁은가다. 경계 하나는 이어진 metadata 쓰기를 덮고 **저장소 호출
앞에서 늘 멈춘다**. DB transaction 안의 파일 시스템 작업은 바이트 전송 시간 내내 connection을 잡기 때문이다.
그래서 업로드 경로의 경계는 하나가 아니라 셋이다: lease 잡기, 바이트 전송, offset 확정.
Where several stores must agree, they share one boundary:
여러 저장소가 함께 맞아야 하는 곳은 경계 하나를 같이 쓴다.
| Unit | Why it is one boundary |
| 단위 | 경계 하나인 이유 |
| --- | --- |
| reserve quota + insert record + create session | a reservation that outlived a failed insert holds capacity for a file that never existed |
| READY transition + quota commit | a finished file whose reservation was never converted holds capacity until the reservation expires |
| `markDeleting` + enqueue cleanup | a file that stopped being reachable with nothing queued to reclaim it is never collected |
| content delete settlement: reclaim + retire record + close queue item | half of it leaves the item to be retried against content that no longer exists |
| 할당량 예약 + 기록 insert + session 생성 | insert가 실패한 뒤 남은 예약은 존재한 적 없는 파일의 용량을 잡는다 |
| READY 전이 + 할당량 확정 | 예약이 확정으로 바뀌지 않은 완료 파일은 예약이 만료될 때까지 용량을 잡는다 |
| `markDeleting` + cleanup 큐 넣기 | 닿을 수 없게 됐는데 회수할 항목이 큐에 없는 파일은 영영 수거되지 않는다 |
| content 삭제 정산: 회수 + 기록 내리기 + 큐 항목 닫기 | 절반만 되면 이미 없는 content를 대상으로 항목이 재시도된다 |
What this cannot make atomic is the storage/metadata seam itself — no database boundary could. That
seam is exactly what the ambiguous-completion path and the reconciler exist for, and the one
hand-written compensation that remains (staging creation failing after the records committed) is
there for the same reason.
이렇게 해도 저장소/metadata 이음매 자체는 원자적으로 만들 수 없다. 어떤 DB 경계도 못 한다. 그 이음매 때문에
결과를 모르는 완료 경로와 맞춰 보기가 있다. 남은 손으로 쓴 보상 하나(기록이 확정된 뒤 staging 생성이 실패한
경우)도 같은 이유로 있다.
Pinned by `FileserverRoundTripContractTest` against real PostgreSQL; the application tests use
`DirectTransactions`, which runs a boundary inline and counts it.
고정하는 테스트: 애플리케이션 테스트는 경계를 그 자리에서 돌리며 세는 `DirectTransactions`를 쓴다. 실제
PostgreSQL에서 조립 전체는 `FileserverCompositionIntegrationTest`(app-bootstrap `integrationTest`)가 돈다.
예전에 이 경계를 실제 PostgreSQL에서 고정하던 `FileserverRoundTripContractTest`는 지금 없다.
## Not implemented
## 구현하지 않은 것
### `AsyncContentStore`, `CapacityAwareContentStore`, `CopyCapableContentStore`, `DelegatedDownloadStore`
Four optional content-store SPIs are declared in `application-core` with no implementation. Each is
an extension point for a backend this template does not ship:
`application-fileserver`에 구현 없이 선언돼 있던 선택 content-store SPI 넷이다. 구현도 호출도 없어서 지웠다
(`docs/capability-status.md` 「제거된 코드」). 각각 이 템플릿이 내놓지 않는 backend를 위한 확장 지점이었다.
- `AsyncContentStore` — for a backend whose native client is non-blocking. The local platform is
blocking, and the reactive transport bridges to it on a dedicated I/O scheduler.
- `CapacityAwareContentStore` — capacity is reported through `StorageHealthPort` and
`StorageUsagePort`, which the local platform implements.
- `CopyCapableContentStore` — server-side copy is delivered by `CopyContentPort`; the local
platform has no cheaper primitive than a streamed copy.
- `DelegatedDownloadStore` — delegation is delivered at the transport boundary by the nginx
`X-Accel-Redirect` strategy, which needs no store participation.
- `AsyncContentStore` — native client가 non-blocking인 backend용. 로컬 플랫폼은 blocking이다.
- `CapacityAwareContentStore` — 용량은 로컬 플랫폼이 구현하는 `StorageHealthPort`와 `StorageUsagePort`로
보고한다.
- `CopyCapableContentStore` — 서버 쪽 copy는 `CopyContentPort`가 한다. 로컬 플랫폼에는 스트리밍 copy보다 싼
방법이 없다.
- `DelegatedDownloadStore` — 위임은 transport 경계에서 nginx `X-Accel-Redirect` 전략이 한다. 저장소가 끼어들
필요가 없다.
`ContentStoreCapabilities` reports what the running store actually supports, so no unimplemented SPI
is advertised as available.
`ContentStoreCapabilities`가 실행 중인 저장소가 실제로 지원하는 것을 보고한다. 그래서 구현하지 않은 것을 쓸 수
있다고 광고하지 않는다.
## The repository's application-layer contract
## 저장소의 애플리케이션 계층 계약
### 5. Fileserver operations are use cases (resolved, owner decision 32)
### 5. Fileserver 연산은 use case다 (해결됨, 소유자 결정 32)
Every operation the transport reaches is a `CommandUseCase` or `QueryUseCase` behind a one-method
port in `application.fileserver.port.in` — create, append, status, cancel, finalize and the
single-request upload; describe, prepare, open and transfer for downloads; delete, copy and move;
and the eight management-plane operations. Each implementation (`*ApplicationUseCase`) declares its
`@UseCaseCapability`, so the ArchUnit rules that check transaction mode, repository access and
outbound calls now see the Fileserver like every other feature.
transport가 닿는 모든 연산은 `application.fileserver.port.in`의 메서드 하나짜리 port 뒤에 있는
`CommandUseCase`나 `QueryUseCase`다.
Two authorities guard a write, and both stay:
- 업로드: create, append, status, cancel, finalize, 요청 하나짜리 업로드
- 다운로드: describe, prepare, open, transfer
- delete, copy, move
- management plane 연산 여덟
| Check | Where | Decides |
구현(`*ApplicationUseCase`)마다 `@UseCaseCapability`를 선언한다. 그래서 transaction 방식, repository 접근,
외부 호출을 검사하는 ArchUnit 규칙이 이제 Fileserver를 다른 기능과 똑같이 본다.
쓰기를 막는 권한은 둘이고, 둘 다 남는다.
| 검사 | 위치 | 정하는 것 |
| --- | --- | --- |
| `@RequiresPermission("file:…")` | the use case's proxy, enforced by the web adapter's method security | whether the caller's roles grant the operation at all |
| `FileAccessPolicyPort` | inside the use case, before any side effect | the tier (read/write/admin), and that the caller owns the file in its tenant |
| `@RequiresPermission("file:…")` | use case의 proxy. web 어댑터의 method security가 강제한다 | 호출자의 role이 그 연산을 아예 허락하는지 |
| `FileAccessPolicyPort` | use case 안, 부수 효과 전 | 등급(read/write/admin), 그리고 호출자가 자기 tenant에서 그 파일의 소유자인지 |
The permissions are `file:read` (describe, download, upload status), `file:upload` (create,
append, finalize, cancel, the single-request upload), `file:delete`, `file:copy`, `file:move` and
`file:admin` (every management-plane operation). `security.yml` grants them to `ROLE_FILE_READ`,
`ROLE_FILE_WRITE` and `ROLE_FILE_ADMIN` — the fileserver's own default tier roles — so a caller
holding a tier holds its permissions. A deployment that renames the tier roles, or supplies its own
`FileAccessPolicyPort` under other role names, maps those names in
`app.authz.role-permissions` too; `security.access-policy: unenforced` relaxes only the
tier and ownership check, never the permission gate.
권한은 `file:read`(describe, 다운로드, 업로드 상태), `file:upload`(create, append, finalize, cancel, 요청
하나짜리 업로드), `file:delete`, `file:copy`, `file:move`, `file:admin`(모든 management plane 연산)이다.
`security.yml`은 이 권한을 fileserver 자신의 기본 등급 role인 `ROLE_FILE_READ`, `ROLE_FILE_WRITE`,
`ROLE_FILE_ADMIN`에 준다. 그래서 등급을 가진 호출자는 그 권한도 가진다. 등급 role 이름을 바꾸거나 다른 role
이름으로 자기 `FileAccessPolicyPort`를 주는 배포는 `app.authz.role-permissions`에도 그 이름을 대응시킨다.
`security.access-policy: unenforced`는 등급과 소유 검사만 풀고 권한 관문은 절대 풀지 않는다.
The resumable transfers run on the transfer pool, and method security reads the security context
of the calling thread, so `BlockingTransferExecutor` carries the request's context onto the worker
(`BlockingTransferExecutorSecurityContextTest`). Without it an authenticated append was refused as
anonymous.
이어 올리기 전송은 전송 pool에서 돌고, method security는 호출한 스레드의 security context를 읽는다. 그래서
`BlockingTransferExecutor`가 요청의 context를 worker로 옮긴다(`BlockingTransferExecutorSecurityContextTest`).
이것이 없으면 인증한 append가 익명으로 거부됐다.
What is not a use case is what no transport calls: `CleanupService` and
`FileReconciliationService` are driven by background workers with no caller identity, and a
mutating use case must declare a permission a scheduler could not hold.
`FileserverUseCaseContractDeviationTest` freezes that list.
The HTTP status vocabulary on `FileserverErrorCode` stays in the application layer, for the reason
this section used to give: the servlet transport and the Nginx delegation path must not answer the
same failure with different statuses.
use case가 아닌 것은 어떤 transport도 부르지 않는 것이다. `CleanupService`와 `FileReconciliationService`는
호출자 신원이 없는 백그라운드 worker가 돌린다. 상태를 바꾸는 use case는 scheduler가 가질 수 없는 권한을
선언해야 한다. `FileserverUseCaseContractDeviationTest`가 그 목록을 고정한다.
`FileserverErrorCode`의 HTTP 상태 어휘는 애플리케이션 계층에 남는다. 이 절이 예전에 든 이유 그대로다:
servlet transport와 Nginx 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.
+77 -82
View File
@@ -1,35 +1,34 @@
# Fileserver HTTP contract
# Fileserver HTTP 계약
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.
모든 공개 endpoint를 여기 적는다. `FileserverDocumentationCoverageTest`가 controller를 훑어서 빠진 것이 있으면
실패하므로, 이 파일은 코드보다 조용히 뒤처질 수 없다.
## Public endpoints
## 공개 endpoint
| Method | Path | Success | Notes |
| Method | Path | 성공 | 비고 |
|---|---|---|---|
| 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 |
| 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 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 |
| 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. 기본으로 꺼져 있다 |
## Management endpoints
## 관리 endpoint
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.
`app.fileserver-platform.enabled=true`와 `app.fileserver-platform.admin.enabled=true`가 둘 다 있을 때만 닿는다.
servlet chain에서 `app.fileserver-platform.security.admin-roles`로 막고, 공개 port가 아니라 관리 port에 두라고
만든 것이다.
| Method | Path |
|---|---|
@@ -42,38 +41,37 @@ port rather than the public one.
| 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 |
| `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` | 저장 용량이 없다 |
## 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`:
모든 실패는 애플리케이션의 오류 모양 하나인 `Envelope`(`application/json`)로 답한다. 안정된 code, 그 분류,
그 분류에 대한 공용 한국어 client 메시지, 그리고 `error.details`의 식별 값을 담는다.
```json
{
@@ -94,40 +92,37 @@ identifying values in `error.details`:
}
```
`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.
`details`는 실패 context가 가진 것만 담는다: `fileId`, `uploadId`, `expectedOffset`, `currentOffset`, `state`,
그리고 참일 때만 `ambiguous`와 `reconciliationRequired` flag. 서버 쪽 예외 메시지는 절대 나오지 않는다.
`ambiguous`는 client가 재시도 전에 읽어야 하는 필드다. 결과를 모르는 실패는 이미 효과가 났을 수 있다.
`retryable`은 이번 발생에 대한 판단이고, 그 code가 허락하는 범위보다 넓어지지 않는다.
A batch upload part that is rejected carries the same `error` object (`code`, `category`,
`message`, `retryable`) in its `results[]` entry.
batch 업로드에서 거부된 part는 `results[]` 항목에 같은 `error` 객체(`code`, `category`, `message`,
`retryable`)를 담는다.
### Protocol exceptions to the Envelope rule
### Envelope 규칙의 프로토콜 예외
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):
소유자 결정 2는 HTTP 오류 모양을 하나로 둔다. 아래 프로토콜 요소는 오류 어휘가 아니므로 프로토콜이 정한
대로 둔다(소유자 결정 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.
- 성공이든 실패든 모든 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가 아닌 실패 본문은 이것 하나뿐이다.
## 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 |
| `Content-Type` | client 값은 주장일 뿐이다. 검증한 형식은 따로 저장한다 |
| `Content-Disposition` | 기본은 `attachment`. 스크립트가 될 수 있는 형식은 절대 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 |
| `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에게 넘기지 않는다 |
+66 -76
View File
@@ -1,14 +1,14 @@
# Fileserver runbooks
# Fileserver runbook
Each runbook names the exact metric that fires it and the exact command that resolves it. A runbook
whose trigger is "someone noticed" is not actionable, so every one below starts from a signal.
runbook마다 그것을 시작하게 하는 metric과 그것을 해결하는 명령을 정확히 적는다. 시작 조건이 「누가 알아챘다」인
runbook은 대응할 수 없다. 그래서 아래 runbook은 모두 신호에서 시작한다.
## Storage full
## 저장소 가득 참
**Signal** — `fileserver.quota{result="rejected"}` rising, or `507` responses appearing.
**신호** — `fileserver.quota{result="rejected"}`가 오르거나 `507` 응답이 나온다.
Storage capacity is exhausted or the high-water guard tripped. Uploads are rejected before any bytes
are written, so nothing is corrupt; the system is refusing work it cannot complete.
저장 용량이 바닥났거나 high-water 보호 장치가 걸렸다. 업로드는 바이트를 쓰기 전에 거부되므로 망가진 것은
없다. 시스템이 끝낼 수 없는 일을 거절하고 있을 뿐이다.
```bash
curl -s $ADMIN/internal/fileserver/storage-health | jq '.usedFraction, .usableBytes'
@@ -16,71 +16,68 @@ curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxByte
curl -s "$ADMIN/internal/fileserver/orphans?limit=200" | jq '[.[].sizeBytes] | add'
```
Drain the cleanup backlog first — it reclaims space the system already knows is dead. Only then
consider an orphan reconcile, and start with a dry run.
cleanup 적체부터 비운다. 시스템이 이미 죽은 것으로 아는 공간을 되찾는다. 그다음에야 고아 맞춰 보기를
생각하고, dry run부터 한다.
## Orphan growth
## 고아 객체 증가
**Signal** — `fileserver.cleanup{result="skipped"}` climbing, or the orphan scan returning more
objects each run.
**신호** — `fileserver.cleanup{result="skipped"}`가 오르거나, 고아 scan이 돌 때마다 더 많은 객체를 돌려준다.
Physical objects exist with no metadata record pointing at them. This is not immediately dangerous —
nothing serves them — but it consumes capacity indefinitely.
물리 객체는 있는데 그것을 가리키는 metadata 기록이 없다. 당장 위험하지는 않다. 아무것도 그것을 내보내지
않는다. 하지만 용량을 끝없이 먹는다.
```bash
# Always look first. A reconcile without dryRun=false is a plan, not an action.
# 늘 먼저 본다. dryRun=false가 없는 reconcile은 실행이 아니라 계획이다.
curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \
-H 'content-type: application/json' -d '{"limit":100}' | jq '.candidates'
# Apply only the fingerprints you were just shown.
# 방금 본 fingerprint만 적용한다.
curl -s -X POST "$ADMIN/internal/fileserver/orphans:reconcile" \
-H 'content-type: application/json' \
-d '{"dryRun":false,"limit":100,"maxBytes":1073741824,
"expectedFingerprints":["<from the dry run>"],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}'
"expectedFingerprints":["<dry run이 보여 준 값>"],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}'
```
Echoing the fingerprints is the safety property: an object that changed between the scan and the
apply is skipped rather than deleted.
fingerprint를 되돌려 보내는 것이 안전 장치다. scan과 적용 사이에 바뀐 객체는 지우지 않고 건너뛴다.
## Verification backlog
## 검증 적체
**Signal** — `fileserver.verification.queue{age_bucket="old"}` non-zero, or files sitting in
VERIFYING.
**신호** — `fileserver.verification.queue{age_bucket="old"}`가 0이 아니거나, 파일이 VERIFYING에 머문다.
A verifier is slow or unavailable. Files stay non-public, which is the correct failure direction: a
`RETRY` verdict never becomes an `ACCEPT`.
검증기가 느리거나 쓸 수 없다. 파일은 공개되지 않은 채 남는다. 맞는 실패 방향이다. `RETRY` 판정은 절대
`ACCEPT`가 되지 않는다.
```bash
curl -s $ADMIN/internal/fileserver/capabilities | jq '.storageType'
# Once the verifier is healthy, quarantined files can be re-examined individually.
# 검증기가 회복되면 격리된 파일을 하나씩 다시 검사할 수 있다.
curl -s -X POST "$ADMIN/internal/fileserver/files/$FILE_ID:reverify"
```
Do not clear the backlog by disabling verification. A file that reached READY without an accepting
verdict cannot be distinguished later from one that was verified.
검증을 꺼서 적체를 비우지 않는다. 받아들이는 판정 없이 READY가 된 파일은 나중에 검증받은 파일과 구분할 수
없다.
## NFS ambiguity
## NFS 결과 모름
**Signal** — problem documents carrying `"ambiguous": true`, or
`fileserver.transfer.interruption{reason="stale_handle"}`.
**신호** — 실패 Envelope의 `error.details`에 `"ambiguous": true`가 있거나,
`fileserver.transfer.interruption{reason="stale_handle"}`이 나온다.
An operation's outcome could not be determined: the response was lost after the write or rename may
have landed. These are never retried automatically.
연산의 결과를 알 수 없다. 쓰기나 rename이 적용됐을 수 있는데 응답이 사라졌다. 이런 연산은 절대 자동으로
재시도하지 않는다.
```bash
# The recovery queue holds the files awaiting a decision.
# 복구 큐에 결정을 기다리는 파일이 있다.
curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" | jq
```
Reconciliation compares the physical size and digest against the record and only confirms READY when
all four of key, size, digest, and version agree. Anything short of that is reported, never guessed.
맞춰 보기는 물리 크기와 digest를 기록과 비교하고, key·크기·digest·
version 넷이 모두 맞을 때만 READY를 확정한다. 그보다 못한 것은 짐작하지 않고 보고한다.
## PVC remount
## PVC 다시 마운트
**Signal** — startup failure naming "atomic move", "same file store", or "not writable".
**신호** — "atomic move", "same file store", "not writable"을 담은 시작 실패.
The volume was remounted somewhere the probe can no longer prove a required capability. The
application refuses traffic rather than serving from storage it cannot publish to atomically.
volume이 다른 곳에 다시 마운트돼서 probe가 필수 capability를 더는 증명하지 못한다. 애플리케이션은 원자적으로
게시할 수 없는 저장소로 내보내지 않고 요청을 거부한다.
```bash
# staging과 content가 같은 파일 저장소(같은 장치 번호)인지 pod 안에서 본다
@@ -91,11 +88,11 @@ kubectl exec <pod> -- stat -c %d /var/lib/backend/files/staging /var/lib/backend
접근 모드, backend, mount 옵션)을 다시 적고, 인증한 묶음과 비교한다. 하나라도 다르면 그것이 원인이다.
인증은 그 차이를 넘어 옮겨지지 않는다.
## Nginx delegation failure
## Nginx 위임 실패
**Signal** — `fileserver.download.delegation{delegated="true"}` with client-visible `404`s.
**신호** — `fileserver.download.delegation{delegated="true"}`인데 client에게 `404`가 보인다.
The internal location is misconfigured, so the proxy cannot resolve the redirect it was handed.
내부 location 설정이 잘못돼서 프록시가 넘겨받은 redirect를 풀지 못한다.
프록시 설정의 내부 location(기본 `/__files/`)이 아래 「운영 환경이 지켜야 할 조건」을 지키는지 본다.
@@ -103,8 +100,7 @@ The internal location is misconfigured, so the proxy cannot resolve the redirect
curl -s $ADMIN/internal/fileserver/capabilities | jq '.capabilities.delegatedDownload'
```
Turning delegation off is a safe immediate mitigation: the application serves the transfer itself,
slower but correct.
위임을 끄는 것이 안전한 즉시 완화책이다. 애플리케이션이 직접 전송한다. 느리지만 맞다.
```bash
app.fileserver-platform.nginx.enabled=false
@@ -136,13 +132,12 @@ app.fileserver-platform.nginx.enabled=false
3. 그 volume이 `storage-certification.md`의 인증 항목(같은 파일 저장소, 원자적 rename, `O_EXCL` 생성)을
통과해야 한다. 기동 때 `FileserverStartupValidator`도 같은 probe를 다시 돌린다.
## Cleanup backlog
## 정리 적체
**Signal** — `fileserver.cleanup{result="deferred"}` rising, or reclaimed bytes flat while deletes
continue.
**신호** — `fileserver.cleanup{result="deferred"}`가 오르거나, 삭제는 계속되는데 회수한 바이트가 평평하다.
Items are being deferred faster than they drain. The usual cause is an active writer lease still
holding staging objects, which is correct behaviour, not a fault.
항목이 비워지는 것보다 빠르게 미뤄진다. 흔한 원인은 아직 살아 있는 writer lease가 staging 객체를 잡고 있는
것이다. 결함이 아니라 맞는 동작이다.
```bash
curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" \
@@ -150,23 +145,21 @@ curl -s "$ADMIN/internal/fileserver/uploads/incomplete?limit=100" \
curl -s -X POST "$ADMIN/internal/fileserver/uploads:cleanup?maxItems=500&maxBytes=10737418240"
```
If the deferrals are all `ACTIVE_WRITER_LEASE`, the backlog resolves itself as those uploads expire.
Never delete staging content to clear a backlog: an upload that is mid-flight will corrupt.
미룬 이유가 모두 `ACTIVE_WRITER_LEASE`면 그 업로드들이 만료되면서 적체는 스스로 풀린다. 적체를 비우려고
staging content를 지우지 않는다. 진행 중인 업로드가 망가진다.
## Namespace quota drift
## Namespace 할당량 어긋남
**Signal** — a namespace's usage (`fileserver.quota` rejections, or the drift query below) disagrees
with the bytes its files actually hold. The known cause is history: before the 2026-11 maturity
review, `move` relocated a file without moving its quota. The bytes of every file moved before that
fix are still booked on the namespace it left, and deleting such a file reclaims from the namespace
it now lives in: the reclaim draws down the bookings of that namespace's other files, newest first,
or stops at zero, and the old booking stays behind either way. A derived
service that moved files across namespaces before taking the fix has this drift; one that never did
should see none.
**신호** — namespace의 사용량(`fileserver.quota` 거부, 또는 아래 drift query)이 그 파일들이 실제로 가진 바이트와
다르다. 알려진 원인은 이력이다. 2026-11 성숙도 리뷰 전에는 `move`가 파일을 옮기면서 할당량은 옮기지 않았다.
그 수정 전에 옮긴 파일의 바이트는 아직 떠나온 namespace에 잡혀 있다. 그런 파일을 지우면 지금 있는 namespace에서
회수한다. 그 회수는 그 namespace의 다른 파일 몫을 최신 것부터 깎거나 0에서 멈추고, 어느 쪽이든 옛 몫은
남는다. 그 수정을 받기 전에 namespace를 넘어 파일을 옮긴 파생 서비스에는 이 어긋남이 있다. 그런 적이 없는
서비스에는 없어야 한다.
What the ledger must equal: quota is committed when a file is published and reclaimed when cleanup
deletes its content, so a namespace's committed bytes are the sizes of its published files that are
not yet `DELETED`. The query compares the two and changes nothing.
ledger가 같아야 하는 값: 할당량은 파일을 게시할 때 확정하고 cleanup이 content를 지울 때 회수한다. 그래서
namespace의 확정 바이트는 아직 `DELETED`가 아닌 게시된 파일 크기의 합이다. 아래 query가 둘을 비교한다.
아무것도 바꾸지 않는다.
```sql
WITH booked AS (
@@ -188,18 +181,15 @@ SELECT coalesce(b.namespace, h.namespace) AS namespace,
WHERE coalesce(b.booked_bytes, 0) <> coalesce(h.held_bytes, 0);
```
A positive `drift_bytes` is booked capacity no file holds (the namespace a file left); a negative one
is held content nothing booked (the namespace it arrived in). While uploads, copies, moves or
cleanup run, a row can show a drift that only means work in flight, so judge drift with the
fileserver's writes stopped.
`drift_bytes`가 양수면 어떤 파일도 갖지 않은 잡힌 용량이다(파일이 떠나온 namespace). 음수면 아무도 잡지 않은
content다(파일이 도착한 namespace). 업로드, copy, move, cleanup이 도는 동안에는 진행 중인 일 때문에 어긋남이
보일 수 있다. 그러니 fileserver 쓰기를 멈춘 상태에서 판단한다.
To correct a namespace, stop every fileserver write to it first — uploads, copy, move, delete, and
the cleanup worker (`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false`) — because the statement below
recomputes from `fs_file` and a publish or reclaim that lands between its two steps would be lost.
It zeroes the namespace's committed rows and books the recomputed total as one row, shaped the way a
publish leaves one (`COMMITTED`, `reserved_bytes` 0, the bytes in `committed_bytes`); the per-row
split has no meaning once reclaims have drawn rows down, and enforcement only ever reads the sum.
`RESERVED` rows (uploads in progress) are left alone.
namespace를 바로잡으려면 먼저 그 namespace로 가는 fileserver 쓰기를 모두 멈춘다. 업로드, copy, move, delete,
그리고 cleanup worker(`APP_FILESERVER_PLATFORM_CLEANUP_ENABLED=false`)다. 아래 문은 `fs_file`에서 다시 계산하므로,
두 단계 사이에 들어온 게시나 회수는 사라진다. 이 문은 그 namespace의 확정 행을 0으로 만들고, 다시 계산한 합계를
게시가 남기는 모양의 행 하나로 잡는다(`COMMITTED`, `reserved_bytes` 0, 바이트는 `committed_bytes`). 회수가 행을
깎은 뒤에는 행별 나눔에 의미가 없고, 강제는 합계만 읽는다. `RESERVED` 행(진행 중인 업로드)은 건드리지 않는다.
```sql
BEGIN;
@@ -221,5 +211,5 @@ SELECT gen_random_uuid(), 'namespace', :'namespace', 0, held,
COMMIT;
```
Run it with `psql -v namespace=<name>`, then run the drift query again: the namespace must be gone
from its result before writes resume.
`psql -v namespace=<name>`으로 돌리고 drift query를 다시 돌린다. 쓰기를 다시 열기 전에 그 namespace가 결과에서
사라져야 한다.
+53 -58
View File
@@ -1,83 +1,78 @@
# Fileserver security model
# Fileserver 보안 모델
## The rule everything else follows
## 나머지가 모두 따르는 규칙
Uploaded content is attacker-controlled. Every guard below exists because some part of the request
— the filename, the declared media type, the range, the offset — is a value the caller chose.
올라온 content는 공격자가 정한다. 아래 보호 장치는 모두 요청의 어떤 부분(파일 이름, 선언한 media type,
range, offset)이 호출자가 고른 값이기 때문에 있다.
## Path safety
## 경로 안전
A client value never becomes a path. The physical key is server-generated, and `ContentKey`'s
character class excludes `.` entirely, so no traversal or extension-shaped segment survives
validation. `DefaultPhysicalPathResolver` is the only place an identifier becomes a `Path`, and it
normalizes and re-checks containment after construction rather than trusting the input.
client 값은 절대 경로가 되지 않는다. 물리 key는 서버가 만들고, `ContentKey`의 글자 집합에는 `.`이 아예 없다.
그래서 경로 거슬러 오르기나 확장자 모양의 조각은 검증을 통과하지 못한다. 식별자가 `Path`가 되는 곳은
`DefaultPhysicalPathResolver` 하나다. 입력을 믿지 않고, 만든 뒤 정규화해서 root 안에 있는지 다시 확인한다.
Symlink refusal happens at open time, not only at construction. A parent directory can be replaced
between the two, so a check that ran only at path-building time would be a race, not a guard.
symlink 거부는 경로를 만들 때만이 아니라 열 때도 한다. 그 사이에 부모 폴더가 바뀔 수 있으므로, 경로를 만들
때만 검사하면 보호 장치가 아니라 경쟁 조건이다.
## Filename handling
## 파일 이름 처리
`OriginalFilenamePolicy` strips path separators, NUL, quoting characters, and the colon — the last
because on Windows it opens both a drive reference and an NTFS alternate data stream, so a name that
keeps it is still path-shaped after the slashes are gone. Control characters and bidirectional
overrides are removed, dot runs collapsed, reserved device names guarded, and the result is bounded
in UTF-8 bytes.
`OriginalFilenamePolicy`는 경로 구분자, NUL, 따옴표 문자, 콜론을 지운다. 콜론은 Windows에서 드라이브 참조와
NTFS alternate data stream을 모두 열기 때문에, 슬래시를 지워도 콜론이 남으면 여전히 경로 모양이다. 제어
문자와 양방향 override를 지우고, 이어진 점을 하나로 줄이고, 예약된 장치 이름을 막고, 결과를 UTF-8 바이트로
제한한다.
The sanitized name is display data. It is never used to build a key, and it reaches a header only
through `ContentDispositionFactory`, which restricts the ASCII form and percent-encodes the UTF-8
form.
정리한 이름은 표시용 데이터다. key를 만드는 데 절대 쓰지 않는다. 헤더에는 `HttpContentDispositionFactory`를
거쳐서만 들어가고, 이것이 ASCII 형태를 제한하고 UTF-8 형태를 percent-encoding한다.
## Content type
## Content 형식
The client's `Content-Type` is stored as a claim. The verified type comes from the verification
pipeline, and only the verified type is served. A claimed type that contradicts the content is
quarantined rather than corrected.
client의 `Content-Type`은 주장으로 저장한다. 검증한 형식은 검증 pipeline에서 오고, 검증한 형식만 내보낸다.
content와 어긋나는 주장 형식은 고치지 않고 격리한다.
Scriptable types are never served inline, whatever the caller asked for: serving stored HTML or SVG
inline from an upload origin is a stored cross-site scripting primitive. Every download also carries
`X-Content-Type-Options: nosniff`.
스크립트가 될 수 있는 형식은 호출자가 무엇을 요청했든 절대 inline으로 내보내지 않는다. 업로드 origin에서
저장된 HTML이나 SVG를 inline으로 내보내면 stored cross-site scripting의 재료가 된다. 모든 다운로드는
`X-Content-Type-Options: nosniff`도 붙인다.
## Verification precedence
## 검증 우선순위
`REJECT > QUARANTINE > RETRY > ACCEPT`. A verifier that times out or throws is `RETRY`, never a
silent pass, and an empty verifier chain answers `RETRY` rather than accepting. A file becomes
publicly readable only after an `ACCEPT`.
`REJECT > QUARANTINE > RETRY > ACCEPT`. 시간 초과나 예외를 낸 검증기는 `RETRY`이고 조용한 통과가 아니다.
검증기가 하나도 없으면 받아들이지 않고 `RETRY`로 답한다. 파일은 `ACCEPT` 뒤에야 공개로 읽을 수 있다.
## Range safety
## Range 안전
The range budget is enforced before content is opened, so a request naming many ranges is rejected
without amplifying into storage work. An unsatisfiable range answers `416` with the real length and
opens nothing.
range 예산은 content를 열기 전에 강제한다. 그래서 range를 많이 적은 요청은 저장소 작업을 불리지 않고
거부된다. 만족할 수 없는 range는 실제 길이를 담은 `416`으로 답하고 아무것도 열지 않는다.
## Authorization
## 권한
Every public operation calls the injected `FileAccessPolicyPort` before any quota reservation or storage
mutation, so a denial leaves no record, no reservation, and no staging object. Finalize is
authorized as `FINALIZE`, and management-plane reads as `ADMIN_READ`. Startup refuses to run a
production profile with an allow-all policy.
모든 공개 연산은 할당량 예약이나 저장소 변경 전에 주입한 `FileAccessPolicyPort`를 부른다. 그래서 거부하면
기록도, 예약도, staging 객체도 남지 않는다. finalize는 `FINALIZE`로, management plane 읽기는 `ADMIN_READ`로
권한을 본다. 시작 단계는 모두 허락하는 정책으로 운영 profile을 돌리는 것을 거부한다.
Each file records its owner: the principal that created it and, when the transport resolved one,
its tenant (the `tenant` subject attribute). The default role policy grants an operation on an
existing file only to its owner in the same tenant, so two callers holding the same role cannot
read, download, finalize, delete, copy or move each other's files. An admin role does not bypass
this — acting on another caller's file is what the audited management plane is for. A file created
before ownership was recorded (migration V5) has no owner and is reachable only through the
management plane. Anonymous read, when enabled, publishes every file and skips the owner check.
파일마다 소유자를 기록한다. 그 파일을 만든 principal, 그리고 transport가 하나를 풀었다면 그 tenant(`tenant`
subject 속성)다. 기본 role 정책은 이미 있는 파일에 대한 연산을 같은 tenant의 소유자에게만 허락한다. 그래서
같은 role을 가진 두 호출자도 서로의 파일을 읽거나, 다운로드하거나, finalize하거나, 지우거나, copy하거나,
move할 수 없다. admin role도 이것을 건너뛰지 않는다. 다른 호출자의 파일을 다루라고 감사하는 management
plane이 있다. 소유자를 기록하기 전(마이그레이션 V5)에 만든 파일은 소유자가 없고 management plane으로만 닿는다.
## Delegation
익명 읽기는 설정으로 켤 수 없다([configuration.md](configuration.md) 「권한」). `role-based` 정책은 늘 끈 채로
만든다. `RoleBasedFileAccessPolicy`를 직접 만들면서 익명 읽기를 켜면 모든 파일을 공개하고 소유자 검사를
건너뛴다.
`X-Accel-Redirect` is emitted only after authorization and the READY gate, and only for a full,
unconditional response. The internal prefix must be an `internal` Nginx location; the front proxy
also strips any client-supplied delegation header so a caller cannot name an internal object.
## 위임
`X-Accel-Redirect`는 권한 확인과 READY 관문을 지난 뒤, 조건 없는 전체 응답에만 내보낸다. 내부 접두사는
Nginx의 `internal` location이어야 한다. 프런트 프록시는 client가 보낸 위임 헤더도 지워서 호출자가 내부 객체를
가리키지 못하게 한다.
## Telemetry
No metric label, span attribute, or audit record carries a file id, upload id, filename, path, or
user id. Where correlation is needed the value is a keyed HMAC fingerprint — keyed because the
identifier space is enumerable and an unkeyed digest of it is reversible by brute force.
metric label, span 속성, 감사 기록 어디에도 file id, upload id, 파일 이름, 경로, user id를 담지 않는다.
상관관계가 필요한 곳은 key를 쓴 HMAC fingerprint를 쓴다. 식별자 공간은 셀 수 있으므로 key 없는 digest는
전수 대입으로 되돌릴 수 있다. 그래서 key가 필요하다.
## Ambiguous failures
## 결과를 모르는 실패
A failure whose operation may already have taken effect is reported as ambiguous and is never
retryable. On a network filesystem a lost response is indistinguishable from a rejection at the
socket level, so anything not provably safe is treated as ambiguous and sent to reconciliation.
연산이 이미 효과를 냈을 수 있는 실패는 결과를 모르는 것(ambiguous)으로 보고하고 절대 재시도할 수 있다고 하지
않는다. 네트워크 파일 시스템에서는 사라진 응답과 socket 수준의 거부를 구분할 수 없다. 그래서 안전하다고
증명할 수 없는 것은 모두 결과를 모르는 것으로 보고 맞춰 보기로 보낸다.
+29 -31
View File
@@ -1,23 +1,22 @@
# Storage certification
# 저장소 인증
## Why a certification is per-volume
## 인증이 volume마다인 이유
Atomic rename, same-file-store guarantees, and symlink refusal are properties of a specific
filesystem behind a specific mount — not of "Kubernetes" or "a PVC". Change the CSI driver, the
StorageClass, the access mode, the backend, or the mount options and any of them can differ. A
certification that does not name all five is not transferable.
원자적 rename, 같은 파일 저장소 보장, symlink 거부는 「Kubernetes」나 「PVC」의 성질이 아니라 특정 mount 뒤의
특정 파일 시스템의 성질이다. CSI driver, StorageClass, 접근 모드, backend, mount 옵션 중 하나만 바꿔도 그중
무엇이든 달라질 수 있다. 다섯을 모두 적지 않은 인증은 다른 곳으로 옮길 수 없다.
## What is certified
## 인증하는 것
| Property | Why it matters |
| 성질 | 중요한 이유 |
|---|---|
| Same file store for staging and content | A rename across stores is a copy, so publication stops being atomic. |
| Atomic rename | The publish path's default strategy. |
| Atomic create (`O_EXCL`) | Makes a publish create-only rather than a silent overwrite. |
| Symlink refusal | Stops a replaced parent from redirecting a write outside the root. |
| Ranged read | The download contract depends on it. |
| staging과 content가 같은 파일 저장소 | 저장소를 넘는 rename은 복사라서 게시가 원자적이지 않게 된다. |
| 원자적 rename | 게시 경로의 기본 전략이다. |
| 원자적 생성(`O_EXCL`) | 게시를 조용한 덮어쓰기가 아니라 새로 만들기만 하게 한다. |
| symlink 거부 | 바뀐 부모 폴더가 쓰기를 root 밖으로 돌리는 것을 막는다. |
| 범위 읽기 | 다운로드 계약이 기댄다. |
## Running the certification
## 인증 돌리기
이 repo는 인증 job 매니페스트를 두지 않는다(2026-11-07 소유자 결정). 배포하는 쪽이 대상 volume을 저장
루트(`/var/lib/backend/files`)에 마운트한 일회성 pod에서 아래를 차례로 확인한다.
@@ -45,31 +44,30 @@ certification that does not name all five is not transferable.
2번이 실패하면 인증하지 않는다. staging과 content가 다른 저장소인 volume은 게시가 소리 없이 복사로 바뀐다.
## Network filesystems
## 네트워크 파일 시스템
```bash
docker compose -f src/adapter/outbound/fileserver/compose/nfs/compose.yml up -d
FILESERVER_NFS_TESTS=true ./gradlew :adapter:outbound:fileserver:test
```
The mount is `hard`, deliberately. A `soft` mount converts a slow server into a short write, which
is exactly the corruption this design refuses to accept.
mount는 일부러 `hard`다. `soft` mount는 느린 서버를 짧게 끝난 쓰기로 바꾼다. 이 설계가 받아들이지 않는 바로
그 손상이다.
## Startup enforcement
## 시작 때 강제
`FileserverStartupValidator` re-runs the probe at boot and refuses to accept traffic when a required
capability is missing — `ATOMIC_MOVE_REQUIRED` on a filesystem that cannot prove an atomic move
fails closed rather than degrading silently.
`FileserverStartupValidator`가 부팅 때 probe를 다시 돌리고, 필수 capability가 없으면 요청을 받지 않는다.
원자적 move를 증명하지 못하는 파일 시스템에 `ATOMIC_MOVE_REQUIRED`를 두면 조용히 기능을 줄이지 않고 닫힌
쪽으로 실패한다.
## Adding a new store
## 새 저장소 더하기
Pass two executable contracts. A prose claim of compatibility is not accepted.
실행되는 계약 둘을 통과해야 한다. 글로 쓴 호환 주장은 받지 않는다.
- `UploadStoragePortContract` — the application port's contract, in `application-fileserver`
testFixtures (`testImplementation testFixtures(project(':application-fileserver'))`). The
application's `FakeUploadStorageGateway` extends it too, so use case tests and the real store obey
the same offset, chunk-checksum and size-ceiling rules (a declared 0-byte upload refuses its first
byte).
- `ContentStoreContract` — the local adapter's internal `BlockingContentStore` SPI, in this
adapter's tests. That SPI stays in the adapter by design (review S1-#12: the application never
calls it), so its contract stays with it; a store that reuses the SPI extends it as well.
- `UploadStoragePortContract` — 애플리케이션 port의 계약이다. `application-fileserver` testFixtures에 있다
(`testImplementation testFixtures(project(':application-fileserver'))`). 애플리케이션의
`FakeUploadStorageGateway`도 이것을 상속한다. 그래서 use case 테스트와 실제 저장소가 같은 offset, chunk
checksum, 크기 상한 규칙을 지킨다(0바이트로 선언한 업로드는 첫 바이트를 거부한다).
- `ContentStoreContract` — 로컬 어댑터의 내부 `BlockingContentStore` SPI 계약이다. 이 어댑터의 테스트에 있다.
그 SPI는 일부러 어댑터 안에 둔다(리뷰 S1-#12: 애플리케이션은 그것을 부르지 않는다). 그래서 계약도 어댑터에
있다. 그 SPI를 다시 쓰는 저장소도 이것을 상속한다.
+50 -52
View File
@@ -1,71 +1,69 @@
# Fileserver support matrix
# Fileserver 지원 매트릭스
A support level here is a claim about evidence, not about intent. Every row names the CI job that
produces that evidence; `FileserverDocumentationCoverageTest` fails the build if a row names a job
that does not exist, so a level can never outlive the test that justified it.
여기의 지원 등급은 의도가 아니라 증거에 대한 주장이다. 행마다 그 증거를 만드는 CI job을 적는다. 행이 없는
job을 적으면 `FileserverDocumentationCoverageTest`가 빌드를 실패시킨다. 그래서 등급은 그것을 정당화한 테스트보다
오래 살 수 없다.
## Levels
## 등급
| Level | What it means |
등급 이름은 원문 그대로 쓴다. 표와 테스트가 이 이름을 그대로 읽는다.
| 등급 | 뜻 |
|---|---|
| Stable | Certified on every pull request. Contract changes are breaking changes. |
| Beta | Certified nightly. The contract may still change with a deprecation notice. |
| Limited | Certified on the release gate only, under stated constraints. |
| Compatibility | Accepted but not optimized; known caveats are listed inline. |
| Experimental | Off by default, unratified upstream, may change without notice. |
| Stable | pull request마다 인증한다. 계약 변경은 깨지는 변경이다. |
| Beta | 매일 밤 인증한다. 폐기 예고와 함께 계약이 아직 바뀔 수 있다. |
| Limited | 밝힌 제약 아래에서 릴리스 게이트에서만 인증한다. |
| Compatibility | 받아들이지만 최적화하지 않는다. 알려진 주의점은 그 자리에 적는다. |
| Experimental | 기본으로 꺼져 있고, 상위 표준이 확정되지 않았으며, 예고 없이 바뀔 수 있다. |
## Runtime profiles
## 런타임 profile
| Profile | Level | CI job |
| Profile | 등급 | CI job |
|---|---|---|
| Local filesystem (ext4) content store | Stable | `fileserver-local-ext4-contract` |
| Spring MVC transport (raw, multipart, batch, download) | Stable | `fileserver-http-contract` |
| Path, filename, range, and problem-detail hardening | Stable | `fileserver-security-suite` |
| Bounded-memory transfer | Stable | `fileserver-bounded-memory` |
| Application and architecture invariants | Stable | `fileserver-unit-and-architecture` |
| Runtime assembly (the capability starts with the flag on) | Stable | `fileserver-unit-and-architecture` |
| tus 1.0 resumable uploads | Stable | `fileserver-http-contract` |
| Crash-recovery matrix | Beta | `fileserver-process-kill-matrix` |
| NFSv4 ambiguity handling | Beta | `fileserver-nfs-ambiguity` |
| Large-file and slow-client performance | Beta | `fileserver-large-file-performance` |
| Multi-instance writer lease | Beta | `fileserver-multi-instance-lease` |
| Nginx `X-Accel-Redirect` delegation | Limited | `fileserver-http-contract` |
| Telemetry sensitive-data suppression | Stable | `fileserver-sensitive-telemetry-scan` |
| Documentation and support-claim coverage | Stable | `fileserver-documentation-gate` |
| Full release verification | Stable | `fileserver-full-verification` |
| 로컬 파일 시스템(ext4) content 저장소 | Stable | `fileserver-local-ext4-contract` |
| Spring MVC transport(raw, multipart, batch, 다운로드) | Stable | `fileserver-http-contract` |
| 경로, 파일 이름, range, problem-detail 강화 | Stable | `fileserver-security-suite` |
| 메모리 상한이 있는 전송 | Stable | `fileserver-bounded-memory` |
| 애플리케이션·아키텍처 불변식 | Stable | `fileserver-unit-and-architecture` |
| 런타임 조립(flag를 켜면 capability가 시작한다) | Stable | `fileserver-unit-and-architecture` |
| tus 1.0 이어 올리기 업로드 | Stable | `fileserver-http-contract` |
| 장애 복구 매트릭스 | Beta | `fileserver-process-kill-matrix` |
| NFSv4 결과 모름 처리 | Beta | `fileserver-nfs-ambiguity` |
| 큰 파일·느린 client 성능 | Beta | `fileserver-large-file-performance` |
| 여러 인스턴스 writer lease | Beta | `fileserver-multi-instance-lease` |
| Nginx `X-Accel-Redirect` 위임 | Limited | `fileserver-http-contract` |
| telemetry 민감 데이터 억제 | Stable | `fileserver-sensitive-telemetry-scan` |
| 문서와 지원 주장 범위 | Stable | `fileserver-documentation-gate` |
| 전체 릴리스 검증 | Stable | `fileserver-full-verification` |
| HTTP resumable uploads draft-12 | Experimental | `fileserver-http-contract` |
### WebFlux transport removed
### WebFlux transport 제거
The reactive router and handlers (`web.fileserver.reactive`) were removed on 2026-09-25 (D4: the
template is servlet on virtual threads). The shipped composition could never select them — the web
leaf puts `DispatcherServlet` on the classpath, so Boot resolves SERVLET.
reactive router와 handler(`web.fileserver.reactive`)는 2026-09-25에 지웠다(D4: 템플릿은 virtual thread 위의
servlet이다). 내보낸 조립은 그것을 고를 수 없었다. web leaf가 `DispatcherServlet`을 classpath에 두므로 Boot는
SERVLET으로 정한다.
## Explicitly not claimed
## 주장하지 않는 것
These have no job, and therefore no claim:
아래는 job이 없고, 그래서 주장도 없다.
- Kubernetes PVC(ReadWriteOnce 포함). 이 repo는 클러스터 매니페스트와 그것을 검사하던 release job을
2026-11-07에 지웠다. volume이 지켜야 할 조건은 [operations.md](operations.md) 「운영 환경이 지켜야 할
조건」, 인증 절차는 [storage-certification.md](storage-certification.md)다. 클러스터 결과는 배포하는 쪽이
만든다.
- Kubernetes ReadWriteMany PVC. 여러 노드의 동시 쓰기는 인증하지 않았다.
- 운영 저장 루트로서의 Windows NTFS. 파일 이름 정책이 NTFS가 예약한 문자를 지우지만, 그 위의 게시 경로를
인증하는 job은 없다.
- content 저장소로서의 object storage. 계약(`ContentStoreContract`)은 있지만 아직 구현한 어댑터가 없다.
- 서버 쪽 악성 코드 검사. 검증 pipeline에 port와 판정 우선순위는 있지만 내놓는 검사기는 없다.
- Kubernetes ReadWriteMany PVC. Concurrent writers across nodes are not certified.
- Windows NTFS as a production storage root. The filename policy strips the characters NTFS
reserves, but no job certifies the publish path there.
- Object storage as a content store. The contract exists (`ContentStoreContract`) but no adapter
implements it yet.
- Server-side malware scanning. The verification pipeline has the port and the verdict precedence;
no scanner is shipped.
## 나머지가 적힌 곳
## Where the rest is written down
- [configuration.md](configuration.md) — every `app.fileserver-platform.*` key, its default, and the
conditions that fail startup rather than degrade.
- [design-deviations.md](design-deviations.md) — where the implementation departs from the frozen
design, why, and the test that pins each decision.
- [http-contract.md](http-contract.md) — the wire contract.
- [security.md](security.md) — the threat model and what enforces each control.
- [operations.md](operations.md) — runbooks, each starting from a metric.
- [storage-certification.md](storage-certification.md) — how a volume is certified.
- [upgrade-guide.md](upgrade-guide.md) — what changes between versions.
- [configuration.md](configuration.md) — 모든 `app.fileserver-platform.*` key, 그 기본값, 기능을 줄이지 않고
시작을 실패시키는 조건.
- [design-deviations.md](design-deviations.md) — 구현이 고정된 설계와 다른 곳, 그 이유, 결정마다 고정하는 테스트.
- [http-contract.md](http-contract.md) — wire 계약.
- [security.md](security.md) — 위협 모델과 각 통제를 강제하는 것.
- [operations.md](operations.md) — 각각 metric에서 시작하는 runbook.
- [storage-certification.md](storage-certification.md) — volume을 인증하는 법.
- [upgrade-guide.md](upgrade-guide.md) — 버전 사이에 바뀌는 것.
+37 -38
View File
@@ -1,9 +1,9 @@
# Fileserver upgrade guide
# Fileserver 업그레이드 안내
## Enabling the capability
## Capability 켜기
The Fileserver ships off. Nothing is registered — no endpoint, no thread pool, no metric — until it
is enabled explicitly.
Fileserver는 꺼진 채로 나온다. 명시적으로 켜기 전에는 아무것도 등록하지 않는다. endpoint도, 스레드 pool도,
metric도 없다.
```yaml
app:
@@ -15,68 +15,67 @@ app:
fingerprint-key: ${FILESERVER_FINGERPRINT_KEY}
```
`instance-id` must be unique per instance: it is the writer-lease owner, and two nodes sharing one
would both believe they hold the same lease.
`instance-id`는 인스턴스마다 달라야 한다. writer lease의 소유자이기 때문이다. 두 노드가 같은 값을 쓰면 둘 다
같은 lease를 가졌다고 믿는다.
`fingerprint-key` is required and has no default. Startup fails without it rather than falling back
to an unkeyed digest, which would be reversible for an enumerable identifier space.
`fingerprint-key`는 필수이고 기본값이 없다. 없으면 key 없는 digest로 물러서지 않고 시작이 실패한다. 셀 수
있는 식별자 공간에서 key 없는 digest는 되돌릴 수 있다.
## Optional surfaces
## 선택 면
Each is a separate switch, and each defaults to off:
각각 따로 된 스위치이고, 모두 기본으로 꺼져 있다.
```yaml
app:
fileserver-platform:
admin:
enabled: false # management plane; intended for a management port
enabled: false # management plane. 관리 port에 둔다
tus:
enabled: false # tus 1.0 Stable
enabled: false # tus 1.0, Stable
httpbis-draft12:
enabled: false # Experimental; unratified, may change without notice
enabled: false # Experimental. 표준 미확정, 예고 없이 바뀔 수 있다
nginx:
enabled: false # front-proxy delegation; needs a validated internal location
enabled: false # 프런트 프록시 위임. 검증한 internal location이 필요하다
```
## Database schema
## DB schema
The metadata schema is installed as a capability migration and starts inactive:
metadata schema는 capability 마이그레이션으로 설치되고 비활성 상태로 시작한다.
```
V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileserver-metadata-v1
```
Activate it deliberately. Enabling the capability without an activated schema fails at startup
rather than at the first upload.
의도해서 활성화한다. 활성화한 schema 없이 capability를 켜면 첫 업로드가 아니라 시작 때 실패한다.
## Choosing a publish mode
## 게시 방식 고르기
| Mode | When |
| 방식 | 언제 |
|---|---|
| `atomic-move-preferred` | Default. Uses an atomic rename when the probe proves one, else a metadata pointer. |
| `atomic-move-required` | Fail closed. Refuses to start on storage that cannot prove an atomic move. |
| `metadata-pointer` | For storage without atomic rename; publication is the metadata commit. |
| `atomic-move-preferred` | 기본값. probe가 증명하면 원자적 rename을, 아니면 metadata pointer를 쓴다. |
| `atomic-move-required` | 닫힌 쪽으로 실패한다. 원자적 move를 증명하지 못하는 저장소에서는 시작을 거부한다. |
| `metadata-pointer` | 원자적 rename이 없는 저장소용. 게시가 곧 metadata 확정이다. |
Pick `atomic-move-required` when the storage is certified and you want a misconfiguration to surface
at boot rather than at publish time.
저장소를 인증했고 잘못된 설정이 게시 때가 아니라 부팅 때 드러나기를 원하면 `atomic-move-required`를 고른다.
## Behaviour that will surprise you
## 놀랄 만한 동작
- **A delete answers `202`, not `204`, when content still exists.** The file is already unreadable;
the physical reclaim is deferred. Treating `202` as a failure will produce spurious retries.
- **A batch upload answers `200` even when parts failed.** The batch is explicitly non-atomic, and a
single status could not report a partial outcome honestly. Read `results[].problem`.
- **An ambiguous failure must not be retried.** Check `"ambiguous": true` in the problem document.
- **`If-Match` takes the strong ETag, not a version number.** A client can only assert about the
representation it was actually served.
- **Inline rendering is refused for scriptable types** even when the caller asks for it.
- **content가 아직 있으면 삭제는 `204`가 아니라 `202`로 답한다.** 파일은 이미 읽을 수 없고, 물리 회수는
미뤘다. `202`를 실패로 다루면 쓸데없이 재시도한다.
- **batch 업로드는 part가 실패해도 `200`으로 답한다.** batch는 명시적으로 원자적이지 않고, 상태 코드 하나로는
부분 결과를 정직하게 알릴 수 없다. `results[].error`를 읽는다.
- **결과를 모르는 실패는 재시도하면 안 된다.** 실패 Envelope의 `error.details`에서 `"ambiguous": true`를 본다.
- **`If-Match`는 version 숫자가 아니라 strong ETag를 받는다.** client는 실제로 받은 표현에 대해서만 주장할 수
있다.
- **스크립트가 될 수 있는 형식은 호출자가 요청해도 inline으로 그리지 않는다.**
## Verifying an upgrade
## 업그레이드 확인
```bash
cd src
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :application-core:check :adapter:inbound:web:check \
:adapter:outbound:fileserver:check --console=plain
./gradlew :app-bootstrap:test --tests '*Fileserver*' --console=plain
./gradlew :application-fileserver:check :adapter:inbound:web-fileserver:check \
:adapter:outbound:fileserver:check :adapter:outbound:persistence-fileserver:check \
:composition:fileserver-platform:check --console=plain
./gradlew :app-bootstrap:architectureTest --console=plain
```
-8
View File
@@ -37,14 +37,6 @@ language docs/adr/ADR-WS-002-resume-and-cluster.md
language docs/adr/ADR-WS-003-stomp-and-broker-relay.md
language docs/compatibility/grpc-advanced-support-matrix.md
language docs/compatibility/grpc-support-matrix.md
language docs/fileserver/configuration.md
language docs/fileserver/design-deviations.md
language docs/fileserver/http-contract.md
language docs/fileserver/operations.md
language docs/fileserver/security.md
language docs/fileserver/storage-certification.md
language docs/fileserver/support-matrix.md
language docs/fileserver/upgrade-guide.md
language docs/httpclient/configuration-reference.md
language docs/httpclient/operations.md
language docs/httpclient/performance-baseline.md
@@ -68,13 +68,13 @@ class FileserverDocumentationCoverageTest {
List<String> requiredRunbooks =
List.of(
"Storage full",
"Orphan growth",
"Verification backlog",
"NFS ambiguity",
"PVC remount",
"Nginx delegation failure",
"Cleanup backlog");
"## 저장소 가득 참",
"## 고아 객체 증가",
"## 검증 적체",
"## NFS 결과 모름",
"## PVC 다시 마운트",
"## Nginx 위임 실패",
"## 정리 적체");
assertThat(requiredRunbooks).allSatisfy(runbook -> assertThat(operations).contains(runbook));
assertThat(operations)
@@ -91,7 +91,7 @@ class FileserverDocumentationCoverageTest {
assertThat(matrix)
.as("an omitted capability reads as an unstated claim; absence must be explicit")
.contains("Explicitly not claimed")
.contains("## 주장하지 않는 것")
.contains("ReadWriteMany");
}
@@ -143,8 +143,9 @@ class FileserverDocumentationCoverageTest {
* Table keys from the configuration reference, minus the ones already qualified by a section.
*
* <p>The document writes a bare key inside a per-section table (for example {@code root} under
* "Storage") and a qualified one elsewhere ({@code upload.ttl}); only the qualified form can be
* bound without reconstructing the section context, so the bare ones are read with their heading.
* the {@code storage} heading) and a qualified one elsewhere ({@code upload.ttl}); only the
* qualified form can be bound without reconstructing the section context, so the bare ones are
* read with their heading.
*/
private static List<String> documentedSettingKeys(Path configuration) throws IOException {
List<String> keys = new ArrayList<>();