설계: 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>
9.1 KiB
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
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.