문제: 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
2.8 KiB
2.8 KiB
application-objectstorage — 객체 저장소 포트
등록 정보
- 모듈 ID:
application-objectstorage - Gradle 경로:
:application-objectstorage - 이 모듈만 시험(Gradle 경로에서 나온 명령):
./gradlew :application-objectstorage:test --console=plain - registry 정본:
gradle/modules.json.
패키지 루트: dev.caskeleton.application.objectstorage. 무엇을 주는지와 조립은 README.md에 있다.
책임
- 객체 저장소를 쓰는 쪽이 보는 포트와 그 값 타입: 전송(
ObjectTransferPort), 검사, 게시(staged·managed), 회수, 결과 확인. model·request·identity·content의 값 타입. 구현은adapter:outbound:objectstorage하나다.- testFixtures
testkit: 포트 계약 셋(ManagedObjectStoragePortContract관리 게시·조회·회수,StagedObjectPublicationPortContract단계 게시와 handoff,ObjectScanMaintenancePortContractscan gate)과 in-memory fakeInMemoryObjectStorage. 서비스의 유스케이스 시험은 그 fake를 쓴다.
규칙
- framework·AWS SDK 의존이 없다(
ca.java-library). 허용 의존은 registry의application-core·shared-contract뿐이다. - S3·MinIO 개념(bucket 정책, presign 구현)은 adapter의 것이다. 포트는 저장소에 상관없는 말로 쓴다.
- 포트나 값 타입의 약속을 바꾸면 testFixtures의 포트 계약과 fake를 같은 변경에서 고친다. fake(이 leaf
test)와 adapter(local-dev provider, adaptertest)가 같은 계약을 상속하므로 둘 다 통과해야 한다(docs/manual/10-capabilities.md기준 5). - adapter testFixtures의
ObjectStorageProviderContract는 adapter 안 provider SPI의 계약이다(local-dev와 MinIO lane이 상속). 포트 계약과 섞지 않는다. 그래도 그 시그니처가 이 leaf의 값 타입을 쓰므로, 값 타입을 바꾸면 provider 계약도 같은 변경에서 고친다. - 포트의 결과와 예외는 각 포트 Javadoc이 정한다.
IllegalArgumentException은 요청 그대로를 거절한 것,IllegalStateException은 지금 상태(다른 claimant의 claim, 검증 전, 이미 게시)에서 거절한 것이다. 둘 다 서버 결함이 아니다. 유스케이스는 그대로 던지지 않고 자기 결과나 기능 오류(상태 충돌이면 CONFLICT carrier)로 바꾼다(docs/manual/06-errors.md의 「서버 탓 =IllegalStateException」과 섞이지 않게). - 예외: 설정되지 않았거나 scan이 필요한 destination으로 보낸
IllegalArgumentException은 유스케이스가 고른 destination이 틀린 것, 곧 조립 오류다. 유스케이스는 이것을IllegalStateException(500)으로 바꾸고 클라이언트 오류로 가리지 않는다.
테스트
./gradlew :application-objectstorage:test --console=plain