fix(objectstorage)!: 포트 밖으로 adapter 예외를 내보내지 않고 포트 실패 하나로 알린다 #45

Open
donghyeon.kang wants to merge 1 commits from claude/r9-objstore-exceptions into main
1 Commits
Author SHA1 Message Date
DongHyeonka e7235bacf2 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
2026-11-13 21:31:38 +09:00