Files
clean-architecture-backend-…/src/adapter/outbound/objectstorage
DongHyeonka afe30e733d build(deps): Spring Boot를 4.0.9로 올린다
문제: Boot 4.0.8 BOM이 고르는 버전에 trivy HIGH·CRITICAL이 있다.
- tomcat-embed-core 11.0.24: CRITICAL 4건. CVE-2026-65182(보안 제약 우회),
  CVE-2026-65637(HTTP/2 SNI 검사 우회), CVE-2026-65905(DIGEST 인증 재전송),
  CVE-2026-68525(FORM 인증 우회). 11.0.25에서 고쳤다.
- jackson 2.21.5(core·databind): HIGH CVE-2026-89407·89425·68497·91776·91777.
  2.21.7에서 고쳤다.
- jackson 3.1.5(core·databind): 같은 CVE 다섯. 3.1.7에서 고쳤다.
이 셋이 trivy 37건 중 15건이다.

고친 방법: Boot 패치 4.0.9 하나로 올린다. 4.0.9 BOM은 tomcat 11.0.27,
jackson-bom 2.21.7·3.1.7을 고른다. Spring이 함께 시험한 묶음을 그대로 받는다.
- 버린 대안: `tomcat.version`·`jackson-2-bom.version`·`jackson-bom.version`
  BOM 속성 override. Boot가 고른 짝과 어긋나고, 지울 조건을 세 곳에 둬야 한다.
- 버린 대안: Boot 4.1.x. 마이너 업그레이드다(Kafka 4.2, httpclient5 5.6 등이
  같이 바뀐다).
카탈로그 주석의 「Spring Boot 4.0.8's own plugin」도 4.0.9로 고쳤다. 4.0.9의
플러그인도 dependency-management 1.1.7을 가져온다.

같이 바뀐 것(모두 4.0.9 BOM 안의 패치): Spring Framework 7.0.9→7.0.10,
Security 7.0.7→7.0.8, Data 4.0.7→4.0.8(Mongo 5.0.7→5.0.8), Integration
7.0.6→7.0.7, GraphQL 2.0.5→2.0.6, graphql-java 25.0→25.1, Hibernate
7.2.24→7.2.25, Hibernate Validator 9.0.1→9.0.2, Netty 4.2.17→4.2.19, Jetty
12.1.12→12.1.14, Micrometer 1.16.7→1.16.8, Reactor 3.8.7→3.8.8, slf4j
2.0.18→2.0.20, PostgreSQL JDBC 42.7.13→42.7.14. lockfile 65개.

위험·한계: 위 라이브러리의 패치 범위 동작 변화는 받는다. commons-lang3
override(3.20.0)는 4.0.9도 3.19.0을 관리하므로 그대로 둔다. 문서에 적힌
「Spring Boot 4.0.8」은 이 커밋에서 고치지 않는다(check-docs 예외 목록에 얼어
있다). build-logic 테스트 fixture의 4.0.8은 그 테스트가 스스로 만드는
카탈로그 값이다.

검증(desktop, 이 트리 2d387179):
- 세 빌드(주, optional, build-logic)를 `--write-locks`로 다시 쓴 뒤 lockfile을
  (좌표, 구성) 쌍으로 비교: 위 버전만 바뀌었고 새로 생기거나 사라진 구성 0.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 2초,
  태스크 752(executed 589, from cache 106, up-to-date 57).
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0, 1분 7초.
2026-11-07 17:10:19 +09:00
..

adapter:outbound:objectstorage — design-decision reference

Object-storage driven adapter under dev.caskeleton.adapter.outbound.objectstorage. It implements the semantic contracts in dev.caskeleton.application.objectstorage and keeps provider keys, paths, SDK types, and control records behind the application boundary.

The allowed production dependencies are owned by src/config/architecture/modules.json. Module rules live in CLAUDE.md, the full design in docs/design/2026-07-28-objectstorage-production-capability-design.md, and exact evidence claims in docs/registries/object-storage-readiness.yaml.

For when to use this capability rather than the HTTP Fileserver platform, see docs/storage-capability-boundary.md.

Current readiness

Batch B implements the provider-neutral namespace/control kernel and filesystem-local-dev managed single upload/download at R1. R1 means bounded local functional evidence only:

  • immutable streamed create with exact SHA-256 and exact version inspection;
  • full/range bounded reads;
  • strict canonical control-record codecs and single-process CAS;
  • same-operation replay without invoking the producer again;
  • restart/path/symlink/corruption/fault characterization;
  • exactly-once selected-provider lifecycle.

It does not prove multi-node CAS, power-loss durability, production credentials/TLS/IAM/encryption, S3 response-loss behavior, or R2 readiness. Direct transfer, multipart, quarantine, retention, and production reconciliation cards remain R0. Direct transfer and multipart have no code: the unassembled implementation was removed (recovery path in docs/capability-status.md 「제거된 코드」).

제공하는 것 · 추가할 한 줄 · env 키

  • 제공: application-objectstorage의 semantic port 구현(ManagedObjectPublicationPort, 읽기/변경 routing adapter), filesystem-local-dev와 S3 provider. 진입점은 모듈 자신의 AutoConfiguration.imports에 있는 ObjectStorageAutoConfiguration 하나이고, 설정 바인딩도 그 안에서 한다(composition root의 properties scan에 기대지 않는다).

  • 추가할 한 줄(기본 조립에는 없다):

    // app-bootstrap/build.gradle
    runtimeOnly project(':adapter:outbound:objectstorage')  // 객체 저장소 (S3/로컬)
    

    이 줄을 지우면 port 구현, provider, 설정 바인딩이 모두 함께 빠진다.

  • 켜기와 끄기: 모듈이 있으면 켜진다. app.object-storage.enabled=false로만 끄고, 그때 모듈은 아무 bean도 두지 않는다.

  • env 키: 전용 APP_* 키는 없다. provider·destination이 map 구조라 배포의 application-*.yml에 app.object-storage.{default-destination, providers.<id>.*, destinations.<id>.*}를 적는다(아래 「Activation and routing」). 빠지면 기동 시 binding compile이 실패한다.

Activation and routing

The canonical namespace is app.object-storage. It is on when the module is present and off only with app.object-storage.enabled=false. On requires an explicit provider, exact provider version, logical destination, route token, binding/policy revisions, and bounded sizes. Settings compile fully before any selected provider creates a directory, client, thread, scheduler, or credential lookup.

filesystem-local-dev is rejected under prod/production. Normal composition contributes only managed publication, inspection/transfer, retirement, and operation-resolution ports. Scanner maintenance composition stays separate. There is no purge or direct-grant port.

S3 retirement deletes the exact version a HEAD verified (DeleteObject with versionId). An If-Match condition on DELETE is not used: the qualified MinIO release ignores it (the MinIO lane shows a stale ETag still deleting), and the SDK documents it for directory buckets only. A version-id DELETE cannot touch an overwrite that landed after the HEAD, so it is conditional without relying on the vendor honouring a header. It needs a bucket with versioning enabled: an S3 operation profile that claims CONDITIONAL_RETIREMENT makes startup read GetBucketVersioning and refuse anything but Enabled, and a retire that finds no version id is refused rather than turned into a by-key delete.

The local provider maps provider-neutral logical control keys to .record leaf files. This permits object-store-valid pairs such as reference and reference/lifecycle without a filesystem file/directory collision; callers and durable control records retain the canonical logical keys.

Provider and dependency scope

The AWS SDK v2 BOM stays module-scoped because Spring Boot does not manage software.amazon.awssdk:*. The whole-byte[] ObjectStoragePort generation and its filesystem/S3 adapters were removed; the canonical semantic ports are the only generation (recovery path in docs/capability-status.md 「제거된 코드」).

Verification

Focused contracts cover codecs/state machines, local provider behavior, fail-closed binding, composition side effects/lifecycle, routing replay/read behavior, and the readiness registry.

cd src
./gradlew :adapter:outbound:objectstorage:check --console=plain

Provider contract for a new provider

ObjectStorageProviderContract is in this leaf's test fixtures, because the ObjectStorageProvider SPI is this leaf's own. The local-dev provider (LocalDevObjectStorageProviderTest) and the S3 provider against MinIO (MinioS3ManagedObjectProviderContractTest) both extend it. A provider a derived service adds extends the same class instead of copying it:

testImplementation testFixtures(project(':adapter:outbound:objectstorage'))

MinIO qualification lanes

objectStorageMinioContractTest and objectStorageMinioFaultTest run a real MinIO and Toxiproxy. They run in the root integrationCheck (main push and nightly) and in .github/workflows/object-storage-qualification.yml on pull requests that touch object storage — not in this leaf's mainCheck, which ran them a second time on every main push. Their images are read from one file, src/test/resources/object-storage/minio-provider-evidence.json, whose image digest is the release the status, excludedProfiles and limitations beside it were measured on. MinioQualificationImage (in src/test, checked by the leaf's test without Docker) reads it.

  • The image is pulled before any container is built. If it cannot be pulled the lane fails with pinned image unavailable: <reference>: a supply failure, not an adapter defect. The lane does not skip, because a skipped vendor lane would be green with no vendor evidence.
  • A mirror of the same digest is set with OBJECT_STORAGE_MINIO_IMAGE or -PobjectStorageMinioImage=<registry>/<repo>@sha256:<evidence digest>. A value that does not end in the evidence digest is refused: a different build is a new measurement, made by re-running the lanes and rewriting the evidence file (image and findings together).
  • The local compose runtime (compose.yaml, and the compose lanes' smoke client in src/app-bootstrap/compose-lanes/lane-services.yaml; LOCAL_MINIO_IMAGE) uses the same digest. ComposeMinioImageMatchesEvidenceTest (leaf test) fails when the compose default and the evidence disagree; change both together.
  • The contract lane also runs MinioS3ManagedObjectProviderContractTest: the S3 adapter itself under the provider contract the local-dev provider inherits, on the production client factory, over TLS with a certificate made for the run (a binding only accepts HTTPS). Its first run found two adapter defects the mocked unit tests could not: every create failed because the SDK cancels the request body once it holds Content-Length bytes (and at once for an empty body), and every read with a consumer chunk below the network buffer size failed because Netty delivers 8 KiB buffers. Both are fixed (S3AsyncRequestBodyBridge, S3AsyncResponseBodyBridge.TRANSPORT_BUFFER_CEILING_BYTES).

Image source (review 05-09, measured 2026-11-02)

Docker Hub minio/minio and quay.io/minio/minio stopped serving MinIO, so the measured digest of the old release (2024-01-16) could not be mirrored. Two maintained builds were pulled and measured with the same requests (create-only PUT twice, stale and current If-Match PUT, create-only multipart completion onto an existing key, stale If-Match DELETE):

Candidate Result Decision
pgsty/minio@sha256:b6bfe723… (community fork on Docker Hub, RELEASE.2026-08-04T00-00-00Z) 412 / 412, 200 / 412; DELETE ignores If-Match Chosen. Named release tags, pgsty/mc with a shell for the compose bucket bootstrap, runs as root like the old image
cgr.dev/chainguard/minio@sha256:0a011000… (RELEASE.2026-10-23T20-06-51Z) Same results Rejected: the free tier offers only a moving latest tag, it runs as uid 65532 (the compose volume would need re-owning), and cgr.dev/chainguard/minio-client has no shell

The new release refuses create-only overwrites, which the old one accepted. So the evidence is now status: SUPPORTED for the managed create-only profiles (supportedProfiles), the direct (presigned) profiles stay excluded because they were not measured, and the adapter allowlist gained the provider type s3-compatible-minio-pgsty-release-2026-08-04t00-00-00z (version release-2026-08-04t00-00-00z-sdk-2.30.0). Only that release may claim IMMUTABLE_CREATE; no MinIO release may claim MULTI_NODE_LINEARIZABLE_CAS or RESPONSE_LOSS_RESOLUTION, because the evidence is one single-node container. The 2024-01-16 type stays for servers that still run it, with its old restrictions.

The compose client minio-init uses pgsty/mc by digest (LOCAL_MINIO_MC_IMAGE overrides it).

cd src
./gradlew :adapter:outbound:objectstorage:objectStorageMinioContractTest --console=plain