- 결정 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>
83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
# 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.
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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`, not `204`, when content still exists.** The file is already unreadable;
|
|
the physical reclaim is deferred. Treating `202` as a failure will produce spurious retries.
|
|
- **A batch upload answers `200` even when parts failed.** The batch is explicitly non-atomic, and a
|
|
single status could not report a partial outcome honestly. Read `results[].problem`.
|
|
- **An ambiguous failure must not be retried.** Check `"ambiguous": true` in the problem document.
|
|
- **`If-Match` takes 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
|
|
|
|
```bash
|
|
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
|
|
```
|