mega-framework 0.1.0

package/src/cli/ws-hub.js

@@ -0,0 +1,582 @@
+// @ts-check
+/**
+ * MegaWsHub — `mega ws-hub` 독립 프로세스의 본 hub (ADR-032/033/059).
+ *
+ * bridge(=mega server)들이 **plaintext + Bearer** WebSocket 으로 붙어 12-타입 프로토콜
+ * (lib/hub-protocol.js)을 주고받는 hub. hub 는 presence(어떤 세션이 어느 bridge·채널에 있는지)를
+ * 들고, JOIN/LEAVE 를 클러스터 전 bridge 에 fan-out 하고, BROADCAST/DIRECT 를 가입 bridge 로
+ * 라우팅한다(ADR-034 namespace=채널, ADR-035 directToUser).
+ *
+ * # 인증 (ADR-059)
+ *   hub link 는 ASP 를 쓰지 않는다. bridge 는 핸드셰이크 Authorization 헤더와 `hub.register`
+ *   payload 양쪽에 Bearer 토큰을 싣고, hub 는 REGISTER payload 의 token 을 `acceptedTokens` 와
+ *   **timing-safe 비교**(`crypto.timingSafeEqual`)한다. 불일치 → `hub.error`(hub.unauthorized) + close.
+ *
+ * # 데이터 보장 = at-most-once (ADR-033)
+ *   in-memory 라우팅이라 절단 시점 메시지 손실 가능. 영속 큐는 코어 미포함(OQ-013).
+ *
+ * # 본 Step 범위
+ *   12-타입 프로토콜 + Bearer + heartbeat + presence + broadcast/direct fan-out. drain(4503)·
+ *   재연결 backoff 지원(05-roadmap).
+ *
+ * # 변경 이력
+ *   ADR-094 의 ASP echo 데모 hub 를 본 12-타입 hub 로 교체(ADR-097). 클라↔bridge ASP
+ *   round-trip 검증은 embedded 종단(`core/ws-upgrade.js`, ws-upgrade.integration)으로 이전됨.
+ *
+ * @module cli/ws-hub
+ */
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { WebSocketServer } from 'ws'
+import { generateMessageId } from '../core/ws-message.js'
+import { buildPerMessageDeflate, COMPRESSION_DEFAULTS } from '../core/ws-compression.js'
+import {
+  HUB_MESSAGE_TYPES,
+  HUB_CLOSE_CODES,
+  createHubMessage,
+  validateHubMessage,
+} from '../lib/hub-protocol.js'
+import { MegaShutdown } from '../lib/mega-shutdown.js'
+
+const T = HUB_MESSAGE_TYPES
+
+/** 기본 heartbeat 주기 (ms, 04-data-models MegaWsHubConfig.heartbeatMs 기본값). */
+export const DEFAULT_HEARTBEAT_MS = 25_000
+
+/** 기본 최대 프레임 크기 (bytes, L3). 1 MiB — 정상 envelope 은 수 KB 이므로 넉넉하다. */
+export const DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576
+
+/**
+ * 토큰 timing-safe 비교 — sha256 으로 길이 정규화 후 `timingSafeEqual`. 후보 전체를 순회하여
+ * 조기 반환 timing 누출도 줄인다(early-return 안 함).
+ * @param {string} token - 검사 대상.
+ * @param {string[]} acceptedTokens - 화이트리스트.
+ * @returns {boolean}
+ */
+function isTokenAccepted(token, acceptedTokens) {
+  const h = createHash('sha256').update(String(token)).digest()
+  let ok = false
+  for (const accepted of acceptedTokens) {
+    const ah = createHash('sha256').update(String(accepted)).digest()
+    if (timingSafeEqual(h, ah)) ok = true
+  }
+  return ok
+}
+
+export class MegaWsHub {
+  /**
+   * @param {Object} [opts]
+   * @param {string[]} [opts.acceptedTokens] - Bridge Bearer 토큰 화이트리스트 (비거나 누락 시 throw).
+   * @param {number} [opts.heartbeatMs=25000] - register_ok 로 알려줄 heartbeat 주기.
+   * @param {number} [opts.maxPayloadBytes=1048576] - WS 프레임 최대 크기(L3). 초과 시 ws 가 1009 close.
+   * @param {string} [opts.hubId] - hub 식별자. 기본 ULID 자동 생성.
+   * @param {import('../core/ws-compression.js').WsCompressionConfig} [opts.compression] - Bridge↔Hub
+   *   link per-message deflate 압축(ADR-078 / wsHub.compression). 디폴트 OFF.
+   *   bridge(MegaHubLink)와 양쪽이 협상해야 활성. 잘못된 threshold/windowBits 면 즉시 throw.
+   * @param {{ warn?: Function, debug?: Function, info?: Function, error?: Function }} [opts.logger]
+   */
+  constructor({ acceptedTokens, heartbeatMs = DEFAULT_HEARTBEAT_MS, maxPayloadBytes = DEFAULT_MAX_PAYLOAD_BYTES, hubId, compression, logger } = {}) {
+    if (!Array.isArray(acceptedTokens) || acceptedTokens.length === 0) {
+      throw new Error('MegaWsHub: acceptedTokens must be a non-empty array (ADR-059).')
+    }
+    this._acceptedTokens = [...acceptedTokens]
+    this._heartbeatMs = Number.isInteger(heartbeatMs) && heartbeatMs > 0 ? heartbeatMs : DEFAULT_HEARTBEAT_MS
+    this._maxPayloadBytes = Number.isInteger(maxPayloadBytes) && maxPayloadBytes > 0 ? maxPayloadBytes : DEFAULT_MAX_PAYLOAD_BYTES
+    this._hubId = typeof hubId === 'string' && hubId.length > 0 ? hubId : `hub-${generateMessageId()}`
+    // Bridge↔Hub link 압축(ADR-078). enabled=false → false. 잘못된 값은 생성자에서 즉시 throw.
+    /** @type {false | Object} WebSocketServer perMessageDeflate 로 전달(start). */
+    this._perMessageDeflate = buildPerMessageDeflate(compression, 'wsHub.compression')
+    this._log = logger ?? null
+
+    /** @type {WebSocketServer | null} */
+    this._wss = null
+    /** heartbeat liveness 체크 interval (M3). @type {ReturnType<typeof setInterval> | null} */
+    this._livenessTimer = null
+    /** 등록된 bridge 연결. connId → { socket, lastSeen }. @type {Map<string, { socket: import('ws').WebSocket, lastSeen: number }>} */
+    this._bridges = new Map()
+    /** presence. sessionId → { bridgeConnId, userId, channels:Set, metadata }. @type {Map<string, { bridgeConnId: string, userId: string, channels: Set<string>, metadata: Object }>} */
+    this._sessions = new Map()
+    /** channel → sessionId 집합. @type {Map<string, Set<string>>} */
+    this._channelSessions = new Map()
+    /** userId → sessionId 집합 (DIRECT fan-out, ADR-035). @type {Map<string, Set<string>>} */
+    this._userSessions = new Map()
+  }
+
+  /** hub 식별자. */
+  get hubId() {
+    return this._hubId
+  }
+
+  /** 등록된 bridge 수 (테스트/관측용). */
+  get bridgeCount() {
+    return this._bridges.size
+  }
+
+  /** 현재 presence 세션 수 (테스트/관측용). */
+  get sessionCount() {
+    return this._sessions.size
+  }
+
+  /**
+   * hub 시작.
+   * @param {{ port?: number, host?: string }} [opts]
+   * @returns {Promise<{ port: number, host: string }>} 실제 바인딩 주소.
+   */
+  async start({ port = 0, host = '127.0.0.1' } = {}) {
+    const wss = new WebSocketServer({ host, port, maxPayload: this._maxPayloadBytes, perMessageDeflate: this._perMessageDeflate })
+    this._wss = wss
+    wss.on('connection', (socket, req) => this._onConnection(socket, req))
+    await new Promise((resolve, reject) => {
+      const onErr = (/** @type {Error} */ err) => reject(err)
+      wss.once('error', onErr)
+      wss.once('listening', () => {
+        wss.removeListener('error', onErr)
+        resolve(undefined)
+      })
+    })
+    // heartbeat liveness 감시 시작(M3) — heartbeatMs 주기로 stale bridge 를 terminate.
+    // unref 로 프로세스 종료를 막지 않는다(테스트/CLI 모두 안전).
+    this._livenessTimer = setInterval(() => this._checkLiveness(), this._heartbeatMs)
+    this._livenessTimer.unref?.()
+    const addr = /** @type {import('node:net').AddressInfo | string | null} */ (wss.address())
+    return typeof addr === 'object' && addr ? { port: addr.port, host: addr.address } : { port, host }
+  }
+
+  /** 현재 바인딩 주소 (테스트용). */
+  address() {
+    const addr = /** @type {import('node:net').AddressInfo | string | null} */ (this._wss?.address() ?? null)
+    return typeof addr === 'object' && addr ? { port: addr.port, host: addr.address } : null
+  }
+
+  /**
+   * 연결 1건 처리. register 전엔 hub.register 만 허용. 인증 통과 시 presence 라우팅 활성.
+   * @param {import('ws').WebSocket} socket
+   * @param {import('node:http').IncomingMessage} _req
+   * @private
+   */
+  _onConnection(socket, _req) {
+    const connId = generateMessageId()
+    let isRegistered = false
+    this._log?.debug?.({ connId }, 'ws-hub connection (awaiting register)')
+
+    socket.on('message', (raw) => {
+      const frame = Array.isArray(raw) ? Buffer.concat(raw).toString('utf8') : raw.toString('utf8')
+      let msg
+      try {
+        msg = JSON.parse(frame)
+      } catch (err) {
+        // 평문이 JSON 아님 = 규약 위반. fail-closed hub.error(연결 유지, 비치명적) + 로그.
+        this._log?.warn?.({ err, connId }, 'ws-hub non-json frame')
+        this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.invalid_message', message: 'frame is not valid JSON' } }))
+        return
+      }
+      const errors = validateHubMessage(msg)
+      if (errors.length > 0) {
+        this._log?.warn?.({ connId, errors }, 'ws-hub invalid hub message')
+        this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.invalid_message', message: 'hub protocol violation', details: errors }, ref: typeof msg?.id === 'string' ? msg.id : undefined }))
+        return
+      }
+
+      if (!isRegistered) {
+        if (msg.type !== T.REGISTER) {
+          // register 전 다른 타입 = 규약 위반. fail-closed.
+          this._log?.warn?.({ connId, type: msg.type }, 'ws-hub message before register')
+          this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.not_registered', message: 'REGISTER must be the first message' }, ref: msg.id }))
+          return
+        }
+        isRegistered = this._handleRegister(connId, socket, msg)
+        return
+      }
+      this._route(connId, socket, msg)
+    })
+
+    socket.on('close', () => {
+      if (isRegistered) this._handleBridgeGone(connId)
+      this._log?.debug?.({ connId }, 'ws-hub connection closed')
+    })
+
+    socket.on('error', (err) => {
+      // 소켓 레벨 에러 — 비치명적, close 가 뒤따른다. 로그만.
+      this._log?.warn?.({ err, connId }, 'ws-hub socket error')
+    })
+  }
+
+  /**
+   * hub.register 처리 — Bearer 검증(timing-safe). 성공 시 bridge 등록 + register_ok.
+   * @param {string} connId
+   * @param {import('ws').WebSocket} socket
+   * @param {Object} msg - 검증된 hub.register envelope.
+   * @returns {boolean} 등록 성공 여부(연결의 isRegistered 갱신용).
+   * @private
+   */
+  _handleRegister(connId, socket, msg) {
+    const payload = /** @type {{ instanceId: string, token: string, capabilities: string[] }} */ (/** @type {any} */ (msg).payload)
+    if (!isTokenAccepted(payload.token, this._acceptedTokens)) {
+      this._log?.warn?.({ connId, instanceId: payload.instanceId }, 'ws-hub register denied — bad token (ADR-059)')
+      this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.unauthorized', message: 'invalid bridge token' }, ref: /** @type {any} */ (msg).id }))
+      socket.close(1008, 'unauthorized') // RFC 6455 1008 = policy violation
+      return false
+    }
+    this._bridges.set(connId, { socket, lastSeen: Date.now() })
+    this._log?.info?.({ connId, instanceId: payload.instanceId, hubId: this._hubId }, 'ws-hub bridge registered')
+    this._safeSend(socket, createHubMessage({ type: T.REGISTER_OK, payload: { hubId: this._hubId, acceptedAt: Date.now(), heartbeatMs: this._heartbeatMs } }))
+    return true
+  }
+
+  /**
+   * 등록된 bridge 의 수신 메시지 라우팅 (12-타입).
+   * @param {string} connId
+   * @param {import('ws').WebSocket} socket
+   * @param {Object} msg - 검증된 hub 메시지.
+   * @returns {void}
+   * @private
+   */
+  _route(connId, socket, msg) {
+    const type = /** @type {any} */ (msg).type
+    const payload = /** @type {any} */ (msg).payload
+    switch (type) {
+      case T.JOIN:
+        this._addSession(connId, payload)
+        // 클러스터 presence 공유 — 다른 모든 bridge 에 같은 JOIN fan-out (07 §2).
+        this._fanOutToOthers(connId, msg)
+        break
+      case T.LEAVE: {
+        const removed = this._removeSession(payload.sessionId)
+        if (removed) this._fanOutToOthers(connId, msg)
+        break
+      }
+      case T.BULK_LEAVE: {
+        const any = payload.sessionIds.map((/** @type {string} */ sid) => this._removeSession(sid)).some(Boolean)
+        if (any) this._fanOutToOthers(connId, msg)
+        break
+      }
+      case T.BROADCAST:
+        // 채널 가입 bridge 들에 fan-out (origin 제외 — origin 은 local 직접 전달). exceptSessionIds 가
+        // 있으면 그 세션은 fan-out 대상에서 빠진다(ADR-098). 제외 세션만 가진 bridge 는
+        // 통째로 스킵되고, 그 외엔 bridge 가 받아 로컬에서 해당 세션을 건너뛴다.
+        this._fanOutChannel(payload.channel, connId, msg, payload.exceptSessionIds)
+        break
+      case T.DIRECT:
+        // userId 의 세션을 가진 bridge 들에 fan-out (ADR-035). origin 제외 — origin 은 local 직접 전달(L7).
+        this._fanOutUser(payload.userId, msg, connId)
+        break
+      case T.METADATA: {
+        const session = this._sessions.get(payload.sessionId)
+        if (session) {
+          session.metadata = payload.metadata
+          this._fanOutToOthers(connId, msg) // presence 메타 동기화
+        }
+        break
+      }
+      case T.DISCONNECT: {
+        // DISCONNECT 는 양방향(M2, ADR-097): bridge A 가 보낸 강제 종료 요청을 hub 가 세션 소유
+        // bridge B 로 라우팅한다(admin-kick: bridge A → hub → owner bridge B). mesh 환경 필수.
+        const session = this._sessions.get(payload.sessionId)
+        if (session) this._sendTo(session.bridgeConnId, JSON.stringify(msg))
+        break
+      }
+      case T.HEARTBEAT: {
+        // application-level keepalive — lastSeen 갱신(M3 liveness) 후 응답 heartbeat 회신.
+        const bridge = this._bridges.get(connId)
+        if (bridge) bridge.lastSeen = Date.now()
+        this._safeSend(socket, createHubMessage({ type: T.HEARTBEAT, payload: { at: Date.now(), pendingDeliveries: 0 } }))
+        break
+      }
+      case T.BINARY:
+        // 본 Step 은 envelope 검증까지 — raw bytes 후속 프레임 라우팅은 후속(05-roadmap). 수락 로그만.
+        this._log?.debug?.({ connId, ref: payload.ref }, 'ws-hub binary meta accepted (raw-frame routing deferred)')
+        break
+      case T.ERROR:
+        this._log?.warn?.({ connId, code: /** @type {any} */ (msg).error?.code }, 'ws-hub received error from bridge')
+        break
+      default:
+        // REGISTER(중복) / REGISTER_OK 등 hub→bridge 전용 타입을 bridge 가 보냄 = 규약 위반.
+        this._log?.warn?.({ connId, type }, 'ws-hub unexpected type from bridge')
+        this._safeSend(socket, createHubMessage({ type: T.ERROR, error: { code: 'hub.unexpected_type', message: `type '${type}' is not bridge→hub` }, ref: /** @type {any} */ (msg).id }))
+    }
+  }
+
+  /**
+   * presence 에 세션 추가.
+   *
+   * sessionId 가 이미 존재하면(같은 세션 재JOIN, 또는 채널 변경) 먼저 옛 매핑을 정리한 뒤 재삽입한다
+   * — 그러지 않으면 옛 채널 인덱스(`_channelSessions`)에 stale 엔트리가 남는다(채널이 바뀐 경우).
+   * 옛 매핑이 **다른 bridge** 소속이면 "sessionId 전역 유일" 계약(ADR-059) 위반이므로 warn 로그를 남기고
+   * last-writer 로 재배정한다 — silent 덮어쓰기 금지(L-3). 이렇게 하면 옛 bridge 의 채널 인덱스가
+   * 제거되어, 옛 bridge 의 `_handleBridgeGone` 이 재배정된 세션을 잘못 지우는 일도 없어진다.
+   *
+   * @param {string} connId
+   * @param {{ userId: string, sessionId: string, channels: string[], metadata?: Object }} entry
+   * @private
+   */
+  _addSession(connId, entry) {
+    const existing = this._sessions.get(entry.sessionId)
+    if (existing) {
+      if (existing.bridgeConnId !== connId) {
+        this._log?.warn?.(
+          { sessionId: entry.sessionId, oldBridge: existing.bridgeConnId, newBridge: connId },
+          'ws-hub duplicate sessionId across bridges — reassigning (global-unique contract violated, L-3)',
+        )
+      }
+      // 옛 채널/유저 인덱스 제거 후 재삽입(같은 bridge 의 채널 변경 stale 방지 + 다른 bridge 재배정 정리).
+      this._removeSession(entry.sessionId)
+    }
+    const channels = new Set(entry.channels)
+    this._sessions.set(entry.sessionId, {
+      bridgeConnId: connId,
+      userId: entry.userId,
+      channels,
+      metadata: entry.metadata ?? {},
+    })
+    for (const ch of channels) {
+      let set = this._channelSessions.get(ch)
+      if (!set) {
+        set = new Set()
+        this._channelSessions.set(ch, set)
+      }
+      set.add(entry.sessionId)
+    }
+    let uset = this._userSessions.get(entry.userId)
+    if (!uset) {
+      uset = new Set()
+      this._userSessions.set(entry.userId, uset)
+    }
+    uset.add(entry.sessionId)
+  }
+
+  /**
+   * presence 에서 세션 제거. 빈 인덱스는 정리.
+   * @param {string} sessionId
+   * @returns {boolean} 실제 제거 여부.
+   * @private
+   */
+  _removeSession(sessionId) {
+    const session = this._sessions.get(sessionId)
+    if (!session) return false
+    this._sessions.delete(sessionId)
+    for (const ch of session.channels) {
+      const set = this._channelSessions.get(ch)
+      if (set) {
+        set.delete(sessionId)
+        if (set.size === 0) this._channelSessions.delete(ch)
+      }
+    }
+    const uset = this._userSessions.get(session.userId)
+    if (uset) {
+      uset.delete(sessionId)
+      if (uset.size === 0) this._userSessions.delete(session.userId)
+    }
+    return true
+  }
+
+  /**
+   * bridge 연결 종료 시 — 그 bridge 의 모든 세션 제거 + 다른 bridge 에 bulk_leave 통지.
+   * @param {string} connId
+   * @private
+   */
+  _handleBridgeGone(connId) {
+    this._bridges.delete(connId)
+    /** @type {string[]} */
+    const orphaned = []
+    for (const [sid, session] of this._sessions) {
+      if (session.bridgeConnId === connId) orphaned.push(sid)
+    }
+    for (const sid of orphaned) this._removeSession(sid)
+    if (orphaned.length > 0) {
+      const env = createHubMessage({ type: T.BULK_LEAVE, payload: { sessionIds: orphaned } })
+      this._fanOutToOthers(connId, env)
+    }
+    this._log?.debug?.({ connId, orphaned: orphaned.length }, 'ws-hub bridge gone — presence cleaned')
+  }
+
+  /**
+   * origin 을 제외한 모든 등록 bridge 로 송신 (presence 공유용). envelope 는 1회만 직렬화(L5).
+   * @param {string} exceptConnId
+   * @param {Object} envelope
+   * @private
+   */
+  _fanOutToOthers(exceptConnId, envelope) {
+    const data = JSON.stringify(envelope)
+    for (const [connId, bridge] of this._bridges) {
+      if (connId !== exceptConnId) this._sendSerialized(bridge.socket, data)
+    }
+  }
+
+  /**
+   * 한 채널의 세션을 가진 bridge 들로 fan-out (origin 제외, 중복 bridge 1회). 직렬화 1회(L5).
+   *
+   * `exceptSessionIds` 가 있으면 해당 세션은 bridge 선정에서 제외한다(ADR-098). 어떤 bridge 의
+   * 채널 세션이 **전부** 제외 대상이면 그 bridge 는 통째로 스킵된다(불필요한 전송 절약). 일부만 제외면
+   * bridge 는 받아서 로컬에서 해당 세션만 건너뛴다(envelope 의 payload.exceptSessionIds 가 그대로 전달됨).
+   *
+   * @param {string} channel
+   * @param {string} exceptConnId
+   * @param {Object} envelope
+   * @param {string[]} [exceptSessionIds] - fan-out 에서 뺄 세션 목록(BROADCAST payload).
+   * @private
+   */
+  _fanOutChannel(channel, exceptConnId, envelope, exceptSessionIds) {
+    const sids = this._channelSessions.get(channel)
+    if (!sids) return
+    const except = Array.isArray(exceptSessionIds) && exceptSessionIds.length > 0 ? new Set(exceptSessionIds) : null
+    const targets = new Set()
+    for (const sid of sids) {
+      if (except && except.has(sid)) continue // 제외 세션은 bridge 선정에 기여하지 않음
+      const session = this._sessions.get(sid)
+      if (session && session.bridgeConnId !== exceptConnId) targets.add(session.bridgeConnId)
+    }
+    if (targets.size === 0) return
+    const data = JSON.stringify(envelope)
+    for (const connId of targets) this._sendTo(connId, data)
+  }
+
+  /**
+   * 한 user 의 세션을 가진 bridge 들로 fan-out (DIRECT, ADR-035). origin 제외(L7) — origin 은
+   * local 직접 전달하므로 hub 가 되돌리지 않는다(BROADCAST 와 동일 패턴). 직렬화 1회(L5).
+   * @param {string} userId
+   * @param {Object} envelope
+   * @param {string} [exceptConnId] - 제외할 origin bridge connId.
+   * @private
+   */
+  _fanOutUser(userId, envelope, exceptConnId) {
+    const sids = this._userSessions.get(userId)
+    if (!sids) return
+    const targets = new Set()
+    for (const sid of sids) {
+      const session = this._sessions.get(sid)
+      if (session && session.bridgeConnId !== exceptConnId) targets.add(session.bridgeConnId)
+    }
+    if (targets.size === 0) return
+    const data = JSON.stringify(envelope)
+    for (const connId of targets) this._sendTo(connId, data)
+  }
+
+  /**
+   * connId 로 직렬화된 프레임 송신 (등록된 bridge 한정).
+   * @param {string} connId
+   * @param {string} serialized - 이미 JSON.stringify 된 envelope.
+   * @private
+   */
+  _sendTo(connId, serialized) {
+    const bridge = this._bridges.get(connId)
+    if (bridge) this._sendSerialized(bridge.socket, serialized)
+  }
+
+  /**
+   * 단일 envelope 송신 — 직렬화 후 위임 (register_ok/error/heartbeat 등 1:1 송신용).
+   * @param {import('ws').WebSocket} socket
+   * @param {Object} envelope
+   * @private
+   */
+  _safeSend(socket, envelope) {
+    this._sendSerialized(socket, JSON.stringify(envelope))
+  }
+
+  /**
+   * 직렬화된 프레임 소켓 송신 — 닫히는 중 등 실패는 비치명적(이유+로그).
+   * @param {import('ws').WebSocket} socket
+   * @param {string} serialized
+   * @private
+   */
+  _sendSerialized(socket, serialized) {
+    try {
+      socket.send(serialized)
+    } catch (err) {
+      this._log?.debug?.({ err }, 'ws-hub send failed (socket closing)')
+    }
+  }
+
+  /**
+   * heartbeat liveness 감시(M3) — heartbeatMs*2 이상 HEARTBEAT 미수신 bridge 를 정리 후 terminate.
+   * half-open 연결(TCP 는 살아있으나 상대가 죽음)이 presence 에 영구 잔존하는 것을 막는다.
+   * @private
+   */
+  _checkLiveness() {
+    const now = Date.now()
+    const deadline = this._heartbeatMs * 2
+    /** @type {string[]} 반복 중 Map 변형을 피하려 먼저 수집. */
+    const stale = []
+    for (const [connId, bridge] of this._bridges) {
+      if (now - bridge.lastSeen > deadline) stale.push(connId)
+    }
+    for (const connId of stale) {
+      const bridge = this._bridges.get(connId)
+      if (!bridge) continue
+      this._log?.warn?.({ connId, sinceMs: now - bridge.lastSeen }, 'ws-hub bridge heartbeat timeout — terminating')
+      // 먼저 presence 정리 + BULK_LEAVE fan-out(이후 close 핸들러의 _handleBridgeGone 은 멱등 no-op).
+      this._handleBridgeGone(connId)
+      bridge.socket.terminate()
+    }
+  }
+
+  /**
+   * hub 종료 — liveness 타이머 정리 + 모든 bridge 연결 닫고 서버 close.
+   *
+   * `drain: true` 면 bridge 소켓을 close code **4503**(DRAIN, ADR-098) 로 닫는다 — bridge 가 "다른 hub
+   * 인스턴스로 재연결하라" 로 해석한다(LB/mesh 회전). 기본(false)은 1001(GOING_AWAY) — 일반 종료.
+   *
+   * @param {{ drain?: boolean }} [opts]
+   * @returns {Promise<void>}
+   */
+  async stop({ drain = false } = {}) {
+    if (this._livenessTimer) {
+      clearInterval(this._livenessTimer)
+      this._livenessTimer = null
+    }
+    if (!this._wss) return
+    const wss = this._wss
+    this._wss = null
+    const code = drain ? HUB_CLOSE_CODES.DRAIN : HUB_CLOSE_CODES.GOING_AWAY
+    const reason = drain ? 'hub draining' : 'hub shutting down'
+    if (drain) this._log?.info?.({ hubId: this._hubId, bridges: this._bridges.size }, 'ws-hub draining (4503)')
+    for (const { socket } of this._bridges.values()) socket.close(code, reason)
+    this._bridges.clear()
+    this._sessions.clear()
+    this._channelSessions.clear()
+    this._userSessions.clear()
+    await new Promise((resolve, reject) => {
+      wss.close((/** @type {Error | undefined} */ err) => (err ? reject(err) : resolve(undefined)))
+    })
+  }
+}
+
+/**
+ * CLI 진입점 — env 로 설정 읽어 hub 기동 (bin/mega-ws-hub.js 에서 호출).
+ *
+ * env: MEGA_WSHUB_TOKENS (필수, 콤마구분 acceptedTokens), MEGA_WSHUB_PORT (기본 3100),
+ *      MEGA_WSHUB_HOST (기본 0.0.0.0), MEGA_WSHUB_HEARTBEAT_MS (선택), MEGA_WSHUB_MAX_PAYLOAD (선택, bytes),
+ *      MEGA_WSHUB_COMPRESSION ('true' 면 압축 ON, ADR-078 디폴트값으로),
+ *      MEGA_WSHUB_COMPRESSION_THRESHOLD (선택, bytes — 압축 ON 일 때만 적용).
+ * 향후 mega.config.js 의 wsHub 블록 로딩으로 대체 (ADR-068) — 그 시점에 6 필드 전체가
+ * config 로 전달된다. 지금 CLI 는 env 한정이라 enabled + threshold 만 노출(나머지는 ADR-078 디폴트).
+ *
+ * SIGTERM/SIGINT 시 MegaShutdown 이 hub.stop({ drain: true })(bridge 소켓 4503 + wss.close)을
+ * 실행한다(L2 + drain) — 독립 hub 종료는 "다른 인스턴스로 재연결" 신호(4503)가 맞다(ADR-098).
+ *
+ * @returns {Promise<MegaWsHub>}
+ */
+export async function runWsHubCli() {
+  const raw = process.env.MEGA_WSHUB_TOKENS
+  const acceptedTokens = typeof raw === 'string' ? raw.split(',').map((t) => t.trim()).filter(Boolean) : []
+  if (acceptedTokens.length === 0) {
+    throw new Error('mega ws-hub: MEGA_WSHUB_TOKENS env is required (comma-separated, ADR-059).')
+  }
+  const port = Number(process.env.MEGA_WSHUB_PORT ?? 3100)
+  const host = process.env.MEGA_WSHUB_HOST ?? '0.0.0.0'
+  const hbRaw = process.env.MEGA_WSHUB_HEARTBEAT_MS
+  const heartbeatMs = hbRaw ? Number(hbRaw) : DEFAULT_HEARTBEAT_MS
+  const mpRaw = process.env.MEGA_WSHUB_MAX_PAYLOAD
+  const maxPayloadBytes = mpRaw ? Number(mpRaw) : DEFAULT_MAX_PAYLOAD_BYTES
+  // 압축(ADR-078) — env 로 ON/threshold 만 노출. enabled=false 면 compression 미전달(OFF).
+  const compressionOn = process.env.MEGA_WSHUB_COMPRESSION === 'true'
+  const thrRaw = process.env.MEGA_WSHUB_COMPRESSION_THRESHOLD
+  const compression = compressionOn
+    ? { enabled: true, threshold: thrRaw ? Number(thrRaw) : COMPRESSION_DEFAULTS.threshold }
+    : undefined
+  const hub = new MegaWsHub({ acceptedTokens, heartbeatMs, maxPayloadBytes, compression, logger: console })
+  const addr = await hub.start({ port, host })
+  // 독립 hub 프로세스 graceful shutdown(L2 + drain) — SIGTERM/SIGINT → hub.stop({ drain: true }).
+  MegaShutdown.register('mega-ws-hub', async () => hub.stop({ drain: true }))
+  MegaShutdown.setupSignals()
+  console.log(`[mega:ws-hub] listening on ${addr.host}:${addr.port} (hubId=${hub.hubId})`)
+  return hub
+}

package/src/core/ajv-mapper.js

@@ -0,0 +1,80 @@
+// @ts-check
+/**
+ * AJV(Fastify 네이티브 JSON Schema 검증) 에러 → MegaValidationError 매퍼 (ADR-090).
+ *
+ * @module core/ajv-mapper
+ */
+import { MegaValidationError } from '../errors/http-errors.js'
+
+/**
+ * 민감 필드명 패턴 (ADR-090 PII 마스킹). 매칭 시 detail.value 를 '[REDACTED]' 로 치환.
+ * 마지막 필드 세그먼트 기준 부분 일치 (대소문자 무시). 시크릿 절대 노출 금지 원칙과 정합.
+ */
+const SENSITIVE_FIELD_RE = /(password|secret|token)/i
+
+/** PII 마스킹된 value 표기. */
+const REDACTED = '[REDACTED]'
+
+/**
+ * Fastify 가 던진 AJV 검증 에러 객체 → MegaValidationError 로 매핑.
+ *
+ * Fastify 의 AJV 에러는 `err.validation: AjvErrorObject[]` + `err.validationContext: string`
+ * 형태. AjvErrorObject 는 { instancePath, schemaPath, keyword, message, params } 가짐.
+ *
+ * envelope details 형식 (ADR-075 배열):
+ *   [{ field: string, rule: string, value?: any, message: string }, ...]
+ *
+ * @param {Error & { validation?: any[], validationContext?: string }} err
+ * @returns {MegaValidationError | null}
+ *   AJV 에러가 아니면 null (호출자가 그대로 throw).
+ */
+export function ajvErrorToValidationError(err) {
+  if (!err || !Array.isArray(err.validation)) return null
+  const details = err.validation.map((e) => ajvItemToDetail(e))
+  const context = err.validationContext ?? 'request'
+  return new MegaValidationError('validation.failed', `Validation failed for ${context}`, {
+    details,
+    cause: err,
+  })
+}
+
+/**
+ * 단일 AJV 에러 항목 → envelope detail. 민감 필드는 value 마스킹 (ADR-090).
+ * @param {{ instancePath?: string, dataPath?: string, keyword?: string, message?: string, params?: any }} e
+ * @returns {{ field: string, rule: string, value: any, message: string }}
+ */
+function ajvItemToDetail(e) {
+  // instancePath 예: '/email' → field = 'email'. '/items/0/name' → 'items[0].name'
+  const field = ajvPathToField(e.instancePath || e.dataPath || '')
+  // ADR-090: required 같은 키워드는 instancePath 가 부모라 params.missingProperty 가 실제 필드.
+  // 마스킹 판단은 instancePath 필드 + missingProperty 둘 다 본다.
+  const missing = e.params && typeof e.params.missingProperty === 'string' ? e.params.missingProperty : ''
+  const isSensitive = SENSITIVE_FIELD_RE.test(field) || SENSITIVE_FIELD_RE.test(missing)
+  return {
+    field,
+    rule: e.keyword || 'unknown',
+    value: isSensitive ? REDACTED : e.params,
+    message: e.message || 'invalid',
+  }
+}
+
+/**
+ * AJV instancePath → 사람이 읽는 field 경로.
+ * 슬래시 분리 후 숫자 인덱스는 `[n]`, 나머지는 dot 연결.
+ * 예: '/email' → 'email', '/items/0/name' → 'items[0].name'.
+ * @param {string} path
+ * @returns {string}
+ */
+function ajvPathToField(path) {
+  if (!path) return ''
+  const parts = path.split('/').filter(Boolean)
+  let out = ''
+  for (const p of parts) {
+    if (/^\d+$/.test(p)) {
+      out += `[${p}]`
+    } else {
+      out += out ? `.${p}` : p
+    }
+  }
+  return out
+}