- 결정 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>
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:
- A
Completeenvelope. The stream finished.lastSequenceis the final position. - A
Failurerecord. Something failed after commit. Carries an error code and a client-safe message. The status is still 200. - 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.