Files
clean-architecture-backend-…/docs/fileserver/upgrade-guide.md
T
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 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>
2026-09-29 17:01:54 +09:00

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

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