문제: 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 등 주석).
76 lines
4.5 KiB
Markdown
76 lines
4.5 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 뒤에 무언가 실패했다. 오류 code와 client에게 보여도 되는 메시지를 담는다. 상태는 여전히
|
|
200이다.
|
|
3. **둘 다 아님.** 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가
|
|
한꺼번에 다시 연결하면 그것이 교체 노드를 쓰러뜨린다.
|