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

5.2 KiB

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가 한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.