Files
clean-architecture-backend-…/src/adapter/outbound/objectstorage
DongHyeonka ecc1400486 fix(objectstorage): Minio TLS 시험이 CI job 안에서도 컨테이너에 닿는다
문제: MinioS3ManagedObjectProviderContractTest는 endpoint를
`https://localhost:<포트>`로 고정했다. Gitea runner의 job 컨테이너 안에서
localhost는 job 컨테이너 자신이고, Testcontainers가 띄운 MinIO는 dind
daemon 쪽에 있다. 그래서 main의 integration job이 run 52·63·79 세 번 모두
이 시험의 연결 거부로 빨갛다. desktop에서는 둘이 같아 통과한다. 시험
인증서도 localhost와 127.0.0.1만 이름으로 가졌다.

고른 방법: 같은 lane의 평문 시험(MinioManagedObjectContractTest)처럼
Testcontainers가 알려 주는 Docker 호스트 주소로 붙고, 그 주소를 인증서
SAN에 더한다(IP면 ip:, 이름이면 dns:). 인증서는 컨테이너보다 먼저
만들어야 하므로 주소는 DockerClientFactory에서 받는다.

버린 대안: 인증서 검증을 끄는 것. 이 시험은 운영 클라이언트 그대로
HTTPS로 붙는 것이 목적이라 검증을 끄면 시험이 다른 경로를 본다.

위험·한계: IPv6 호스트는 URI에 대괄호를 씌우는 것만 넣었고 그 환경에서
돌려 보지 않았다.

검증: desktop integrationCheck, runner main 수동 실행(이 PR 본문에 적는다).
2026-11-12 01:16:56 +09:00
..

adapter:outbound:objectstorage — 설계 결정 참고

dev.caskeleton.adapter.outbound.objectstorage 아래의 object storage driven 어댑터다. dev.caskeleton.application.objectstorage의 semantic 계약을 구현하고, provider 키·경로·SDK 타입·제어 레코드를 애플리케이션 경계 뒤에 둔다.

허용 운영 의존은 gradle/modules.json이 가진다. 모듈 규칙은 AGENTS.md, 전체 설계는 docs/design/2026-07-28-objectstorage-production-capability-design.md, 정확한 증거 주장은 docs/registries/object-storage-readiness.yaml에 있다.

HTTP 파일 서버 플랫폼 대신 이 capability를 언제 쓰는지는 docs/storage-capability-boundary.md를 본다.

지금 준비 상태

Batch B가 provider 중립 namespace·제어 핵심과 filesystem-local-dev의 관리형 단일 업로드·다운로드를 R1으로 구현한다. R1은 한계 있는 로컬 기능 증거만 뜻한다:

  • 정확한 SHA-256과 정확한 version 검사를 하는, 바뀌지 않는 streaming 생성;
  • 전체·범위 지정의 한계 있는 읽기;
  • 엄격한 정규형 제어 레코드 codec과 단일 프로세스 CAS;
  • producer를 다시 부르지 않는 같은 operation의 재생;
  • 재시작·경로·symlink·손상·장애 특성 확인;
  • 고른 provider의 lifecycle을 정확히 한 번.

여러 노드 CAS, 전원 상실 내구성, 운영 credential·TLS·IAM·암호화, S3 응답 유실 동작, R2 준비는 증명하지 않는다. direct transfer, multipart, quarantine, retention, 운영 reconciliation card는 R0에 머문다. direct transfer와 multipart는 코드가 없다: 조립되지 않은 구현을 지웠다(되살리는 길은 docs/capability-status.md 「제거된 코드」).

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

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

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

    // src/bootstrap/app/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>.*}를 적는다(아래 「켜기와 라우팅」). 빠지면 기동 시 binding compile이 실패한다.

켜기와 라우팅

정해진 namespace는 app.object-storage다. 모듈이 있으면 켜지고 app.object-storage.enabled=false일 때만 꺼진다. 켜려면 명시한 provider, 정확한 provider version, 논리 destination, route token, binding·policy revision, 한계 있는 크기가 필요하다. 고른 provider가 디렉터리, client, 스레드, scheduler, credential 조회를 만들기 전에 설정을 모두 컴파일한다.

filesystem-local-dev는 prod/production에서 거절한다. 보통 조립은 관리형 게시, 조회·전송, 폐기, operation 해석 포트만 기여한다. scanner 유지보수 조립은 따로 둔다. purge나 direct-grant 포트는 없다.

S3 폐기는 HEAD가 확인한 정확한 version을 지운다(versionId를 준 DeleteObject). DELETE에 If-Match 조건은 쓰지 않는다: 검증한 MinIO 릴리스는 그것을 무시하고(MinIO lane에서 낡은 ETag로도 지워진다), SDK는 그것을 directory bucket에만 적는다. version id를 준 DELETE는 HEAD 뒤에 들어온 덮어쓰기를 건드릴 수 없으니, vendor가 header를 지키는지에 기대지 않고도 조건부다. versioning이 켜진 bucket이 필요하다: CONDITIONAL_RETIREMENT를 주장하는 S3 operation profile은 기동 때 GetBucketVersioning을 읽고 Enabled가 아니면 거절한다. version id를 찾지 못한 폐기는 키 기준 삭제로 바꾸지 않고 거절한다.

로컬 provider는 provider 중립 논리 제어 키를 .record leaf 파일에 대응시킨다. 그래서 reference와 reference/lifecycle처럼 object store에서는 맞는 짝이 파일 시스템의 파일·디렉터리 충돌 없이 함께 있을 수 있다. 호출자와 durable 제어 레코드는 정규 논리 키를 그대로 가진다.

provider와 의존 범위

Spring Boot가 software.amazon.awssdk:*를 관리하지 않으니 AWS SDK v2 BOM은 모듈 범위에 둔다. byte[] 전체를 쓰던 ObjectStoragePort 세대와 그 파일 시스템·S3 어댑터는 지웠다. 정해진 semantic 포트가 유일한 세대다 (되살리는 길은 docs/capability-status.md 「제거된 코드」).

검증

이 모듈만 보는 계약이 codec·상태 기계, 로컬 provider 동작, 실패하면 닫히는 바인딩, 조립 부작용·lifecycle, 라우팅 재생·읽기 동작, readiness registry를 덮는다.

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

새 provider를 위한 provider 계약

ObjectStorageProvider SPI가 이 leaf의 것이므로 ObjectStorageProviderContract는 이 leaf의 test fixtures에 있다. local-dev provider(LocalDevObjectStorageProviderTest)와 MinIO에 대고 도는 S3 provider (MinioS3ManagedObjectProviderContractTest)가 모두 그것을 상속한다. 파생 서비스가 더하는 provider는 복사하지 않고 같은 클래스를 상속한다:

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

MinIO 검증 lane

objectStorageMinioContractTest와 objectStorageMinioFaultTest는 실제 MinIO와 Toxiproxy를 돌린다. 루트 integrationCheck(main push와 nightly)에서 돈다. 이 leaf의 mainCheck에서는 돌지 않는다. 거기서도 돌던 때는 main push마다 두 번 돌았다. object storage를 건드린 pull request에서 따로 돌던 workflow job은 2026-11-08에 지웠다(같은 태스크를 integrationCheck가 돌린다). image는 파일 하나 src/test/resources/object-storage/minio-provider-evidence.json에서 읽는다. 그 image digest는 옆에 적힌 status, excludedProfiles, limitations를 잰 릴리스다. MinioQualificationImage(src/test에 있고, leaf의 test가 Docker 없이 검사한다)가 그것을 읽는다.

  • container를 만들기 전에 image를 받는다. 받지 못하면 lane은 pinned image unavailable: <reference>로 실패한다: 어댑터 결함이 아니라 공급 실패다. lane은 건너뛰지 않는다. 건너뛴 vendor lane은 vendor 증거 없이 초록이 되기 때문이다.
  • 같은 digest의 mirror는 OBJECT_STORAGE_MINIO_IMAGE나 -PobjectStorageMinioImage=<registry>/<repo>@sha256:<evidence digest>로 정한다. 증거 digest로 끝나지 않는 값은 거절한다: 다른 build는 새 측정이고, lane을 다시 돌려 증거 파일(image와 측정 결과를 함께)을 다시 써서 만든다.
  • 로컬 compose 런타임(compose.yaml, 그리고 compose lane의 smoke client src/bootstrap/app/compose-lanes/lane-services.yaml. LOCAL_MINIO_IMAGE)도 같은 digest를 쓴다. ComposeMinioImageMatchesEvidenceTest(leaf test)는 compose 기본값과 증거가 다르면 실패한다. 둘을 함께 바꾼다.
  • contract lane은 MinioS3ManagedObjectProviderContractTest도 돌린다: S3 어댑터 자체를 local-dev provider가 상속하는 provider 계약 아래에서, 운영 client factory로, 그 실행을 위해 만든 인증서로 TLS 위에서 시험한다 (binding은 HTTPS만 받는다). 첫 실행에서 mock 단위 시험이 찾지 못한 어댑터 결함 둘을 찾았다: SDK가 Content-Length 바이트를 받으면 요청 body를 취소해서(빈 body이면 바로) 모든 생성이 실패했고, Netty가 8 KiB buffer로 넘겨서 network buffer 크기보다 작은 소비자 chunk로 하는 모든 읽기가 실패했다. 둘 다 고쳤다 (S3AsyncRequestBodyBridge, S3AsyncResponseBodyBridge.TRANSPORT_BUFFER_CEILING_BYTES).

image 출처 (review 05-09, 2026-11-02 측정)

Docker Hub minio/minio와 quay.io/minio/minio가 MinIO 제공을 멈춰서, 옛 릴리스(2024-01-16)의 측정한 digest를 mirror할 수 없었다. 유지되는 build 둘을 받아 같은 요청(create-only PUT 두 번, 낡은·현재 If-Match PUT, 있는 키 위의 create-only multipart 완료, 낡은 If-Match DELETE)으로 쟀다:

후보 결과 결정
pgsty/minio@sha256:b6bfe723…(Docker Hub의 커뮤니티 fork, RELEASE.2026-08-04T00-00-00Z) 412 / 412, 200 / 412. DELETE는 If-Match를 무시한다 골랐다. 이름 있는 릴리스 태그, compose bucket 준비용 셸이 있는 pgsty/mc, 옛 image처럼 root로 돈다
cgr.dev/chainguard/minio@sha256:0a011000…(RELEASE.2026-10-23T20-06-51Z) 같은 결과 버렸다: 무료 등급은 움직이는 latest 태그만 주고, uid 65532로 돌며(compose volume 소유자를 바꿔야 한다), cgr.dev/chainguard/minio-client에는 셸이 없다

새 릴리스는 옛 릴리스가 받아 주던 create-only 덮어쓰기를 거절한다. 그래서 증거는 이제 관리형 create-only profile(supportedProfiles)에 대해 status: SUPPORTED이고, direct(presigned) profile은 재지 않았으니 계속 빠지며, 어댑터 허용 목록에 provider 타입 s3-compatible-minio-pgsty-release-2026-08-04t00-00-00z(version release-2026-08-04t00-00-00z-sdk-2.30.0)가 더해졌다. 그 릴리스만 IMMUTABLE_CREATE를 주장할 수 있다. 증거가 단일 노드 container 하나이므로 어떤 MinIO 릴리스도 MULTI_NODE_LINEARIZABLE_CAS나 RESPONSE_LOSS_RESOLUTION을 주장할 수 없다. 2024-01-16 타입은 아직 그것을 돌리는 서버를 위해 옛 제한과 함께 남는다.

compose client minio-init은 digest로 pgsty/mc를 쓴다(LOCAL_MINIO_MC_IMAGE가 덮어쓴다).

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