mega-framework 0.1.5 → 0.1.7

package/src/core/ws-presence.js

@@ -0,0 +1,624 @@
+// @ts-check
+/**
+ * MegaWsPresence — 앱의 WS presence/클러스터 동기화 협력자 (MegaApp 에서 분리).
+ *
+ * 책임: ① 로컬 연결 인덱스 3종(ns→연결·userId→연결·sessionId→연결) 관리(_track/_untrack),
+ * ② hub link(connectHub — BROADCAST/DIRECT 수신·presence 재동기화·admin-kick), ③ NATS
+ * wsCluster/redis wsRoster 동기화, ④ broadcast/directToUser/updateMetadata 의 로컬+클러스터
+ * fan-out, ⑤ roster/presenceList 조회. MegaApp 은 같은 이름의 공개 메서드를 본 협력자에
+ * 위임한다(분리 전 호출부·테스트와 표면 동일).
+ *
+ * MegaApp(HTTP 앱 골격: 보안/세션/i18n/템플릿/헬스/upgrade 핸드셰이크)과 분리한 이유 —
+ * 연결 인덱스 불변식(joinSession 의 dangling 정리, _untrack 의 동일성 확인)이 한 모듈에
+ * 모여야 검증·유지보수가 좁아진다. 분리는 위임 기반이라 동작 변화 0.
+ *
+ * @module core/ws-presence
+ */
+import { MegaHubLink } from './hub-link.js'
+import { CLOSE_CODE_REQUEUE } from './ws-upgrade.js'
+import { HUB_MESSAGE_TYPES } from '../lib/hub-protocol.js'
+import { MegaShutdown } from '../lib/mega-shutdown.js'
+
+export class MegaWsPresence {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.appName - 소유 앱 이름(hook 이름·로그 식별자).
+   * @param {import('pino').Logger | { debug?: Function, warn?: Function } | null} [opts.log] -
+   *   앱 공유 로거(보통 `app.fastify.log`). 미주입이면 무로그.
+   */
+  constructor({ appName, log } = /** @type {any} */ ({})) {
+    if (typeof appName !== 'string' || appName.length === 0) {
+      throw new Error('MegaWsPresence: appName is required')
+    }
+    /** @type {string} */
+    this._appName = appName
+    /** @type {any} */
+    this._log = log ?? null
+    /** @type {MegaHubLink|null} hub 연결 (scaffold 권장). */
+    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>>} */
+    this._userConns = new Map()
+    /** sessionId → 활성 로컬 연결 1개 (세션단위 JOIN/LEAVE). @type {Map<string, import('./ws-upgrade.js').MegaWsConnection>} */
+    this._sessionConns = new Map()
+    /** @type {string[]} connectHub 으로 구독한 채널. */
+    this._hubChannels = []
+    /** connectHub 의 bridgeId (재연결 재구독·세션 JOIN 에 재사용). @type {string|null} */
+    this._hubBridgeId = null
+  }
+
+  /** 현재 연결된 hub link (미연결 시 null). */
+  get hubLink() {
+    return this._hubLink
+  }
+
+  /**
+   * 이 bridge 를 hub 에 연결한다 (ADR-033/059). REGISTER 핸드셰이크 완료 후
+   * 선언 채널을 구독(bridge-subscriber JOIN)하고, hub 의 BROADCAST/DIRECT 를 로컬 소켓에 전달한다.
+   *
+   * single 모드는 embedded 종단이라 hub 가 필수는 아니지만(02-architecture §3), 멀티 인스턴스
+   * fan-out 이 필요하면 single 에서도 사용 가능하다. scaffold(멀티앱/클러스터)에서 권장.
+   *
+   * @param {Object} config - MegaBridgeHubConfig (§2.1) + 구독 채널.
+   * @param {string} config.url - hub URL.
+   * @param {string} config.token - Bearer 토큰.
+   * @param {string} config.bridgeId - 운영 식별자.
+   * @param {string} [config.instanceId]
+   * @param {string[]} [config.capabilities]
+   * @param {string[]} [config.channels] - 자동 구독할 채널 목록.
+   * @param {import('../lib/mega-retry.js').MegaRetryOptions} [config.retry] - 지정 시 재연결 활성(ADR-098).
+   *   hub 재시작·drain(4503)·네트워크 단절 시 지수 백오프로 재연결하고, 성공하면 presence(채널·세션
+   *   JOIN)를 자동 재동기화한다(hub 는 절단 시점 presence 를 잃으므로).
+   * @param {import('./ws-compression.js').WsCompressionConfig} [config.compression] - Bridge↔Hub
+   *   link 압축(ADR-078 / MegaWsHubCompressionConfig). Global `wsHub.compression`
+   *   블록을 그대로 전달한다 — hub 서버와 같은 스키마. 디폴트 OFF. 잘못된 threshold/windowBits 면
+   *   즉시 throw(부팅 fail-fast).
+   * @returns {Promise<MegaHubLink>} 등록 완료된 link.
+   */
+  async connectHub(config = /** @type {any} */ ({})) {
+    const link = new MegaHubLink({
+      url: config.url,
+      token: config.token,
+      bridgeId: config.bridgeId,
+      instanceId: config.instanceId,
+      capabilities: config.capabilities,
+      retry: config.retry,
+      compression: config.compression,
+      logger: this._log,
+    })
+    this._hubLink = link
+    this._hubBridgeId = config.bridgeId
+    this._hubChannels = Array.isArray(config.channels) ? [...config.channels] : []
+    // 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))
+    // admin-kick (ADR-097 양방향 DISCONNECT): 다른 bridge 의 강제 종료 요청이 세션 소유 bridge(여기)로
+    // 라우팅되면 해당 로컬 소켓을 닫는다. 이 핸들러가 없으면 hub 가 라우팅해도 소켓이 안 닫힌다.
+    link.on(HUB_MESSAGE_TYPES.DISCONNECT, (msg) => this._handleHubDisconnect(/** @type {any} */ (msg).payload))
+    // 허브가 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()
+
+    // 채널 구독 — bridge-subscriber 세션 JOIN(zero-config 브로드캐스트 수신용) + 이미 붙어 있는 실
+    // 사용자 세션 재JOIN(예: 첫 connect 전에 클라가 연결됐을 수 있음).
+    this._resyncPresence()
+
+    // shutdown hook 누수 방지(L1) — 재연결 등으로 connectHub 가 다시 불려도 hook 은 항상 1개.
+    const hookName = `mega-hublink:${this._appName}`
+    MegaShutdown.unregister(hookName)
+    MegaShutdown.register(hookName, async () => link.close())
+    return link
+  }
+
+  /**
+   * hub presence 재동기화 — bridge-subscriber 채널 JOIN + 활성 사용자 세션 JOIN 을 모두 다시 보낸다.
+   * 최초 등록 직후와 재연결(RECONNECTED) 직후에 호출된다. hub 의 JOIN 처리는 멱등(같은 sessionId 덮어씀).
+   * @returns {void}
+   * @private
+   */
+  _resyncPresence() {
+    const link = this._hubLink
+    if (!link?.isRegistered) return
+    const bridgeId = this._hubBridgeId ?? this._appName
+    // 1) bridge-subscriber JOIN — bridge 가 채널 멤버가 되어 zero-config 브로드캐스트를 받게 한다.
+    for (const ch of this._hubChannels) {
+      link.join({
+        userId: `bridge:${bridgeId}`,
+        sessionId: `bridge:${bridgeId}#${ch}`,
+        channels: [ch],
+      })
+    }
+    // 2) 실 사용자 세션 JOIN — joinSession 으로 매핑된 활성 세션을 다시 등록(DIRECT 타겟 복구).
+    //    채널 + metadata 까지 재동기화한다(M-1) — hub 는 절단 시점 presence 를 통째로 잃으므로,
+    //    metadata 를 빠뜨리면 재연결 후 hub presence 의 메타가 silent 사라진다.
+    for (const [sessionId, conn] of this._sessionConns) {
+      if (!conn.isOpen) continue
+      link.join({
+        userId: /** @type {string} */ (conn.userId),
+        sessionId,
+        channels: conn.channels ? [...conn.channels] : [],
+        ...(conn.metadata ? { metadata: conn.metadata } : {}),
+      })
+    }
+  }
+
+  /**
+   * 실 사용자 세션을 hub presence 에 등록하고 로컬 매핑을 만든다 (OQ-010/ADR-098).
+   *
+   * 표준 패턴: WS upgrade 의 `before` 미들웨어가 인증 후 신원을 `ctx.auth` 로 싣고(ADR-091 DI),
+   * 채널의 `onConnect(sock, ctx)` 에서 `ctx.app.joinSession(sock, { userId: ctx.auth.userId, ... })`
+   * 를 호출한다. 이 매핑이 있어야 DIRECT 가 **해당 userId 세션에만** 전달된다(cross-user flood 방지,
+   * H-latent guard). 매핑 없는 연결은 DIRECT 대상에서 제외된다.
+   *
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn - onConnect 가 받은 소켓 래퍼.
+   * @param {Object} entry
+   * @param {string} entry.userId - 인증된 사용자 식별자(비어 있으면 throw).
+   * @param {string} entry.sessionId - 세션 식별자(비어 있으면 throw). 전역 유일 권장.
+   * @param {string[]} [entry.channels] - 가입 채널 목록.
+   * @param {Object} [entry.metadata] - presence 메타데이터(명시 필드만, ADR-059).
+   * @returns {this}
+   * @throws {Error} conn/userId/sessionId 누락 시 — 잘못된 매핑을 silent 통과시키지 않는다.
+   */
+  joinSession(conn, { userId, sessionId, channels = [], metadata } = /** @type {any} */ ({})) {
+    if (!conn || typeof conn.send !== 'function') {
+      throw new Error('MegaApp.joinSession: conn (MegaWsConnection) is required.')
+    }
+    if (typeof userId !== 'string' || userId.length === 0) {
+      throw new Error('MegaApp.joinSession: userId (non-empty string) is required.')
+    }
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw new Error('MegaApp.joinSession: sessionId (non-empty string) is required.')
+    }
+    const chans = Array.isArray(channels) ? [...channels] : []
+
+    // L-4: 같은 sessionId 가 다른 conn 으로 다시 join 되면(전역 유일 계약 위반) 옛 conn 을 인덱스에서
+    // 떼어 dangling 을 막는다 — 단 소켓 자체는 닫지 않는다(클라가 정리). 옛 conn 의 신원도 비워,
+    // 이후 옛 conn 의 close(_untrackWsConn)가 새 conn 이 차지한 sessionId 로 LEAVE 를 잘못 보내지
+    // 않게 한다(그대로 두면 새 세션의 hub presence 가 silent 제거됨).
+    const prior = this._sessionConns.get(sessionId)
+    if (prior && prior !== conn) {
+      this._log?.warn?.(
+        { app: this._appName, sessionId, priorUserId: prior.userId, userId },
+        'ws.joinSession duplicate sessionId — prior conn left dangling (detached, not closed)',
+      )
+      if (prior.userId !== undefined) {
+        const pset = this._userConns.get(prior.userId)
+        if (pset) {
+          pset.delete(prior)
+          if (pset.size === 0) this._userConns.delete(prior.userId)
+        }
+      }
+      if (prior.ns !== undefined) {
+        const nsset = this._wsConns.get(prior.ns)
+        if (nsset) {
+          nsset.delete(prior)
+          if (nsset.size === 0) this._wsConns.delete(prior.ns)
+        }
+      }
+      prior.userId = undefined
+      prior.sessionId = undefined
+      prior.channels = null
+    }
+
+    // 연결에 신원 부착(매핑 키). _untrackWsConn 이 close 시 이 값으로 인덱스를 정리한다.
+    conn.userId = userId
+    conn.sessionId = sessionId
+    conn.channels = new Set(chans)
+    conn.metadata = metadata // M-1: 재연결 재동기화(_resyncPresence)가 보존할 수 있게 저장.
+
+    let uset = this._userConns.get(userId)
+    if (!uset) {
+      uset = new Set()
+      this._userConns.set(userId, uset)
+    }
+    uset.add(conn)
+    this._sessionConns.set(sessionId, conn)
+
+    this._log?.debug?.({ app: this._appName, userId, sessionId, channels: chans }, 'ws.joinSession')
+    // hub presence 등록 — 등록 상태일 때만(미연결/재연결 중이면 _resyncPresence 가 나중에 복구).
+    if (this._hubLink?.isRegistered) {
+      this._hubLink.join({ userId, sessionId, channels: chans, ...(metadata ? { metadata } : {}) })
+    }
+    // NATS roster 동기화 (ADR-176) — 프레임워크가 클러스터 접속자 목록을 자동 관리한다(개발자 코드 불요).
+    // ns 는 연결의 namespace. roster:'none' 이면 로컬만 갱신한다.
+    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._log?.warn?.({ err, channel: ch, app: this._appName }, 'ws-roster add failed'),
+        )
+      }
+    }
+    return this
+  }
+
+  /**
+   * 채널 broadcast — 로컬 ns 소켓에 즉시 전달 + (hub 연결 시) 클러스터 fan-out.
+   *
+   * @param {{ ns: string, channel: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} args
+   * @returns {void}
+   * @throws {Error} message.type(string) 누락 시 — 호출부 입력 오류를 silent drop 하지 않고 즉시 알린다(L6).
+   */
+  broadcast({ ns, channel, message, exceptSessionIds }) {
+    // 입력 검증을 한곳에서(L6) — 로컬은 받고 hub 는 message.type 없이 전송하던 비대칭을 제거.
+    if (!message || typeof message.type !== 'string') {
+      throw new Error('MegaApp.broadcast: message.type (string) is required')
+    }
+    this._deliverBroadcast({ ns, channel, message, exceptSessionIds })
+    if (this._hubLink?.isRegistered) {
+      // L-7: 빈 배열도 truthy 라 `exceptSessionIds: []` 가 wire 로 새던 비대칭 제거 — 비어 있으면 생략.
+      const hasExcept = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0
+      try {
+        this._hubLink.broadcast({ ns, channel, message, ...(hasExcept ? { exceptSessionIds } : {}) })
+      } catch (err) {
+        // 로컬 전달은 이미 성공. 클러스터 fan-out 은 best-effort(at-most-once, ADR-033)이며 소켓이
+        // 닫히는 중이면 비치명적 — 재연결 시 presence 가 재동기화된다. warn 후 호출자 보호.
+        const log = /** @type {any} */ (this._log)
+        log?.warn?.({ err, ns, channel, app: this._appName }, 'app.broadcast hub fan-out failed (local delivered)')
+      }
+    }
+    // NATS 클러스터 fan-out (ADR-176, boot 자동배선). 로컬은 위에서 전달했고, 다른 인스턴스는 구독으로
+    // 받아 각자 전달한다(echo 는 instanceId 로 스킵). publish 실패는 best-effort — local 은 이미 성공.
+    if (this._wsCluster) {
+      this._wsCluster.publishBroadcast({ ns, channel, message, exceptSessionIds }).catch((err) => {
+        const log = /** @type {any} */ (this._log)
+        log?.warn?.({ err, ns, channel, app: this._appName }, 'app.broadcast nats fan-out failed (local delivered)')
+      })
+    }
+  }
+
+  /**
+   * 특정 사용자에게 직접 전송 (directToUser, ADR-035) — 로컬에서 그 userId 로 매핑된 연결에만 전달
+   * (H-latent guard) + (hub 연결 시) 클러스터 fan-out(다른 bridge 의 같은 userId 세션까지).
+   *
+   * {@link MegaWsPresence#joinSession} 으로 매핑된 연결만 대상이다 — 매핑 없는 userId 면 로컬 no-op.
+   *
+   * @param {string} userId - 대상 사용자.
+   * @param {{ type: string, payload?: Object }} message - 내부 envelope `{ type, payload }`.
+   * @returns {void}
+   * @throws {Error} userId/message.type 누락 시(broadcast 와 동일한 입력 보호, L6).
+   */
+  directToUser(userId, message) {
+    if (typeof userId !== 'string' || userId.length === 0) {
+      throw new Error('MegaApp.directToUser: userId (non-empty string) is required')
+    }
+    if (!message || typeof message.type !== 'string') {
+      throw new Error('MegaApp.directToUser: message.type (string) is required')
+    }
+    this._deliverDirect({ userId, message })
+    if (this._hubLink?.isRegistered) {
+      try {
+        this._hubLink.direct({ userId, message })
+      } catch (err) {
+        // 로컬 전달은 이미 성공. 클러스터 fan-out 은 best-effort(at-most-once, ADR-033). warn 후 보호.
+        const log = /** @type {any} */ (this._log)
+        log?.warn?.({ err, userId, app: this._appName }, 'app.directToUser hub fan-out failed (local delivered)')
+      }
+    }
+    // NATS 클러스터 direct (ADR-176) — 다른 인스턴스의 같은 userId 세션까지. echo 는 instanceId 로 스킵.
+    if (this._wsCluster) {
+      this._wsCluster.publishDirect(userId, message).catch((err) => {
+        const log = /** @type {any} */ (this._log)
+        log?.warn?.({ err, userId, app: this._appName }, 'app.directToUser nats fan-out failed (local delivered)')
+      })
+    }
+  }
+
+  /**
+   * 세션 presence 메타데이터 갱신 (METADATA, ADR-059) — 로컬 conn 에 저장 + (hub 연결 시) 전파.
+   *
+   * 로컬 conn 의 `metadata` 를 갱신해 두면 이후 재연결 시 {@link MegaWsPresence#_resyncPresence} 가 최신
+   * 메타까지 복구한다(M-1). 매핑 없는 sessionId 면 no-op(로컬 저장 없이 hub 전파만은 하지 않음 —
+   * 재연결 보존 대상이 없으므로). broadcast/directToUser 와 같은 best-effort fan-out.
+   *
+   * @param {string} sessionId - 대상 세션(joinSession 으로 매핑된 것).
+   * @param {Object} metadata - 갱신할 메타데이터(명시 필드만).
+   * @returns {this}
+   * @throws {Error} sessionId/metadata 누락 시(입력 보호, L6 와 동일 원칙).
+   */
+  updateMetadata(sessionId, metadata) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) {
+      throw new Error('MegaApp.updateMetadata: sessionId (non-empty string) is required')
+    }
+    if (!metadata || typeof metadata !== 'object') {
+      throw new Error('MegaApp.updateMetadata: metadata (object) is required')
+    }
+    const conn = this._sessionConns.get(sessionId)
+    if (!conn) {
+      // 매핑 없는 세션 — 재연결로 보존할 로컬 대상이 없으므로 no-op(다른 bridge 세션은 그쪽이 관리).
+      this._log?.debug?.({ app: this._appName, sessionId }, 'ws.updateMetadata — no local session (no-op)')
+      return this
+    }
+    conn.metadata = metadata // 재연결 재동기화가 최신 메타를 복구하도록 저장(M-1).
+    if (this._hubLink?.isRegistered) {
+      try {
+        this._hubLink.updateMetadata({ sessionId, metadata })
+      } catch (err) {
+        // hub 전파 실패는 비치명적 — 로컬 저장은 됐고 재연결 시 _resyncPresence 가 복구.
+        const log = /** @type {any} */ (this._log)
+        log?.warn?.({ err, sessionId, app: this._appName }, 'app.updateMetadata hub propagate failed (local stored)')
+      }
+    }
+    return this
+  }
+
+  /**
+   * NATS 클러스터 fan-out/roster 를 이 앱에 배선한다 (ADR-176). boot 가 `wsCluster` config 를 보고
+   * 자동 호출하므로 개발자가 직접 부를 일은 없다(테스트·고급 용도로만 공개).
+   * @param {import('./ws-cluster.js').MegaWsCluster|null} cluster
+   * @returns {this}
+   */
+  setWsCluster(cluster) {
+    this._wsCluster = cluster
+    return this
+  }
+
+  /**
+   * 해당 ns(WS 채널 경로)의 **클러스터 전역 접속자 목록**을 반환한다 (ADR-176). `wsCluster` 자동배선 +
+   * `joinSession`/disconnect 훅으로 프레임워크가 동기화하므로 개발자는 roster 코드를 짜지 않고 읽기만 한다.
+   * wsCluster 미배선(또는 roster:'none')이면 로컬 멤버만 반환한다.
+   *
+   * @param {string} ns - WS namespace(채널 경로, 예: '/ws/chat').
+   * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
+   */
+  roster(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) {
+      if (conn.ns !== ns || !conn.isOpen) continue
+      out.push({ sessionId, userId: /** @type {string} */ (conn.userId), ...(conn.metadata ? { metadata: conn.metadata } : {}) })
+    }
+    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.
+   *
+   * `exceptSessionIds` 에 든 sessionId 로 매핑된 연결은 제외한다(ADR-098). 세션 매핑이 없는
+   * 연결(zero-config·미JOIN)은 sessionId 가 없어 제외 대상에 걸리지 않으므로 그대로 받는다.
+   *
+   * @param {{ ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} payload
+   * @returns {void}
+   */
+  _deliverBroadcast({ ns, message, exceptSessionIds }) {
+    const set = this._wsConns.get(ns)
+    if (!set || !message || typeof message.type !== 'string') return
+    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
+    for (const conn of set) {
+      if (!conn.isOpen) continue
+      if (except && conn.sessionId !== undefined && except.has(conn.sessionId)) continue
+      conn.send({ type: message.type, ns, payload: message.payload })
+    }
+  }
+
+  /**
+   * direct payload 를 **해당 userId 로 매핑된 로컬 연결에만** 전달한다 (H-latent guard).
+   *
+   * 초기에는 매핑이 없어 모든 연결에 flood 됐다(cross-user 누출). {@link MegaWsPresence#joinSession}
+   * 으로 만든 `userId → 연결` 매핑을 통해 대상 사용자에게만 보낸다. 매핑이 없는 userId 면 no-op
+   * (다른 사용자에게 새지 않음).
+   *
+   * @param {{ userId: string, message: { type: string, payload?: Object } }} payload
+   * @returns {void}
+   */
+  _deliverDirect({ userId, message }) {
+    if (!message || typeof message.type !== 'string') return
+    if (typeof userId !== 'string' || userId.length === 0) return
+    const set = this._userConns.get(userId)
+    if (!set) return
+    for (const conn of set) {
+      if (conn.isOpen) conn.send({ type: message.type, payload: message.payload })
+    }
+  }
+
+  /**
+   * hub 가 라우팅한 DISCONNECT(admin-kick/재배치, ADR-097)를 처리한다 — sessionId 로 매핑된 로컬
+   * 소켓을 닫는다. `requeue` 로 두 시맨틱이 갈린다:
+   *
+   *   - `requeue: false`(기본) = **kick** — RFC 6455 `1008`(policy violation, hub Bearer 거부와 동일
+   *     코드). "돌아오지 마라" — 클라이언트는 재연결하지 않아야 한다.
+   *   - `requeue: true` = **우아한 재배치** — `4503`({@link import('./ws-upgrade.js').CLOSE_CODE_REQUEUE},
+   *     bridge↔hub drain 과 동일 규약). "세션 유지한 채 즉시 재연결하라" — HTTP 세션은 그대로이므로
+   *     재연결이 LB 를 거쳐 다른 워커에 닿아도 `before` 인증이 세션 쿠키로 자연 통과한다
+   *     (transparent re-route — 워커 drain·리밸런싱용).
+   *
+   * reason 은 WS close frame 한도(123 bytes)에 맞춰 자른다.
+   *
+   * @param {{ sessionId: string, reason?: string, requeue?: boolean }} payload
+   * @returns {void}
+   */
+  _handleHubDisconnect({ sessionId, reason, requeue } = /** @type {any} */ ({})) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return
+    const conn = this._sessionConns.get(sessionId)
+    this._log?.debug?.(
+      { sessionId, reason, requeue: requeue === true, found: Boolean(conn), app: this._appName },
+      'ws.hub disconnect received',
+    )
+    if (!conn) return // 이미 닫혔거나 다른 인스턴스로 옮겨간 세션 — hub presence 정리는 LEAVE 가 처리.
+    if (conn.isOpen) {
+      if (requeue === true) {
+        const closeReason = typeof reason === 'string' ? reason.slice(0, 123) : 'requeued — reconnect'
+        conn.close(CLOSE_CODE_REQUEUE, closeReason)
+      } else {
+        const closeReason = typeof reason === 'string' ? reason.slice(0, 123) : 'disconnected by hub'
+        conn.close(1008, closeReason)
+      }
+    }
+  }
+
+  /**
+   * 로컬 WS 연결 등록 (driveWsConnection 이 호출 — framework-internal). hub broadcast 의 local 전달 대상.
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+   * @returns {void}
+   */
+  _trackWsConn(conn) {
+    if (!conn.ns) return
+    let set = this._wsConns.get(conn.ns)
+    if (!set) {
+      set = new Set()
+      this._wsConns.set(conn.ns, set)
+    }
+    set.add(conn)
+  }
+
+  /**
+   * 로컬 WS 연결 해제 (close 시 driveWsConnection 이 호출 — framework-internal).
+   * @param {import('./ws-upgrade.js').MegaWsConnection} conn
+   * @returns {void}
+   */
+  _untrackWsConn(conn) {
+    const set = conn.ns ? this._wsConns.get(conn.ns) : undefined
+    if (set) {
+      set.delete(conn)
+      if (set.size === 0) this._wsConns.delete(conn.ns)
+    }
+    // 세션·유저 매핑 정리 + hub presence LEAVE (joinSession 으로 매핑된 연결만).
+    if (conn.userId !== undefined) {
+      const uset = this._userConns.get(conn.userId)
+      if (uset) {
+        uset.delete(conn)
+        if (uset.size === 0) this._userConns.delete(conn.userId)
+      }
+    }
+    if (conn.sessionId !== undefined) {
+      // 같은 sessionId 가 다른(새) 연결로 교체된 경우엔 이 연결만 지운다(오래된 연결의 close 가
+      // 새 매핑을 지우지 않게 동일성 확인).
+      if (this._sessionConns.get(conn.sessionId) === conn) this._sessionConns.delete(conn.sessionId)
+      if (this._hubLink?.isRegistered) {
+        try {
+          this._hubLink.leave(conn.sessionId)
+        } catch (err) {
+          // 소켓이 닫히는 중이면 LEAVE 송신 실패 — 비치명적. hub 의 bridge-gone 정리가 보강한다.
+          this._log?.debug?.({ err, sessionId: conn.sessionId, app: this._appName }, 'ws.leave send failed')
+        }
+      }
+      // 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._log?.warn?.({ err, channel: ch, app: this._appName }, 'ws-roster remove failed'),
+          )
+        }
+      }
+    }
+  }
+
+
+  /**
+   * presence 전체 정리 — hub link → NATS cluster → redis roster → 연결 인덱스 순.
+   * 각 자원의 shutdown hook 도 짝맞춰 해제한다(닫힌 앱의 hook 잔존·중복 정리 방지).
+   * MegaApp.close 가 WS 클라이언트 종료(1001) **전에** 호출한다.
+   * @returns {Promise<void>}
+   */
+  async close() {
+    // hub link 먼저 끊는다 (더 이상 fan-out 수신 불필요). shutdown hook 도 함께 떼어 누수 방지(L1).
+    if (this._hubLink) {
+      this._hubLink.close()
+      this._hubLink = null
+      this._hubBridgeId = null
+      MegaShutdown.unregister(`mega-hublink:${this._appName}`)
+    }
+    // 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._log?.warn?.({ err, app: this._appName }, 'ws-cluster stop failed'))
+      this._wsCluster = null
+      MegaShutdown.unregister(`mega-ws-cluster:${this._appName}`)
+    }
+    // redis roster 정리(ADR-177) — heartbeat 중지 + 로컬 멤버 즉시 제거. _sessionConns 를 비우기 **전에**
+    // 호출해야 stop() 이 localRosterMembers 로 자기 멤버를 redis 에서 뺄 수 있다.
+    if (this._wsRoster) {
+      await this._wsRoster.stop().catch((err) => this._log?.warn?.({ err, app: this._appName }, 'ws-roster stop failed'))
+      this._wsRoster = null
+      MegaShutdown.unregister(`mega-wsroster:${this._appName}`)
+    }
+    this._wsConns.clear()
+    this._userConns.clear()
+    this._sessionConns.clear()
+  }
+}

package/src/core/ws-roster.js

@@ -156,8 +156,11 @@ export class MegaWsRedisRoster {
     if (this._hbTimer) clearInterval(this._hbTimer)
     this._hbTimer = null
     // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리).
+    // 실패해도 종료는 계속(lazy 만료가 정리) — 단 명단에 TTL 까지 남으므로 묵히지 않고 알린다.
     for (const { channel, sessionId } of this._getLocalMembers()) {
-      await this.remove(channel, sessionId).catch(() => {})
+      await this.remove(channel, sessionId).catch((err) =>
+        this._log?.warn?.({ err, channel, sessionId }, 'ws-roster graceful remove failed (stale until TTL)'),
+      )
     }
   }
 }