mega-framework 0.1.0 → 0.1.2

package/src/core/boot.js

@@ -49,6 +49,7 @@ import { MegaShutdown } from '../lib/mega-shutdown.js'
 import { buildLogger } from '../lib/mega-logger.js'
 import { buildFromGlobalConfig, connectAll, get as getAdapter, entries as adapterEntries } from '../adapters/adapter-manager.js'
 import { buildWorkers, startAll as startWorkers, contextProxy as workersContext } from './workers-manager.js'
+import { MegaWsCluster } from './ws-cluster.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
 import { MegaWsHub } from '../cli/ws-hub.js'
@@ -293,6 +294,47 @@ export async function bootApp(projectRoot, { listen = true, port, host: listenHo
     megaApps.push(app)
   }
 
+  // 클러스터 전송 자동배선 (ADR-176) — 앱당 **하나**(상호배타, config-validator 가 충돌 fail-fast). config 로 선택:
+  //   - app.config `bridgeHub` → **WS Hub**(`app.connectHub`, 평문 12-타입). `mega ws-hub` 서버에 자동 연결.
+  //   - global `wsCluster.bus`(NATS) → **MegaWsCluster**(NATS pub/sub broadcast + roster 동기화).
+  // 둘 다 개발자가 connectHub 같은 코드를 쓰지 않고 config 만으로 동작한다(ADR-176 이 ADR-137 의 자동배선
+  // 거부를 **명시 config 가 있을 때만** 번복 — 설정이 곧 의도라 "추측 배선" 아님). megaApps[i] 와 apps[i] 동순서.
+  const wsClusterCfg = /** @type {any} */ (global).wsCluster
+  const wsClusterBus = wsClusterCfg?.bus ? getAdapter('bus', wsClusterCfg.bus) : null
+  for (let i = 0; i < megaApps.length; i++) {
+    const app = megaApps[i]
+    const a = /** @type {any} */ (app) // _deliverBroadcast/_deliverDirect 는 framework-internal(@private).
+    const bridgeHub = /** @type {any} */ (apps[i].config).bridgeHub
+    if (bridgeHub?.url) {
+      // 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)')
+      } catch (err) {
+        logger?.warn?.({ err, app: app.name, url: bridgeHub.url }, 'boot.bridgeHub initial connect failed (retry if configured)')
+      }
+    } else if (wsClusterBus) {
+      const cluster = new MegaWsCluster({
+        bus: /** @type {any} */ (wsClusterBus),
+        appName: app.name,
+        deliverBroadcast: (/** @type {any} */ p) => a._deliverBroadcast(p),
+        deliverDirect: (/** @type {any} */ p) => a._deliverDirect(p),
+        subjectPrefix: wsClusterCfg.subjectPrefix,
+        roster: wsClusterCfg.roster,
+        logger: /** @type {any} */ (app.fastify.log),
+      })
+      await cluster.start()
+      app.setWsCluster(cluster)
+      // MegaShutdown LIFO — 어댑터 disconnect 보다 먼저 정리(graceful LEAVE 가 NATS 끊기기 전에 나가게).
+      MegaShutdown.register(`mega-ws-cluster:${app.name}`, async () => cluster.stop())
+    }
+  }
+  if (wsClusterBus) {
+    logger?.debug?.({ bus: wsClusterCfg.bus, roster: wsClusterCfg.roster?.driver ?? 'none' }, 'boot.wsCluster wired (ADR-176)')
+  }
+
   // 9단계: HTTP listen(분기 — CLI/테스트가 listen=false 로 mount 까지만 받을 수 있음).
   if (listen) {
     await server.listen({ port: resolvedPort, host: resolvedHost })

package/src/core/config-validator.js

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

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 })