Files
clean-architecture-backend-…/docs/web/streaming-contract.md
T
donghyeon-kaandClaude Opus 5.5 27f23add08 review-followup Wave 3: 설정 prefix app.* 통일(P20), Wave 3 종료
- 결정 16: `ca-skeleton.*`·`backend.graphql` 등 → `app.*`(APP_* env 키 이름 유지), selector 키 상수 하나(`CapabilitySelectors`),
  바인딩만 되던 `streaming-idle` 삭제
- `StrictSettingsBinder`가 env 오타까지 거부 — 모든 capability(graphql·websocket·mongo는 edge 제약으로 파일만 strict),
  httpclient 리플렉션 `HttpClientEnvironmentKeys` 삭제
- persistence-jpa가 `APP_DATASOURCE_PASSWORD` secret 요구를 기여(bootstrap이 JPA 스위치를 읽지 않음), Redis ACL fixture에서 pub/sub 권한 제거
- 결함 수정: SMTP 설정 env 이름 충돌(P20-new-1), `bindExcept`가 system env까지 filter(P20-new-2), graphql 빈 deployment-mode 메시지(P20-new-6)
- 통합: P30과 충돌 11건(P30의 명시적 bean 구조 유지), P30 코드의 옛 키를 app.*로, persistence-jpa 포맷
- 현황표: 소유자 결정 36(persistence-jpa 설정은 플랫폼 키만 app.persistence-jpa.*로, 공유 기능 트리 예외), 재개 문서에 일시 정지 상태

Wave 3 종료 검증: check · ci verifyDependencyLocks --warning-mode=fail(714 task) · mainCheck · architectureCheck
verifyPublicPathSnapshot :app-bootstrap:verifyEnvKeys configContractCheck · :app-bootstrap:integrationTest
:sample-portfolio:integrationTest :sample-portfolio:systemTest · integrationCheck · -p build-logic test ·
-p optional-platforms ci · :app-bootstrap:qualificationBootJar releaseCheck 통과

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-29 17:01:54 +09:00

4.1 KiB

Web streaming: the client contract

What a client must implement to consume NDJSON or application/json-seq from this platform. SSE framing exists, but since the WebFlux twin was removed (2026-09-25) nothing on the servlet stack writes it.

The writers ship in adapter:inbound:web-advanced (opt-in, switched by app.web.advanced.ndjson.enabled / app.web.advanced.json-sequence.enabled); no default composition carries them.

Three outcomes, not two

After the first byte the HTTP status is 200 and cannot change. So the status tells you nothing about whether the stream succeeded, and a closed connection is ambiguous. There are three endings:

  1. A Complete envelope. The stream finished. lastSequence is the final position.
  2. A Failure record. Something failed after commit. Carries an error code and a client-safe message. The status is still 200.
  3. Neither. The connection closed mid-stream. The server records this as ABRUPT_CLOSE; from the client's side it is indistinguishable from a completed stream unless the client is looking for the terminal envelope.

A client that treats a closed connection as completion will silently truncate data. No server change can fix that for it. Looking for the terminal envelope is the contract.

Positions

Every Item carries a sequence, counting from 1. Positions are strictly increasing, and the server enforces it — a repeat or a regression is a server-side error, not something a client has to tolerate.

Zero is never a valid position. A stream whose first item claimed 0 and one whose sequence was never set would look identical.

Resuming

Where a route supports it, send the last position you applied as Last-Event-ID.

  • If the source still holds it, delivery continues from the next position.
  • If it does not, the response is a resnapshot-required error, not a partial stream. Resuming from the oldest retained position would give you contiguous positions with a hole in the middle, and nothing in the data would say so.

A resnapshot means re-reading the resource from its normal endpoint and starting a fresh stream. Clients that cannot do that cheaply should not use the resume path.

Framing

Format Media type Framing Truncation behaviour
SSE text/event-stream data: lines, blank-line separated Partial event at the end
NDJSON application/x-ndjson One JSON value, then \n The truncated line has no newline, and the delimiter is what was lost
JSON-seq application/json-seq 0x1E, value, \n The next 0x1E unambiguously starts the next record

Prefer JSON-seq where truncation matters. Its separator comes first, so a parser resynchronises at the next record rather than trying to parse the truncation joined to what follows. For a long-lived stream, truncation is the normal way it ends.

Records never contain a raw newline. The server refuses to write one, because for NDJSON the consumer's line split is the only record boundary there is.

Heartbeats and timeouts

The server writes a keepalive every heartbeatInterval. A client that sees nothing for longer than that should assume the connection is dead — a silent connection and a disconnected one are the same thing at the socket, and the heartbeat is what separates them.

Streams are closed at idleTimeout (nothing produced) and at maxStreamAge (regardless of activity). Both are normal endings, and both send a terminal envelope where the connection permits.

Slow consumers

The server buffers at most maxBufferedItems for a consumer that is behind. Past that it closes the connection rather than growing the buffer. A client that cannot keep up should reconnect with a resume cursor, not expect the server to hold its backlog.

Shutdown

During a rolling deploy, open streams receive a reconnect request before the node stops accepting. Reconnect promptly — the node force-closes anything still open at its drain deadline, and that arrives as an abrupt close.

Do not reconnect immediately on an abrupt close without backoff and jitter. If a node's streams are all cut at once, every client reconnecting at once is what keeps the replacement down.