문제: docs/web 아래 살아 있는 문서 7개가 영어였다(language 예외). http-contract.md는 짝 프론트 repo의 문서를 이 repo 경로처럼 인라인 코드로 적었다(reference 예외). repository-adaptation.md는 번역하며 보니 지금 코드와 여러 곳이 달랐다. - 1절 표: 설계 모듈 대부분을 「planned」로 적었지만 `core`·`mvc`는 web leaf에, `contract`·`versioning`·`admin`·`openapi`·`idempotency`는 web-advanced leaf에 이미 있다. `fileserver.*`·`notification.*`는 web leaf가 아니라 web-fileserver·web-notification leaf다. - Advanced 절: Advanced가 「이 leaf」의 package이고 `WebArchitectureRules.stableDoesNotDependOnAdvanced()` (`WEB-ARCH-ADV`)가 방향을 막는다고 했다. 그런 규칙은 없고, Advanced는 따로 된 leaf `adapter:inbound:web-advanced`이며 registry가 web-advanced → web 방향만 허락한다. - 4절: Spring Boot 기준을 4.0.8로 옮겨 적고 없는 `.vscode/settings.json`을 근거로 들었다. - 6절: 다시 보내기 JSON 인코딩이 web leaf에 남는다고 했지만 web-advanced에 있다. - 7절: web leaf가 의존할 수 있는 leaf에서 `adapter-outbound-support`가 빠졌다. 고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·설정 key·오류 코드·표 구조는 원문으로 둔다. 위 불일치는 registry와 트리에 맞춰 고쳤다. 다른 repo 문서는 경로 대신 repo 이름과 문서 이름을 문장으로 쓴다. 버전은 src/gradle/libs.versions.toml을 가리킨다. 버린 대안: 1절 표를 지우고 registry만 가리키기. 설계와 트리를 대조하는 사람에게 필요한 대응이 사라진다. 위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 검증: python3 scripts/check-docs.py에서 이 폴더 예외 줄 0. docs/web을 읽는 테스트는 주석뿐이다(`grep -rn 'docs/web' src --include=*.java`: EnvelopeWireShapeTest 등 주석).
4.5 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은 결과를 알 수 없다. 끝은 셋이다.
Completeenvelope. stream이 끝났다.lastSequence가 마지막 위치다.Failure기록. commit 뒤에 무언가 실패했다. 오류 code와 client에게 보여도 되는 메시지를 담는다. 상태는 여전히 200이다.- 둘 다 아님. stream 중간에 connection이 닫혔다. 서버는 이것을
ABRUPT_CLOSE로 기록한다. client 쪽에서는 끝 envelope를 찾지 않는 한 끝난 stream과 구분할 수 없다.
닫힌 connection을 완료로 보는 client는 데이터를 조용히 잘라 먹는다. 어떤 서버 변경도 그것을 대신 고칠 수 없다. 끝 envelope를 찾는 것이 계약이다.
위치
모든 Item은 1부터 세는 sequence를 가진다. 위치는 엄격히 증가하고, 서버가 그것을 강제한다. 반복이나 후퇴는 client가
견뎌야 할 것이 아니라 서버 쪽 오류다.
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와 시간 초과
서버는 heartbeatInterval마다 keepalive를 쓴다. 그보다 오래 아무것도 보지 못한 client는 connection이 죽었다고 봐야
한다. socket에서는 조용한 connection과 끊긴 connection이 같고, heartbeat가 둘을 가른다.
stream은 idleTimeout(만든 것이 없음)과 maxStreamAge(활동과 상관없음)에 닫힌다. 둘 다 보통의 끝이고, connection이
허락하면 둘 다 끝 envelope를 보낸다.
느린 소비자
서버는 뒤처진 소비자를 위해 최대 maxBufferedItems까지만 버퍼링한다. 그것을 넘으면 버퍼를 키우지 않고 connection을
닫는다. 따라가지 못하는 client는 서버가 밀린 것을 쥐고 있기를 기대하지 말고, 이어 받기 cursor로 다시 연결한다.
종료
rolling 배포 중에는 노드가 받기를 멈추기 전에 열린 stream이 다시 연결하라는 요청을 받는다. 바로 다시 연결한다. 노드는 drain 기한에 아직 열린 것을 강제로 닫고, 그것은 갑작스러운 닫힘으로 도착한다.
갑작스러운 닫힘에 backoff와 jitter 없이 바로 다시 연결하지 않는다. 노드의 stream이 한꺼번에 끊겼을 때 모든 client가 한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.