문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(Critical 0, 회귀 0)가 Important 27건·Minor 41건을 찾았다. 수정이 새로 만든 결함이 많았다. @SystemInvoked가 권한 규칙의 탈출구가 됐고, 데모 계정 거부가 정확히 prod일 때만 걸렸고, outbox 순서 번호가 업그레이드 때 뒤로 갔고, GraphQL union 아래 복잡도가 0이었고, 서블릿 오류 응답이 success:true로 나갔고, 호출자 deadline이 breaker를 열었다. 원래 리뷰 색인이 06 영역 발견 5건(06-10~14)을 빠뜨려 그동안 처리되지 않았다. 방법: 영역별 7묶음이 test-driven-development 절차로 실패 테스트를 먼저 쓰고 고쳤다. 결정은 재리뷰 README 4절에 적었다: 순서 번호는 V21이 기록한 전역 floor부터, 데모 계정은 local·test·demo 허용 목록, @SystemInvoked bean은 기동 실패, complete 단계 실패는 IDEMPOTENCY_COMPLETION_UNKNOWN(결과 불명), 캐시 조건부 쓰기는 별도 SCRIPT lane, strict lane 정책은 build cache 입력, 끝나지 않는 재시도 행은 원인 코드·지표·PARKED 절차. 레지스트리가 선언만 하고 아무 코드도 내보내지 않던 redis.capability.* 지표 6개는 빼고 runbook을 실제 지표(redis.lane.*) 기준으로 고쳤다. 위험·한계: V21을 V22 없이 직접 고쳤다(어느 배포에도 아직 없음). 이 브랜치의 V21을 적용한 개발 DB는 다시 만들어야 한다. 서블릿 오류 디스패치를 보안 체인이 허용한다. 발행·저장소 포트 시그니처가 바뀌어 파생 서비스 코드가 깨진다. prod에서 fixture-로 시작하는 설정값은 기동을 막는다. httpclient failure-injection lane의 main 단계 중복 실행은 이전 결정대로 남겼다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, :integrationCheck, -p optional-platforms ci integrationCheck performanceCheck, :performanceCheck, :releaseCheck (-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. 첫 실행의 실패 2건(FindSecBugs 1, sample 동시 생성 테스트의 v4 event id)은 고친 뒤 ci·integrationCheck·mainCheck를 다시 돌려 통과했다. Refs: docs/reviews/2026-11-03-rereview/README.md 3·4·6·7절 BREAKING CHANGE: outbox 발행 포트와 저장소 포트 시그니처, 순서 번호 첫 값(V21 floor 다음), 샘플 데모 계정 프로필 허용 목록, 새 오류 코드 IDEMPOTENCY_COMPLETION_UNKNOWN, prod의 fixture- 값 거부, 기동 rule은 static·의존 없음이어야 한다.
210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# Fileserver configuration
|
|
|
|
Every key below lives under `app.fileserver-platform` (environment form
|
|
`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.
|
|
|
|
## Minimum to start
|
|
|
|
```yaml
|
|
app:
|
|
fileserver-platform:
|
|
enabled: true
|
|
instance-id: ${HOSTNAME} # writer-lease owner; must be unique per node
|
|
storage:
|
|
root: /var/lib/backend/files # absolute, outside any webroot or config dir
|
|
security:
|
|
access-policy: role-based # or supply your own 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 |
|
|
|
|
## Authorization — `security`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `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 |
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
`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.
|
|
|
|
## Storage — `storage`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `root` | `/var/lib/backend/files` | absolute path; the only place a path exists |
|
|
| `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) |
|
|
|
|
`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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Upload, download, transfer
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `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 |
|
|
|
|
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.
|
|
|
|
## Verification — `verification`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `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 |
|
|
|
|
Set `inline-safe-profile: true` only when downloads are never served inline from a trusted origin.
|
|
|
|
## Quota and admission — `quota`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `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 |
|
|
|
|
`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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Background reclamation — `cleanup`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `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 |
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
`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.
|
|
|
|
## Management plane — `admin`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `enabled` | `false` | expose `/internal/fileserver/**` |
|
|
| `orphan-minimum-age` | `1h` | how long an unreferenced object must exist before a scan may name it |
|
|
|
|
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.
|
|
|
|
## Front-proxy delegation — `nginx`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `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 |
|
|
|
|
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.
|
|
|
|
## Protocols — `tus`
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `enabled` | `false` | expose the tus 1.0 endpoints |
|
|
|
|
The HTTPbis resumable-upload draft-12 surface is experimental and documented in
|
|
[support-matrix.md](support-matrix.md).
|