Files
clean-architecture-backend-…/docs/fileserver/configuration.md
T
DongHyeonka bbe944bd3c fix!: 재리뷰가 찾은 결함과 색인에서 빠졌던 발견 5건을 고친다
문제: 성숙도 리뷰 수정을 다시 읽은 재리뷰(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·의존 없음이어야 한다.
2026-11-03 23:29:35 +09:00

12 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 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

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.