Files
clean-architecture-backend-…/src/adapter/outbound/objectstorage
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +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/superpowers/specs/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 (docker-compose.infra.yml, 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