mega-framework 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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.2"
   dependencies:
     "@fastify/cookie" "^11.0.2"
     "@fastify/cors" "^11.2.0"

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) {
+      for (const ch of want) {
+        for (const m of await this._wsRoster.list(ch)) 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,13 @@ export class MegaApp {
       this._hubBridgeId = null
       MegaShutdown.unregister(`mega-hublink:${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/ws-roster.js

@@ -0,0 +1,163 @@
+// @ts-check
+/**
+ * MegaWsRedisRoster — **채널별** 클러스터 접속자 목록(roster)을 redis 로 관리 (ADR-177).
+ *
+ * roster 는 "전송(broadcast)"이 아니라 **공유 상태(누가 어느 채널에 접속 중인지)** 라, 허브 개수와 무관한
+ * **공유 스토어(redis)** 가 단일 source-of-truth 다. 이로써 (1) **멀티 허브**에서도 명단이 정합하고,
+ * (2) 신규/재연결 브릿지가 `HGETALL` 한 번으로 **전체 명단을 즉시** 획득하며(허브 presence 스냅샷 불요),
+ * (3) TTL+heartbeat 로 crash 워커의 stale 엔트리를 자동 정리한다. broadcast(메시지)는 그대로 허브(또는
+ * NATS)가 fan-out 하고, 본 모듈은 **roster(상태)만** 다룬다(관심사 분리).
+ *
+ * # 키 스키마 — 채널 기준
+ *   `<prefix>:<channel>` = HASH( sessionId → JSON({ userId, metadata?, expiresAt }) )
+ *   예) `ws:roster:chat`. 룸(채널 내 더 잘게 나눔)은 **앱 비즈니스 로직** — 프레임워크는 채널 단위만.
+ *
+ * # crash 정리(TTL) — HEXPIRE 없이 모든 redis 버전 호환
+ *   per-field TTL(HEXPIRE)은 redis 7.4+ 라, 대신 **값에 `expiresAt` 을 싣고 읽을 때 lazy 만료**한다.
+ *   각 워커가 heartbeat 로 자기 로컬 세션의 `expiresAt` 을 주기 갱신 → 살아있는 세션은 유지, crash 워커의
+ *   세션은 갱신이 끊겨 만료된다. `list` 는 만료 엔트리를 결과에서 빼고 best-effort 로 `HDEL` 한다.
+ *
+ * @module core/ws-roster
+ */
+
+/** 기본 키 접두. */
+const DEFAULT_KEY_PREFIX = 'ws:roster'
+/** 기본 멤버 TTL(ms) — heartbeat 미갱신 시 stale 로 간주. */
+const DEFAULT_TTL_MS = 30_000
+
+/**
+ * 채널 roster 멤버(redis 에 저장되는 형태 — sessionId 는 HASH field 라 값엔 안 넣음).
+ * @typedef {Object} RosterMember
+ * @property {string} userId
+ * @property {Object} [metadata]
+ */
+
+/**
+ * redis 기반 채널별 roster.
+ *
+ * 앱(MegaApp) 1개당 1 인스턴스. boot 가 `bridgeHub.roster.driver==='redis'` 일 때 생성·start·shutdown 한다.
+ * redis 핸들은 캐시 어댑터의 `.native`(ioredis) 를 받는다 — pub/sub 가 아니라 HASH 명령(HSET/HGETALL/HDEL)만 쓴다.
+ */
+export class MegaWsRedisRoster {
+  /**
+   * @param {Object} opts
+   * @param {import('ioredis').Redis} opts.redis - 캐시 어댑터의 raw ioredis 핸들.
+   * @param {() => Array<{ channel: string, sessionId: string, member: RosterMember }>} opts.getLocalMembers -
+   *   이 워커의 현재 로컬 멤버 목록(heartbeat 갱신 대상). 보통 mega-app 의 세션 매핑에서 도출.
+   * @param {string} [opts.keyPrefix] - 키 접두(기본 'ws:roster').
+   * @param {number} [opts.ttlMs] - 멤버 TTL(ms, 기본 30000).
+   * @param {{ debug?: Function, warn?: Function, error?: Function }} [opts.logger]
+   */
+  constructor({ redis, getLocalMembers, keyPrefix, ttlMs, logger } = /** @type {any} */ ({})) {
+    if (!redis || typeof redis.hset !== 'function' || typeof redis.hgetall !== 'function') {
+      throw new Error('MegaWsRedisRoster: a redis(ioredis) handle (cache adapter .native) is required.')
+    }
+    this._redis = redis
+    this._getLocalMembers = typeof getLocalMembers === 'function' ? getLocalMembers : () => /** @type {Array<{ channel: string, sessionId: string, member: RosterMember }>} */ ([])
+    this._prefix = typeof keyPrefix === 'string' && keyPrefix.length > 0 ? keyPrefix : DEFAULT_KEY_PREFIX
+    this._ttlMs = Number.isInteger(ttlMs) && /** @type {number} */ (ttlMs) > 0 ? /** @type {number} */ (ttlMs) : DEFAULT_TTL_MS
+    this._log = logger
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this._hbTimer = null
+  }
+
+  /** 채널 → redis 키. @param {string} channel @returns {string} @private */
+  _key(channel) {
+    return `${this._prefix}:${channel}`
+  }
+
+  /**
+   * 채널 roster 에 멤버 추가/갱신(joinSession). 키 자체에도 EXPIRE 를 걸어 버려진 채널이 새지 않게 한다.
+   * @param {string} channel @param {string} sessionId @param {RosterMember} member @returns {Promise<void>}
+   */
+  async add(channel, sessionId, member) {
+    if (typeof channel !== 'string' || typeof sessionId !== 'string') return
+    const key = this._key(channel)
+    const value = JSON.stringify({ userId: member?.userId, ...(member?.metadata ? { metadata: member.metadata } : {}), expiresAt: Date.now() + this._ttlMs })
+    await this._redis.hset(key, sessionId, value)
+    // 채널 HASH 키 전체 TTL — 모든 멤버가 stale 가 돼도 키가 영구히 남지 않게(멤버 TTL 의 2배 여유).
+    await this._redis.pexpire(key, this._ttlMs * 2)
+  }
+
+  /**
+   * 채널 roster 에서 멤버 제거(disconnect).
+   * @param {string} channel @param {string} sessionId @returns {Promise<void>}
+   */
+  async remove(channel, sessionId) {
+    if (typeof channel !== 'string' || typeof sessionId !== 'string') return
+    await this._redis.hdel(this._key(channel), sessionId)
+  }
+
+  /**
+   * 채널의 **현재 접속자 목록**(만료 제외). 만료 엔트리는 best-effort 로 정리한다.
+   * @param {string} channel @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+   */
+  async list(channel) {
+    if (typeof channel !== 'string') return []
+    /** @type {Record<string, string>} */
+    const raw = await this._redis.hgetall(this._key(channel))
+    const now = Date.now()
+    /** @type {Array<{ sessionId: string, userId: string, metadata?: Object }>} */
+    const out = []
+    /** @type {string[]} 만료돼 정리할 field. */
+    const expired = []
+    for (const [sessionId, json] of Object.entries(raw ?? {})) {
+      let m
+      try {
+        m = JSON.parse(json)
+      } catch (err) {
+        // 손상 엔트리는 결과에서 제외 + 정리(silent 금지 — 사유 로그).
+        this._log?.warn?.({ err, channel, sessionId }, 'ws-roster corrupt entry (dropping)')
+        expired.push(sessionId)
+        continue
+      }
+      if (typeof m.expiresAt === 'number' && m.expiresAt < now) {
+        expired.push(sessionId) // heartbeat 끊긴 crash 세션 — 만료.
+        continue
+      }
+      out.push({ sessionId, userId: m.userId, ...(m.metadata ? { metadata: m.metadata } : {}) })
+    }
+    if (expired.length > 0) {
+      // best-effort 정리(실패해도 다음 list 에서 다시 시도) — 결과엔 이미 제외됨.
+      this._redis.hdel(this._key(channel), ...expired).catch((err) => this._log?.warn?.({ err, channel }, 'ws-roster expired cleanup failed'))
+    }
+    return out
+  }
+
+  /**
+   * heartbeat 시작 — 주기적으로 로컬 멤버의 `expiresAt` 을 갱신해 살아있음을 알린다(crash 워커는 갱신이
+   * 끊겨 만료). 프로세스 종료를 막지 않게 unref. 멱등(중복 호출 무시).
+   * @returns {void}
+   */
+  startHeartbeat() {
+    if (this._hbTimer) return
+    const intervalMs = Math.max(1000, Math.floor(this._ttlMs / 2))
+    this._hbTimer = setInterval(() => {
+      this._refreshLocal().catch((err) => this._log?.warn?.({ err }, 'ws-roster heartbeat refresh failed'))
+    }, intervalMs)
+    this._hbTimer.unref?.()
+  }
+
+  /**
+   * 로컬 멤버 전체를 다시 add(=expiresAt 갱신). @returns {Promise<void>} @private
+   */
+  async _refreshLocal() {
+    const members = this._getLocalMembers()
+    for (const { channel, sessionId, member } of members) {
+      await this.add(channel, sessionId, member)
+    }
+  }
+
+  /**
+   * 정리 — heartbeat 중지 + 로컬 멤버를 redis 에서 제거(graceful 종료 시 다른 워커가 즉시 정합).
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (this._hbTimer) clearInterval(this._hbTimer)
+    this._hbTimer = null
+    // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리).
+    for (const { channel, sessionId } of this._getLocalMembers()) {
+      await this.remove(channel, sessionId).catch(() => {})
+    }
+  }
+}

package/src/core/ws-upgrade.js

@@ -175,14 +175,21 @@ export class MegaWsConnection {
  * @param {import('./mega-app.js').MegaApp|null|undefined} app
  * @param {MegaWsConnection} conn
  * @param {string|undefined} ns
- * @returns {{ list: () => Array<object>, join: (entry: object) => void, directToUser: (userId: string, message: object) => void, broadcast: (args: object) => void } | null}
+ * @returns {{ list: () => Promise<Array<object>>, join: (entry: object) => void, directToUser: (userId: string, message: object) => void, broadcast: (args: object) => void } | null}
  */
 function buildWsPresence(app, conn, ns) {
   if (!app || typeof (/** @type {any} */ (app).joinSession) !== 'function' || typeof ns !== 'string') return null
   const a = /** @type {any} */ (app)
   return {
-    /** 이 채널 ns 의 **클러스터 전역** 접속자 목록(wsCluster roster). 미배선이면 로컬 멤버만. */
-    list: () => a.roster(ns),
+    /**
+     * 이 연결이 가입한 채널의 **클러스터 전역** 접속자 목록(async). redis roster(ADR-177) 배선 시 채널 기준
+     * (redis HASH, 멀티 허브 정합); 미배선이면 NATS/로컬 ns 기준. 룸별 필터는 앱이 직접(프레임워크는 채널 단위).
+     * @returns {Promise<Array<{ sessionId: string, userId: string, metadata?: Object }>>}
+     */
+    list: async () => {
+      if (a._wsRoster && conn.channels && conn.channels.size > 0) return a.presenceList([...conn.channels])
+      return a.roster(ns)
+    },
     /** 연결을 신원에 매핑 — `{ userId, sessionId, channels?, metadata? }`. roster 등록이 자동으로 따라온다. */
     join: (entry) => {
       a.joinSession(conn, entry)

package/src/lib/logger/telegram-core.js

@@ -68,7 +68,14 @@ const LEVEL_NAMES = /** @type {Record<number, string>} */ ({
 
 /**
  * disk-backed retry queue — 전송 실패한 텍스트를 파일(JSONL)에 쌓고, 다음 기회에 재시도한다(전송 실패해도
- * 메시지를 잃지 않음, ADR-023). worker thread 내에서만 접근하므로 락 불필요(단일 소비자).
+ * 메시지를 잃지 않음, ADR-023).
+ *
+ * # in-process 직렬화 락 (ADR-023)
+ *   단일 스레드라도 `append`(open→write→close)와 `drain`(rename→read→rm)은 각 await 사이에서 **이벤트루프
+ *   인터리브**된다. 인터리브되면 append 의 `open` 이 drain 의 `rename` 보다 먼저 일어날 때, write 가 이미
+ *   rename·rm 된 inode 로 가서 항목이 **유실**된다(rename-claim 의 "유실 0" 이 깨지는 좁은 창). 그래서 큐
+ *   연산을 promise 체인 mutex 로 **직렬화**해 인터리브를 원천 차단한다. 큐 연산은 드물어(전송 실패 시
+ *   append + 주기 drain) 직렬화 비용은 무시 가능. rename-claim 은 cross-process 안전용으로 그대로 둔다.
  */
 export class RetryQueue {
   /**
@@ -77,16 +84,32 @@ export class RetryQueue {
   constructor(filePath) {
     /** @type {string} */
     this._file = filePath
+    /** @type {Promise<unknown>} 직렬화 락의 꼬리 — append/drain/clear 를 이 체인에 줄세운다. */
+    this._tail = Promise.resolve()
+  }
+
+  /**
+   * 큐 연산을 직렬화 — 앞 연산이 끝난 뒤(성패 무관) `fn` 을 실행한다. 한 연산의 실패가 다음 연산을 막지
+   * 않도록 락 체인은 에러를 삼키되, 호출자에겐 결과/에러를 그대로 전파한다.
+   * @template T @param {() => Promise<T>} fn @returns {Promise<T>} @private
+   */
+  _serialize(fn) {
+    const result = this._tail.then(() => fn())
+    // 락 꼬리: 앞 연산의 성패와 무관하게 다음 연산을 진행시킨다(에러는 result 로 호출자에게만 전파).
+    this._tail = result.catch(() => {})
+    return result
   }
 
   /**
-   * 실패 메시지를 큐에 append.
+   * 실패 메시지를 큐에 append (직렬화됨).
    * @param {string} text
    * @returns {Promise<void>}
    */
   async append(text) {
-    await mkdir(dirname(this._file), { recursive: true })
-    await appendFile(this._file, JSON.stringify({ text, ts: Date.now() }) + '\n', 'utf8')
+    return this._serialize(async () => {
+      await mkdir(dirname(this._file), { recursive: true })
+      await appendFile(this._file, JSON.stringify({ text, ts: Date.now() }) + '\n', 'utf8')
+    })
   }
 
   /**
@@ -100,34 +123,38 @@ export class RetryQueue {
    * @returns {Promise<string[]>}
    */
   async drain() {
-    const claim = `${this._file}.draining`
-    try {
-      await rename(this._file, claim)
-    } catch (e) {
-      // 큐 파일 없음(아직 실패 없음) 또는 다른 drain 이 이미 가로챔 → 처리할 것 없음.
-      if (/** @type {NodeJS.ErrnoException} */ (e)?.code === 'ENOENT') return []
-      throw e
-    }
-    const raw = await readFile(claim, 'utf8')
-    await rm(claim, { force: true })
-    /** @type {string[]} */
-    const texts = []
-    for (const line of raw.split('\n')) {
-      if (!line.trim()) continue
+    return this._serialize(async () => {
+      const claim = `${this._file}.draining`
       try {
-        const obj = JSON.parse(line)
-        if (typeof obj.text === 'string') texts.push(obj.text)
-      } catch {
-        // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
-        continue
+        await rename(this._file, claim)
+      } catch (e) {
+        // 큐 파일 없음(아직 실패 없음) 또는 다른 drain 이 이미 가로챔 → 처리할 것 없음.
+        if (/** @type {NodeJS.ErrnoException} */ (e)?.code === 'ENOENT') return []
+        throw e
+      }
+      const raw = await readFile(claim, 'utf8')
+      await rm(claim, { force: true })
+      /** @type {string[]} */
+      const texts = []
+      for (const line of raw.split('\n')) {
+        if (!line.trim()) continue
+        try {
+          const obj = JSON.parse(line)
+          if (typeof obj.text === 'string') texts.push(obj.text)
+        } catch {
+          // 손상된 라인은 건너뛴다 — 큐 전체를 막지 않기 위함(비치명적, 다음 항목 계속).
+          continue
+        }
       }
-    }
-    return texts
+      return texts
+    })
   }
 
-  /** 큐 파일 제거(테스트·정리용). @returns {Promise<void>} */
+  /** 큐 파일 제거(테스트·정리용, 직렬화됨). @returns {Promise<void>} */
   async clear() {
-    await rm(this._file, { force: true })
+    return this._serialize(async () => {
+      await rm(this._file, { force: true })
+    })
   }
 }