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:
+138
-145
@@ -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)에 적었다.
|
||||
|
||||
@@ -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 위임 경로가 같은 실패에 다른 상태로 답하면 안 된다.
|
||||
|
||||
@@ -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에게 넘기지 않는다 |
|
||||
|
||||
@@ -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
@@ -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 수준의 거부를 구분할 수 없다. 그래서 안전하다고
|
||||
증명할 수 없는 것은 모두 결과를 모르는 것으로 보고 맞춰 보기로 보낸다.
|
||||
|
||||
@@ -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를 다시 쓰는 저장소도 이것을 상속한다.
|
||||
|
||||
@@ -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) — 버전 사이에 바뀌는 것.
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
@@ -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
|
||||
|
||||
+11
-10
@@ -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<>();
|
||||
|
||||
Reference in New Issue
Block a user