docs(realtime): 짝 백엔드 실시간 출구와 프론트 transport 대응표를 적는다

문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.

고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
  두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
  길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
  줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
  금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
  StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
  없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
  적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
  않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
  함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.

위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
  바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).

검증
- verify:documentation PASS_SCOPED. documentation-readiness·
  changelog-review-ids 테스트 15건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
This commit is contained in:
DongHyeonka
2026-11-04 20:29:32 +09:00
parent b4ae4c1ed3
commit 615da352b9
3 changed files with 45 additions and 0 deletions
@@ -208,6 +208,11 @@ Web Push를 함께 설치하지 않는다.
- detailed status, target contract와 구현 work package는
[Realtime events, Web Push, and bounded polling](./realtime-events-web-push-and-bounded-polling.md)을
따른다. 현재 concrete runtime과 product selection은 없다.
- 짝 백엔드 템플릿의 실시간 출구(STOMP-over-SockJS, NDJSON)와 이 repo의 SSE·
`realtime.v1` WebSocket 어댑터는 그대로 연결되지 않는다. 지금 두 템플릿만으로
되는 경로는 bounded polling이다. 대응표와 push를 고를 때의 세 길은 설계 문서
[0.1절](./realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02)에
있다(1103/04-02).
### IndexedDB/OPFS
@@ -78,6 +78,45 @@ row의 `referenceRuntime.status=AVAILABLE_NOT_COMPOSED`가 reusable source의
| always-on background SSE/WebSocket/Polling | `PLATFORM_LIMITED` | 없음 | hidden/frozen/terminated browser 상태에서 공통 보장하지 않음 |
| timely cross-browser Web Push | `PLATFORM_LIMITED` | 없음 | best-effort notification과 foreground authoritative refresh만 제공 |
### 0.1 짝 백엔드 템플릿과의 대응 (1103/04-02)
결론: 짝 백엔드(`clean-architecture-backend-template`)의 실시간 출구와 이
repo의 SSE·WebSocket 어댑터는 **지금 그대로 연결되는 조합이 없다.** 지금 두
템플릿만으로 되는 경로는 bounded polling 하나다. push가 필요하면 한쪽에 새 코드를
써야 하고, 어느 쪽을 쓸지는 제품이 정한다.
```text
프론트 SSE 어댑터 → Accept: text/event-stream, REALTIME_EVENT_V1 envelope
프론트 WS 어댑터 → subprotocol 정확히 "realtime.v1", REALTIME_EVENT_V1 envelope
짝 백엔드 STOMP 채널 → SockJS /ws, /topic 구독 1개, Map<String,String> 투영, 재전송 없음
짝 백엔드 스트리밍 → NDJSON, JSON text sequence(RFC 7464). SSE writer는 없다
```
| 프론트 transport | 짝 백엔드 출구 | 지금 연결되나 | 이유 |
| --- | --- | --- | --- |
| SSE (`fetch-sse-connection.ts`) | 없음 | 아니오 | 백엔드에 SSE writer가 없다(`StreamMediaType.SSE`는 OpenAPI 생성기만 쓴다). 아키텍처 테스트가 MVC `SseEmitter`를 금지한다(`ForbiddenApiArchitectureTest` `NO_SSE_EMITTER`, 백엔드 결정 D3). 스트리밍 writer는 NDJSON·JSON text sequence뿐이다(`src/adapter/inbound/web-advanced/README.md`) |
| WebSocket (`websocket-connection.ts`) | STOMP-over-SockJS 채널 | 아니오 | 프론트는 협상된 subprotocol이 정확히 `realtime.v1`이어야 연다(`websocket-protocol.ts`). 백엔드에는 subprotocol 협상 코드가 없다. STOMP frame은 `REALTIME_EVENT_V1` envelope(streamEpoch, sequence, eventId, scopeBinding)이 아니다 |
| WebSocket | raw WebSocket 라이브러리 API(`servlet/`) | 아니오(새 코드 필요) | 서비스 어댑터가 handler를 직접 조립한다. `realtime.v1` 협상과 envelope을 구현한 예시는 없다 |
| bounded polling (`bounded-poll-coordinator.ts`) | REST GET + Envelope | **예** | V3 실행기가 짝 백엔드 Envelope을 읽는다. poll 전용 operation의 `retryBudget`을 0으로 둔다(9.2절) |
push가 필요할 때 고를 길(제품 결정, 리뷰 1103/04-02 결정의 근거):
1. **백엔드에 `realtime.v1` WebSocket handler를 쓴다.** 프론트 어댑터를 그대로
쓰고 `CURSOR` 복구까지 갈 수 있다. 백엔드에 sequence·replay 저장소(outbox)가
필요하다. SSE는 백엔드 결정 D3을 먼저 바꿔야 하므로 이 표에서는 WebSocket을
먼저 적는다.
2. **프론트에 STOMP transport를 쓴다.** 백엔드는 그대로다. STOMP frame에는
sequence·epoch가 없어 stream coordinator의 gap·cursor 기능을 못 쓴다. frame을
query 무효화 hint로만 쓰고 데이터는 snapshot(REST GET)으로 다시 읽는다
(`INVALIDATION_HINT` + `SNAPSHOT_ONLY`). simple broker는 재전송이 없으므로
연결이 끊긴 동안의 변경은 재연결 뒤 snapshot으로만 회복한다.
3. **push 없이 bounded polling만 쓴다.** 두 repo 모두 새 코드가 없다. freshness는
poll 주기(최소 5초)로 정해진다.
다시 볼 때: 백엔드에 `realtime.v1` handler나 SSE writer가 생기거나, 프론트에 STOMP
transport가 생기면 이 표를 고친다. 백엔드 쪽 정본은 백엔드 repo의
`src/adapter/inbound/websocket/README.md`다.
별도로 realtime catalog row 자체는 `RECIPE_AVAILABLE`이다. 이것은 primary
runtime status가 아니다. 기존 copyable `RealtimePort`를 production wire
authority나 generic mega port로 확장하지 않았고, reference runtime의 공개 계약은
+1
View File
@@ -104,6 +104,7 @@ release admission refused for staging:
- `tests/e2e/accessibility.spec.ts`: 경로 파라미터가 `:resourceId`가 아닐 때, 또는 모든 API가 `[]`를 답하면 그려지지 않는 보호 페이지일 때. 치환 줄 고치는 법은 [01 문서 6단계](01-add-a-feature.md#6단계-라우트).
- `src/bootstrap/product-composition.ts`: `needs`에 템플릿이 만들지 않는 capability를 적었을 때. 제품 인증 프로필의 자격 증명도 여기서 준다.
- 템플릿 파일 `src/bootstrap/runtime-adapters.ts`는 고치지 않는다.
- 실시간 갱신: 짝 백엔드의 실시간 출구(STOMP·NDJSON)와 프론트 realtime 어댑터(SSE·`realtime.v1` WebSocket)는 그대로 연결되지 않는다. 지금 되는 경로는 bounded polling이다. 대응표: [realtime 설계 0.1절](../architecture/realtime-events-web-push-and-bounded-polling.md#01-짝-백엔드-템플릿과의-대응-110304-02).
- `src/contracts/product-contracts.ts`: 제품 인증 프로필이나 제품 런타임 설정 키가 필요할 때.
- 템플릿 파일 `src/contracts/rest-profiles.ts`는 고치지 않는다.
- `config/runtime/<profile>.json`: 환경별로 기능을 끄고 싶을 때(`FEATURE_OVERRIDES`).