- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`), 바인딩만 되던 `streaming-idle` 삭제 - `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict), httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제 - persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거 - 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6) - 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷 - 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태 Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest :sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test · -p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
3.0 KiB
Fileserver upgrade guide
Enabling the capability
The Fileserver ships off. Nothing is registered — no endpoint, no thread pool, no metric — until it is enabled explicitly.
app:
fileserver-platform:
enabled: true
instance-id: ${HOSTNAME}
default-namespace: default
observability:
fingerprint-key: ${FILESERVER_FINGERPRINT_KEY}
instance-id must be unique per instance: it is the writer-lease owner, and two nodes sharing one
would both believe they hold the same lease.
fingerprint-key is required and has no default. Startup fails without it rather than falling back
to an unkeyed digest, which would be reversible for an enumerable identifier space.
Optional surfaces
Each is a separate switch, and each defaults to off:
app:
fileserver-platform:
admin:
enabled: false # management plane; intended for a management port
tus:
enabled: false # tus 1.0 Stable
httpbis-draft12:
enabled: false # Experimental; unratified, may change without notice
nginx:
enabled: false # front-proxy delegation; needs a validated internal location
Database schema
The metadata schema is installed as a capability migration and starts inactive:
V1__create_fileserver_metadata.sql → capability_schema_registry: jpa-fileserver-metadata-v1
Activate it deliberately. Enabling the capability without an activated schema fails at startup rather than at the first upload.
Choosing a publish mode
| Mode | When |
|---|---|
atomic-move-preferred |
Default. Uses an atomic rename when the probe proves one, else a metadata pointer. |
atomic-move-required |
Fail closed. Refuses to start on storage that cannot prove an atomic move. |
metadata-pointer |
For storage without atomic rename; publication is the metadata commit. |
Pick atomic-move-required when the storage is certified and you want a misconfiguration to surface
at boot rather than at publish time.
Behaviour that will surprise you
- A delete answers
202, not204, when content still exists. The file is already unreadable; the physical reclaim is deferred. Treating202as a failure will produce spurious retries. - A batch upload answers
200even when parts failed. The batch is explicitly non-atomic, and a single status could not report a partial outcome honestly. Readresults[].problem. - An ambiguous failure must not be retried. Check
"ambiguous": truein the problem document. If-Matchtakes the strong ETag, not a version number. A client can only assert about the representation it was actually served.- Inline rendering is refused for scriptable types even when the caller asks for it.
Verifying an upgrade
cd src
./gradlew verifyCleanArchitectureDependencies --console=plain
./gradlew :application-core:check :adapter:inbound:web:check \
:adapter:outbound:fileserver:check --console=plain
./gradlew :app-bootstrap:test --tests '*Fileserver*' --console=plain