Files
clean-architecture-backend-…/src/adapter/outbound/objectstorage
DongHyeonka 81573f7098 build(deps): Checkstyle 도구의 plexus-utils를 3.6.1로 고정한다
문제: Checkstyle 13.5.0의 doxia 1.12.0이 plexus-utils 3.3.0을 가져온다. HIGH
CVE-2025-67030(extractFile 경로 조작)이 있고 3.x 줄에서는 3.6.1, 4.x에서는
4.0.3에서 고쳤다. 모든 leaf의 checkstyle 구성에 걸린다.

고친 방법: 앞 커밋의 `pinned-*` 묶음에 `pinned-plexus-utils`(3.6.1)를 더한다.
3.x 안에서 고친 가장 작은 버전이다.
- 버린 대안: 4.0.3. 메이저다. 4.0은 XML 클래스를 plexus-xml로 떼어 냈다.
- 버린 대안: doxia를 뺀 Checkstyle 13.11.0으로 올리기. plexus-utils는
  사라지지만 Checkstyle 규칙이 여섯 마이너만큼 바뀐다.

위험·한계: doxia는 Checkstyle의 사이트 문서 생성에만 쓰여 Gradle checkstyle
태스크에서는 plexus-utils를 거의 부르지 않는다. 그래도 모든 leaf의
checkstyle이 이 구성으로 돈다.

검증(desktop, 이 트리 00b8e235):
- 세 빌드를 `--write-locks`로 다시 썼다. lockfile 64개의 checkstyle 구성에서
  plexus-utils 3.3.0→3.6.1만 바뀌었다.
- `./gradlew :ci :verifyDependencyLocks --warning-mode=fail` rc=0, 6분 32초,
  태스크 752(executed 641, up-to-date 111). checkstyle 태스크 109개가 실제로 돌았다.
- `./gradlew -p platforms/optional-build ci verifyDependencyLocks` rc=0,
  checkstyle 태스크 17개 실행.
2026-11-07 17:47:41 +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