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

Open
donghyeon.kang wants to merge 1 commits from claude/r9-objstore-exceptions into main
Owner

무엇을, 왜

round9 리뷰가 B20을 고치며 찾은 RR9-03-34를 고친다. objectstorage 포트 밖으로 adapter 예외가 그대로 나갔다. 저장소 실패, 내용 불일치, producer·consumer 실패가 ObjectStorageProviderException·ObjectControlConflictException(adapter 패키지)이었다. 포트를 쓰는 유스케이스는 그 타입을 import할 수 없어 RuntimeException으로만 다뤘고, 포트 계약도 그 경우를 「어떤 unchecked 예외든」으로 비워 뒀다.

  • 포트 소유 예외: model.ObjectStorageFailureException 하나와 분류 error()(ObjectOperationError).
    • 분류 셋을 더했다: CONTENT_MISMATCH, CONTENT_PRODUCTION_FAILED, CONTENT_CONSUMPTION_FAILED.
    • 분류마다 뜻(다시 해도 되는가, 원인이 무엇인가)은 그 클래스 Javadoc이 정한다.
    • 포트 8개의 Javadoc이 @throws로 선언한다.
  • 포트 경계 한 곳: routing adapter의 포트 메서드 11개와 handoff 4개가 모두 routing.ObjectStoragePortBoundary를 지난다.
    • provider 실패와 제어 레코드 충돌·손상은 거기서만 포트 예외로 바뀐다.
    • 요청 거절(IllegalArgumentException·IllegalStateException)은 그대로 나간다.
    • handoff 포트는 kernel 서비스가 직접 구현하던 것을 RoutingObjectPublicationHandoffAdapter로 옮겼다.
  • 누가 실패했는지 가르기(provider.ContentCallbackFailures): 전에는 local·S3 모두 producer 자신의 실패, sink 안의 취소, sink의 쓰기 실패를 IO_FAILURE 하나로 뭉갰다.
    • 이제 sink·source가 낸 실패가 먼저다.
    • 그다음은 요청의 취소다.
    • 그 밖은 callback 자신의 실패로 PRODUCER_FAILED·CONSUMER_FAILED가 되고, 그 예외가 원인으로 실린다.
    • S3 PUT이 body 쪽 이유(producer 실패·내용 불일치·호출자 취소)로 끝나면, SDK가 감싼 INDETERMINATE 대신 body가 기록한 분류를 쓴다.
  • 겹친 호출:
    • managed 게시나 finalize가 같은 key의 다른 호출에 CAS를 지고 그 호출이 게시를 끝냈으면, 한 번 더 돌아 REPLAYED다. producer는 다시 부르지 않는다.
    • 아직 끝내지 않았으면 CONFLICT다.
  • fake와 adapter가 갈리던 곳: 중단한 stage의 transferForScan. fake는 IllegalStateException이었고, adapter는 abort가 지운 데이터를 읽으려다 provider 예외를 냈다. adapter도 같은 거절을 먼저 한다.
  • 거절 타입으로 나가던 저장소 장애: 이 PR이 정한 규칙(IAE·ISE는 포트가 선언한 거절에만)대로 고쳤다.
    • local 제어 store IO 실패 → IO_FAILURE
    • 저장 디렉터리에 심긴 symlink·비디렉터리 → CORRUPT_DATA(읽지 않는 것은 그대로)
    • S3 제어 응답에 ETag 없음 → IO_FAILURE
    • 결과를 모르는 create → INDETERMINATE
    • 있어야 할 데이터가 없거나 기록과 다름 → CORRUPT_DATA
    • abort 뒤 retire 실패 → IO_FAILURE(다시 abort하면 된다)
    • 기동 때 root 검사와 adapter가 만든 key의 불변식은 IAE로 남겼다(조립·코드 결함).
  • 반쯤 게시된 reference: 게시는 manifest → pointer → lifecycle 순서로 쓴다. pointer와 lifecycle 사이에서 멈춘 reference를 inspect가 IllegalArgumentException으로 답했다. 이제 빈 값이고, transfer는 「게시되지 않음」 거절이다(포트 Javadoc대로). 같은 key로 다시 게시하면 끝난다.
  • call budget과 시한 초과 가르기: 요청 자신의 budget 소진은 CANCELLED이고, provider·SDK 시한 초과는 PROVIDER_UNAVAILABLE이다. 전에는 둘 다 DEADLINE_EXCEEDED였다.
  • 설정 오류: 권한·owner·region·보존 거절은 UNSUPPORTED_CAPABILITY다(다시 해도 소용없다). create 전 확인(resolveCreate)이 이 거절과 손상까지 「결과 모름」으로 삼키던 것도 고쳤다. 이제 결과를 모르는 실패(IO·시한·throttle·불명)만 그렇다.
  • 세 구현을 하나의 규칙으로: 요청 범위를 정확히 다 읽은 consumer는 EOF를 한 번 더 읽지 않아도 된다(S3만 요구하던 것). 취소를 삼키고 돌아온 producer·consumer도 CANCELLED다(local·fake는 CONTENT_MISMATCH, S3는 CANCELLED였다). 다 쓰고 스스로 실패한 producer는 S3에서도 PRODUCER_FAILED다(SDK가 길이를 다 받고 거는 cancel을 취소로 세던 것).
  • S3 응답 bridge 순서: consumer 실패 때 subscriber를 먼저 cancel하면 SDK가 그것을 stream 실패로 먼저 알릴 수 있었다. 이제 결과를 먼저 완료한 뒤 cancel한다.
  • S3 분류 바로잡기: 읽기 쪽 checksum 증거 불일치와 PUT 응답의 checksum 불일치가 CONTENT_MISMATCH(호출자 바이트 문제)였다. CORRUPT_DATA로 바꿨다. PUT이 암호화 profile을 적용하지 않은 것은 UNSUPPORTED다. body가 선언대로 끝났는데 S3가 BadDigest를 답하면 전송 중 손상이라 IO_FAILURE다(다시 하면 된다). 읽기 증거 불일치(PRECONDITION_FAILED)도 CORRUPT_DATA다. 전에는 포트에서 「그새 바뀜, 다시 해도 됨」으로 읽혔다.

고른 방법과 버린 대안

  • 기존 ObjectOperationError(receipt가 이미 쓰는 분류)를 예외에도 쓴다. 예외마다 타입을 나누는 안(ObjectContentMismatchException 등 여럿)은 버렸다. 유스케이스가 잡을 타입이 늘고, receipt의 분류와 두 어휘가 된다.
  • routing adapter마다 try/catch를 두는 안은 버렸다. 메서드 하나를 빠뜨리면 다시 샌다. 경계 한 곳과 변환표 시험(ObjectStoragePortBoundaryTest)으로 고정한다.
  • 겹친 호출의 충돌을 늘 다시 도는 안은 버렸다. 다른 호출이 아직 쓰는 중이면 producer가 두 번 돌 수 있다. PUBLISHED를 확인한 뒤에만 한 번 더 돈다.

정한 기본값

  • 결정 ⑩(리뷰 기록에 더할 것): 포트 실패는 예외 하나 + 분류다. 분류를 더하는 것은 ObjectOperationError에 값을 더하는 공개 API 변경이다. 소유자가 뒤집을 수 있다.

위험과 영향(파생 서비스가 따라 할 일)

docs/upgrade/2026-11-round9-objectstorage.md 5~14행. 커밋 ! 하나.

  • 겹친 managed 게시에서 진 호출이 CONFLICT를 받고 바로 다시 해도 안전하다. 다른 호출의 DATA_PUT이 진행 중이면 create-if-absent가 하나만 통과시키고, 진 쪽은 다시 CONFLICT다.

검증

desktop, --no-build-cache.

  • RED(b21-red): 기준(B20) 코드에 새 시험과 선언 타입(포트 예외, enum 값)만 얹었다. adapter 쪽 15건이 실패하고 fake 쪽은 모두 통과했다. 실패한 곳은 포트 계약의 내용 불일치·producer·consumer·취소·중단 stage scan, provider 계약의 consumer 둘·producer, 겹친 게시 둘이다.
  • 분야 게이트(b21-green8, 트리 47483690): 두 leaf check, architectureCheck, :app-bootstrap:architectureTest, testQualityCheck 둘, objectStorageMinioContractTest(실제 MinIO). 663건 실패 0, rc=0. MinIO lane은 따로 다섯 번 다시 돌려 모두 통과했다(b21-green6).
  • MinIO가 찾은 것: SDK가 응답 bridge의 실패를 SdkClientException으로 감싸 consumer 실패가 IO_FAILURE로 나왔다. callerSideReadFailure로 고쳤다.
  • desktop scripts/verify.sh pr --no-cache: head e7235bac(트리 7a1986b5) 7103건 실패 0, 건너뜀 35, rc=0, FROM-CACHE 0. 기준 main c7a18ec7. 첫 실행은 SpotBugs USO_UNSAFE_METHOD_SYNCHRONIZATION(바깥에 드러난 자기 객체로 잠금)을 잡았다. AtomicReference로 고쳤다. 둘째 실행에서는 새 BadDigest 시험이 mock 순서 때문에 흔들려 고쳤다. 그 뒤 rc=0이다
  • 노트북: scripts/verify.sh docs rc=0.
  • 새 눈 리뷰 세 바퀴:
    • 리뷰어: reviewer(be-api-contract + be-domain), reviewer(be-testing), arch-reviewer, 3차에 새 reviewer(api-contract + testing + domain).
    • 결과: Critical·High 0. Medium·Low는 모두 고쳤고, 낸 리뷰어가 풀렸다고 확인했다. HARD-STOP 0.
    • 받아들인 한계: fake 안의 「삼킨 sink 실패를 다시 던지는」 두 줄은 계약으로 fake와 adapter에 같은 경우를 만들 수 없어 보조 경로로 둔다. ArchUnit 「경계를 부른다」 규칙은 메서드가 call을 부르는지만 본다.

발견 ID 표

ID 판정 커밋
RR9-03-34 고침(겹친 managed 게시의 CAS 충돌 포함) e7235bac

관련

  • B20 PR #35(병합됨, main c7a18ec7) 다음 묶음이다.
  • 리뷰 기록: docs/reviews/2026-11-12-round9-review/(기록 갱신 PR #36이 RR9-03-34를 적는다).
## 무엇을, 왜 round9 리뷰가 B20을 고치며 찾은 RR9-03-34를 고친다. objectstorage 포트 밖으로 adapter 예외가 그대로 나갔다. 저장소 실패, 내용 불일치, producer·consumer 실패가 `ObjectStorageProviderException`·`ObjectControlConflictException`(adapter 패키지)이었다. 포트를 쓰는 유스케이스는 그 타입을 import할 수 없어 `RuntimeException`으로만 다뤘고, 포트 계약도 그 경우를 「어떤 unchecked 예외든」으로 비워 뒀다. - **포트 소유 예외**: `model.ObjectStorageFailureException` 하나와 분류 `error()`(`ObjectOperationError`). - 분류 셋을 더했다: `CONTENT_MISMATCH`, `CONTENT_PRODUCTION_FAILED`, `CONTENT_CONSUMPTION_FAILED`. - 분류마다 뜻(다시 해도 되는가, 원인이 무엇인가)은 그 클래스 Javadoc이 정한다. - 포트 8개의 Javadoc이 `@throws`로 선언한다. - **포트 경계 한 곳**: routing adapter의 포트 메서드 11개와 handoff 4개가 모두 `routing.ObjectStoragePortBoundary`를 지난다. - provider 실패와 제어 레코드 충돌·손상은 거기서만 포트 예외로 바뀐다. - 요청 거절(`IllegalArgumentException`·`IllegalStateException`)은 그대로 나간다. - handoff 포트는 kernel 서비스가 직접 구현하던 것을 `RoutingObjectPublicationHandoffAdapter`로 옮겼다. - **누가 실패했는지 가르기**(`provider.ContentCallbackFailures`): 전에는 local·S3 모두 producer 자신의 실패, sink 안의 취소, sink의 쓰기 실패를 `IO_FAILURE` 하나로 뭉갰다. - 이제 sink·source가 낸 실패가 먼저다. - 그다음은 요청의 취소다. - 그 밖은 callback 자신의 실패로 `PRODUCER_FAILED`·`CONSUMER_FAILED`가 되고, 그 예외가 원인으로 실린다. - S3 PUT이 body 쪽 이유(producer 실패·내용 불일치·호출자 취소)로 끝나면, SDK가 감싼 `INDETERMINATE` 대신 body가 기록한 분류를 쓴다. - **겹친 호출**: - managed 게시나 finalize가 같은 key의 다른 호출에 CAS를 지고 그 호출이 게시를 끝냈으면, 한 번 더 돌아 `REPLAYED`다. producer는 다시 부르지 않는다. - 아직 끝내지 않았으면 `CONFLICT`다. - **fake와 adapter가 갈리던 곳**: 중단한 stage의 `transferForScan`. fake는 `IllegalStateException`이었고, adapter는 abort가 지운 데이터를 읽으려다 provider 예외를 냈다. adapter도 같은 거절을 먼저 한다. - **거절 타입으로 나가던 저장소 장애**: 이 PR이 정한 규칙(IAE·ISE는 포트가 선언한 거절에만)대로 고쳤다. - local 제어 store IO 실패 → `IO_FAILURE` - 저장 디렉터리에 심긴 symlink·비디렉터리 → `CORRUPT_DATA`(읽지 않는 것은 그대로) - S3 제어 응답에 ETag 없음 → `IO_FAILURE` - 결과를 모르는 create → `INDETERMINATE` - 있어야 할 데이터가 없거나 기록과 다름 → `CORRUPT_DATA` - abort 뒤 retire 실패 → `IO_FAILURE`(다시 abort하면 된다) - 기동 때 root 검사와 adapter가 만든 key의 불변식은 IAE로 남겼다(조립·코드 결함). - **반쯤 게시된 reference**: 게시는 manifest → pointer → lifecycle 순서로 쓴다. pointer와 lifecycle 사이에서 멈춘 reference를 `inspect`가 `IllegalArgumentException`으로 답했다. 이제 빈 값이고, `transfer`는 「게시되지 않음」 거절이다(포트 Javadoc대로). 같은 key로 다시 게시하면 끝난다. - **call budget과 시한 초과 가르기**: 요청 자신의 budget 소진은 `CANCELLED`이고, provider·SDK 시한 초과는 `PROVIDER_UNAVAILABLE`이다. 전에는 둘 다 `DEADLINE_EXCEEDED`였다. - **설정 오류**: 권한·owner·region·보존 거절은 `UNSUPPORTED_CAPABILITY`다(다시 해도 소용없다). create 전 확인(`resolveCreate`)이 이 거절과 손상까지 「결과 모름」으로 삼키던 것도 고쳤다. 이제 결과를 모르는 실패(IO·시한·throttle·불명)만 그렇다. - **세 구현을 하나의 규칙으로**: 요청 범위를 정확히 다 읽은 consumer는 EOF를 한 번 더 읽지 않아도 된다(S3만 요구하던 것). 취소를 삼키고 돌아온 producer·consumer도 `CANCELLED`다(local·fake는 `CONTENT_MISMATCH`, S3는 `CANCELLED`였다). 다 쓰고 스스로 실패한 producer는 S3에서도 `PRODUCER_FAILED`다(SDK가 길이를 다 받고 거는 cancel을 취소로 세던 것). - **S3 응답 bridge 순서**: consumer 실패 때 subscriber를 먼저 cancel하면 SDK가 그것을 stream 실패로 먼저 알릴 수 있었다. 이제 결과를 먼저 완료한 뒤 cancel한다. - **S3 분류 바로잡기**: 읽기 쪽 checksum 증거 불일치와 PUT 응답의 checksum 불일치가 `CONTENT_MISMATCH`(호출자 바이트 문제)였다. `CORRUPT_DATA`로 바꿨다. PUT이 암호화 profile을 적용하지 않은 것은 `UNSUPPORTED`다. body가 선언대로 끝났는데 S3가 BadDigest를 답하면 전송 중 손상이라 `IO_FAILURE`다(다시 하면 된다). 읽기 증거 불일치(`PRECONDITION_FAILED`)도 `CORRUPT_DATA`다. 전에는 포트에서 「그새 바뀜, 다시 해도 됨」으로 읽혔다. ## 고른 방법과 버린 대안 - 기존 `ObjectOperationError`(receipt가 이미 쓰는 분류)를 예외에도 쓴다. 예외마다 타입을 나누는 안(`ObjectContentMismatchException` 등 여럿)은 버렸다. 유스케이스가 잡을 타입이 늘고, receipt의 분류와 두 어휘가 된다. - routing adapter마다 `try/catch`를 두는 안은 버렸다. 메서드 하나를 빠뜨리면 다시 샌다. 경계 한 곳과 변환표 시험(`ObjectStoragePortBoundaryTest`)으로 고정한다. - 겹친 호출의 충돌을 늘 다시 도는 안은 버렸다. 다른 호출이 아직 쓰는 중이면 producer가 두 번 돌 수 있다. PUBLISHED를 확인한 뒤에만 한 번 더 돈다. ## 정한 기본값 - 결정 ⑩(리뷰 기록에 더할 것): 포트 실패는 예외 하나 + 분류다. 분류를 더하는 것은 `ObjectOperationError`에 값을 더하는 공개 API 변경이다. 소유자가 뒤집을 수 있다. ## 위험과 영향(파생 서비스가 따라 할 일) `docs/upgrade/2026-11-round9-objectstorage.md` 5~14행. 커밋 `!` 하나. - 겹친 managed 게시에서 진 호출이 CONFLICT를 받고 바로 다시 해도 안전하다. 다른 호출의 DATA_PUT이 진행 중이면 create-if-absent가 하나만 통과시키고, 진 쪽은 다시 CONFLICT다. ## 검증 desktop, `--no-build-cache`. - RED(`b21-red`): 기준(B20) 코드에 새 시험과 선언 타입(포트 예외, enum 값)만 얹었다. adapter 쪽 15건이 실패하고 fake 쪽은 모두 통과했다. 실패한 곳은 포트 계약의 내용 불일치·producer·consumer·취소·중단 stage scan, provider 계약의 consumer 둘·producer, 겹친 게시 둘이다. - 분야 게이트(`b21-green8`, 트리 `47483690`): 두 leaf `check`, `architectureCheck`, `:app-bootstrap:architectureTest`, `testQualityCheck` 둘, `objectStorageMinioContractTest`(실제 MinIO). 663건 실패 0, rc=0. MinIO lane은 따로 다섯 번 다시 돌려 모두 통과했다(`b21-green6`). - MinIO가 찾은 것: SDK가 응답 bridge의 실패를 `SdkClientException`으로 감싸 consumer 실패가 `IO_FAILURE`로 나왔다. `callerSideReadFailure`로 고쳤다. - desktop `scripts/verify.sh pr --no-cache`: head `e7235bac`(트리 `7a1986b5`) 7103건 실패 0, 건너뜀 35, rc=0, `FROM-CACHE` 0. 기준 main `c7a18ec7`. 첫 실행은 SpotBugs `USO_UNSAFE_METHOD_SYNCHRONIZATION`(바깥에 드러난 자기 객체로 잠금)을 잡았다. `AtomicReference`로 고쳤다. 둘째 실행에서는 새 BadDigest 시험이 mock 순서 때문에 흔들려 고쳤다. 그 뒤 rc=0이다 - 노트북: `scripts/verify.sh docs` rc=0. - 새 눈 리뷰 세 바퀴: - 리뷰어: reviewer(be-api-contract + be-domain), reviewer(be-testing), arch-reviewer, 3차에 새 reviewer(api-contract + testing + domain). - 결과: Critical·High 0. Medium·Low는 모두 고쳤고, 낸 리뷰어가 풀렸다고 확인했다. HARD-STOP 0. - 받아들인 한계: fake 안의 「삼킨 sink 실패를 다시 던지는」 두 줄은 계약으로 fake와 adapter에 같은 경우를 만들 수 없어 보조 경로로 둔다. ArchUnit 「경계를 부른다」 규칙은 메서드가 `call`을 부르는지만 본다. ## 발견 ID 표 | ID | 판정 | 커밋 | | --- | --- | --- | | RR9-03-34 | 고침(겹친 managed 게시의 CAS 충돌 포함) | e7235bac | ## 관련 - B20 PR #35(병합됨, main `c7a18ec7`) 다음 묶음이다. - 리뷰 기록: `docs/reviews/2026-11-12-round9-review/`(기록 갱신 PR #36이 RR9-03-34를 적는다).
donghyeon.kang added 1 commit 2026-11-13 15:08:37 +00:00
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
All checks were successful
pr / done (pull_request) Successful in 13m24s
Required
Details
This pull request is blocked because it's outdated.
You are not authorized to merge this pull request.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin claude/r9-objstore-exceptions:claude/r9-objstore-exceptions
git checkout claude/r9-objstore-exceptions
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#45