문제: 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
4.7 KiB
Web patch: client 계약
patch 형식은 둘이고, 서로 바꿔 쓸 수 없다. 두 applier 모두 adapter:inbound:web-advanced(골라 쓰는 leaf)의 라이브러리
코드다. 서비스가 그 leaf를 더하고 자기 controller에서 JsonMergePatchApplier나 JsonPatchApplier를 부른다.
하나 고르기
route는 정확히 하나만 받고, 다른 것을 보내면 최선의 짐작 대신 415다. 어긋남이 가장 나쁜 방향으로 조용하기 때문이다.
{"a": null}은 merge patch로는a를 지운다. JSON Patch로는 patch가 아예 아니다. 배열이 필요한 곳의 객체다.- JSON Patch 배열을 merge patch로 읽으면 필드가 배열 index인 문서다. 아무것도 합치지 않고 성공을 보고한다.
| Merge patch | JSON Patch | |
|---|---|---|
| Media type | application/merge-patch+json |
application/json-patch+json |
| RFC | 7396 | 6902 |
| 모양 | 부분 문서 | 순서 있는 연산 배열 |
| 삭제 | "field": null |
{"op":"remove","path":"/field"} |
| 배열 | 통째로 바꾼다 | index마다 가리킬 수 있다 |
| 선행 조건 | If-Match만 |
If-Match, 그리고 필드별 test |
「이 필드들을 바꿔라」에는 merge patch를 쓴다. 배열 원소를 고치거나, If-Match로 표현할 수 없는 필드 하나의 선행
조건이 필요하면 JSON Patch를 쓴다.
거부하는 것
허용 목록 밖의 필드. 서버가 merge patch가 바꿀 수 있는 필드와 JSON Patch가 가리킬 수 있는 pointer를 선언한다. 그 밖의 것은 거부하고, 거부한 경로는 모두 이름을 댄다. 왕복 한 번에 하나씩 알게 되지 않는다.
허용 목록은 무엇이든 적용하기 전에 검사한다. 거부는 지금 값에 대해 아무것도 알려 주지 않는다. 일부러 그렇다. 거부한 필드가 「실제로 무언가를 바꿨는지」를 나중에 따지면 읽어서는 안 되는 데이터에 대한 질문에 답하게 된다.
pointer 권한은 위로 올라가지 않는다. /profile에 대한 권한은 /profile/displayName을 덮는다.
/profile/displayName에 대한 권한은 /profile을 덮지 않는다. 부모를 바꾸면 모든 형제가 지워지기 때문이다.
move는 양쪽 끝의 권한이 필요하다. 목적지만 검사하면 건드릴 수 없는 필드의 데이터를 옮겨 낼 수 있다.
한도. 연산은 최대 100개, pointer 깊이는 최대 16, merge patch 중첩 깊이는 최대 32. 앞의 둘은 곱해진다. 연산마다 서버가 먼저 깊이 복사한 문서 위로 pointer를 따라 걷는다.
거부 코드. 형식이 틀린 문서(JSON이 아닌 본문, 빈 문서, 한도 초과, 연산 모양 오류)는 모두 400 PATCH_REJECTED다.
허용 목록 밖의 경로만 403 PATCH_PATH_FORBIDDEN이고, 실패한 test는 409 PATCH_TEST_FAILED다. 너무 깊은 pointer는
권한 문제가 아니라 형식 문제라 400이다.
원자성
JSON Patch 문서는 전부 적용되거나 하나도 적용되지 않는다. 모든 연산은 작업 사본에서 돈다. 모든 연산이 성공하고 결과가 전체 검증을 통과하기 전에는 자원을 건드리지 않는다.
그래서 test가 쓸모 있다. test를 맨 앞에 둔 client는 test가 실패하면 그 뒤의 어떤 것도 일어나지 않았다고 믿고,
그 믿음은 지켜진다.
[
{"op": "test", "path": "/version", "value": 4},
{"op": "replace", "path": "/displayName", "value": "new"}
]
실패한 test는 400이 아니라 409다. 문서는 형식이 맞고 허락됐지만, 자원이 기대한 상태가 아니었을 뿐이다. 다시
읽고 재시도한다. 응답은 실패한 pointer의 이름을 대고 서버의 값은 돌려주지 않는다. 돌려주면 test가 읽어서는 안 되는
필드를 읽는 도구가 된다.
검증
patch를 적용한 결과는 필드 하나씩이 아니라 문서 전체로 검증한다. 필드 하나하나는 모두 유효한 patch가 유효하지 않은 객체를 만들 수 있다. 서로 맞아야 하는 두 필드, 허락되지 않은 상태 전이 같은 것이다. 바뀐 것만 검증하면 그중 아무것도 보지 못한다.
- 두 applier는 서비스의 Bean Validation
Validator를 생성자로 받고, 결과 객체 전체를 검증한 뒤에 돌려준다. 위반은@Valid본문과 같은400 VALIDATION_FAILED와 필드별details다. - 결과가 자원 타입으로 읽히지 않으면(숫자 자리에 문자열)
400 PATCH_REJECTED다. - 상태 전이처럼 업무 규칙인 검증은 여기서 하지 않는다. 유스케이스가 한다.
선행 조건
patch route는 If-Match를 요구한다. 그 사이에 바뀐 자원에 대한 부분 갱신은 본 적 없는 버전에 변경을 적용한다.