설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
175 lines
9.1 KiB
Markdown
175 lines
9.1 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
|
|
capability is off, the admin plane is off, background reclamation is off, 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
|
|
ca-skeleton:
|
|
fileserver:
|
|
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 FileAccessPolicy 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 `FileAccessPolicy` 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 |
|
|
|
|
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 namespace admits |
|
|
| `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 are refused |
|
|
|
|
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` | `false` | run the cleanup worker on this node |
|
|
| `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 deletes physical objects, so it is off until a deployment decides otherwise. A node
|
|
without it still queues cleanup items; another node or an operator reclaims them. An item that fails
|
|
eight times is abandoned rather than retried forever — it stays visible to an operator, parked
|
|
rather than discarded.
|
|
|
|
## 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).
|