diff --git a/docs/fileserver/configuration.md b/docs/fileserver/configuration.md index 60af6511..70b14b68 100644 --- a/docs/fileserver/configuration.md +++ b/docs/fileserver/configuration.md @@ -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)에 적었다. diff --git a/docs/fileserver/design-deviations.md b/docs/fileserver/design-deviations.md index 0273e4a9..6e9b23b9 100644 --- a/docs/fileserver/design-deviations.md +++ b/docs/fileserver/design-deviations.md @@ -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 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 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 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다. diff --git a/docs/fileserver/http-contract.md b/docs/fileserver/http-contract.md index 84034bfd..a5fb6aa6 100644 --- a/docs/fileserver/http-contract.md +++ b/docs/fileserver/http-contract.md @@ -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에게 넘기지 않는다 | diff --git a/docs/fileserver/operations.md b/docs/fileserver/operations.md index f3930451..a534d2bd 100644 --- a/docs/fileserver/operations.md +++ b/docs/fileserver/operations.md @@ -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":[""],"reasonCode":"ORPHAN_GROWTH_RUNBOOK"}' + "expectedFingerprints":[""],"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 -- 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=`, then run the drift query again: the namespace must be gone -from its result before writes resume. +`psql -v namespace=`으로 돌리고 drift query를 다시 돌린다. 쓰기를 다시 열기 전에 그 namespace가 결과에서 +사라져야 한다. diff --git a/docs/fileserver/security.md b/docs/fileserver/security.md index cc27c308..54c39804 100644 --- a/docs/fileserver/security.md +++ b/docs/fileserver/security.md @@ -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 수준의 거부를 구분할 수 없다. 그래서 안전하다고 +증명할 수 없는 것은 모두 결과를 모르는 것으로 보고 맞춰 보기로 보낸다. diff --git a/docs/fileserver/storage-certification.md b/docs/fileserver/storage-certification.md index 19117e1e..34638589 100644 --- a/docs/fileserver/storage-certification.md +++ b/docs/fileserver/storage-certification.md @@ -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를 다시 쓰는 저장소도 이것을 상속한다. diff --git a/docs/fileserver/support-matrix.md b/docs/fileserver/support-matrix.md index 8e1c90ff..50b30b6a 100644 --- a/docs/fileserver/support-matrix.md +++ b/docs/fileserver/support-matrix.md @@ -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) — 버전 사이에 바뀌는 것. diff --git a/docs/fileserver/upgrade-guide.md b/docs/fileserver/upgrade-guide.md index e9bbf8bf..7e9dbf46 100644 --- a/docs/fileserver/upgrade-guide.md +++ b/docs/fileserver/upgrade-guide.md @@ -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 ``` diff --git a/scripts/check-docs-exceptions.txt b/scripts/check-docs-exceptions.txt index 2ab3c206..550fc337 100644 --- a/scripts/check-docs-exceptions.txt +++ b/scripts/check-docs-exceptions.txt @@ -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 diff --git a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java index 29af491b..3a5dbf88 100644 --- a/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java +++ b/src/composition/fileserver-platform/src/test/java/dev/caskeleton/composition/fileserver/FileserverDocumentationCoverageTest.java @@ -68,13 +68,13 @@ class FileserverDocumentationCoverageTest { List 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. * *

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 documentedSettingKeys(Path configuration) throws IOException { List keys = new ArrayList<>();