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