test(objectstorage): 포트 계약을 포트 소유 leaf에 두고 fake와 adapter가 함께 통과하게 한다

문제: 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
This commit is contained in:
DongHyeonka
2026-11-13 13:49:40 +09:00
parent b44aa49e7a
commit 1ab96de01d
33 changed files with 3507 additions and 39 deletions
+34
View File
@@ -372,6 +372,40 @@ testFixtures(`dev.caskeleton.application.fileserver.testkit`)에 있고, 실제
- 소유자 규칙: fake와 실제 정책이 같은 규칙을 따로 썼다(principal·tenant 비교 두 벌). 정본
`FileAccessSubject.owns` 하나를 둘 다 부른다. fake 규칙에서 tenant 비교를 빼는 변이가 계약 2건으로 잡힌다.
### 9.4 application-objectstorage 포트 (2026-11-13 round9 리뷰 RR9-03-31)
포트 8개. 계약 셋과 fake는 `application-objectstorage` testFixtures(`dev.caskeleton.application.objectstorage.testkit`)에
있다. 실제 구현 쪽은 adapter `test`의 `contract` 패키지가 local-dev provider 위에서 돌린다. 계약은 각 포트
Javadoc이 선언한 결과와 예외 타입만 단언한다. 예외 메시지는 구현의 것이라 단언하지 않는다.
| 포트 | 계약 | fake | 상속하는 실제 구현 테스트 |
| --- | --- | --- | --- |
| `ManagedObjectPublicationPort`·`ObjectInspectionPort`·`ObjectTransferPort`·`ObjectOperationResolutionPort`·`ObjectRetirementPort` | `ManagedObjectStoragePortContract` | `InMemoryObjectStorage` | `LocalDevManagedObjectStorageContractTest` |
| `StagedObjectPublicationPort`·`ObjectPublicationHandoffPort` | `StagedObjectPublicationPortContract` | 같은 fake | `LocalDevStagedObjectPublicationContractTest` |
| `ObjectScanMaintenancePort` | `ObjectScanMaintenancePortContract` | 같은 fake | `LocalDevObjectScanMaintenanceContractTest` |
- 실제 벤더: S3 provider는 readiness registry(`docs/registries/object-storage-readiness.yaml`)에서 아직 배포
대상이 아니다. MinIO에서는 provider 계약(`ObjectStorageProviderContract`, `objectStorageMinioContractTest`)이
돈다. 포트 계약을 MinIO로 묶는 일은 S3를 배포 대상으로 올릴 때 같이 한다.
- 소비자 없는 fake(9.2, 결정 2026-11-03)의 예외: 이 fake의 소비자는 객체 저장소를 쓰는 서비스의 유스케이스
시험이다. 템플릿 안에는 그런 유스케이스가 없지만 capability 기준 5(`docs/manual/10-capabilities.md`)가 fake를
요구한다(round9 리뷰 6절 ⑧).
- lease 만료 경로(만료 뒤 다른 claimant, 만료된 claim의 finalize)는 계약에 없다. 계약의 lease는 5분이고
시계를 움직이지 않는다. adapter 쪽은 `StagedObjectPublicationLifecycleTest`가 고정 시계로 본다.
계약을 처음 적용할 때 드러난 것과 처리:
- 운영 결함: 불변 Set(`Set.of`)으로 만든 게시·stage 요청이 `ObjectRequestSupport`의 `contains(null)`에서 NPE를
냈다. 원소를 도는 검사로 고쳤다(`ObjectRequestCapabilitiesTest`).
- adapter: 실패한 managed 게시를 다시 하면 이번 호출이 게시했는데도 `REPLAYED`였다(stage는 `APPLIED`). 이제
`PUBLISHED`로 바꾼 호출 하나만 `APPLIED`다(같은 key로 겹친 호출은 `REPLAYED`, `ManagedPublicationOutcomeTest`).
검증한 뒤 중단한 stage를 다시 검증하면 `REPLAYED`였다. 이제 중단된 operation의 검증은 거절한다.
- fake를 실제에 맞춘 것: 실패한 게시·stage도 operation을 남긴다(복구 조회는 진행 중), 범위를 끝까지 읽지 않은
consumer를 거절한다, capability 집합은 같은 의도 판정에 넣지 않는다, 중단한 stage의 검증을 거절하고 판정
뒤에도 중단으로 둔다.
- adapter 전용 예외 `ObjectStorageProviderException`이 포트 밖으로 나간다. 그래서 바이트 불일치와 consumer
실패는 계약이 "unchecked 예외"까지만 단언한다(round9 리뷰 RR9-03-34, 따로 고친다).
### 9.2 계약이 없는 포트 (의도)
| 포트 | 실제 구현 | fake | 계약이 없는 이유 | 다음 단계 |