From 615da352b9537416b52d9c38760540f1f2a77368 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:29:32 +0900 Subject: [PATCH] =?UTF-8?q?docs(realtime):=20=EC=A7=9D=20=EB=B0=B1?= =?UTF-8?q?=EC=97=94=EB=93=9C=20=EC=8B=A4=EC=8B=9C=EA=B0=84=20=EC=B6=9C?= =?UTF-8?q?=EA=B5=AC=EC=99=80=20=ED=94=84=EB=A1=A0=ED=8A=B8=20transport=20?= =?UTF-8?q?=EB=8C=80=EC=9D=91=ED=91=9C=EB=A5=BC=20=EC=A0=81=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개, Map 투영, 재전송 없음)과 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 --- docs/architecture/optional-adapter-recipes.md | 5 +++ ...ime-events-web-push-and-bounded-polling.md | 39 +++++++++++++++++++ docs/manual/03-outside-feature-folder.md | 1 + 3 files changed, 45 insertions(+) diff --git a/docs/architecture/optional-adapter-recipes.md b/docs/architecture/optional-adapter-recipes.md index 4281ddba..e85d9487 100644 --- a/docs/architecture/optional-adapter-recipes.md +++ b/docs/architecture/optional-adapter-recipes.md @@ -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 diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/architecture/realtime-events-web-push-and-bounded-polling.md index 8b34816d..93317107 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -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 투영, 재전송 없음 +짝 백엔드 스트리밍 → 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의 공개 계약은 diff --git a/docs/manual/03-outside-feature-folder.md b/docs/manual/03-outside-feature-folder.md index 1c13012f..4e36de80 100644 --- a/docs/manual/03-outside-feature-folder.md +++ b/docs/manual/03-outside-feature-folder.md @@ -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/.json`: 환경별로 기능을 끄고 싶을 때(`FEATURE_OVERRIDES`).