fix(web-advanced)!: patch·stream·virtual thread가 약속한 계약대로 답한다
문제: web-advanced의 계약 문서와 코드가 다섯 곳에서 갈렸다. - patch 거부가 세 코드로 갈렸다. 형식 오류는 PATCH_REJECTED(400), 빈 문서·연산 모양 오류·merge 깊이 초과는 IllegalArgumentException이라 BAD_PARAMETER(400), 너무 깊은 pointer는 권한 거절 PATCH_PATH_FORBIDDEN(403) 이었다. JSON이 아닌 본문과 결과가 대상 타입으로 읽히지 않는 patch는 Jackson 예외로 catch-all에 닿아 500 INTERNAL_ERROR였다. - patch-contract.md는 결과를 문서 전체로 검증한다고 했지만 두 applier는 검증기를 받지 않았다. - streaming-contract.md는 서버가 위치 증가를 강제하고 heartbeat·idle·max age·버퍼 상한·drain 재연결을 한다고 했다. MvcStreamWriter는 그 어느 것도 하지 않았다. - commit 뒤 Failure 기록이 어디에도 등록되지 않은 DEPENDENCY_FAILURE로 고정이라, STREAM_ITEM_TOO_LARGE 같은 carrier 코드가 사라졌다. - virtual thread profile은 503 + Retry-After를 약속했지만 admission guard는 bean만 있었고 요청 경로에서 아무도 부르지 않았다. - web AGENTS B2는 merge patch를 쓰지 않는다고 했고 patch-contract는 필드 변경에 merge patch를 쓰라고 했다(정본 충돌). 고른 방법: - 형식이 틀린 patch 문서는 모두 JsonPatchRejectedException(PATCH_REJECTED) 이다. 본문 파싱과 결과 변환은 PatchBodies가 감싼다. 너무 깊은 pointer는 권한 검사 앞에서 400으로 거절한다. 대상 타입이 객체가 아닌 것은 서버 결함이라 IllegalStateException이다. - 두 applier가 Bean Validation Validator를 받아 결과 객체 전체를 검증한다. 위반은 @Valid 본문과 같은 ConstraintViolationException → VALIDATION_FAILED. - writer는 위치가 앞 항목보다 크지 않으면 그 항목을 쓰지 않고 INTERNAL_ERROR Failure 기록으로 끝낸다. Failure 기록은 cause 사슬의 carrier 코드, 없으면 INTERNAL_ERROR, 문구는 category 고정 문구다. - writer가 할 수 없는 것(heartbeat, idle·max age, 버퍼, drain)은 계약 문서를 고쳐 누가 하는지(WebStreamPolicy·Registry·DrainCoordinator를 쓰는 서비스) 적었다. 요청 thread의 동기 writer라 heartbeat를 넣으려면 thread 모델을 바꿔야 해서 버렸다. - VirtualThreadAdmissionFilter가 모든 요청을 guard 아래 둔다(request-id filter 바로 뒤). async 요청은 async가 끝날 때 permit을 돌려준다. guard에 Permit API를 더했다. - 정본 충돌은 리뷰 README 6절 ③대로 patch-contract를 정본으로 두고 web AGENTS B2가 그쪽을 가리킨다. 위험·한계: patch를 쓰는 서비스는 applier 생성자에 Validator를 넘겨야 컴파일된다. client가 보는 patch·stream 오류 코드가 바뀐다. virtual thread profile을 켠 배포는 처음으로 상한에 걸릴 수 있다(upgrade 안내 1~5). BREAKING CHANGE: JsonMergePatchApplier·JsonPatchApplier 생성자가 Validator를 받는다. patch 거부는 모두 PATCH_REJECTED(400), 결과 제약 위반은 VALIDATION_FAILED, stream Failure 코드는 실패의 코드나 INTERNAL_ERROR다. 할 일은 docs/upgrade/2026-11-round9-contracts.md. Refs: RR9-03-23, RR9-03-24, RR9-03-25, RR9-03-26, RR9-03-27, RR9-03-28
This commit is contained in:
@@ -38,6 +38,10 @@ route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작
|
||||
**한도.** 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다
|
||||
서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
|
||||
|
||||
**거부 코드.** 형식이 틀린 문서(JSON이 아닌 본문, 빈 문서, 한도 초과, 연산 모양 오류)는 모두 `400 PATCH_REJECTED`다.
|
||||
허용 목록 밖의 경로만 `403 PATCH_PATH_FORBIDDEN`이고, 실패한 `test`는 `409 PATCH_TEST_FAILED`다. 너무 깊은 pointer는
|
||||
권한 문제가 아니라 형식 문제라 400이다.
|
||||
|
||||
## 원자성
|
||||
|
||||
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고
|
||||
@@ -63,6 +67,11 @@ patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검
|
||||
객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도
|
||||
보지 못한다.
|
||||
|
||||
- 두 applier는 서비스의 Bean Validation `Validator`를 생성자로 받고, 결과 객체 전체를 검증한 뒤에 돌려준다. 위반은
|
||||
`@Valid` 본문과 같은 `400 VALIDATION_FAILED`와 필드별 `details`다.
|
||||
- 결과가 자원 타입으로 읽히지 않으면(숫자 자리에 문자열) `400 PATCH_REJECTED`다.
|
||||
- 상태 전이처럼 업무 규칙인 검증은 여기서 하지 않는다. 유스케이스가 한다.
|
||||
|
||||
## 선행 조건
|
||||
|
||||
patch route는 `If-Match`를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.
|
||||
|
||||
Reference in New Issue
Block a user