- 결정 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>
85 lines
4.1 KiB
Markdown
85 lines
4.1 KiB
Markdown
# 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.
|