mega-framework 0.1.0 → 0.1.1

package/src/core/mega-app.js

@@ -182,6 +182,8 @@ export class MegaApp {
     this._wss = 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
     /** 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>>} */
@@ -758,6 +760,11 @@ export class MegaApp {
     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 } : {}) })
+    }
     return this
   }
 
@@ -786,6 +793,14 @@ export class MegaApp {
         log?.warn?.({ err, ns, channel, app: this.name }, '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.fastify.log)
+        log?.warn?.({ err, ns, channel, app: this.name }, 'app.broadcast nats fan-out failed (local delivered)')
+      })
+    }
   }
 
   /**
@@ -816,6 +831,13 @@ export class MegaApp {
         log?.warn?.({ err, userId, app: this.name }, '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.fastify.log)
+        log?.warn?.({ err, userId, app: this.name }, 'app.directToUser nats fan-out failed (local delivered)')
+      })
+    }
   }
 
   /**
@@ -856,6 +878,37 @@ export class MegaApp {
     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)
+    // wsCluster 미배선 — joinSession 으로 매핑된 로컬 세션 중 해당 ns 만.
+    /** @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
+  }
+
   /**
    * broadcast payload 를 로컬 ns 소켓에 전달한다. message 는 `{ type, payload }` 내부 envelope.
    *
@@ -944,6 +997,8 @@ export class MegaApp {
           this.fastify.log?.debug?.({ err, sessionId: conn.sessionId, app: this.name }, 'ws.leave send failed')
         }
       }
+      // NATS roster 제거 (ADR-176) — disconnect 시 클러스터 접속자 목록에서 자동 제거(개발자 코드 불요).
+      this._wsCluster?.rosterRemove(conn.sessionId)
     }
   }
 

package/src/core/scope-registry.js

@@ -11,6 +11,7 @@ export const GLOBAL_ONLY_KEYS = Object.freeze([
   'services', // databases/caches/buses 그룹 정의
   'server', // port, cluster, sessionSecret
   'wsHub', // mega ws-hub 명령용 (ADR-068)
+  'wsCluster', // NATS 기반 WS 클러스터 broadcast/roster 자동배선 (ADR-176)
   'logger', // 전역 로거 sinks
   'apps', // 활성 앱 whitelist (ADR-066)
   'asp', // masterSecret 등 시크릿

package/src/core/ws-cluster.js

@@ -0,0 +1,352 @@
+// @ts-check
+/**
+ * MegaWsCluster — NATS 기반 WS 클러스터 fan-out + roster(접속자 목록) 동기화 (ADR-176).
+ *
+ * `app.broadcast`/`directToUser`(로컬 전달)는 단일 프로세스 안에서만 닿는다 — 클러스터(워커 N개·다중
+ * 인스턴스)에서는 다른 인스턴스에 붙은 클라에게 닿지 않는다. 본 모듈이 **프레임워크 레벨에서** NATS
+ * 버스(`services.buses.<key>`, driver:'nats')로 그 간극을 메운다. config 에 `wsCluster.bus` 가 있으면
+ * boot 가 **자동 배선**한다(ADR-176 이 ADR-137 의 "자동배선 거부"를 wsCluster 에 한해 번복) — 개발자는
+ * `connectHub` 같은 배선 코드를 쓰지 않고 `app.broadcast`/`joinSession` 만 호출하면 된다.
+ *
+ * # broadcast / direct — core NATS pub/sub
+ *   - 송신: `app.broadcast` 가 로컬 전달 후 본 클러스터의 {@link publishBroadcast} 로 NATS publish.
+ *   - 수신: 모든 인스턴스가 같은 subject 를 subscribe 하고, 도착하면 자기 로컬 연결에 전달.
+ *   - echo 회피: 각 인스턴스는 고유 `instanceId` 를 갖고 envelope 에 `o`(origin) 로 싣는다. 자기 자신이
+ *     publish 한 메시지(`o === instanceId`)는 **이미 로컬 전달했으므로** 수신 시 건너뛴다(중복 방지).
+ *
+ * # roster — 설정형(ADR-176, `wsCluster.roster.driver`)
+ *   - `'nats'`: join/leave 델타 publish + 주기 heartbeat(멤버 전체) + TTL sweep(crash 인스턴스의 stale
+ *     멤버 자동 제거) + 신규 인스턴스의 sync_request(전원 즉시 heartbeat 응답 → 빠른 수렴).
+ *   - `'none'`: 클러스터 roster 미동기화(로컬 연결만). `roster(ns)` 는 로컬 멤버만 반환.
+ *
+ * NATS 는 단일 멀티플렉스 연결이라 redis pub/sub 처럼 구독 전용 연결을 `duplicate()` 할 필요가 없다.
+ * 직렬화는 NatsAdapter 의 JSONCodec 이 표준화하므로 본 모듈은 평범한 객체만 주고받는다.
+ *
+ * @module core/ws-cluster
+ */
+
+/**
+ * roster 멤버(클러스터 공유). sessionId 는 joinSession 전역 유일 계약(ADR-098)으로 키가 된다.
+ * @typedef {Object} RosterMember
+ * @property {string} ns - WS namespace(채널 경로, 예: '/ws/chat').
+ * @property {string} sessionId - 세션 식별자(전역 유일).
+ * @property {string} userId - 사용자 식별자.
+ * @property {Object} [metadata] - presence 메타(명시 필드만).
+ */
+
+/** roster 델타 op. */
+const ROSTER_OP = Object.freeze({
+  ADD: 'add',
+  REMOVE: 'remove',
+  HEARTBEAT: 'heartbeat', // 멤버 전체 재공지(TTL 갱신).
+  SYNC_REQUEST: 'sync_request', // 신규 인스턴스가 전원에게 즉시 heartbeat 를 요청.
+})
+
+/** 기본 subject 접두. */
+const DEFAULT_SUBJECT_PREFIX = 'mega.ws'
+/** 기본 roster 멤버 TTL(ms) — heartbeat 미수신 시 stale 로 간주하고 제거. */
+const DEFAULT_ROSTER_TTL_MS = 30_000
+
+/**
+ * 짧은 랜덤 식별자(instanceId) — Math.random 기반. 인스턴스 echo 구분용이라 암호학적 강도 불필요.
+ * @returns {string}
+ */
+function randomId() {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36)
+}
+
+/**
+ * NATS 기반 WS 클러스터 fan-out + roster.
+ *
+ * 앱 1개당 1 인스턴스. boot 가 생성·start·shutdown 을 관리한다(자동 배선). subject 는 앱 이름으로
+ * 격리되어(`<prefix>.<appName>.*`) 다중 앱이 한 NATS 를 공유해도 섞이지 않는다.
+ */
+export class MegaWsCluster {
+  /**
+   * @param {Object} opts
+   * @param {import('../adapters/mega-bus-adapter.js').MegaBusAdapter} opts.bus - 연결된 NATS 버스 어댑터.
+   * @param {string} opts.appName - 앱 이름(subject 격리 + 로그).
+   * @param {(payload: { ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }) => void} opts.deliverBroadcast -
+   *   수신한 broadcast 를 로컬 연결에 전달하는 콜백(보통 `app._deliverBroadcast`).
+   * @param {(payload: { userId: string, message: { type: string, payload?: Object } }) => void} opts.deliverDirect -
+   *   수신한 direct 를 로컬 연결에 전달하는 콜백(보통 `app._deliverDirect`).
+   * @param {{ debug?: Function, info?: Function, warn?: Function, error?: Function }} [opts.logger]
+   * @param {string} [opts.subjectPrefix] - subject 접두(기본 'mega.ws').
+   * @param {{ driver?: 'nats'|'none', ttlMs?: number }} [opts.roster] - roster 동기화 설정.
+   */
+  constructor({ bus, appName, deliverBroadcast, deliverDirect, logger, subjectPrefix, roster } = /** @type {any} */ ({})) {
+    if (!bus || typeof bus.publish !== 'function' || typeof bus.subscribe !== 'function') {
+      throw new Error('MegaWsCluster: a connected NATS bus adapter (publish/subscribe) is required.')
+    }
+    if (typeof appName !== 'string' || appName.length === 0) {
+      throw new Error('MegaWsCluster: appName (non-empty string) is required.')
+    }
+    /** @type {import('../adapters/mega-bus-adapter.js').MegaBusAdapter} */
+    this._bus = bus
+    this._appName = appName
+    this._deliverBroadcast = deliverBroadcast
+    this._deliverDirect = deliverDirect
+    this._log = logger
+    /** 이 프로세스의 고유 식별자 — echo 구분. */
+    this.instanceId = randomId()
+
+    const prefix = typeof subjectPrefix === 'string' && subjectPrefix.length > 0 ? subjectPrefix : DEFAULT_SUBJECT_PREFIX
+    this._subjBroadcast = `${prefix}.${appName}.bcast`
+    this._subjDirect = `${prefix}.${appName}.direct`
+    this._subjRoster = `${prefix}.${appName}.roster`
+
+    this._rosterDriver = roster?.driver === 'nats' ? 'nats' : 'none'
+    this._rosterTtlMs = Number.isInteger(roster?.ttlMs) && /** @type {number} */ (roster?.ttlMs) > 0 ? /** @type {number} */ (roster?.ttlMs) : DEFAULT_ROSTER_TTL_MS
+
+    /** 이 인스턴스가 보유한 로컬 멤버. sessionId → RosterMember. */
+    this._localMembers = new Map()
+    /** 클러스터 전역 view. sessionId → RosterMember & { instanceId, expiresAt }. */
+    this._view = new Map()
+
+    /** @type {Array<{ unsubscribe: () => Promise<void> }>} 활성 구독 핸들. */
+    this._subs = []
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this._heartbeatTimer = null
+    /** @type {ReturnType<typeof setInterval>|null} */
+    this._sweepTimer = null
+    this._isStarted = false
+  }
+
+  /** 시작됐는지. @returns {boolean} */
+  get isStarted() {
+    return this._isStarted
+  }
+
+  /**
+   * 구독 시작 — broadcast/direct subject + (roster:'nats' 면) roster subject 를 subscribe 하고, roster
+   * 동기화 타이머(heartbeat/sweep)를 켜고, 신규 인스턴스 sync_request 를 보낸다. 멱등(중복 호출 무시).
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this._isStarted) return
+    this._isStarted = true
+
+    // broadcast 수신 — 자기 echo 는 건너뛴다(이미 로컬 전달함).
+    this._subs.push(
+      await this._bus.subscribe(this._subjBroadcast, (/** @type {any} */ env) => {
+        if (!env || env.o === this.instanceId) return
+        this._deliverBroadcast?.({ ns: env.ns, channel: env.channel, message: env.message, exceptSessionIds: env.exceptSessionIds })
+      }),
+    )
+    // direct 수신 — 자기 echo skip. 로컬에 그 userId 매핑이 없으면 deliverDirect 가 no-op.
+    this._subs.push(
+      await this._bus.subscribe(this._subjDirect, (/** @type {any} */ env) => {
+        if (!env || env.o === this.instanceId) return
+        this._deliverDirect?.({ userId: env.userId, message: env.message })
+      }),
+    )
+
+    if (this._rosterDriver === 'nats') {
+      this._subs.push(await this._bus.subscribe(this._subjRoster, (/** @type {any} */ msg) => this._onRosterMessage(msg)))
+      // crash 정리: heartbeat 로 자기 멤버를 주기 재공지, sweep 로 만료 멤버 제거.
+      this._heartbeatTimer = setInterval(() => this._publishHeartbeat(), Math.max(1000, Math.floor(this._rosterTtlMs / 2)))
+      this._sweepTimer = setInterval(() => this._sweepExpired(), this._rosterTtlMs)
+      // setInterval 이 이벤트루프를 살리지 않게 unref(프로세스 종료 차단 방지).
+      this._heartbeatTimer.unref?.()
+      this._sweepTimer.unref?.()
+      // 신규 인스턴스 — 전원에게 즉시 heartbeat 요청(빠른 수렴) + 자기 현재 멤버 공지.
+      await this._publishRoster({ op: ROSTER_OP.SYNC_REQUEST }).catch(() => {})
+      await this._publishHeartbeat()
+    }
+
+    this._log?.debug?.(
+      { app: this._appName, instanceId: this.instanceId, roster: this._rosterDriver, subjects: { b: this._subjBroadcast, d: this._subjDirect } },
+      'ws-cluster started',
+    )
+  }
+
+  /**
+   * broadcast 를 클러스터로 publish. 송신측은 이미 로컬 전달했으므로 `o`(origin)로 자기 echo 를 표시한다.
+   * @param {{ ns: string, channel?: string, message: { type: string, payload?: Object }, exceptSessionIds?: string[] }} payload
+   * @returns {Promise<void>}
+   */
+  async publishBroadcast(payload) {
+    await this._bus.publish(this._subjBroadcast, {
+      o: this.instanceId,
+      ns: payload.ns,
+      channel: payload.channel,
+      message: payload.message,
+      ...(Array.isArray(payload.exceptSessionIds) && payload.exceptSessionIds.length > 0
+        ? { exceptSessionIds: payload.exceptSessionIds }
+        : {}),
+    })
+  }
+
+  /**
+   * direct(특정 userId)를 클러스터로 publish — 다른 인스턴스의 같은 userId 세션까지 닿게 한다.
+   * @param {string} userId
+   * @param {{ type: string, payload?: Object }} message
+   * @returns {Promise<void>}
+   */
+  async publishDirect(userId, message) {
+    await this._bus.publish(this._subjDirect, { o: this.instanceId, userId, message })
+  }
+
+  /**
+   * roster 에 멤버 추가(joinSession 훅). 로컬 보유 + 전역 view 반영 + 델타 publish. roster:'none' 이면
+   * 로컬만 갱신한다.
+   * @param {RosterMember} member
+   * @returns {void}
+   */
+  rosterAdd(member) {
+    if (!member || typeof member.sessionId !== 'string' || typeof member.ns !== 'string') return
+    this._localMembers.set(member.sessionId, member)
+    if (this._rosterDriver === 'none') return
+    this._upsertView(member, this.instanceId)
+    this._publishRoster({ op: ROSTER_OP.ADD, member }).catch((err) =>
+      this._log?.warn?.({ err, app: this._appName }, 'ws-cluster roster add publish failed'),
+    )
+  }
+
+  /**
+   * roster 에서 멤버 제거(disconnect 훅). 로컬 제거 + 전역 view 제거 + 델타 publish.
+   * @param {string} sessionId
+   * @returns {void}
+   */
+  rosterRemove(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0) return
+    const had = this._localMembers.delete(sessionId)
+    if (this._rosterDriver === 'none') return
+    this._view.delete(sessionId)
+    if (!had) return // 우리 멤버가 아니면 publish 안 함(다른 인스턴스가 관리).
+    this._publishRoster({ op: ROSTER_OP.REMOVE, sessionId }).catch((err) =>
+      this._log?.warn?.({ err, app: this._appName }, 'ws-cluster roster remove publish failed'),
+    )
+  }
+
+  /**
+   * 해당 ns 의 클러스터 전역 접속자 목록. roster:'none' 이면 로컬 멤버만.
+   * @param {string} ns
+   * @returns {Array<{ sessionId: string, userId: string, metadata?: Object }>}
+   */
+  roster(ns) {
+    const src = this._rosterDriver === 'nats' ? this._view : this._localMembers
+    /** @type {Array<{ sessionId: string, userId: string, metadata?: Object }>} */
+    const out = []
+    for (const m of src.values()) {
+      if (m.ns !== ns) continue
+      out.push({ sessionId: m.sessionId, userId: m.userId, ...(m.metadata ? { metadata: m.metadata } : {}) })
+    }
+    return out
+  }
+
+  /**
+   * 정리 — 타이머 해제 + 구독 해제 + 자기 멤버 LEAVE 공지(graceful 종료 시 다른 인스턴스 roster 즉시 정리).
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    if (!this._isStarted) return
+    this._isStarted = false
+    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer)
+    if (this._sweepTimer) clearInterval(this._sweepTimer)
+    this._heartbeatTimer = null
+    this._sweepTimer = null
+    // graceful: 자기 멤버를 LEAVE 로 공지(crash 가 아닌 정상 종료라 즉시 정리되게).
+    if (this._rosterDriver === 'nats' && this._localMembers.size > 0) {
+      for (const sessionId of this._localMembers.keys()) {
+        await this._publishRoster({ op: ROSTER_OP.REMOVE, sessionId }).catch(() => {})
+      }
+    }
+    for (const sub of this._subs) {
+      await sub.unsubscribe().catch(() => {})
+    }
+    this._subs = []
+    this._localMembers.clear()
+    this._view.clear()
+    this._log?.debug?.({ app: this._appName, instanceId: this.instanceId }, 'ws-cluster stopped')
+  }
+
+  // ── 내부 ───────────────────────────────────────────────────────────────────
+
+  /**
+   * roster subject 수신 처리. 자기 echo 는 건너뛰되, sync_request 만은 자기 요청이어도 무관(상대가 응답).
+   * @param {any} msg
+   * @returns {void}
+   * @private
+   */
+  _onRosterMessage(msg) {
+    if (!msg || typeof msg.op !== 'string') return
+    // 다른 인스턴스의 sync_request → 우리 멤버를 즉시 heartbeat 로 응답.
+    if (msg.op === ROSTER_OP.SYNC_REQUEST) {
+      if (msg.o !== this.instanceId) this._publishHeartbeat().catch(() => {})
+      return
+    }
+    if (msg.o === this.instanceId) return // 자기 add/remove/heartbeat echo — 로컬에서 이미 반영.
+    switch (msg.op) {
+      case ROSTER_OP.ADD:
+        if (msg.member) this._upsertView(msg.member, msg.o)
+        break
+      case ROSTER_OP.REMOVE:
+        if (typeof msg.sessionId === 'string') this._view.delete(msg.sessionId)
+        break
+      case ROSTER_OP.HEARTBEAT:
+        if (Array.isArray(msg.members)) for (const m of msg.members) this._upsertView(m, msg.o)
+        break
+      default:
+        // 알 수 없는 op 는 무시하되 로그(silent 금지) — 프로토콜 진화 시 디버깅 단서.
+        this._log?.debug?.({ app: this._appName, op: msg.op }, 'ws-cluster roster unknown op (ignored)')
+    }
+  }
+
+  /**
+   * view 에 멤버 upsert + 만료시각 갱신. 멤버 출처 instanceId 를 함께 저장(sweep 판단·자기멤버 구분).
+   * @param {RosterMember} member @param {string} instanceId @returns {void}
+   * @private
+   */
+  _upsertView(member, instanceId) {
+    if (!member || typeof member.sessionId !== 'string' || typeof member.ns !== 'string') return
+    this._view.set(member.sessionId, {
+      ns: member.ns,
+      sessionId: member.sessionId,
+      userId: member.userId,
+      ...(member.metadata ? { metadata: member.metadata } : {}),
+      instanceId,
+      expiresAt: Date.now() + this._rosterTtlMs,
+    })
+  }
+
+  /**
+   * 만료(heartbeat 끊긴 crash 인스턴스) 멤버를 view 에서 제거. 자기 멤버는 항상 fresh 하므로 영향 없음.
+   * @returns {void}
+   * @private
+   */
+  _sweepExpired() {
+    const now = Date.now()
+    let removed = 0
+    for (const [sessionId, m] of this._view) {
+      if (m.instanceId !== this.instanceId && m.expiresAt < now) {
+        this._view.delete(sessionId)
+        removed++
+      }
+    }
+    if (removed > 0) this._log?.debug?.({ app: this._appName, removed }, 'ws-cluster roster swept stale members')
+  }
+
+  /**
+   * 자기 로컬 멤버 전체를 heartbeat 로 공지(다른 인스턴스의 TTL 갱신) + 자기 view 도 fresh 유지.
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _publishHeartbeat() {
+    if (this._rosterDriver !== 'nats') return
+    const members = [...this._localMembers.values()]
+    for (const m of members) this._upsertView(m, this.instanceId) // 자기 멤버 만료시각 갱신.
+    await this._publishRoster({ op: ROSTER_OP.HEARTBEAT, members }).catch((err) =>
+      this._log?.warn?.({ err, app: this._appName }, 'ws-cluster roster heartbeat publish failed'),
+    )
+  }
+
+  /**
+   * roster subject 로 메시지 publish(자기 instanceId 를 origin 으로).
+   * @param {Object} body @returns {Promise<void>}
+   * @private
+   */
+  async _publishRoster(body) {
+    await this._bus.publish(this._subjRoster, { o: this.instanceId, ...body })
+  }
+}

package/src/core/ws-upgrade.js

@@ -166,6 +166,34 @@ export class MegaWsConnection {
   }
 }
 
+/**
+ * `ctx.presence` — 채널 핸들러용 presence 단축 API (ADR-176). ns·conn 을 미리 바인딩해, 채널이
+ * `ctx.presence.list()` / `.join({...})` / `.broadcast({...})` / `.directToUser(...)` 로 클러스터 presence 를
+ * 다룬다. roster 동기화·클러스터 fan-out 은 프레임워크(wsCluster, NATS)가 처리하므로 채널은 비즈니스
+ * 로직만 작성한다(개발자가 redis/배선 코드를 쓰지 않는다). mock app(단위 테스트)·ns 부재면 null.
+ *
+ * @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}
+ */
+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),
+    /** 연결을 신원에 매핑 — `{ userId, sessionId, channels?, metadata? }`. roster 등록이 자동으로 따라온다. */
+    join: (entry) => {
+      a.joinSession(conn, entry)
+    },
+    /** 특정 userId 에게 직접 전송(클러스터 전역, joinSession 매핑된 세션만). */
+    directToUser: (userId, message) => a.directToUser(userId, message),
+    /** 이 채널 ns 전체 broadcast(클러스터 전역) — `{ channel?, message, exceptSessionIds? }`. */
+    broadcast: (args) => a.broadcast({ ns, ...args }),
+  }
+}
+
 /**
  * 핸드셰이크 완료된 raw 소켓에 채널 라이프사이클을 구동한다.
  *
@@ -204,6 +232,9 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
     req,
     connId: conn.id,
     tracer: MegaTracing.tracer, // ctx.tracer.span(name, fn) — WS 핸들러에서도 사용자 직접 span(ADR-126).
+    // presence 단축 API (ADR-176) — list(클러스터 roster)/join/directToUser/broadcast 를 ns·conn 바인딩으로
+    // 노출. 클러스터 동기화는 wsCluster 가 처리하므로 채널은 비즈니스 로직만 쓴다. mock app 이면 null.
+    presence: buildWsPresence(app, conn, route.ns),
     ...(app?.adapterAccessors ?? {}),
   }
   channel._bind({ ctx, app, log, services: null })

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

@@ -1,115 +0,0 @@
-// @ts-check
-/**
- * chat-bus.js — redis pub/sub 기반 cluster-wide 채팅 broadcast (ADR-158).
- *
- * `app.broadcast`(로컬 ns fan-out)는 단일 프로세스 안에서만 전달된다 — 클러스터(워커 N개)에선 다른
- * 워커에 붙은 클라에게 닿지 않는다. hub 프로세스 없이 cluster-wide 전파를 하기 위해 redis pub/sub 를 쓴다:
- *   - 송신: 메시지를 redis 채널(`ws:chat:bcast`)에 **PUBLISH** 만 한다(로컬 직접 전달 안 함).
- *   - 수신: **워커마다** 전용 구독 연결(ioredis `duplicate()`)이 그 채널을 **SUBSCRIBE** 하고, 도착한
- *     메시지를 자기 워커의 로컬 연결들에 전달한다.
- * 결과: PUBLISH 1건 → 모든 워커의 구독자가 받아 각자 로컬 전달 → 전 클러스터 클라가 정확히 1회씩 수신
- * (송신자 본인 워커도 구독자 경로로 전달받아 echo). 구독 연결은 명령 전용 연결과 분리해야 하므로
- * (subscribe 모드 연결은 일반 명령 불가) `demo` 캐시의 raw ioredis 를 `duplicate()` 한다.
- *
- * 접속자 명단(roster)도 cluster-wide 다 — redis HASH(`ws:chat:roster`, field=sessionId→userName)에 두어
- * 어느 워커에서든 같은 명단·인원수를 본다(INCR/DECR 카운터의 비정상종료 드리프트 회피, 명단까지 공유).
- *
- * @module channels/chat-bus
- */
-import { MegaShutdown } from 'mega-framework'
-
-/** cluster-wide 전파 채널(redis pub/sub 은 db 와 무관한 글로벌 네임스페이스). */
-export const BCAST_CHANNEL = 'ws:chat:bcast'
-/** 접속자 명단 HASH 키 — field=sessionId, value=userName. */
-export const ROSTER_KEY = 'ws:chat:roster'
-
-/** 이 워커의 로컬 연결 레지스트리. sock → { sessionId, userName }. */
-const localConns = new Map()
-/** 이 워커의 전용 구독 연결(1개, lazy). */
-let subscriber = null
-
-/**
- * 이 워커의 구독자를 1회 보장한다(첫 연결 시). 채널 SUBSCRIBE + 메시지 → 로컬 전달 + graceful 종료 hook.
- *
- * @param {any} app - MegaApp(로깅용).
- * @param {import('ioredis').Redis} redisNative - `demo` 캐시의 raw ioredis(여기서 duplicate).
- * @returns {void}
- */
-export function ensureSubscriber(app, redisNative) {
-  if (subscriber) return
-  const log = app?.fastify?.log
-  subscriber = redisNative.duplicate()
-  subscriber.on('message', (/** @type {string} */ _channel, /** @type {string} */ raw) => {
-    let env
-    try {
-      env = JSON.parse(raw)
-    } catch (err) {
-      // 손상 페이로드는 전달하지 않는다(사유 명시 + 로그, silent 금지).
-      log?.warn?.({ err }, 'chat-bus subscribe payload parse failed')
-      return
-    }
-    deliverLocal(env)
-  })
-  subscriber.on('error', (/** @type {Error} */ err) => {
-    // 구독 연결 오류는 비치명적(ioredis 가 재연결) — 로그만.
-    log?.warn?.({ err }, 'chat-bus subscriber connection error')
-  })
-  // subscribe 실패는 전파 자체가 죽는 심각한 신호 — 로그 + throw(fail-closed, silent 금지).
-  subscriber.subscribe(BCAST_CHANNEL).catch((err) => {
-    log?.error?.({ err, channel: BCAST_CHANNEL }, 'chat-bus subscribe failed')
-    throw err
-  })
-  // 워커 graceful 종료 시 구독 연결 정리(이벤트루프 누수 방지).
-  MegaShutdown.register('sample-chat-bus', async () => {
-    const s = subscriber
-    subscriber = null
-    localConns.clear()
-    if (s) await s.quit().catch(() => {})
-  })
-}
-
-/**
- * 구독으로 받은 메시지를 이 워커의 로컬 연결에 전달한다. exceptSessionIds 에 든 세션은 건너뛴다.
- * @param {{ message: { type: string, payload?: object }, exceptSessionIds?: string[] }} env
- * @returns {void}
- */
-function deliverLocal({ message, exceptSessionIds }) {
-  if (!message || typeof message.type !== 'string') return
-  const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
-  for (const [sock, meta] of localConns) {
-    if (!sock.isOpen) continue
-    if (except && except.has(meta.sessionId)) continue
-    sock.send({ type: message.type, payload: message.payload })
-  }
-}
-
-/**
- * 로컬 연결 등록(onConnect). @param {any} sock @param {{ sessionId: string, userName: string }} meta
- * @returns {void}
- */
-export function registerConn(sock, meta) {
-  localConns.set(sock, meta)
-}
-
-/** 로컬 연결 해제(onDisconnect). @param {any} sock @returns {void} */
-export function unregisterConn(sock) {
-  localConns.delete(sock)
-}
-
-/**
- * cluster-wide 전파 — redis 채널에 PUBLISH(모든 워커 구독자가 받아 로컬 전달).
- * @param {import('ioredis').Redis} redisNative
- * @param {{ message: { type: string, payload?: object }, exceptSessionIds?: string[] }} env
- * @returns {Promise<void>}
- */
-export async function publish(redisNative, env) {
-  await redisNative.publish(BCAST_CHANNEL, JSON.stringify(env))
-}
-
-/** 테스트 정리용 — 구독 연결 종료 + 레지스트리 초기화. @returns {Promise<void>} */
-export async function closeChatBus() {
-  const s = subscriber
-  subscriber = null
-  localConns.clear()
-  if (s) await s.quit().catch(() => {})
-}