mega-framework 0.1.2 → 0.1.4

package/package.json

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

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

@@ -82,6 +82,10 @@ export default {
     bridgeId: process.env.BRIDGE_ID ?? 'main-1',
     channels: ['chat'],
     retry: { retries: 30, minTimeout: 1000, maxTimeout: 10_000 },
+    // 접속자 목록(roster)은 broadcast(허브)와 별개로 **redis** 로 관리한다(ADR-177). 멀티 허브에서도 명단이
+    // 정합하고, 신규/재연결 브릿지가 즉시 전체 명단을 받는다(허브 presence 스냅샷 불요). cache='demo'(글로벌
+    // redis 캐시, db1). 룸은 앱 비즈니스 로직 — 프레임워크는 **채널별 전체 접속자**만 관리한다(키 ws:roster:<channel>).
+    roster: { driver: 'redis', cache: 'demo', ttlMs: 30_000 },
   },
 
   // rate limit 상향(ADR-073) — /demo/worker 데모는 1초 간격 하트비트 ping(메인 스레드 non-block 시연)으로

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

@@ -2,14 +2,15 @@
 /**
  * ChatChannel — /ws/chat 실시간 채팅 WS 채널 (ADR-158/176).
  *
- * 클러스터 전파(broadcast)와 접속자 목록(roster) 동기화는 **프레임워크가 자동 처리**한다(ADR-176,
- * `wsCluster` = NATS). 채널은 `ctx.presence`/`ctx.app.broadcast` 로 **비즈니스 로직만** 작성하고, redis
- * pub/sub·roster 동기화 코드를 직접 두지 않는다(개발자 배선 불요). 최근 메시지 기록(history)만 redis
- * (`demo` 캐시)에 KV 로 둔다 — 이건 전파/roster 가 아니라 단순 저장이다.
+ * 클러스터 전파(broadcast)와 접속자 목록(roster)은 **프레임워크가 자동 처리**한다 — 전파는 **WS Hub**(broadcast
+ * fan-out, ADR-176), 접속자 목록은 **redis**(채널별 roster, ADR-177)로 **분리**된다(멀티 허브 정합). 채널은
+ * `ctx.presence`/`ctx.app.broadcast` 로 **비즈니스 로직만** 작성하고 전파·roster 동기화 코드를 직접 두지 않는다.
+ * 최근 메시지 기록(history)만 redis(`demo` 캐시)에 KV 로 둔다 — 이건 전파/roster 가 아니라 단순 저장이다.
  *
- *   - 전파: `ctx.presence.broadcast({ message })` → 같은 ns 의 전 클러스터 클라가 1회씩 수신(NATS fan-out).
- *   - 접속자: `ctx.presence.join({...})`(자동 roster 등록·동기화) + `ctx.presence.list()`(클러스터 전역 명단).
+ *   - 전파: `ctx.presence.broadcast({ message })` → 같은 채널의 전 클러스터 클라가 1회씩 수신(허브 fan-out).
+ *   - 접속자: `ctx.presence.join({...})`(자동 roster 등록) + `await ctx.presence.list()`(채널 전역 명단, redis).
  *   - 기록: redis RPUSH/LTRIM(최근 N건 cap), 연결 시 replay.
+ *   - 룸(채널 내 세분화)은 앱 몫 — 프레임워크는 **채널별 전체 접속자**만 관리한다.
  *
  * ASP: `/ws/chat` 는 asp.websocket.namespaces 라 E: 암호화. 코덱은 프레임워크가 종단(평문 envelope 만 다룸).
  * 인증: before(makeWsRequireAuth) 가 로그인 세션만 통과 → ctx.auth(userId/sessionId/userName) 보장.
@@ -39,7 +40,7 @@ export class ChatChannel extends MegaWebSocketController {
 
     // 최근 기록 replay (redis KV — 전파/roster 와 무관한 단순 저장).
     const items = await this._loadHistory(ctx, sock)
-    const members = this._members(ctx) // 클러스터 전역 명단(자동 동기화된 roster).
+    const members = await this._members(ctx) // 클러스터 전역 명단(redis roster, ADR-177).
 
     // 입장 본인: 신원 + 최근기록 + 현재 명단/인원 + 워커 PID(클러스터 확인용).
     sock.send({
@@ -86,7 +87,7 @@ export class ChatChannel extends MegaWebSocketController {
     if (!ctx.auth) return
     const { sessionId, userName } = ctx.auth
     // 본인을 제외한 명단(자동 roster 제거 타이밍과 무관하게 sessionId 로 명시 제외).
-    const members = this._members(ctx, sessionId)
+    const members = await this._members(ctx, sessionId)
     ctx.presence.broadcast({
       channel: CHANNEL,
       message: { type: 'chat.presence', payload: { event: 'leave', userName, online: members.length, members } },
@@ -95,13 +96,14 @@ export class ChatChannel extends MegaWebSocketController {
   }
 
   /**
-   * 클러스터 전역 접속자 이름 목록(자동 동기화된 roster). exceptSessionId 가 주어지면 그 세션은 뺀다.
-   * @param {any} ctx @param {string} [exceptSessionId] @returns {string[]}
+   * 클러스터 전역 접속자 이름 목록(프레임워크가 redis 로 동기화한 채널 roster, ADR-177). `ctx.presence.list()`
+   * 는 async(redis 조회)다. exceptSessionId 가 주어지면 그 세션은 뺀다.
+   * @param {any} ctx @param {string} [exceptSessionId] @returns {Promise<string[]>}
    * @private
    */
-  _members(ctx, exceptSessionId) {
-    return ctx.presence
-      .list()
+  async _members(ctx, exceptSessionId) {
+    const list = await ctx.presence.list()
+    return 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)

package/sample/crud/apps/main/locales/server/en.json

@@ -212,6 +212,7 @@
   "ws_status_closed": "Disconnected",
   "ws_status_error": "Error",
   "ws_online": "{n} online",
+  "ws_members_label": "Online",
   "ws_presence_join": "{user} joined.",
   "ws_presence_leave": "{user} left.",
   "ws_empty": "No messages yet. Be the first to say hi.",

package/sample/crud/apps/main/locales/server/ko.json

@@ -212,6 +212,7 @@
   "ws_status_closed": "연결 끊김",
   "ws_status_error": "오류",
   "ws_online": "접속자 {n}명",
+  "ws_members_label": "접속자",
   "ws_presence_join": "{user} 님이 입장했습니다.",
   "ws_presence_leave": "{user} 님이 퇴장했습니다.",
   "ws_empty": "아직 메시지가 없습니다. 첫 메시지를 보내보세요.",

package/sample/crud/apps/main/public/js/ws-chat.js

@@ -15,6 +15,7 @@ const messagesEl = document.getElementById('chat-messages')
 const statusEl = document.getElementById('chat-status')
 const statusDot = document.getElementById('chat-status-dot')
 const onlineEl = document.getElementById('chat-online')
+const membersListEl = document.getElementById('chat-members-list')
 const workerEl = document.getElementById('chat-worker')
 const form = /** @type {HTMLFormElement} */ (document.getElementById('chat-form'))
 const input = /** @type {HTMLInputElement} */ (document.getElementById('chat-input'))
@@ -49,12 +50,39 @@ function setStatus(state) {
   if (canSend) input.focus()
 }
 
-/** 접속자 수 뱃지 + 명단 툴팁 갱신(roster 는 cluster-wide redis HASH 공유). */
+/**
+ * 접속자 수 뱃지 + **가시적 명단(칩)** 갱신. roster 는 cluster-wide — 프레임워크가 wsCluster(NATS) 또는
+ * WS Hub(bridgeHub) 로 워커 전역 접속자를 동기화한다(ADR-176). 서버가 매 chat.history/chat.presence 에
+ * 갱신된 members 를 실어 보내므로, 받을 때마다 명단을 통째로 다시 그린다(서버 authoritative).
+ * @param {number} [online] @param {string[]} [members]
+ */
 function setRoster(online, members) {
   if (onlineEl && typeof online === 'number') {
     onlineEl.textContent = fill(d.tOnline, { n: online })
     if (Array.isArray(members)) onlineEl.title = members.join(', ')
   }
+  renderMembers(members)
+}
+
+/** 접속자 명단 칩을 다시 그린다(textContent 만 — XSS 방지). @param {string[]} [members] */
+function renderMembers(members) {
+  if (!membersListEl) return
+  const list = Array.isArray(members) ? members : null
+  if (!list) return
+  membersListEl.replaceChildren() // 기존 칩 제거(innerHTML 미사용).
+  if (list.length === 0) {
+    const empty = document.createElement('span')
+    empty.className = 'text-body-secondary'
+    empty.textContent = '—'
+    membersListEl.append(empty)
+    return
+  }
+  for (const name of list) {
+    const chip = document.createElement('span')
+    chip.className = 'badge rounded-pill text-bg-light border'
+    chip.textContent = String(name ?? '') // ← XSS 방지: 닉네임은 textContent 로만.
+    membersListEl.append(chip)
+  }
 }
 
 /** 이 연결이 붙은 클러스터 워커 PID 표시(cluster broadcast 실증용). */
@@ -137,7 +165,7 @@ async function start() {
     setRoster(payload?.online, payload?.members)
     setWorker(payload?.workerPid)
   })
-  // 채팅 메시지(본인 echo 포함) — cluster-wide redis pub/sub 로 모든 워커에서 도착.
+  // 채팅 메시지(본인 echo 포함) — cluster-wide(프레임워크가 WS Hub 또는 NATS 로 모든 워커에 fan-out, ADR-176).
   sock.on('chat.msg', (payload) => appendMessage(payload ?? {}))
   // 입퇴장 알림 + 갱신된 명단/수(cluster-wide).
   sock.on('chat.presence', (payload) => {

package/sample/crud/apps/main/views/ws/index.ejs

@@ -37,6 +37,13 @@
     <span id="chat-online" class="badge text-bg-light" data-bs-toggle="tooltip" title=""></span>
   </div>
 
+  <%# 접속자 명단(cluster-wide) — JS(ws-chat.js)가 chat.history/chat.presence 의 members 로 칩을 채운다.
+      XSS 방지: 닉네임은 textContent 로만 삽입. %>
+  <div id="chat-members" class="px-3 py-2 d-flex flex-wrap align-items-center gap-1 border-bottom bg-body-tertiary small">
+    <span class="text-body-secondary me-1"><%= t('ws_members_label', { defaultValue: '접속자' }) %>:</span>
+    <span id="chat-members-list" class="d-flex flex-wrap gap-1"></span>
+  </div>
+
   <%# 메시지 목록 — JS 가 textContent 로만 채운다(XSS 방지: 사용자 입력을 innerHTML 로 넣지 않음). %>
   <div id="chat-messages" class="list-group list-group-flush overflow-auto" style="height: 22rem" aria-live="polite">
     <div data-empty class="list-group-item text-body-secondary small text-center py-5"><%= t('ws_empty', { defaultValue: '아직 메시지가 없습니다. 첫 메시지를 보내보세요.' }) %></div>

package/sample/crud/yarn.lock

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

package/src/adapters/file-adapter.js

@@ -6,6 +6,11 @@
  * 같은 `get/set/del/has` API 를 로컬 파일로 만족시킨다 — driver 키 한 줄만 바꿔 환경 전환(ADR-082).
  * **신규 의존성 0** (`node:fs/promises`/`node:path`/`node:crypto` 표준만).
  *
+ * ⚠️ **만료 파일 능동 정리 없음(디스크 증가 주의)**: 만료 envelope 은 **재접근(get/has) 시에만 lazy 삭제**된다.
+ * set 후 다시 조회되지 않는 만료 키는 파일로 영구 잔존하므로, **짧은 TTL + 높은 키 카디널리티**(요청별 캐시 키
+ * 등) 워크로드에선 디스크/inode 가 누적될 수 있다. 그래서 file 캐시는 **dev / 단일·단명 인스턴스 권장**이며,
+ * 프로덕션 장기 구동에는 redis 캐시 또는 외부 정리(cron unlink)를 전제로 한다(능동 sweep 은 후속 과제).
+ *
  * # 표준 표면 (MegaCacheAdapter 상속)
  *   - `_connect()`   — `fs.mkdir(basePath, { recursive: true })` 로 디렉토리 보장.
  *   - `_disconnect()`— no-op (파일시스템은 close 개념 없음).

package/src/adapters/mega-cache-adapter.js

@@ -3,8 +3,12 @@
  * MegaCacheAdapter — key-value 캐시 표준 인터페이스 (추상, 08-class-specs §3.4).
  *
  * `ctx.cache(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaRedisAdapter` /
- * `MegaFileAdapter` (ADR-082). 사용자 `key` 에 자동 prefix
- * `mega:cache:<appName>:<key>` 가 코어에서 부착됨 (ADR-064).
+ * `MegaFileAdapter` (ADR-082).
+ *
+ * ⚠️ **키 네임스페이스(ADR-064)**: ADR-064 가 `mega:cache:<appName>:<key>` 자동 prefix 를 *결정*했으나
+ * **현재 코어에 미구현**이다(get/set/del 이 raw `key` 를 그대로 사용). 멀티앱이 같은 redis 를 공유하면
+ * 키 충돌 위험이 있으니, **현재는 사용자가 키에 앱별 네임스페이스를 직접 붙여야 한다**. 자동 prefix 구현은
+ * 후속 과제(ADR-064 open). 단일앱(현 sample)에선 무관.
  *
  * @module adapters/mega-cache-adapter
  */

package/src/adapters/nats-adapter.js

@@ -295,11 +295,16 @@ export class MegaNatsAdapter extends MegaBusAdapter {
    * 잡 처리 등록 — **queue group** 구독(같은 queue 구독자끼리 load-balance). 기본 queue 이름은 jobName
    * (같은 잡의 모든 워커가 한 그룹).
    *
+   * ⚠️ **전달 보장 = at-most-once(비영속, H5)**: 이건 **core NATS** queue group 이라 메시지가 디스크에
+   * 남지 않는다 — 구독자가 없거나 처리 중 죽으면 그 메시지는 **유실**된다(재시도·DLQ 없음). 유실이
+   * 치명적이거나 영속 큐/재시도/DLQ 가 필요하면 **`MegaJobQueue`(JetStream, at-least-once, ADR-028/112)**
+   * 를 쓴다. `ctx.bus(x).process` 와 `mega worker`(JetStream) 는 **전달 보장이 다르므로 혼용 금지**.
+   *
    * **subscription 핸들을 반환하지 않는 건 의도적**(L-2): worker 는 앱 수명 동안 상주하는 것이
    * 정상이고(개별 잡 처리 등록을 런타임에 떼었다 붙였다 하는 패턴은 비표준), 정리는 disconnect 시
    * `_disconnect()` 의 `nc.drain()` 이 **모든 구독을 일괄 비우며** 처리한다. 개별 unsubscribe 가
    * 필요한 일시 구독은 `subscribe()`(핸들 반환)를 쓴다 — `process` 는 fire-and-forget `enqueue` 와
-   * 대칭인 상주 worker 용이다. 영속 큐/재시도/DLQ 가 필요하면 `MegaJob`(jetstream, ADR-028).
+   * 대칭인 상주 worker 용이다.
    *
    * @param {string} jobName
    * @param {(payload: any) => any} handler

package/src/cli/commands/console-cmd.js

@@ -30,7 +30,7 @@ function defaultReplFactory() {
  * @param {(msg: string) => void} [deps.out]
  * @param {() => (Promise<void> | void)} [deps.shutdown] - 주입용(테스트). REPL 종료 시 호출하는 graceful
  *   shutdown 트리거. 기본 {@link MegaShutdown.now}(등록 hook 실행 후 process.exit).
- * @param {(opts: { signals?: string[] }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
+ * @param {(opts: { signals?: string[], globalErrorHandlers?: boolean }) => void} [deps.setupSignals] - 주입용(테스트). 시그널 핸들러 등록.
  *   기본 {@link MegaShutdown.setupSignals}.
  * @returns {Promise<{ ctx: Record<string, any>, config: object, server: { context: Record<string, any> } }>}
  */
@@ -44,7 +44,9 @@ export async function startConsole(
   // 두면 REPL 종료 후에도 열린 핸들(DB 풀·redis·wsHub listen)로 프로세스가 행하고 어댑터가 미정리된다.
   // 따라서 SIGTERM 은 graceful shutdown 으로 받는다. SIGINT 은 REPL 이 소유(빈 줄 클리어 / 이중 입력 시
   // 'exit')하므로 가로채지 않는다 — 가로채면 한 번의 Ctrl-C 가 콘솔을 죽인다(ADR-167).
-  setupSignals({ signals: ['SIGTERM'] })
+  // REPL 은 전역 에러 핸들러를 끈다(globalErrorHandlers:false) — 대화형에서 사용자 코드 예외가
+  // 프로세스를 graceful shutdown 시키면 안 되고, REPL 자체 에러 복구를 방해하지 않기 위함(ADR-178).
+  setupSignals({ signals: ['SIGTERM'], globalErrorHandlers: false })
   const server = replFactory()
   Object.assign(server.context, { ctx, config: global, mega: { config: global, host } })
   // REPL 종료(.exit / Ctrl-D / 이중 Ctrl-C)는 'exit' 이벤트로 온다 — 이때 graceful shutdown 으로 어댑터 등을

package/src/core/boot.js

@@ -34,6 +34,7 @@
  * @module core/boot
  */
 import { join } from 'node:path'
+import nodeCluster from 'node:cluster' // 워커 식별자(cluster.worker.id)로 bridgeId 유일화(ADR-176, L-3).
 // 빌트인 어댑터(postgres/mongodb/mariadb/sqlite/redis/file/nats/redlock)는 import 시 레지스트리에
 // 자기등록한다(ADR-044). CLI 런타임 부팅(`mega start`/`worker`/`scheduler`/`migrate`)은 사용자 코드가
 // 'mega-framework' 를 import 하기 전에 `buildFromGlobalConfig` 로 driver 를 resolve 하므로, 이 배럴을
@@ -50,6 +51,7 @@ 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 { MegaWsRedisRoster } from './ws-roster.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
 import { MegaWsHub } from '../cli/ws-hub.js'
@@ -306,15 +308,40 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
     const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal(@private).
     const bridgeHub = /** @type {any} */ (apps[i].config).bridgeHub
     if (bridgeHub?.url) {
+      // ⚠️ 클러스터 워커마다 별개 브릿지라 bridgeId 가 **워커별로 유일**해야 한다(허브 sessionId global-unique
+      // 계약). 모든 워커가 같은 bridgeId 면 bridge-subscriber sessionId(`bridge:<id>#<ch>`, mega-app
+      // _resyncPresence)가 충돌해 허브가 계속 재할당(thrashing)한다(L-3). 설정 bridgeId 를 베이스로 워커
+      // 식별자(cluster.worker.id, 단일 프로세스면 pid)를 붙여 유일화한다. instanceId 도 동일하게 유일화
+      // (hub-link 는 instanceId 미지정 시 bridgeId 로 폴백하므로).
+      const baseId = bridgeHub.bridgeId ?? app.name
+      const workerTag = nodeCluster.worker?.id ?? process.pid
+      const uniqueBridgeId = `${baseId}-w${workerTag}`
       // WS Hub 자동연결(ADR-065/176). connectHub 가 _hubLink 를 세워 app.broadcast/joinSession 의 hub 경로를
       // 활성화한다(shutdown hook 도 connectHub 가 등록). 허브 다운이어도 boot 를 막지 않는다 — 초기 연결
       // 실패는 warn 하고(retry 설정 시 백그라운드 재연결, ADR-098) 앱은 계속 뜬다(로컬 전달은 동작).
       try {
-        await app.connectHub(bridgeHub)
-        logger?.debug?.({ app: app.name, url: bridgeHub.url }, 'boot.bridgeHub connected (ADR-176)')
+        await app.connectHub({ ...bridgeHub, bridgeId: uniqueBridgeId, instanceId: bridgeHub.instanceId ?? uniqueBridgeId })
+        logger?.debug?.({ app: app.name, url: bridgeHub.url, bridgeId: uniqueBridgeId }, 'boot.bridgeHub connected (ADR-176)')
       } catch (err) {
         logger?.warn?.({ err, app: app.name, url: bridgeHub.url }, 'boot.bridgeHub initial connect failed (retry if configured)')
       }
+      // redis roster 자동배선(ADR-177) — `bridgeHub.roster.driver==='redis'` 면 **채널별 접속자 목록**을 redis HASH 로
+      // 관리한다(broadcast 와 별개 — 멀티 허브에서도 정합, 신규/재연결 브릿지가 즉시 전체 명단). 캐시 어댑터의 raw
+      // ioredis(`.native`)를 쓰고, heartbeat 로 crash 워커 stale 정리. hub 연결 성패와 무관(roster 는 redis 독립).
+      const rosterCfg = /** @type {any} */ (bridgeHub).roster
+      if (rosterCfg?.driver === 'redis') {
+        const cacheAdapter = /** @type {any} */ (getAdapter('cache', rosterCfg.cache))
+        const redis = cacheAdapter?.native
+        if (!redis || typeof redis.hset !== 'function') {
+          logger?.warn?.({ app: app.name, cache: rosterCfg.cache }, 'boot.wsRoster: cache adapter has no native redis — roster disabled')
+        } else {
+          const roster = new MegaWsRedisRoster({ redis, getLocalMembers: () => a.localRosterMembers(), ttlMs: rosterCfg.ttlMs, keyPrefix: rosterCfg.keyPrefix, logger })
+          roster.startHeartbeat()
+          a.setWsRoster(roster)
+          MegaShutdown.register(`mega-wsroster:${app.name}`, () => roster.stop())
+          logger?.debug?.({ app: app.name, cache: rosterCfg.cache }, 'boot.wsRoster connected (ADR-177, redis)')
+        }
+      }
     } else if (wsClusterBus) {
       const cluster = new MegaWsCluster({
         bus: /** @type {any} */ (wsClusterBus),

package/src/core/config-validator.js

@@ -287,6 +287,45 @@ export function validateAppConfig(appConfig, expectedFolderName, globalConfig) {
         { details: { app: expectedFolderName, bridgeHubUrl: bh.url, wsClusterBus: globalConfig.wsCluster.bus } },
       )
     }
+    // bridgeHub.roster(채널별 접속자 목록 백엔드, ADR-177) — broadcast 와 별개. driver='redis' 면 cache 는
+    // 글로벌 services.caches 의 **redis** 어댑터 키여야 한다(멀티 허브 정합용 공유 스토어).
+    if (bh.roster !== undefined) {
+      const r = bh.roster
+      if (typeof r !== 'object' || r === null || Array.isArray(r)) {
+        throw new MegaConfigError('config.bridgeHub_roster_invalid', `app '${expectedFolderName}': bridgeHub.roster must be an object ({ driver, cache?, ttlMs? }).`, {
+          details: { app: expectedFolderName },
+        })
+      }
+      const VALID_ROSTER_DRIVERS = ['redis', 'none']
+      if (r.driver !== undefined && !VALID_ROSTER_DRIVERS.includes(r.driver)) {
+        throw new MegaConfigError('config.bridgeHub_roster_driver_invalid', `app '${expectedFolderName}': bridgeHub.roster.driver must be one of ${VALID_ROSTER_DRIVERS.join('|')}.`, {
+          details: { app: expectedFolderName, driver: r.driver },
+        })
+      }
+      if (r.driver === 'redis') {
+        const cacheSvc = typeof r.cache === 'string' ? globalConfig?.services?.caches?.[r.cache] : undefined
+        if (typeof r.cache !== 'string' || r.cache.length === 0) {
+          throw new MegaConfigError('config.bridgeHub_roster_cache_required', `app '${expectedFolderName}': bridgeHub.roster.cache (global redis cache key) is required when driver='redis'.`, {
+            details: { app: expectedFolderName },
+          })
+        }
+        if (!cacheSvc) {
+          throw new MegaConfigError('config.bridgeHub_roster_cache_unknown', `app '${expectedFolderName}': bridgeHub.roster.cache '${r.cache}' is not a registered global cache (services.caches).`, {
+            details: { app: expectedFolderName, cache: r.cache },
+          })
+        }
+        if (cacheSvc.driver !== 'redis') {
+          throw new MegaConfigError('config.bridgeHub_roster_cache_not_redis', `app '${expectedFolderName}': bridgeHub.roster.cache '${r.cache}' must be a redis cache (driver='redis'), got '${cacheSvc.driver}'.`, {
+            details: { app: expectedFolderName, cache: r.cache, driver: cacheSvc.driver },
+          })
+        }
+      }
+      if (r.ttlMs !== undefined && (!Number.isInteger(r.ttlMs) || r.ttlMs <= 0)) {
+        throw new MegaConfigError('config.bridgeHub_roster_ttl_invalid', `app '${expectedFolderName}': bridgeHub.roster.ttlMs must be a positive integer (ms).`, {
+          details: { app: expectedFolderName, ttlMs: r.ttlMs },
+        })
+      }
+    }
   }
 
   // 3) Shared-Reference 키 검증 — 참조하는 키가 globalConfig.services 에 존재해야 함

package/src/core/mega-app.js

@@ -184,6 +184,9 @@ export class MegaApp {
     this._hubLink = null
     /** @type {import('./ws-cluster.js').MegaWsCluster|null} NATS 기반 클러스터 fan-out/roster (ADR-176, boot 자동배선). */
     this._wsCluster = null
+    /** @type {import('./ws-roster.js').MegaWsRedisRoster|null} 채널별 redis roster(ADR-177, boot 자동배선).
+     * 접속자 목록(상태)을 redis HASH 로 cluster-wide 관리한다(broadcast 와 별개 — 멀티 허브 정합·즉시 스냅샷). */
+    this._wsRoster = null
     /** ns(=ws path) → 활성 로컬 연결 집합 (hub broadcast 의 local fan-out 용). @type {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
     this._wsConns = new Map()
     /** userId → 활성 로컬 연결 집합 (DIRECT 타겟팅, H-latent guard). @type {Map<string, Set<import('./ws-upgrade.js').MegaWsConnection>>} */
@@ -636,7 +639,17 @@ export class MegaApp {
     // hub → bridge 푸시를 로컬 소켓에 전달.
     link.on(HUB_MESSAGE_TYPES.BROADCAST, (msg) => this._deliverBroadcast(/** @type {any} */ (msg).payload))
     link.on(HUB_MESSAGE_TYPES.DIRECT, (msg) => this._deliverDirect(/** @type {any} */ (msg).payload))
-    // 재연결 성공 시 presence 재동기화(ADR-098) — hub 는 절단 시점 presence 를 잃으므로 다시 JOIN.
+    // 허브가 fan-out 하는 presence(JOIN/LEAVE/METADATA)·heartbeat 는 broadcast 채널 멤버십·keepalive 용으로만
+    // 의미 있다. **roster(접속자 목록)는 redis(MegaWsRedisRoster, ADR-177)가 별도 관리**하므로 브릿지는 이들을
+    // 소비하지 않는다 — no-op 핸들러로 "no handler for type" 노이즈만 차단한다(JOIN 자체는 joinSession 이
+    // broadcast 채널 가입용으로 계속 송신). 멀티 허브에서도 redis 가 single source-of-truth 라 명단이 정합.
+    const noopHub = () => {}
+    link.on(HUB_MESSAGE_TYPES.JOIN, noopHub)
+    link.on(HUB_MESSAGE_TYPES.LEAVE, noopHub)
+    link.on(HUB_MESSAGE_TYPES.BULK_LEAVE, noopHub)
+    link.on(HUB_MESSAGE_TYPES.METADATA, noopHub)
+    link.on(HUB_MESSAGE_TYPES.HEARTBEAT, noopHub)
+    // 재연결 성공 시 presence 재동기화(ADR-098) — hub 는 절단 시점 presence 를 잃으므로 broadcast 채널을 다시 JOIN.
     link.on(MegaHubLink.EVENTS.RECONNECTED, () => this._resyncPresence())
     await link.connect()
 
@@ -765,6 +778,15 @@ export class MegaApp {
     if (this._wsCluster && typeof conn.ns === 'string') {
       this._wsCluster.rosterAdd({ ns: conn.ns, sessionId, userId, ...(metadata ? { metadata } : {}) })
     }
+    // redis roster 동기화 (ADR-177) — **채널별** 접속자 목록을 redis HASH 에 add(멀티 허브 정합). best-effort.
+    if (this._wsRoster && chans.length > 0) {
+      const member = { userId, ...(metadata ? { metadata } : {}) }
+      for (const ch of chans) {
+        this._wsRoster.add(ch, sessionId, member).catch((err) =>
+          this.fastify.log?.warn?.({ err, channel: ch, app: this.name }, 'ws-roster add failed'),
+        )
+      }
+    }
     return this
   }
 
@@ -898,8 +920,9 @@ export class MegaApp {
    * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
    */
   roster(ns) {
-    if (this._wsCluster) return this._wsCluster.roster(ns)
-    // wsCluster 미배선 — joinSession 으로 매핑된 로컬 세션 중 해당 ns 만.
+    if (this._wsCluster) return this._wsCluster.roster(ns) // NATS: 이미 cluster-wide(roster 동기화 포함).
+    // ns 기준 로컬 명단(동기 API). **채널 기준 redis roster(ADR-177)** 는 `ctx.presence.list()`(async)가
+    // 다룬다 — 이 메서드는 NATS/로컬용 ns 기준 동기 API 로 유지(하위호환).
     /** @type {Array<{ sessionId: string, userId: string, metadata?: Object }>} */
     const out = []
     for (const [sessionId, conn] of this._sessionConns) {
@@ -909,6 +932,65 @@ export class MegaApp {
     return out
   }
 
+  /**
+   * 채널별 redis roster(ADR-177)를 이 앱에 배선한다. boot 가 `bridgeHub.roster.driver==='redis'` 일 때
+   * 자동 호출하므로 개발자가 직접 부를 일은 없다(테스트·고급 용도로만 공개).
+   * @param {import('./ws-roster.js').MegaWsRedisRoster|null} roster
+   * @returns {this}
+   */
+  setWsRoster(roster) {
+    this._wsRoster = roster
+    return this
+  }
+
+  /**
+   * 주어진 **채널들**의 cluster-wide 접속자 목록 — redis roster(원격 포함) + 로컬 세션을 병합한다(ADR-177).
+   * 로컬을 항상 포함해 join 직후 redis HSET 반영 전에도 본인이 빠지지 않게 한다. `ctx.presence.list()` 의
+   * redis 경로가 호출(async). roster 미배선이면 로컬 채널 멤버만.
+   * @param {string[]} channels
+   * @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+   */
+  async presenceList(channels) {
+    const want = new Set(Array.isArray(channels) ? channels : [])
+    /** @type {Map<string, { sessionId: string, userId: string, metadata?: Object }>} */
+    const out = new Map()
+    // 로컬 세션(이 워커) — 요청 채널에 가입한 것. 항상 fresh(본인 포함).
+    for (const [sessionId, conn] of this._sessionConns) {
+      if (!conn.isOpen || !conn.channels) continue
+      let inCh = false
+      for (const ch of conn.channels) {
+        if (want.has(ch)) {
+          inCh = true
+          break
+        }
+      }
+      if (inCh) out.set(sessionId, { sessionId, userId: /** @type {string} */ (conn.userId), ...(conn.metadata ? { metadata: conn.metadata } : {}) })
+    }
+    // redis(cluster-wide) — 다른 워커/허브의 세션까지.
+    if (this._wsRoster) {
+      // 여러 채널 redis 조회를 **병렬화**(Promise.all) — onConnect 핫패스의 직렬 라운드트립 누적 제거(Med).
+      const lists = await Promise.all([...want].map((ch) => this._wsRoster.list(ch)))
+      for (const list of lists) for (const m of list) if (!out.has(m.sessionId)) out.set(m.sessionId, m)
+    }
+    return [...out.values()]
+  }
+
+  /**
+   * 이 워커의 로컬 멤버 목록 — redis roster heartbeat 갱신 대상(ADR-177). joinSession 으로 매핑된
+   * (채널 × 세션)마다 1개. MegaWsRedisRoster 가 주기적으로 이 목록의 expiresAt 을 갱신한다.
+   * @returns {Array<{ channel: string, sessionId: string, member: { userId: string, metadata?: Object } }>}
+   */
+  localRosterMembers() {
+    /** @type {Array<{ channel: string, sessionId: string, member: { userId: string, metadata?: Object } }>} */
+    const out = []
+    for (const [sessionId, conn] of this._sessionConns) {
+      if (!conn.isOpen || !conn.channels) continue
+      const member = { userId: /** @type {string} */ (conn.userId), ...(conn.metadata ? { metadata: conn.metadata } : {}) }
+      for (const ch of conn.channels) out.push({ channel: ch, sessionId, member })
+    }
+    return out
+  }
+
   /**
    * broadcast payload 를 로컬 ns 소켓에 전달한다. message 는 `{ type, payload }` 내부 envelope.
    *
@@ -999,6 +1081,14 @@ export class MegaApp {
       }
       // NATS roster 제거 (ADR-176) — disconnect 시 클러스터 접속자 목록에서 자동 제거(개발자 코드 불요).
       this._wsCluster?.rosterRemove(conn.sessionId)
+      // redis roster 제거 (ADR-177) — 이 세션이 가입한 모든 채널에서 제거. best-effort.
+      if (this._wsRoster && conn.channels) {
+        for (const ch of conn.channels) {
+          this._wsRoster.remove(ch, /** @type {string} */ (conn.sessionId)).catch((err) =>
+            this.fastify.log?.warn?.({ err, channel: ch, app: this.name }, 'ws-roster remove failed'),
+          )
+        }
+      }
     }
   }
 
@@ -1169,6 +1259,21 @@ export class MegaApp {
       this._hubBridgeId = null
       MegaShutdown.unregister(`mega-hublink:${this.name}`)
     }
+    // NATS 클러스터 정리(ADR-176) — 구독·heartbeat/sweep 타이머·roster 멤버 해제. boot 의 shutdown hook 과
+    // **양쪽**에서 정리해야 시그널을 안 거치는 종료(server.close()/프로그램적 재시작/멀티앱 부분 종료)에서도
+    // 누수가 없다(_hubLink/_wsRoster 와 동일 대칭, H1). stop() 은 _isStarted 가드로 멱등이라 중복 안전.
+    if (this._wsCluster) {
+      await this._wsCluster.stop().catch((err) => this.fastify.log?.warn?.({ err, app: this.name }, 'ws-cluster stop failed'))
+      this._wsCluster = null
+      MegaShutdown.unregister(`mega-ws-cluster:${this.name}`)
+    }
+    // redis roster 정리(ADR-177) — heartbeat 중지 + 로컬 멤버 즉시 제거. _sessionConns 를 비우기 **전에**
+    // 호출해야 stop() 이 localRosterMembers 로 자기 멤버를 redis 에서 뺄 수 있다.
+    if (this._wsRoster) {
+      await this._wsRoster.stop().catch((err) => this.fastify.log?.warn?.({ err, app: this.name }, 'ws-roster stop failed'))
+      this._wsRoster = null
+      MegaShutdown.unregister(`mega-wsroster:${this.name}`)
+    }
     this._wsConns.clear()
     this._userConns.clear()
     this._sessionConns.clear()

package/src/core/mega-cluster.js

@@ -50,10 +50,16 @@ export class MegaCluster {
     /** @type {(() => Promise<void>) | null} */
     this._workerFn = null
 
-    // M1 — respawn backoff (crash-loop 보호)
-    this._respawnTooFast = 0          // 빠른 연속 crash 카운터
-    this._maxRapidRespawn = 5         // 5번 연속 너무 빨리 crash 하면 중단
-    this._minRespawnIntervalMs = 1000 // 1초 이내 crash 는 "너무 빠름"
+    // M1 — respawn backoff (crash-loop 보호). 멀티워커 정확성: 전역 카운터 + 정상종료-리셋은 한 워커의
+    // 정상 종료가 다른 워커들의 누적 빠른-crash 카운트를 통째로 지워 crash-loop 를 마스킹한다. 그래서
+    // **빠른 crash 타임스탬프의 슬라이딩 윈도우**로 판정한다(윈도우 내 N회 → 포기). 정상 종료는 카운트에
+    // 기여하지 않고, 오래된 빠른-crash 는 윈도우에서 자연 소거된다(안정화되면 자동 리셋).
+    this._maxRapidRespawn = 5         // 윈도우 내 5번 빠른 crash 면 중단
+    this._minRespawnIntervalMs = 1000 // 이 lifetime 미만 crash 는 "너무 빠름"
+    /** @type {number[]} 윈도우 내 빠른-crash 타임스탬프(ms). */
+    this._rapidCrashTimes = []
+    /** @type {ReturnType<typeof setTimeout>|null} SIGTERM grace 강제-kill 타이머(전원 정상종료 시 취소). */
+    this._graceTimer = null
   }
 
   /**
@@ -103,13 +109,15 @@ export class MegaCluster {
       this._shuttingDown = true
       console.log(`[mega-cluster] received ${sig}, broadcasting shutdown to ${this._workers.size} workers (grace ${this._gracePeriodMs}ms)`)
       this._broadcastShutdown()
-      // grace 초과 시 강제 kill
-      setTimeout(() => {
+      // grace 초과 시 강제 kill. 핸들을 보관해 전원 정상종료(exit 핸들러) 시 취소 — 정상 종료가 이 타이머의
+      // exit(1) 과 경합해 exit code 가 흔들리지 않게 한다(k8s/systemd 종료 판정 노이즈 제거).
+      this._graceTimer = setTimeout(() => {
         for (const w of this._workers) {
           try { w.kill('SIGKILL') } catch (err) { console.warn('[mega-cluster] SIGKILL failed:', err.message) }
         }
         this._proc.exit(1)
-      }, this._gracePeriodMs).unref()
+      }, this._gracePeriodMs)
+      this._graceTimer.unref()
     }
     this._proc.on('SIGTERM', () => onSignal('SIGTERM'))
     this._proc.on('SIGINT', () => onSignal('SIGINT'))
@@ -124,33 +132,35 @@ export class MegaCluster {
       this._workers.delete(worker)
       if (this._shuttingDown) {
         if (this._workers.size === 0) {
+          if (this._graceTimer) clearTimeout(this._graceTimer) // 전원 정상종료 — 강제-kill 타이머 취소(exit code 경합 제거).
+          this._graceTimer = null
           console.log('[mega-cluster] all workers exited, primary exiting 0')
           this._proc.exit(0)
         }
         return
       }
       if (this._respawn) {
-        // M1 — respawn backoff: 너무 빨리 연속 crash 하면 crash-loop 으로 보고 respawn 중단.
+        // M1 — respawn backoff: 빠른 crash 의 슬라이딩 윈도우로 crash-loop 판정(멀티워커 정확).
         const now = Date.now()
         const lastBirth = worker._megaBirthAt ?? now
         const lifetimeMs = now - lastBirth
+        // 윈도우 = maxRapidRespawn 회의 빠른 재시작이 걸릴 시간 + 여유. 이보다 오래된 빠른-crash 는 소거.
+        const windowMs = this._minRespawnIntervalMs * this._maxRapidRespawn * 2
+        this._rapidCrashTimes = this._rapidCrashTimes.filter((t) => now - t < windowMs)
         if (lifetimeMs < this._minRespawnIntervalMs) {
-          this._respawnTooFast += 1
-          if (this._respawnTooFast >= this._maxRapidRespawn) {
-            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로
-            //   보인다 → systemd/k8s 가 "정상 종료" 로 판단해 재시작 안 함.
-            //   명시적 exit 1 로 "비정상 종료" 를 외부 supervisor 에 알려 재시작을 유도한다.
+          this._rapidCrashTimes.push(now) // 빠른 crash 만 윈도우에 기록(정상 lifetime 은 기여 X).
+          if (this._rapidCrashTimes.length >= this._maxRapidRespawn) {
+            // H-1 — crash-loop 포기 시 그냥 return 하면 이벤트루프가 비어 exit 0(성공)으로 보인다 →
+            //   systemd/k8s 가 "정상 종료" 로 오판. 명시적 exit 1 로 비정상 종료를 알려 재시작을 유도한다.
             console.error(
-              `[mega-cluster] rapid crash-loop detected (${this._respawnTooFast} restarts within ${this._minRespawnIntervalMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
+              `[mega-cluster] rapid crash-loop detected (${this._rapidCrashTimes.length} rapid crashes within ${windowMs}ms), giving up — exiting 1. Last exit: code=${code}, signal=${signal}.`,
             )
             this._proc.exit(1)
             return   // 실 process.exit 은 즉시 종료하나, 주입된 fake 는 계속 실행되므로 명시적 중단
           }
-        } else {
-          this._respawnTooFast = 0   // 정상 lifetime 이면 카운터 reset
         }
         console.warn(
-          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crash-count=${this._respawnTooFast}/${this._maxRapidRespawn})`,
+          `[mega-cluster] worker ${worker.process.pid} died (code=${code}, signal=${signal}, lifetime=${lifetimeMs}ms), respawning (rapid-crashes=${this._rapidCrashTimes.length}/${this._maxRapidRespawn} in ${windowMs}ms)`,
         )
         this._forkWorker()
       } else {