Files
clean-architecture-backend-…/docs/web/streaming-contract.md
T
DongHyeonka 18188f78c9 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
2026-11-13 04:08:16 +09:00

81 lines
5.2 KiB
Markdown

# Web 스트리밍: client 계약
이 플랫폼의 NDJSON이나 `application/json-seq`를 받으려면 client가 무엇을 구현해야 하는지 적는다. SSE framing은 있지만,
WebFlux 쌍을 지운 뒤(2026-09-25) servlet stack에서는 아무것도 그것을 쓰지 않는다.
writer는 `adapter:inbound:web-advanced`(골라 쓰는 leaf, `app.web.advanced.ndjson.enabled` /
`app.web.advanced.json-sequence.enabled`로 켠다)에 있다. 기본 조립에는 없다.
## 끝은 둘이 아니라 셋이다
첫 바이트 뒤에는 HTTP 상태가 200이고 바뀔 수 없다. 그래서 상태는 stream이 성공했는지 아무것도 말해 주지 않고, 닫힌
connection은 결과를 알 수 없다. 끝은 셋이다.
1. **`Complete` envelope.** stream이 끝났다. `lastSequence`가 마지막 위치다.
2. **`Failure` 기록.** commit 뒤에 무언가 실패했다. 상태는 여전히 200이다. `code`는 실패한 예외의 코드다(예:
`STREAM_ITEM_TOO_LARGE`). 코드가 없는 실패는 등록된 `INTERNAL_ERROR`다. `message`는 그 category의 고정 문구다. commit 전에
던져졌다면 받았을 코드·문구와 같다.
3. **둘 다 아님.** stream 중간에 connection이 닫혔다. 서버는 이것을 `ABRUPT_CLOSE`로 기록한다. client 쪽에서는 *끝
envelope를 찾지 않는 한* 끝난 stream과 구분할 수 없다.
**닫힌 connection을 완료로 보는 client는 데이터를 조용히 잘라 먹는다.** 어떤 서버 변경도 그것을 대신 고칠 수 없다.
끝 envelope를 찾는 것이 계약이다.
## 위치
모든 `Item`은 1부터 세는 `sequence`를 가진다. 위치는 엄격히 증가하고, 서버가 그것을 강제한다. 반복이나 후퇴는 client가
견뎌야 할 것이 아니라 서버 쪽 오류다. writer는 그런 항목을 쓰지 않고 stream을 `INTERNAL_ERROR` `Failure` 기록으로 끝낸다.
0은 절대 유효한 위치가 아니다. 첫 항목이 0을 주장한 stream과 sequence를 아예 정하지 않은 stream이 똑같아 보이기
때문이다.
## 이어 받기
route가 지원하면 마지막으로 적용한 위치를 `Last-Event-ID`로 보낸다.
- source가 아직 그 위치를 가지고 있으면 다음 위치부터 이어서 보낸다.
- 가지고 있지 않으면 응답은 부분 stream이 아니라 **resnapshot-required** 오류다. 남아 있는 가장 오래된 위치부터 이어
주면 위치는 이어지는데 가운데에 구멍이 생기고, 데이터 어디에도 그 사실이 드러나지 않는다.
resnapshot은 자원을 보통 endpoint에서 다시 읽고 새 stream을 시작한다는 뜻이다. 그것을 싸게 할 수 없는 client는 이어
받기 경로를 쓰지 않는다.
## Framing
| 형식 | Media type | Framing | 잘렸을 때 |
| --- | --- | --- | --- |
| SSE | `text/event-stream` | `data:` 줄, 빈 줄로 구분 | 끝에 반쪽 event |
| NDJSON | `application/x-ndjson` | JSON 값 하나, 그다음 `\n` | 잘린 줄에는 줄바꿈이 없고, 잃은 것이 바로 구분자다 |
| JSON-seq | `application/json-seq` | `0x1E`, 값, `\n` | 다음 `0x1E`가 모호함 없이 다음 기록의 시작이다 |
잘림이 중요하면 JSON-seq를 쓴다. 구분자가 *먼저* 오므로, parser는 잘린 것과 뒤따르는 것을 이어 파싱하려 하지 않고 다음
기록에서 다시 맞춘다. 오래 사는 stream에서는 잘림이 보통의 끝이다.
기록에는 날것의 줄바꿈이 절대 없다. 서버가 그것을 쓰기를 거부한다. NDJSON에서는 소비자의 줄 나누기가 유일한 기록
경계이기 때문이다.
## Heartbeat와 시간 초과
writer(`MvcStreamWriter`)는 요청 thread에서 source를 차례로 쓴다. 그래서 heartbeat를 보내지 않고, `idleTimeout`·
`maxStreamAge`로 stream을 닫지도 않는다. 그 값은 `WebStreamPolicy`에 있고, 자기 stream을 `WebStreamRegistry`에 올려
돌리는 서비스가 쓴다.
- client는 heartbeat를 기대하지 않는다. 자기 읽기 시간 초과를 두고, 그 시간에 아무것도 오지 않으면 끝 envelope 없이
닫힌 것으로 보고 이어 받기 cursor로 다시 연결한다.
- socket에서는 조용한 connection과 끊긴 connection이 같다. heartbeat가 필요한 route는 서비스가 그것을 더하고 이 문서의
route 설명에 적는다.
## 느린 소비자
writer는 버퍼를 두지 않는다. 느린 소비자는 서버의 쓰기를 막고, 그동안 source도 멈춘다. 서버 heap에 밀린 항목이 쌓이지
않는다. `maxBufferedItems`는 버퍼를 두는 서비스 구현의 한도다. 따라가지 못하는 client는 이어 받기 cursor로 다시 연결한다.
## 종료
drain 순서(받기를 멈추고, 다시 연결을 요청하고, 기한에 강제로 닫기)는 `WebStreamDrainCoordinator`에 있다. 서비스가
자기 stream을 `WebStreamRegistry`에 등록하고 그 조정기를 종료 순서에 넣었을 때만 돈다. 기본 writer만 쓰는 배포에서는
종료 때 열린 stream이 갑작스러운 닫힘으로 끝난다.
갑작스러운 닫힘에 backoff와 jitter 없이 바로 다시 연결하지 않는다. 노드의 stream이 한꺼번에 끊겼을 때 모든 client가
한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.