fix(objectstorage)!: 포트 밖으로 adapter 예외를 내보내지 않고 포트 실패 하나로 알린다
pr / done (pull_request) Successful in 13m24s

objectstorage 포트가 저장소 실패, 내용 불일치, producer·consumer 실패를
adapter의 ObjectStorageProviderException·ObjectControlConflictException으로
그대로 내보냈다. 유스케이스는 그 타입을 import할 수 없어 실패를 가르지
못했고, 포트 계약도 그 경우를 "어떤 unchecked 예외든"으로 비워 뒀다.
저장소 장애·손상 일부는 요청 거절 타입(IAE·ISE)으로 나가 거절로 읽혔다.

- 포트 소유 예외 ObjectStorageFailureException과 분류 error()를 둔다.
  ObjectOperationError에 CONTENT_MISMATCH·CONTENT_PRODUCTION_FAILED·
  CONTENT_CONSUMPTION_FAILED를 더하고 포트 Javadoc이 @throws로 선언한다.
- routing adapter의 포트 메서드와 handoff 포트(RoutingObjectPublicationHandoffAdapter)가
  모두 ObjectStoragePortBoundary 한 곳을 지나 거기서만 바뀐다. ArchUnit이 지킨다.
- ContentCallbackFailures가 sink·source가 낸 실패, 요청 취소, callback 자신의
  실패를 가른다. sink·source는 callback에 선언된 chunk 예외만 던진다.
- 저장소 장애·손상은 거절 타입이 아니다: 제어 store IO, 저장 디렉터리의 symlink,
  결과 모르는 create, 기록과 다른 저장 객체, 제어 레코드 누락. resolveCreate는
  결과를 모르는 실패만 INDETERMINATE로 답한다.
- 요청 call budget 소진은 CANCELLED, provider·SDK 시한 초과는 PROVIDER_UNAVAILABLE,
  설정 거절(권한·owner·region·보존)은 UNSUPPORTED_CAPABILITY다.
- S3는 SDK가 감싼 실패 대신 bridge가 기록한 호출자 쪽 분류를 쓴다(PUT·GET).
  정확히 다 읽은 consumer는 EOF를 읽지 않아도 된다(local·fake와 같게).
- 겹친 managed 게시·finalize에서 진 호출은 상대가 게시를 끝냈으면 REPLAYED다.
- 게시 중(pointer만 있고 lifecycle 없음)인 reference는 inspect가 빈 값이다.
- 중단한 stage의 scan 전송을 adapter도 거절한다(fake와 같게).
- 포트 계약·provider 계약(MinIO lane 포함)이 실패 분류까지 단언한다.

BREAKING CHANGE: 포트 호출의 실패가 ObjectStorageFailureException이다.
ObjectOperationError에 값 셋이 늘었다. ObjectPublicationHandoffService는
포트를 구현하지 않는다. 할 일은 docs/upgrade/2026-11-round9-objectstorage.md
5~14행이다.

Refs: RR9-03-34
This commit is contained in:
DongHyeonka
2026-11-13 21:31:38 +09:00
parent c7a18ec7fa
commit e7235bacf2
55 changed files with 2539 additions and 192 deletions
+6 -2
View File
@@ -376,7 +376,8 @@ testFixtures(`dev.caskeleton.application.fileserver.testkit`)에 있고, 실제
포트 8개. 계약 셋과 fake는 `application-objectstorage` testFixtures(`dev.caskeleton.application.objectstorage.testkit`)에
있다. 실제 구현 쪽은 adapter `test`의 `contract` 패키지가 local-dev provider 위에서 돌린다. 계약은 각 포트
Javadoc이 선언한 결과와 예외 타입만 단언한다. 예외 메시지는 구현의 것이라 단언하지 않는다.
Javadoc이 선언한 결과와 예외 타입, 그리고 `ObjectStorageFailureException`이면 그 분류(`error()`)만 단언한다. 예외
메시지는 구현의 것이라 단언하지 않는다.
| 포트 | 계약 | fake | 상속하는 실제 구현 테스트 |
| --- | --- | --- | --- |
@@ -386,7 +387,10 @@ Javadoc이 선언한 결과와 예외 타입만 단언한다. 예외 메시지
- 실제 벤더: S3 provider는 readiness registry(`docs/registries/object-storage-readiness.yaml`)에서 아직 배포
대상이 아니다. MinIO에서는 provider 계약(`ObjectStorageProviderContract`, `objectStorageMinioContractTest`)이
돈다. 포트 계약을 MinIO로 묶는 일은 S3를 배포 대상으로 올릴 때 같이 한다.
돈다. 그 계약은 producer·consumer 자신의 실패, 내용 불일치, 취소, 범위를 다 읽지 않은 consumer의 실패
종류(`ObjectStorageProviderException.Failure`)를 보므로, 그 분류가 S3 경로에서도 같은지 MinIO에서 확인된다.
손상·설정 거절 분류는 S3 단위 시험(SDK mock)이 본다. 포트 계약을 MinIO로 묶는 일은 S3를 배포 대상으로 올릴 때
같이 한다.
- 소비자 없는 fake(9.2, 결정 2026-11-03)의 예외: 이 fake의 소비자는 객체 저장소를 쓰는 서비스의 유스케이스
시험이다. 템플릿 안에는 그런 유스케이스가 없지만 capability 기준 5(`docs/manual/10-capabilities.md`)가 fake를
요구한다(round9 리뷰 6절 ⑧).