mega-framework 0.1.0 → 0.1.2

package/.env

@@ -92,7 +92,7 @@ NATS_JOBS_URL=nats://localhost:4222
 # WS Hub (mega ws-hub CLI — src/cli/ws-hub.js, runWsHubCli)
 # 코드가 읽는 키는 MEGA_WSHUB_* (언더스코어 없는 단일 service 토큰). TOKENS 만 필수.
 # 비밀 토큰은 운영에서 교체. hub 는 `mega ws-hub` 실행 시에만 기동(자동 기동 없음).
-MEGA_WSHUB_TOKENS=change-me
+MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
 MEGA_WSHUB_PORT=3100
 MEGA_WSHUB_HOST=0.0.0.0
 MEGA_WSHUB_HEARTBEAT_MS=25000

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {
@@ -118,4 +118,4 @@
     "redlock": "5.0.0-beta.2",
     "ws": "^8.21.0"
   }
-}
+}

package/sample/crud/.env

@@ -1,4 +1,4 @@
-PORT=4102
+PORT=3000
 DATABASE_URL=postgres://mega:dkTkqkfl12@localhost:5432/mega_test
 MEGA_CLUSTER_WORKERS=8
 SESSION_SECRET=Zz4VoSzf0sYMEoqASu8G_wx5l3uKi2MlHsxDK3MSkoE
@@ -9,6 +9,13 @@ REDIS_LOCK_URL=redis://:dkTkqkfl12@localhost:6379/3
 MONGO_URL=mongodb://mega:dkTkqkfl12@localhost:27017/mega_test?authSource=admin
 NATS_JOBS_URL=nats://localhost:4222
 ASP_MASTER_SECRET=demo-asp-master-7Qe2mWzR1tYbN8sLpKvX0cAfH4dG6jU
+
+MEGA_WSHUB_TOKENS=dev-bridge-token-change-me
+MEGA_WSHUB_TOKEN=dev-bridge-token-change-me
+MEGA_WSHUB_PORT=3100
+MEGA_WSHUB_HOST=0.0.0.0
+MEGA_WSHUB_URL=ws://localhost:3100
+
 MEGA_OTEL_ENABLED=true
 MEGA_OTEL_SERVICE_NAME=sample-crud
 MEGA_OTEL_ENDPOINT=http://localhost:4318/v1/traces
@@ -16,3 +23,5 @@ MEGA_OTEL_EXPORTER=otlp
 MEGA_OTEL_SAMPLING_RATIO=1.0
 MEGA_OTEL_ZIPKIN_API=http://localhost:9411/api/v2
 DEMO_UPLOAD_DIR=var/uploads
+
+BRIDGE_ID=crud-1

package/sample/crud/apps/main/app.config.js

@@ -72,6 +72,18 @@ export default {
     },
   },
 
+  // WS Hub 브릿지(ADR-065/176) — 별도 `mega ws-hub` 서버(localhost:3100, .env MEGA_WSHUB_*)에 연결.
+  // boot 가 이 블록을 보고 **app.connectHub 를 자동 호출**한다(ADR-176 자동배선 — connectHub 코드 불요).
+  // 채팅(/ws/chat)은 app.broadcast → hub fan-out 으로 클러스터 전파된다. retry 로 허브 재시작·drain(4503)·
+  // 네트워크 단절 시 지수 백오프 재연결(ADR-098). ⚠️ global wsCluster(NATS)와 **동시 사용 불가**(부팅 fail-fast).
+  bridgeHub: {
+    url: process.env.MEGA_WSHUB_URL ?? 'ws://localhost:3100',
+    token: process.env.MEGA_WSHUB_TOKEN,
+    bridgeId: process.env.BRIDGE_ID ?? 'main-1',
+    channels: ['chat'],
+    retry: { retries: 30, minTimeout: 1000, maxTimeout: 10_000 },
+  },
+
   // rate limit 상향(ADR-073) — /demo/worker 데모는 1초 간격 하트비트 ping(메인 스레드 non-block 시연)으로
   // 폴링한다. 기본 한도(100/분)는 폴링 + 일반 탐색이 겹치면 쉽게 넘어 데모가 429 로 끊긴다. 데모 앱이라
   // 폴링을 허용하도록 한도를 넉넉히 둔다(여전히 ON — 무제한 아님). 운영 앱은 엔드포인트별로 더 낮게 잡는다.

package/sample/crud/apps/main/channels/chat-channel.js

@@ -1,28 +1,26 @@
 // @ts-check
 /**
- * ChatChannel — /ws/chat 실시간 채팅 WS 채널 (ADR-158).
+ * ChatChannel — /ws/chat 실시간 채팅 WS 채널 (ADR-158/176).
  *
- * MegaWebSocketController 를 상속해 라이프사이클 3훅 + `type` 자동 디스패치(ADR-015)를 쓴다. 채널
- * 인스턴스는 **연결마다 새로 생성**되므로 공유 상태는 인스턴스가 아니라:
- *   - **전파(cluster-wide)**: redis pub/sub({@link module:channels/chat-bus}) — `publish` 로 모든 워커에
- *     fan-out. `app.broadcast`(로컬 ns 전용)는 클러스터에서 다른 워커에 안 닿으므로 쓰지 않는다(hub 불요).
- *   - **접속자 명단·기록**: redis(`demo` 캐시 `.native`) — roster HASH(field=sessionId→userName, cluster-wide
- *     인원수·명단) + 최근기록 캡 리스트(RPUSH/LTRIM).
- * 에 둔다.
+ * 클러스터 전파(broadcast)와 접속자 목록(roster) 동기화는 **프레임워크가 자동 처리**한다(ADR-176,
+ * `wsCluster` = NATS). 채널은 `ctx.presence`/`ctx.app.broadcast` 로 **비즈니스 로직만** 작성하고, redis
+ * pub/sub·roster 동기화 코드를 직접 두지 않는다(개발자 배선 불요). 최근 메시지 기록(history)만 redis
+ * (`demo` 캐시)에 KV 로 둔다 — 이건 전파/roster 가 아니라 단순 저장이다.
  *
- * ASP: `/ws/chat` 는 asp.websocket.namespaces 에 들어 기본 암호화(E: 프레임). 코덱은 프레임워크
- * (ws-upgrade.js)가 종단하므로 채널은 **평문 envelope** 만 다룬다 — 암복호는 transport 계층 책임.
+ *   - 전파: `ctx.presence.broadcast({ message })` → 같은 ns 의 전 클러스터 클라가 1회씩 수신(NATS fan-out).
+ *   - 접속자: `ctx.presence.join({...})`(자동 roster 등록·동기화) + `ctx.presence.list()`(클러스터 전역 명단).
+ *   - 기록: redis RPUSH/LTRIM(최근 N건 cap), 연결 시 replay.
  *
- * 인증: `before`(makeWsRequireAuth) 가 로그인 세션만 통과시키므로 `ctx.auth`(userId/sessionId/userName)가 보장된다.
+ * ASP: `/ws/chat` 는 asp.websocket.namespaces 라 E: 암호화. 코덱은 프레임워크가 종단(평문 envelope 만 다룸).
+ * 인증: before(makeWsRequireAuth) 가 로그인 세션만 통과 → ctx.auth(userId/sessionId/userName) 보장.
  *
  * @module channels/chat-channel
  */
 import { MegaWebSocketController } from 'mega-framework'
-import { ensureSubscriber, registerConn, unregisterConn, publish, ROSTER_KEY } from './chat-bus.js'
 
 /** broadcast 논리 채널명(payload 분류용). */
 const CHANNEL = 'chat'
-/** redis 키 — 최근 메시지 캡 리스트(RPUSH + LTRIM). */
+/** redis 키 — 최근 메시지 캡 리스트(RPUSH + LTRIM). 전파가 아니라 기록 KV 용도. */
 const HISTORY_KEY = 'ws:chat:history'
 /** 보관·재생할 최근 메시지 개수. */
 const HISTORY_LIMIT = 30
@@ -31,48 +29,27 @@ const HISTORY_TTL_SEC = 86_400
 
 export class ChatChannel extends MegaWebSocketController {
   /**
-   * 연결 수립 — 워커 구독자 보장 + 로컬 등록 + roster 갱신(cluster-wide) + 최근기록 재생 + 입장 전파.
+   * 연결 수립 — 신원 매핑(자동 roster 등록) + 최근기록 재생 + 입장 전파.
    * @param {any} sock @param {any} ctx @returns {Promise<void>}
    */
   async onConnect(sock, ctx) {
     const { userId, sessionId, userName } = ctx.auth
-    const redis = this._redis(ctx)
-    if (!redis) {
-      // redis 가 전파 transport — 없으면 채팅 불가. 명시적으로 닫는다(silent 진행 금지).
-      ctx.log?.error?.({ connId: sock.id }, 'ws.chat: redis(demo) unavailable — closing')
-      if (sock.isOpen) sock.close(1011, 'chat backend unavailable')
-      return
-    }
-    ensureSubscriber(ctx.app, redis) // 이 워커의 cluster-wide 구독 1회 보장.
-    registerConn(sock, { sessionId, userName })
+    // 신원 매핑 + 클러스터 roster 자동 등록(프레임워크가 NATS 로 동기화). roster/전파 배선 코드 불요(ADR-176).
+    ctx.presence.join({ userId, sessionId, channels: [CHANNEL], metadata: { userName } })
 
-    let roster = [userName]
-    let items = []
-    try {
-      await redis.hset(ROSTER_KEY, sessionId, userName)
-      roster = await redis.hvals(ROSTER_KEY)
-      const raw = await redis.lrange(HISTORY_KEY, -HISTORY_LIMIT, -1)
-      for (const s of raw) {
-        try {
-          items.push(JSON.parse(s))
-        } catch (err) {
-          // 손상된 기록 1건은 재생에서 제외(전체 재생을 막지 않음) — 사유 명시 + debug 로그(silent 금지).
-          ctx.log?.debug?.({ err, connId: sock.id }, 'ws.chat skip corrupt history entry')
-        }
-      }
-    } catch (err) {
-      // roster/기록 조회 실패는 비치명적 — 빈 명단·기록으로라도 연결은 유지(다음 동작에서 복구).
-      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat onConnect redis read failed (non-fatal)')
-    }
+    // 최근 기록 replay (redis KV — 전파/roster 와 무관한 단순 저장).
+    const items = await this._loadHistory(ctx, sock)
+    const members = this._members(ctx) // 클러스터 전역 명단(자동 동기화된 roster).
 
-    // 입장 본인에게: 신원 + 최근기록 + 현재 명단/인원 + 워커 PID(클러스터 확인용).
+    // 입장 본인: 신원 + 최근기록 + 현재 명단/인원 + 워커 PID(클러스터 확인용).
     sock.send({
       type: 'chat.history',
-      payload: { me: { userId, userName }, items, online: roster.length, members: roster, workerPid: process.pid },
+      payload: { me: { userId, userName }, items, online: members.length, members, workerPid: process.pid },
     })
-    // 다른 접속자(전 클러스터)에게: 입장 알림 + 갱신된 명단(본인은 제외).
-    await this._publish(ctx, redis, {
-      message: { type: 'chat.presence', payload: { event: 'join', userName, online: roster.length, members: roster } },
+    // 다른 접속자(전 클러스터): 입장 알림 + 갱신 명단(본인 제외). NATS fan-out 은 프레임워크가 처리.
+    ctx.presence.broadcast({
+      channel: CHANNEL,
+      message: { type: 'chat.presence', payload: { event: 'join', userName, online: members.length, members } },
       exceptSessionIds: [sessionId],
     })
   }
@@ -84,59 +61,79 @@ export class ChatChannel extends MegaWebSocketController {
   async ['chat.send'](sock, msg, ctx) {
     const text = String(msg.payload?.text ?? '').trim()
     if (text.length === 0) return // 스키마가 minLength 1 강제하지만 trim 후 공백뿐이면 무시.
-    const redis = this._redis(ctx)
-    if (!redis) return
     const entry = { userId: ctx.auth.userId, userName: ctx.auth.userName, text, ts: Date.now() }
-    try {
-      await redis.rpush(HISTORY_KEY, JSON.stringify(entry))
-      await redis.ltrim(HISTORY_KEY, -HISTORY_LIMIT, -1)
-      await redis.expire(HISTORY_KEY, HISTORY_TTL_SEC)
-    } catch (err) {
-      // 기록 적재 실패는 비치명적 — 전파는 그대로 진행(다른 사용자는 메시지를 받는다).
-      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat history append failed (non-fatal)')
+
+    const redis = this._redis(ctx)
+    if (redis) {
+      try {
+        await redis.rpush(HISTORY_KEY, JSON.stringify(entry))
+        await redis.ltrim(HISTORY_KEY, -HISTORY_LIMIT, -1)
+        await redis.expire(HISTORY_KEY, HISTORY_TTL_SEC)
+      } catch (err) {
+        // 기록 적재 실패는 비치명적 — 전파는 그대로 진행(다른 사용자는 메시지를 받는다).
+        ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat history append failed (non-fatal)')
+      }
     }
-    // exceptSessionIds 없음 → 본인도 구독자 경로로 echo 받아 렌더(optimistic 렌더 안 함 → 중복 없음).
-    await this._publish(ctx, redis, { message: { type: 'chat.msg', payload: entry } })
+    // exceptSessionIds 없음 → 본인도 클러스터 경로로 echo 받아 렌더(optimistic 렌더 안 함 → 중복 없음).
+    ctx.presence.broadcast({ channel: CHANNEL, message: { type: 'chat.msg', payload: entry } })
   }
 
   /**
-   * 연결 종료 — 로컬 해제 + roster 제거(cluster-wide) + 퇴장 전파.
+   * 연결 종료 — 퇴장 전파(roster 제거는 프레임워크가 disconnect 훅에서 자동 처리).
    * @param {any} sock @param {any} ctx @returns {Promise<void>}
    */
   async onDisconnect(sock, ctx) {
-    unregisterConn(sock)
     if (!ctx.auth) return
     const { sessionId, userName } = ctx.auth
-    const redis = this._redis(ctx)
-    if (!redis) return
-    let roster = []
-    try {
-      await redis.hdel(ROSTER_KEY, sessionId)
-      roster = await redis.hvals(ROSTER_KEY)
-    } catch (err) {
-      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat onDisconnect redis failed (non-fatal)')
-    }
-    await this._publish(ctx, redis, {
-      message: { type: 'chat.presence', payload: { event: 'leave', userName, online: roster.length, members: roster } },
+    // 본인을 제외한 명단(자동 roster 제거 타이밍과 무관하게 sessionId 로 명시 제외).
+    const members = this._members(ctx, sessionId)
+    ctx.presence.broadcast({
+      channel: CHANNEL,
+      message: { type: 'chat.presence', payload: { event: 'leave', userName, online: members.length, members } },
       exceptSessionIds: [sessionId],
     })
   }
 
   /**
-   * 전파 1건 — 실패해도 연결을 막지 않는다(메시지 1건 유실은 비치명적, 로그). silent 금지.
-   * @param {any} ctx @param {import('ioredis').Redis} redis @param {object} env @returns {Promise<void>}
+   * 클러스터 전역 접속자 이름 목록(자동 동기화된 roster). exceptSessionId 가 주어지면 그 세션은 뺀다.
+   * @param {any} ctx @param {string} [exceptSessionId] @returns {string[]}
+   * @private
+   */
+  _members(ctx, exceptSessionId) {
+    return ctx.presence
+      .list()
+      .filter((/** @type {any} */ m) => exceptSessionId == null || m.sessionId !== exceptSessionId)
+      .map((/** @type {any} */ m) => m.metadata?.userName)
+      .filter((/** @type {any} */ n) => typeof n === 'string' && n.length > 0)
+  }
+
+  /**
+   * 최근 메시지 기록 replay(redis KV). 미배선이면 빈 배열. 손상 1건은 제외(전체 replay 막지 않음).
+   * @param {any} ctx @param {any} sock @returns {Promise<object[]>}
    * @private
    */
-  async _publish(ctx, redis, env) {
+  async _loadHistory(ctx, sock) {
+    const redis = this._redis(ctx)
+    if (!redis) return []
+    /** @type {object[]} */
+    const items = []
     try {
-      await publish(redis, env)
+      const raw = await redis.lrange(HISTORY_KEY, -HISTORY_LIMIT, -1)
+      for (const s of raw) {
+        try {
+          items.push(JSON.parse(s))
+        } catch (err) {
+          ctx.log?.debug?.({ err, connId: sock.id }, 'ws.chat skip corrupt history entry')
+        }
+      }
     } catch (err) {
-      ctx.log?.warn?.({ err }, 'ws.chat publish failed (message dropped)')
+      ctx.log?.warn?.({ err, connId: sock.id }, 'ws.chat history read failed (non-fatal)')
     }
+    return items
   }
 
   /**
-   * 'demo' redis 캐시의 raw ioredis 핸들(원자적 연산·pub/sub용). 미배선(단위 테스트 mock app)이면 null.
+   * 'demo' redis 캐시의 raw ioredis 핸들(기록 RPUSH/LTRIM 용). 미배선(단위 테스트 mock)이면 null.
    * @param {any} ctx @returns {any|null} @private
    */
   _redis(ctx) {

package/sample/crud/mega.config.js

@@ -79,6 +79,19 @@ export default {
     },
   },
 
+  // ── 클러스터 전송 선택(ADR-176, 앱당 하나·상호배타) ───────────────────────────────────────────
+  // 이 샘플은 현재 **WS Hub**(app.config 의 bridgeHub → `mega ws-hub` 서버, localhost:3100)로 채팅을
+  // 클러스터 전파한다. boot 가 bridgeHub 를 보고 app.connectHub 를 자동 호출한다(개발자 배선 불요).
+  //
+  // ⚠️ NATS 로 다시 전환하려면: app.config 의 `bridgeHub` 블록을 제거(또는 주석)하고 아래 wsCluster 를
+  //    되살린다. **둘을 동시에 두면 부팅 시 config.cluster_transport_conflict 로 fail-fast**(이중 전파 방지).
+  //
+  // // NATS wsCluster (대안 — bridgeHub 와 동시 사용 불가):
+  // wsCluster: {
+  //   bus: 'jobs',                                  // services.buses 의 NATS 키 재사용
+  //   roster: { driver: 'nats', ttlMs: 15_000 },    // 접속자목록도 NATS 동기화(crash 정리 heartbeat). 'none'=로컬만
+  // },
+
   // 정기 작업(ADR-028/118) — `mega scheduler` 프로세스가 등록·실행한다(config.schedules, ADR-123).
   schedules: [CronCounterSchedule],
 

package/sample/crud/scripts/start-ws-hub.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# sample/crud — WS Hub 서버 기동 스크립트 (ADR-032/176)
+#
+# 별도 hub 프로세스(`mega-ws-hub` 바이너리, mega-framework bin)를 localhost:3100 에 띄운다.
+# 앱(`yarn dev` = `mega start`)이 app.config 의 `bridgeHub` 로 이 허브에 **자동 연결**한다(ADR-176).
+#
+# ⚠️ `mega-ws-hub` 는 `mega start` 와 달리 `.env` 를 자동 로드하지 않는다(직접 process.env 만 읽음,
+#    src/cli/ws-hub.js). 그래서 Node 20.6+ 의 `--env-file` 로 .env 를 주입한다.
+#    읽는 env(src/cli/ws-hub.js runWsHubCli): MEGA_WSHUB_TOKENS(필수, 콤마구분) /
+#    MEGA_WSHUB_PORT(기본 3100) / MEGA_WSHUB_HOST(기본 0.0.0.0) / MEGA_WSHUB_HEARTBEAT_MS.
+#
+# 사용:
+#   sample/crud/scripts/start-ws-hub.sh                 # .env 값으로 기동(localhost:3100)
+#   MEGA_WSHUB_PORT=4100 scripts/start-ws-hub.sh        # 일부 오버라이드(실 env 가 .env 보다 우선)
+#   scripts/start-ws-hub.sh --some-extra-flag           # 추가 인자는 mega-ws-hub 로 전달
+# ─────────────────────────────────────────────────────────────────────────────
+set -euo pipefail
+
+# sample/crud 루트로 이동(스크립트 위치 기준 — 어디서 호출해도 동작).
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+ENV_FILE=".env"
+BIN="node_modules/mega-framework/bin/mega-ws-hub.js"
+
+# 사전 점검 — 누락 시 silent 진행 금지, 이유를 명확히 알린다(P4/P7).
+[ -f "$ENV_FILE" ] || {
+  echo "✗ $ROOT/$ENV_FILE 가 없습니다 — MEGA_WSHUB_TOKENS 등 허브 설정이 필요합니다." >&2
+  exit 1
+}
+[ -f "$BIN" ] || {
+  echo "✗ $BIN 없음 — 먼저 'yarn install --ignore-engines'(또는 npm install) 로 mega-framework 를 설치/동기화하세요." >&2
+  exit 1
+}
+
+echo "▶ WS Hub 기동 (mega-ws-hub) — host=${MEGA_WSHUB_HOST:-(.env)} port=${MEGA_WSHUB_PORT:-(.env, 기본 3100)}.  Ctrl+C 로 종료."
+# --env-file: .env 를 process.env 로 로드(이미 export 된 실 env 가 우선 — --env-file 표준 동작).
+# exec 로 교체 실행 → 시그널(SIGINT/SIGTERM)이 mega-ws-hub 로 그대로 전달되어 graceful 종료(drain 4503).
+exec node --env-file="$ENV_FILE" "$BIN" "$@"

package/sample/crud/test/apps/main/chat-channel.test.js

@@ -1,31 +1,16 @@
 // @ts-check
 /**
- * ChatChannel 단위 테스트(ADR-158) — 라이프사이클 훅이 chat-bus(redis pub/sub) + roster HASH 를
- * 올바르게 호출하는지 mock 으로 검증. 인프라 불필요(redis native·chat-bus 모듈은 spy).
- *
- * 채널은 cluster-wide 전파를 chat-bus.publish 에, 로컬 등록을 register/unregisterConn 에, 접속자 명단을
- * redis HASH(hset/hvals/hdel)에 위임한다 — 그 위임 계약을 단언한다(app.broadcast/joinSession 미사용).
+ * ChatChannel 단위 테스트(ADR-158/176) — 라이프사이클 훅이 **프레임워크 presence/broadcast API**
+ * (ctx.presence.join/list/broadcast)와 history redis(KV)를 올바르게 호출하는지 mock 으로 검증.
+ * 인프라 불필요(presence·redis native 는 spy). redis pub/sub·roster HASH 직접 호출은 더 이상 없다 —
+ * 클러스터 전파·접속자목록 동기화는 프레임워크(wsCluster, NATS)가 처리한다.
  */
 import { describe, test, expect, vi, beforeEach } from 'vitest'
-
-// chat-bus(redis pub/sub) 모듈은 mock — 채널이 올바른 env 로 호출하는지만 본다.
-vi.mock('../../../apps/main/channels/chat-bus.js', () => ({
-  ensureSubscriber: vi.fn(),
-  registerConn: vi.fn(),
-  unregisterConn: vi.fn(),
-  publish: vi.fn(async () => {}),
-  ROSTER_KEY: 'ws:chat:roster',
-}))
-
 import { ChatChannel } from '../../../apps/main/channels/chat-channel.js'
-import * as chatBus from '../../../apps/main/channels/chat-bus.js'
 
-/** native redis spy — roster HASH + 기록 리스트. @param {object} [o] */
-function fakeNative({ roster = ['kim'], history = [] } = {}) {
+/** native redis spy — history 리스트(전파/roster 아님, 단순 기록 KV). @param {object} [o] */
+function fakeNative({ history = [] } = {}) {
   return {
-    hset: vi.fn(async () => 1),
-    hvals: vi.fn(async () => roster),
-    hdel: vi.fn(async () => 1),
     rpush: vi.fn(async () => 1),
     ltrim: vi.fn(async () => 'OK'),
     expire: vi.fn(async () => 1),
@@ -33,17 +18,27 @@ function fakeNative({ roster = ['kim'], history = [] } = {}) {
   }
 }
 
-/** 채널 ctx mock — auth/app/cache/log. @param {object} [o] */
-function makeCtx({ roster = ['kim'], history = [], userName = 'kim' } = {}) {
-  const native = fakeNative({ roster, history })
+/**
+ * 채널 ctx mock — auth/presence/cache/log. presence.list 가 클러스터 roster 를 흉내낸다.
+ * @param {object} [o]
+ */
+function makeCtx({ members = [{ sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } }], history = [], userName = 'kim' } = {}) {
+  const native = fakeNative({ history })
+  const presence = {
+    join: vi.fn(),
+    list: vi.fn(() => members),
+    broadcast: vi.fn(),
+    directToUser: vi.fn(),
+  }
   return {
     ctx: {
       auth: { userId: 'u1', sessionId: 's1', userName },
-      app: { fastify: { log: { warn: vi.fn(), debug: vi.fn(), error: vi.fn() } } },
+      presence,
       cache: vi.fn(() => ({ native })),
       log: { warn: vi.fn(), debug: vi.fn(), error: vi.fn() },
     },
     native,
+    presence,
   }
 }
 
@@ -55,40 +50,46 @@ function makeSock() {
 beforeEach(() => vi.clearAllMocks())
 
 describe('ChatChannel.onConnect', () => {
-  test('구독자 보장 + 로컬등록 + roster HSET + 기록재생 + 입장 publish(본인 제외) + 워커PID', async () => {
-    const { ctx, native } = makeCtx({
-      roster: ['kim', 'old'],
+  test('presence.join(자동 roster) + 기록재생 + 입장 broadcast(본인 제외) + chat.history(워커PID)', async () => {
+    const { ctx, presence } = makeCtx({
+      members: [
+        { sessionId: 's0', userId: 'u0', metadata: { userName: 'old' } },
+        { sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } },
+      ],
       history: [JSON.stringify({ userId: 'u0', userName: 'old', text: 'hi', ts: 1 })],
     })
     const sock = makeSock()
     await new ChatChannel().onConnect(sock, ctx)
 
-    expect(chatBus.ensureSubscriber).toHaveBeenCalledWith(ctx.app, native)
-    expect(chatBus.registerConn).toHaveBeenCalledWith(sock, { sessionId: 's1', userName: 'kim' })
-    expect(native.hset).toHaveBeenCalledWith('ws:chat:roster', 's1', 'kim')
+    // 신원 매핑 + 자동 roster 등록(프레임워크에 위임).
+    expect(presence.join).toHaveBeenCalledWith({ userId: 'u1', sessionId: 's1', channels: ['chat'], metadata: { userName: 'kim' } })
 
-    // 본인에게: chat.history(me + items + 명단 + 워커PID).
+    // 본인에게: chat.history(me + items + 클러스터 명단 + 워커PID).
     const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
     expect(hist.payload.me).toEqual({ userId: 'u1', userName: 'kim' })
     expect(hist.payload.items).toHaveLength(1)
     expect(hist.payload.online).toBe(2)
-    expect(hist.payload.members).toEqual(['kim', 'old'])
+    expect(hist.payload.members).toEqual(['old', 'kim'])
     expect(hist.payload.workerPid).toBe(process.pid)
 
-    // 전 클러스터에: 입장 presence(본인 sessionId 제외).
-    const pub = chatBus.publish.mock.calls.at(-1)[1]
-    expect(pub).toMatchObject({
+    // 전 클러스터에: 입장 presence broadcast(본인 sessionId 제외). NATS fan-out 은 프레임워크 처리.
+    const env = presence.broadcast.mock.calls.at(-1)[0]
+    expect(env).toMatchObject({
+      channel: 'chat',
       message: { type: 'chat.presence', payload: { event: 'join', userName: 'kim', online: 2 } },
       exceptSessionIds: ['s1'],
     })
   })
 
-  test('redis 없으면 1011 로 닫는다(전파 transport 부재)', async () => {
+  test('redis(history) 없으면 빈 기록으로 연결 유지(close 안 함)', async () => {
+    const presence = { join: vi.fn(), list: vi.fn(() => [{ sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } }]), broadcast: vi.fn() }
+    const ctx = { auth: { userId: 'u1', sessionId: 's1', userName: 'kim' }, presence, cache: vi.fn(() => ({ native: null })), log: { warn: vi.fn(), debug: vi.fn() } }
     const sock = makeSock()
-    const ctx = { auth: { userId: 'u1', sessionId: 's1', userName: 'kim' }, cache: vi.fn(() => ({ native: null })), log: { error: vi.fn() } }
     await new ChatChannel().onConnect(sock, ctx)
-    expect(sock.close).toHaveBeenCalledWith(1011, expect.any(String))
-    expect(chatBus.registerConn).not.toHaveBeenCalled()
+    expect(sock.close).not.toHaveBeenCalled()
+    expect(presence.join).toHaveBeenCalled()
+    const hist = sock.send.mock.calls.find(([m]) => m.type === 'chat.history')[0]
+    expect(hist.payload.items).toEqual([])
   })
 
   test('손상된 기록 1건은 건너뛰고 나머지는 재생(debug 로그)', async () => {
@@ -102,43 +103,47 @@ describe('ChatChannel.onConnect', () => {
 })
 
 describe('ChatChannel.chat.send', () => {
-  test('검증된 text 를 기록 적재 + 전 클러스터 publish(본인 포함)', async () => {
-    const { ctx, native } = makeCtx()
+  test('검증된 text 를 기록 적재 + 전 클러스터 broadcast(본인 포함)', async () => {
+    const { ctx, native, presence } = makeCtx()
     await new ChatChannel()['chat.send'](makeSock(), { type: 'chat.send', payload: { text: '  hello  ' } }, ctx)
     expect(native.rpush).toHaveBeenCalled()
     expect(native.ltrim).toHaveBeenCalledWith('ws:chat:history', -30, -1)
-    const pub = chatBus.publish.mock.calls.at(-1)[1]
-    expect(pub.message.type).toBe('chat.msg')
-    expect(pub.message.payload).toMatchObject({ userId: 'u1', userName: 'kim', text: 'hello' })
-    expect(pub.exceptSessionIds).toBeUndefined() // 본인도 echo.
+    const env = presence.broadcast.mock.calls.at(-1)[0]
+    expect(env.message.type).toBe('chat.msg')
+    expect(env.message.payload).toMatchObject({ userId: 'u1', userName: 'kim', text: 'hello' })
+    expect(env.exceptSessionIds).toBeUndefined() // 본인도 echo.
   })
 
   test('공백뿐인 메시지는 무시(전파·적재 없음)', async () => {
-    const { ctx, native } = makeCtx()
+    const { ctx, native, presence } = makeCtx()
     await new ChatChannel()['chat.send'](makeSock(), { type: 'chat.send', payload: { text: '   ' } }, ctx)
-    expect(chatBus.publish).not.toHaveBeenCalled()
+    expect(presence.broadcast).not.toHaveBeenCalled()
     expect(native.rpush).not.toHaveBeenCalled()
   })
 })
 
 describe('ChatChannel.onDisconnect', () => {
-  test('로컬 해제 + roster HDEL + 퇴장 publish(본인 제외)', async () => {
-    const { ctx, native } = makeCtx({ roster: [] })
+  test('퇴장 broadcast(본인 명단 제외) — roster 제거는 프레임워크 자동', async () => {
+    // disconnect 시점에 roster 가 아직 본인을 포함할 수도 있으므로, 채널은 sessionId 로 명시 제외해야 한다.
+    const { ctx, presence } = makeCtx({
+      members: [
+        { sessionId: 's1', userId: 'u1', metadata: { userName: 'kim' } },
+        { sessionId: 's2', userId: 'u2', metadata: { userName: 'lee' } },
+      ],
+    })
     const sock = makeSock()
     await new ChatChannel().onDisconnect(sock, ctx)
-    expect(chatBus.unregisterConn).toHaveBeenCalledWith(sock)
-    expect(native.hdel).toHaveBeenCalledWith('ws:chat:roster', 's1')
-    const pub = chatBus.publish.mock.calls.at(-1)[1]
-    expect(pub.message).toMatchObject({ type: 'chat.presence', payload: { event: 'leave', userName: 'kim' } })
-    expect(pub.exceptSessionIds).toEqual(['s1'])
+    const env = presence.broadcast.mock.calls.at(-1)[0]
+    expect(env.message).toMatchObject({ type: 'chat.presence', payload: { event: 'leave', userName: 'kim' } })
+    expect(env.message.payload.members).toEqual(['lee']) // 본인(s1) 제외.
+    expect(env.message.payload.online).toBe(1)
+    expect(env.exceptSessionIds).toEqual(['s1'])
   })
 
-  test('auth 없으면 로컬 해제만(전파 없음)', async () => {
-    const { ctx } = makeCtx()
+  test('auth 없으면 전파 없음', async () => {
+    const { ctx, presence } = makeCtx()
     ctx.auth = null
-    const sock = makeSock()
-    await new ChatChannel().onDisconnect(sock, ctx)
-    expect(chatBus.unregisterConn).toHaveBeenCalledWith(sock)
-    expect(chatBus.publish).not.toHaveBeenCalled()
+    await new ChatChannel().onDisconnect(makeSock(), ctx)
+    expect(presence.broadcast).not.toHaveBeenCalled()
   })
 })

package/sample/crud/test/apps/main/ws-chat.integration.test.js

@@ -18,7 +18,6 @@ import { MegaAspCrypto } from 'mega-framework/lib'
 import { fileURLToPath } from 'node:url'
 import { dirname, resolve } from 'node:path'
 import { User } from '../../../apps/main/models/user.js'
-import { closeChatBus, ROSTER_KEY } from '../../../apps/main/channels/chat-bus.js'
 
 const { wsEncrypt, wsDecrypt } = MegaAspCrypto
 const PROJECT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..')
@@ -34,6 +33,7 @@ const hasInfra = Boolean(
     process.env.REDIS_RATE_URL &&
     process.env.REDIS_DEMO_URL &&
     process.env.MONGO_URL &&
+    process.env.NATS_JOBS_URL && // wsCluster(broadcast/roster) 가 NATS 'jobs' 버스를 쓴다(ADR-176).
     process.env.SESSION_SECRET &&
     SECRET,
 )
@@ -155,21 +155,22 @@ d('WS 채팅 + ASP E2E — sample/crud 실 인프라 (ADR-158)', () => {
     )
     await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS password_hash TEXT')
     await User.query('ALTER TABLE users ADD COLUMN IF NOT EXISTS last_login_at TIMESTAMPTZ')
-    await boot.ctx.cache('demo').del(ROSTER_KEY) // 결정적 접속자 명단.
+    // roster 는 이제 프레임워크(wsCluster, NATS)가 인메모리로 관리한다 — 새 부팅이라 빈 명단에서 시작(별도 정리 불필요).
     jarA = await registerUser(fastify, emailA)
     jarB = await registerUser(fastify, emailB)
   })
 
   afterAll(async () => {
     if (!boot) return
-    await closeChatBus() // redis pub/sub 구독 연결 정리(이벤트루프 누수 방지).
+    const app = boot.megaApps.find((a) => a.name === 'main')
+    // wsCluster(NATS 구독·타이머) 정리 — 이벤트루프 누수 방지(framework-internal stop).
+    await /** @type {any} */ (app)?._wsCluster?.stop().catch(() => {})
     await User.query('DELETE FROM users WHERE email = ANY($1)', [[emailA, emailB]]).catch(() => {})
-    await boot.ctx.cache('demo').del(ROSTER_KEY).catch(() => {})
     await boot.server.close().catch(() => {})
-    const app = boot.megaApps.find((a) => a.name === 'main')
     await app?.sessionStore?.disconnect().catch(() => {})
     await boot.ctx.cache('rate').disconnect().catch(() => {})
     await boot.ctx.cache('demo').disconnect().catch(() => {})
+    await boot.ctx.bus('jobs').disconnect().catch(() => {}) // wsCluster 가 쓰던 NATS 버스.
     await boot.ctx.db('mongo').disconnect().catch(() => {})
     await boot.ctx.db('primary').disconnect().catch(() => {})
     MegaShutdown._reset()
@@ -200,7 +201,7 @@ d('WS 채팅 + ASP E2E — sample/crud 실 인프라 (ADR-158)', () => {
       expect(history.payload.me.userId).toBeTruthy()
       expect(Array.isArray(history.payload.items)).toBe(true)
       expect(history.payload.online).toBeGreaterThanOrEqual(1)
-      // roster(cluster-wide redis HASH) 에 내 이름이 있고, 워커 PID 가 실린다.
+      // roster(cluster-wide, 프레임워크 NATS 동기화) 에 내 이름이 있고, 워커 PID 가 실린다.
       expect(history.payload.members).toContain(history.payload.me.userName)
       expect(typeof history.payload.workerPid).toBe('number')
     } finally {

package/sample/crud/yarn.lock

@@ -1234,7 +1234,7 @@ marked@^18.0.5:
   integrity sha512-S6GcvALHg6K4ohtu4E7x0a1AqhAjp6cV8KhLSyN9qVapnzJkusVBxZRcIU9AeYsbe6P1hKDusSbEOzGyyuce6w==
 
 "mega-framework@file:../..":
-  version "0.1.0"
+  version "0.1.1"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"

package/sample/simple/package.json

@@ -16,7 +16,7 @@
     "test": "mega test"
   },
   "dependencies": {
-    "mega-framework": "file:../.."
+    "mega-framework": "^0.1.1"
   },
   "devDependencies": {
     "concurrently": "^9.0.0",