mega-framework 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

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,15 @@ export default {
     },
   },
 
+  // WS 클러스터 broadcast + roster 자동배선(ADR-176) — `bus`(NATS 'jobs' 재사용)가 있으면 프레임워크가
+  // app.broadcast/joinSession 의 **클러스터 fan-out·접속자목록 동기화**를 NATS 로 자동 처리한다. 채널
+  // (ChatChannel)은 connectHub·redis pub/sub·roster 코드 없이 ctx.presence 로 비즈니스 로직만 작성한다.
+  // roster.driver:'nats' → 접속자 목록도 NATS 로 동기화(crash 정리는 ttlMs heartbeat). 'none' 이면 로컬만.
+  wsCluster: {
+    bus: 'jobs',
+    roster: { driver: 'nats', ttlMs: 15_000 },
+  },
+
   // 정기 작업(ADR-028/118) — `mega scheduler` 프로세스가 등록·실행한다(config.schedules, ADR-123).
   schedules: [CronCounterSchedule],
 

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/src/core/boot.js

@@ -49,6 +49,7 @@ import { MegaShutdown } from '../lib/mega-shutdown.js'
 import { buildLogger } from '../lib/mega-logger.js'
 import { buildFromGlobalConfig, connectAll, get as getAdapter, entries as adapterEntries } from '../adapters/adapter-manager.js'
 import { buildWorkers, startAll as startWorkers, contextProxy as workersContext } from './workers-manager.js'
+import { MegaWsCluster } from './ws-cluster.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
 import { MegaWsHub } from '../cli/ws-hub.js'
@@ -293,6 +294,35 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
     megaApps.push(app)
   }
 
+  // wsCluster 자동배선 (ADR-176) — global `wsCluster.bus`(NATS) 가 있으면 앱마다 MegaWsCluster 를 만들어
+  // app.broadcast/directToUser/joinSession 의 **클러스터 fan-out·roster 동기화**를 배선한다. 개발자는
+  // connectHub 같은 코드를 쓰지 않고 비즈니스 로직만 작성한다(ADR-176 이 ADR-137 자동배선 거부를 wsCluster
+  // 에 한해 번복). bus 는 글로벌 키 직접 lookup(이미 connect 됨). roster 설정(driver/ttlMs)을 그대로 전달.
+  const wsClusterCfg = /** @type {any} */ (global).wsCluster
+  if (wsClusterCfg?.bus) {
+    const busAdapter = getAdapter('bus', wsClusterCfg.bus)
+    for (const app of megaApps) {
+      const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal(@private).
+      const cluster = new MegaWsCluster({
+        bus: /** @type {any} */ (busAdapter),
+        appName: app.name,
+        deliverBroadcast: (/** @type {any} */ p) => a._deliverBroadcast(p),
+        deliverDirect: (/** @type {any} */ p) => a._deliverDirect(p),
+        subjectPrefix: wsClusterCfg.subjectPrefix,
+        roster: wsClusterCfg.roster,
+        logger: /** @type {any} */ (app.fastify.log),
+      })
+      await cluster.start()
+      app.setWsCluster(cluster)
+      // MegaShutdown LIFO — 어댑터 disconnect 보다 먼저 정리(graceful LEAVE 가 NATS 끊기기 전에 나가게).
+      MegaShutdown.register(`mega-ws-cluster:${app.name}`, async () => cluster.stop())
+    }
+    logger?.debug?.(
+      { bus: wsClusterCfg.bus, apps: megaApps.length, roster: wsClusterCfg.roster?.driver ?? 'none' },
+      'boot.wsCluster wired (ADR-176)',
+    )
+  }
+
   // 9단계: HTTP listen(분기 — CLI/테스트가 listen=false 로 mount 까지만 받을 수 있음).
   if (listen) {
     await server.listen({ port: resolvedPort, host: resolvedHost })

package/src/core/config-validator.js

@@ -75,6 +75,12 @@ export function validateGlobalConfig(globalConfig) {
     })
   }
 
+  // 4b) wsCluster 검증 (ADR-176) — NATS 기반 WS 클러스터 broadcast/roster 자동배선.
+  //     `bus` 가 있으면 boot 가 자동 배선하므로, 가리키는 글로벌 버스 키가 실제 NATS 인지 부팅 시 확정한다.
+  if (globalConfig.wsCluster !== undefined) {
+    validateWsClusterConfig(globalConfig.wsCluster, globalConfig.services?.buses)
+  }
+
   // 5) jobs / schedules / workers 명시 등록 배열 검증 (M-2 + ADR-124 / 04-data-models §1.1).
   //    GLOBAL_ONLY_KEYS 에 키만 등록돼 있고 shape 검증이 없어, `jobs: SendEmailJob`(배열 잊음)이나
   //    원소가 클래스 아닌 값이면 흡수 로직이 silent drop 했다. 부팅 시 fail-fast 로 드러낸다.
@@ -119,6 +125,68 @@ function validateSessionSecret(secret) {
   }
 }
 
+/** wsCluster.roster.driver 허용값. */
+const WS_CLUSTER_ROSTER_DRIVERS = Object.freeze(['nats', 'none'])
+
+/**
+ * `wsCluster` config 검증 (ADR-176). 자동배선의 트리거라 잘못된 설정을 부팅 시 fail-fast 한다.
+ *  (1) `bus`(string) 필수 — 가리키는 글로벌 버스 키가 `services.buses` 에 있고 driver:'nats' 여야 한다.
+ *  (2) `roster.driver` 가 있으면 'nats'|'none' 중 하나.
+ *  (3) `roster.ttlMs` 가 있으면 양의 정수.
+ *
+ * @param {any} wsCluster - globalConfig.wsCluster.
+ * @param {Record<string, any>|undefined} buses - globalConfig.services.buses.
+ * @throws {MegaConfigError} 위 위반 시.
+ */
+function validateWsClusterConfig(wsCluster, buses) {
+  if (typeof wsCluster !== 'object' || wsCluster === null || Array.isArray(wsCluster)) {
+    throw new MegaConfigError('config.wsCluster_invalid', 'wsCluster must be an object ({ bus, roster? }).', {
+      details: { type: Array.isArray(wsCluster) ? 'array' : typeof wsCluster },
+    })
+  }
+  const bus = wsCluster.bus
+  if (typeof bus !== 'string' || bus.length === 0) {
+    throw new MegaConfigError('config.wsCluster_bus_required', 'wsCluster.bus (a global buses key) is required.', {
+      details: { bus },
+    })
+  }
+  const busDef = buses?.[bus]
+  if (!busDef) {
+    throw new MegaConfigError(
+      'config.wsCluster_bus_not_found',
+      `wsCluster.bus '${bus}' is not defined in services.buses. Declared: [${Object.keys(buses ?? {}).join(', ') || '(none)'}].`,
+      { details: { bus, declared: Object.keys(buses ?? {}) } },
+    )
+  }
+  if (busDef.driver !== 'nats') {
+    throw new MegaConfigError(
+      'config.wsCluster_bus_not_nats',
+      `wsCluster.bus '${bus}' must be a NATS bus (driver:'nats'), got driver:'${busDef.driver}'. Cluster fan-out uses NATS pub/sub (ADR-176).`,
+      { details: { bus, driver: busDef.driver } },
+    )
+  }
+  const roster = wsCluster.roster
+  if (roster !== undefined) {
+    if (typeof roster !== 'object' || roster === null || Array.isArray(roster)) {
+      throw new MegaConfigError('config.wsCluster_roster_invalid', 'wsCluster.roster must be an object ({ driver, ttlMs? }).', {
+        details: { type: Array.isArray(roster) ? 'array' : typeof roster },
+      })
+    }
+    if (roster.driver !== undefined && !WS_CLUSTER_ROSTER_DRIVERS.includes(roster.driver)) {
+      throw new MegaConfigError(
+        'config.wsCluster_roster_driver_invalid',
+        `wsCluster.roster.driver must be one of [${WS_CLUSTER_ROSTER_DRIVERS.join(', ')}], got '${roster.driver}'.`,
+        { details: { driver: roster.driver } },
+      )
+    }
+    if (roster.ttlMs !== undefined && (!Number.isInteger(roster.ttlMs) || roster.ttlMs <= 0)) {
+      throw new MegaConfigError('config.wsCluster_roster_ttl_invalid', 'wsCluster.roster.ttlMs must be a positive integer (ms).', {
+        details: { ttlMs: roster.ttlMs },
+      })
+    }
+  }
+}
+
 /**
  * `jobs`/`schedules`/`workers` 같은 "클래스(함수) 배열" config 키를 검증한다 (M-2/ADR-124). 미정의면
  * 통과(선택 키). 정의됐으면 (1) 배열이어야 하고 (2) 모든 원소가 함수(클래스)여야 한다 — 위반 시 부팅 fail-fast.