문제: capability 기준 5(docs/manual/10-capabilities.md)는 포트를 가진 모듈의
testFixtures에 포트 계약을 두고 fake와 실제 adapter가 모두 통과하게 한다.
application-objectstorage에는 testFixtures도 fake도 없었다. 포트 수준 동작은 adapter
안의 local-dev 시험으로만 봤고, 포트 인터페이스는 결과와 예외를 적지 않았다.
capability-status는 app-bootstrap 통합 시험이 MinIO로 조립한다고 적었지만 실제로는
local-dev다.
고친 것:
- 포트 여덟의 Javadoc에 결과(APPLIED·REPLAYED·REJECTED 등)와 예외 타입을 적었다.
IllegalArgumentException은 요청 그대로를, IllegalStateException은 지금 상태에서의
거절이다. 유스케이스가 감싸 기능 오류로 바꾸고, 설정이 틀린 destination은 조립
오류(500)로 바꾼다(AGENTS 규칙). 예외 메시지는 구현의 것이라 계약이 단언하지 않는다.
- testFixtures testkit: 계약 셋(ManagedObjectStoragePortContract 관리 게시·조회·
전송·복구 조회·회수, StagedObjectPublicationPortContract 단계 게시·handoff·중단,
ObjectScanMaintenancePortContract scan gate), in-memory fake InMemoryObjectStorage,
destination 설명 ObjectStorageDestinationPolicy.
- fake(이 leaf test)와 adapter routing 구현(local-dev, adapter test contract/LocalDev*)이
같은 계약을 상속한다. adapter 쪽 destination 설명은 조립된 policySnapshot에서 읽는다.
- adapter에서 계약이 드러낸 것 둘:
- 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 REPLAYED였다(stage 재시도는
APPLIED). 이제 PUBLISHED로 바꾼 호출 하나만 APPLIED다. 같은 key로 겹친 호출은
REPLAYED다(ManagedPublicationOutcomeTest가 겹침을 결정적으로 재현한다).
- 검증한 뒤 중단한 stage를 다시 검증하면 REPLAYED였다. 중단된 operation의 검증을
거절한다.
- 문서: application-objectstorage AGENTS·README, adapter README 「포트 계약」,
TESTING_STRATEGY 9.4, capability-status Object storage 증거 칸.
버린 대안: MinIO에서 포트 계약 돌리기. S3 provider는 readiness registry에서 아직 배포
대상이 아니다(docs/registries/object-storage-readiness.yaml). 포트 경로를 MinIO로 묶는
일은 S3를 배포 대상으로 올리는 일과 같이 간다. MinIO에서는 provider 계약이 돈다.
남은 것: adapter 전용 ObjectStorageProviderException이 포트 밖으로 나가 바이트
불일치·consumer 실패는 계약이 unchecked 예외까지만 단언한다(RR9-03-34, 따로 고친다).
검증: desktop, :application-objectstorage:check :adapter:outbound:objectstorage:check
:app-bootstrap:architectureTest architectureCheck -p build-logic test 726건 실패 0.
RED: main에 ManagedPublicationOutcomeTest만 → 실패. 돌연변이: adapter의 회수 재시도를
REPLAYED→APPLIED로 바꾸면 계약 1건이 실패한다.
Refs: RR9-03-31, RR9-03-35, RR9-04-46
11 KiB
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_OBJECTSTORAGE_ENABLED(끄기) 하나뿐이다. 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
포트 계약
이 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는 복사하지
않고 같은 클래스를 상속한다:
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 clientsrc/bootstrap/app/compose-lanes/lane-services.yaml.LOCAL_MINIO_IMAGE)도 같은 digest를 쓴다.ComposeMinioImageMatchesEvidenceTest(leaftest)는 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