# adapter:outbound:objectstorage — 설계 결정 참고 `dev.caskeleton.adapter.outbound.objectstorage` 아래의 object storage driven 어댑터다. `dev.caskeleton.application.objectstorage`의 semantic 계약을 구현하고, provider 키·경로·SDK 타입·제어 레코드를 애플리케이션 경계 뒤에 둔다. 허용 운영 의존은 `gradle/modules.json`이 가진다. 모듈 규칙은 [AGENTS.md](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`](../../../../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에 기대지 않는다). - 추가할 한 줄(기본 조립에는 없다): ```groovy // src/bootstrap/app/build.gradle runtimeOnly project(':adapter:outbound:objectstorage') // 객체 저장소 (S3/로컬) ``` 이 줄을 지우면 port 구현, provider, 설정 바인딩이 모두 함께 빠진다. - 켜기와 끄기: 모듈이 있으면 켜진다. `app.object-storage.enabled=false`로만 끄고, 그때 모듈은 아무 bean도 두지 않는다. - env 키: `APP_OBJECTSTORAGE_ENABLED`(끄기) 하나뿐이다. provider·destination은 map 구조라 배포의 `application-*.yml`에 `app.object-storage.{default-destination, providers..*, destinations..*}`를 적는다(아래 「켜기와 라우팅」). 빠지면 기동 시 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를 덮는다. ```bash ./gradlew :adapter:outbound:objectstorage:check --console=plain ``` ### 포트 계약 이 leaf의 포트 구현(`RoutingObjectMutationAdapter`, `RoutingObjectReadAdapter`, `ObjectPublicationHandoffService`, `RoutingObjectScanMaintenanceAdapter`)은 application-objectstorage testFixtures의 포트 계약 셋을 local-dev provider 위에서 상속한다(`contract/LocalDev*ContractTest`). in-memory fake도 같은 계약을 상속한다. 포트 동작을 바꾸면 두 쪽이 함께 통과해야 한다. ### 새 provider를 위한 provider 계약 `ObjectStorageProvider` SPI가 이 leaf의 것이므로 `ObjectStorageProviderContract`는 이 leaf의 test fixtures에 있다. local-dev provider(`LocalDevObjectStorageProviderTest`)와 MinIO에 대고 도는 S3 provider (`MinioS3ManagedObjectProviderContractTest`)가 모두 그것을 상속한다. 파생 서비스가 더하는 provider는 복사하지 않고 같은 클래스를 상속한다: ```groovy 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: `로 실패한다: 어댑터 결함이 아니라 공급 실패다. lane은 건너뛰지 않는다. 건너뛴 vendor lane은 vendor 증거 없이 초록이 되기 때문이다. - 같은 digest의 mirror는 `OBJECT_STORAGE_MINIO_IMAGE`나 `-PobjectStorageMinioImage=/@sha256:`로 정한다. 증거 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`가 덮어쓴다). ```bash ./gradlew :adapter:outbound:objectstorage:objectStorageMinioContractTest --console=plain ```