문제: 앞 커밋 뒤에도 알림·파일 서버 묶음이 합쳐지지 않았고, 포트 다수에 fake와 실제 구현이 함께 통과하는 공유 계약이 없었고, SpotBugs가 신뢰도 HIGH만 봤고, application-core에 관계없는 클래스 묶음 패키지(outbound)가 있었다. 묶음을 합치자 lane·검사가 새로 드러낸 결함도 있었다(JpaOutbox Store가 읽기 전용 트랜잭션에서 이벤트를 조용히 잃음, gRPC admission controller가 public synchronized라 외부 lock에 막힘, 소비자 decode 타입 등록 경로 없음, compose Redis 익명 접근, local-fileserver lane DB 없음). 방법: 리뷰 README 15절에 남은 결정을 모두 적고 그대로 고쳤다. 트랜잭션· 멱등성·발행·notification 포트에 testFixtures 계약 키트를 두고 fake와 PG·Redis 구현이 상속한다(fake 변이로 계약이 잡는지 확인). SpotBugs는 MEDIUM으로 내리고 진짜 결함은 고치고 오탐은 위치·패턴별 이유를 단 제외로 처리했다. 업무 기능 패키지 규칙을 application-core/CLAUDE.md에 정본으로 두고 ArchUnit 2개와 생성 명령이 강제한다. compose Redis는 infra/redis-sdk ACL로 뜬다. 묶음별 결과는 리뷰 README 16절에 있다. 위험·한계: APP_FLYWAY_ENABLED가 dev·prod에도 적용된다. app.security 오타 키가 이제 기동을 막는다. SES 콜백 replay 창 기본값이 1시간이다. 템플릿 패키지 목록은 CLAUDE.md 표와 TemplatePackageOwnership 두 곳에 있고 일치 검사는 없다. 실제 CI runner 실행은 확인하지 못했다. 검증: ci, mainCheck, integrationCheck, -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision), verify-compose-profile-contracts(18 lane) 통과. compose lane 실제 기동: local-fileserver, notification ingest·serving·handoff, local-redis, all-adapters(smoke 3개 포함). Refs: docs/reviews/2026-11-01-maturity-review/README.md 15·16절 BREAKING CHANGE: APP_FLYWAY_ENABLED가 dev·prod 프로필에도 적용되고, app.security의 모르는 키는 기동을 거부한다. MessageHandler에 schemaVersions()가 생겨 decode 목록을 handler 선언에서 만든다.
206 lines
12 KiB
Markdown
206 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 or copy that would pass it is refused with `QUOTA_EXCEEDED` (413) before any record or byte exists |
|
|
|
|
`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.
|
|
|
|
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).
|