mega-framework 0.1.6 → 0.1.8

package/src/core/ws-roster.js

@@ -74,9 +74,25 @@ export class MegaWsRedisRoster {
     if (typeof channel !== 'string' || typeof sessionId !== 'string') return
     const key = this._key(channel)
     const value = JSON.stringify({ userId: member?.userId, ...(member?.metadata ? { metadata: member.metadata } : {}), expiresAt: Date.now() + this._ttlMs })
-    await this._redis.hset(key, sessionId, value)
-    // 채널 HASH 키 전체 TTL — 모든 멤버가 stale 가 돼도 키가 영구히 남지 않게(멤버 TTL 의 2배 여유).
-    await this._redis.pexpire(key, this._ttlMs * 2)
+    // HSET + 채널 HASH 키 TTL(멤버 TTL 2배 — 전원 stale 돼도 키가 영구히 안 남게)을 pipeline 1 RT 로.
+    // 직렬 await 2회는 joinSession(채널 수만큼 add)·heartbeat 경로에서 왕복 수가 비용을 지배했다.
+    const results = await this._redis.pipeline().hset(key, sessionId, value).pexpire(key, this._ttlMs * 2).exec()
+    this._throwFirstPipelineError(results)
+  }
+
+  /**
+   * ioredis pipeline.exec() 결과(`[err, res][]`)에서 첫 명령 오류를 throw 한다 — pipeline 은 명령별
+   * 오류를 reject 가 아니라 결과 배열에 싣기 때문에, 묵히면 호출부의 기존 실패 처리(catch+warn)가
+   * 더는 동작하지 않는다(직렬 await 시절의 throw 계약 유지).
+   * @param {Array<[Error | null, any]> | null} results
+   * @returns {void}
+   * @private
+   */
+  _throwFirstPipelineError(results) {
+    if (!Array.isArray(results)) return
+    for (const [err] of results) {
+      if (err) throw err
+    }
   }
 
   /**
@@ -139,13 +155,29 @@ export class MegaWsRedisRoster {
   }
 
   /**
-   * 로컬 멤버 전체를 다시 add(=expiresAt 갱신). @returns {Promise<void>} @private
+   * 로컬 멤버 전체의 `expiresAt` 을 한 pipeline 으로 일괄 갱신. 직렬 add 루프(멤버당 2 RT)는 멤버
+   * 1,000 에 주기당 수백 ms — 갱신 지연이 TTL 윈도를 침식해 살아있는 세션이 lazy 만료될 수 있었다.
+   * pipeline 이면 단일 왕복 수준(실측 ~200×). 채널 키 PEXPIRE 는 채널당 1회만 싣는다.
+   * @returns {Promise<void>} @private
    */
   async _refreshLocal() {
     const members = this._getLocalMembers()
+    if (members.length === 0) return
+    const expiresAt = Date.now() + this._ttlMs
+    const pipeline = this._redis.pipeline()
+    /** @type {Set<string>} PEXPIRE 를 이미 실은 채널(중복 제거). */
+    const touchedChannels = new Set()
     for (const { channel, sessionId, member } of members) {
-      await this.add(channel, sessionId, member)
+      if (typeof channel !== 'string' || typeof sessionId !== 'string') continue
+      const key = this._key(channel)
+      const value = JSON.stringify({ userId: member?.userId, ...(member?.metadata ? { metadata: member.metadata } : {}), expiresAt })
+      pipeline.hset(key, sessionId, value)
+      if (!touchedChannels.has(channel)) {
+        touchedChannels.add(channel)
+        pipeline.pexpire(key, this._ttlMs * 2)
+      }
     }
+    this._throwFirstPipelineError(await pipeline.exec())
   }
 
   /**
@@ -155,9 +187,19 @@ export class MegaWsRedisRoster {
   async stop() {
     if (this._hbTimer) clearInterval(this._hbTimer)
     this._hbTimer = null
-    // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리).
-    for (const { channel, sessionId } of this._getLocalMembers()) {
-      await this.remove(channel, sessionId).catch(() => {})
+    // graceful: 자기 로컬 멤버 즉시 제거(crash 가 아닌 정상 종료라 TTL 대기 없이 정리) — 한 pipeline 으로.
+    // 실패해도 종료는 계속(lazy 만료가 정리) — 단 명단에 TTL 까지 남으므로 묵히지 않고 알린다.
+    const members = this._getLocalMembers()
+    if (members.length === 0) return
+    const pipeline = this._redis.pipeline()
+    for (const { channel, sessionId } of members) {
+      if (typeof channel !== 'string' || typeof sessionId !== 'string') continue
+      pipeline.hdel(this._key(channel), sessionId)
+    }
+    try {
+      this._throwFirstPipelineError(await pipeline.exec())
+    } catch (err) {
+      this._log?.warn?.({ err }, 'ws-roster graceful remove failed (stale until TTL)')
     }
   }
 }

package/src/core/ws-upgrade.js

@@ -25,7 +25,7 @@
  *
  * @module core/ws-upgrade
  */
-import { createWsMessage, parseWsMessage, generateMessageId, WS_TYPE_PATTERN } from './ws-message.js'
+import { createWsMessage, parseWsMessage, generateMessageId, WS_TYPE_PATTERN, WS_PROTOCOL_VERSION } from './ws-message.js'
 import { MegaAspDecryptError } from '../lib/asp/errors.js'
 import * as MegaTracing from '../lib/mega-tracing.js'
 import * as MegaMetrics from '../lib/mega-metrics.js'
@@ -49,9 +49,148 @@ export const CLOSE_CODE_INTERNAL_ERROR = 1011
 /** 느린 소비자 백프레셔 close code (RFC 6455 §7.4.1 표준 1013 "Try Again Later", Med). */
 export const CLOSE_CODE_SLOW_CONSUMER = 1013
 
+/**
+ * 재배치(requeue) close code — 4503. "이 워커 말고 다른 곳으로 즉시 재연결하라"는 신호로,
+ * bridge↔hub 의 drain(4503, `hub-protocol.js` CLOSE_CODE_DRAIN)과 같은 코드를 써서 클라이언트가
+ * 한 가지 규약("4503 = 세션 유지한 채 재연결")으로 두 링크를 모두 처리한다. admin-kick 의
+ * `requeue: true`(hub.disconnect) 가 사용 — kick(1008, 돌아오지 마라)과 의미가 반대다.
+ * HTTP 세션은 보존되므로 재연결 시 `before` 인증이 세션 쿠키로 자연 통과한다(transparent re-route).
+ */
+export const CLOSE_CODE_REQUEUE = 4503
+
 /** send 버퍼(bufferedAmount) 기본 상한(바이트). 초과 = 소비자가 ack 를 못 따라옴 → 연결 종료(서버 OOM 방지). */
 export const DEFAULT_MAX_BUFFERED_BYTES = 16 * 1024 * 1024
 
+/**
+ * 프로세스 **합산** send 버퍼 기본 budget(바이트, ADR-215 — G5 audit M-6).
+ *
+ * per-conn 상한(위 16MiB)은 연결 1개의 OOM 방어일 뿐이라, 느린 소비자 N 개가 각자 cap 직전까지
+ * 쌓으면 합산은 무제한이었다(이론상 1,000개 × 16MiB = 16GB). 합산이 본 budget 을 넘으면 **가장 큰
+ * 송신 큐를 보유한 연결부터** 1013(slow consumer)으로 종료해 budget 아래로 회수한다.
+ * `configureWsSendBudget({ maxTotalBufferedBytes: 0 })` 으로 무제한 옵트아웃.
+ */
+export const DEFAULT_MAX_TOTAL_BUFFERED_BYTES = 256 * 1024 * 1024
+
+/** 합산 budget 스윕 최소 간격(ms) — 매 send 마다 전 연결 O(N) 합산을 돌지 않게 하는 비용 상한. */
+const BUDGET_SWEEP_INTERVAL_MS = 250
+
+/** budget 추적 대상 연결 — driveWsConnection 경유 실연결만(직접 생성한 테스트 더블은 미추적). @type {Set<MegaWsConnection>} */
+const budgetConns = new Set()
+
+/** @type {number} 현재 합산 budget(바이트). Infinity = 옵트아웃. */
+let maxTotalBufferedBytes = DEFAULT_MAX_TOTAL_BUFFERED_BYTES
+
+/** @type {number} 마지막 budget 스윕 시각(epoch ms). */
+let lastBudgetSweepAt = 0
+
+/**
+ * 프로세스 합산 send budget 을 조정한다(ADR-215). 부팅/운영 튜닝 진입점.
+ * @param {{ maxTotalBufferedBytes?: number }} [opts] - 바이트 budget. `0` = 무제한(옵트아웃).
+ * @returns {{ maxTotalBufferedBytes: number }} 적용된 현재 값.
+ * @throws {TypeError} 음수/비숫자 — 설정 실수 fail-fast.
+ */
+export function configureWsSendBudget({ maxTotalBufferedBytes: max } = {}) {
+  if (max !== undefined) {
+    if (typeof max !== 'number' || Number.isNaN(max) || max < 0) {
+      throw new TypeError(`configureWsSendBudget: maxTotalBufferedBytes must be a non-negative number (0 = unlimited). Got ${max}`)
+    }
+    maxTotalBufferedBytes = max === 0 ? Infinity : max
+  }
+  return { maxTotalBufferedBytes }
+}
+
+/**
+ * 합산 budget 스윕 — 추적 중 전 연결의 `bufferedAmount` 를 합산해 budget 초과면 가장 큰 큐 보유
+ * 연결부터 종료한다. 스로틀({@link BUDGET_SWEEP_INTERVAL_MS}) 안쪽 재호출은 no-op(send 핫패스 보호).
+ * @param {number} [now] - epoch ms(테스트 주입용).
+ * @returns {void}
+ */
+function sweepWsSendBudget(now = Date.now()) {
+  if (now - lastBudgetSweepAt < BUDGET_SWEEP_INTERVAL_MS) return
+  lastBudgetSweepAt = now
+  if (budgetConns.size === 0 || maxTotalBufferedBytes === Infinity) return
+  let total = 0
+  for (const c of budgetConns) total += c._raw.bufferedAmount ?? 0
+  while (total > maxTotalBufferedBytes) {
+    /** @type {MegaWsConnection | null} */
+    let worst = null
+    for (const c of budgetConns) {
+      if (worst === null || (c._raw.bufferedAmount ?? 0) > (worst._raw.bufferedAmount ?? 0)) worst = c
+    }
+    const worstBytes = worst === null ? 0 : (worst._raw.bufferedAmount ?? 0)
+    if (worst === null || worstBytes === 0) break // 잔여가 전부 0 이면 더 회수할 게 없음(무한루프 차단).
+    budgetConns.delete(worst) // close 이벤트 전에 즉시 제외 — 같은 스윕 내 재선정 방지.
+    total -= worstBytes
+    try {
+      worst._raw.close(CLOSE_CODE_SLOW_CONSUMER, 'backpressure: process-wide send budget exceeded')
+    } catch {
+      // 이미 닫히는 중이면 close 는 무의미 — per-conn 가드와 동일 의미(비치명적). Set 에선 이미 제거됨.
+    }
+  }
+}
+
+/** budget 추적 등록(driveWsConnection 전용). @param {MegaWsConnection} conn @returns {void} */
+function trackWsSendBudget(conn) {
+  budgetConns.add(conn)
+}
+
+/** budget 추적 해제(연결 close 시). @param {MegaWsConnection} conn @returns {void} */
+function untrackWsSendBudget(conn) {
+  budgetConns.delete(conn)
+}
+
+/**
+ * 테스트 격리용 — budget 상태 초기화(추적 Set·스로틀·budget 디폴트 복원).
+ * @returns {void}
+ */
+export function _resetWsSendBudget() {
+  budgetConns.clear()
+  lastBudgetSweepAt = 0
+  maxTotalBufferedBytes = DEFAULT_MAX_TOTAL_BUFFERED_BYTES
+}
+
+/** 테스트용 — 연결을 budget 추적에 등록. @param {MegaWsConnection} conn @returns {void} */
+export function _trackWsSendBudget(conn) {
+  trackWsSendBudget(conn)
+}
+
+/** 테스트용 — 스로틀 우회 가능한 스윕 직접 호출. @param {number} [now] @returns {void} */
+export function _sweepWsSendBudget(now) {
+  sweepWsSendBudget(now)
+}
+
+/**
+ * 클라↔bridge ping/pong liveness 기본 주기(ms) — 30초. 주기마다 ping 을 보내고 직전 주기의 pong 이
+ * 없으면 half-open(상대 사망·네트워크 단절) 으로 보고 terminate 한다 — 좀비 연결이 OS TCP 타임아웃까지
+ * `_wsConns`/roster 에 잔존하는 것을 막는다. 라우트 `opts.heartbeatMs` 로 조정, `0` = 끔.
+ */
+export const DEFAULT_WS_HEARTBEAT_MS = 30_000
+
+/**
+ * onConnect 완료 전 도착한 프레임의 대기 큐 상한 — 초과 시 연결 종료(1013). onConnect 가 느릴 때
+ * 악의적/과속 클라이언트가 큐로 메모리를 채우는 것을 막는다.
+ */
+export const MAX_PENDING_FRAMES_BEFORE_CONNECT = 256
+
+/**
+ * 라우트 opts 의 `heartbeatMs` 를 검증해 반환한다. 미지정 → 기본 30초, `0` = liveness 끔.
+ * 무효값(음수/비정수/비숫자)은 운영 실수 — 조용히 보정하지 않고 warn 로그 후 기본값을 쓴다
+ * (연결 구동 시점이라 throw 하면 핸드셰이크 콜백 밖으로 새므로 로그+기본값이 안전한 fail-safe).
+ *
+ * @param {{ heartbeatMs?: number } | undefined} opts - WS 라우트 opts.
+ * @param {any} [log] - 로거(warn).
+ * @returns {number} 적용할 주기(ms). 0 = 끔.
+ */
+export function resolveWsHeartbeatMs(opts, log) {
+  const v = opts?.heartbeatMs
+  if (v === undefined || v === null) return DEFAULT_WS_HEARTBEAT_MS
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < 0) {
+    log?.warn?.({ heartbeatMs: v }, `ws route opts.heartbeatMs is invalid (integer >= 0 expected) — using default ${DEFAULT_WS_HEARTBEAT_MS}ms`)
+    return DEFAULT_WS_HEARTBEAT_MS
+  }
+  return v
+}
+
 /**
  * WS 프레임 코덱 — 평문/암호 와이어 변환을 추상화한다.
  * @typedef {Object} WsFrameCodec
@@ -122,6 +261,8 @@ export class MegaWsConnection {
     this.channels = null
     /** @type {Object|undefined} joinSession/updateMetadata 로 저장한 presence 메타(재연결 재동기화에 보존, M-1). */
     this.metadata = undefined
+    /** @type {number} 협상된 envelope 프로토콜 버전(기본 v1) — driveWsConnection 이 핸드셰이크 결과로 설정. */
+    this.protocolVersion = 1
   }
 
   /** 하위 raw `ws` WebSocket (escape hatch — 바이너리/직접 제어용). */
@@ -154,6 +295,10 @@ export class MegaWsConnection {
       }
       return
     }
+    // 프로세스 합산 budget 스윕(ADR-215) — per-conn cap 아래의 "다수의 느린 소비자" 합산 OOM 방어.
+    // 스로틀이 있어 핫패스 비용은 주기당 O(N) 1회. 스윕이 이 연결을 닫았으면(가장 큰 큐) 송신 생략.
+    sweepWsSendBudget()
+    if (this._raw.readyState !== undefined && this._raw.readyState !== 1) return
     // ns 자동 주입 (L1): 명시 안 됐고 연결 ns 가 있으면 채운다. 명시값은 덮어쓰지 않음.
     const withNs = fields.ns === undefined && this.ns !== undefined ? { ...fields, ns: this.ns } : fields
     const env = createWsMessage(withNs)
@@ -234,10 +379,17 @@ function buildWsPresence(app, conn, ns) {
  * @param {any} args.log - request 로거 (debug/warn/error).
  * @param {any} [args.auth] - `before` 미들웨어가 인증 후 돌려준 신원(`{ userId, sessionId, ... }`).
  *   `ctx.auth` 로 노출 — onConnect 에서 `app.joinSession(sock, { userId: ctx.auth.userId, ... })` 에 쓴다.
+ * @param {number} [args.protocolVersion] - 핸드셰이크에서 협상된 envelope 버전(`mega.v<N>` subprotocol,
+ *   {@link import('./ws-message.js').negotiateWsProtocol}). 미지정 = v1(레거시). 이 연결의 envelope
+ *   검증 기준이 되고 `conn.protocolVersion`/`ctx.protocolVersion` 으로 노출된다.
  * @returns {MegaWsConnection}
  */
-export function driveWsConnection({ raw, req, route, app, codec, log, auth = null }) {
+export function driveWsConnection({ raw, req, route, app, codec, log, auth = null, protocolVersion = WS_PROTOCOL_VERSION }) {
   const conn = new MegaWsConnection(raw, codec, { ns: route.ns, path: route.path })
+  // 프로세스 합산 send budget 추적(ADR-215) — 실연결만 등록, close 에서 해제(아래 'close' 핸들러).
+  trackWsSendBudget(conn)
+  // 협상된 envelope 버전 — 이 연결의 검증 기준이자 v2 도입 시 코덱/검증 분기의 기준점.
+  conn.protocolVersion = protocolVersion
   // ChannelClass 는 부팅 시 MegaWebSocketController 상속 검증됨 (router.ws). 여기선 인스턴스화만.
   const channel = /** @type {import('./ws-controller.js').MegaWebSocketController} */ (
     new (/** @type {any} */ (route.ChannelClass))()
@@ -256,6 +408,7 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
     path: route.path,
     req,
     connId: conn.id,
+    protocolVersion, // 협상된 envelope 버전(v1 기본) — 채널이 버전별 동작을 분기할 때 사용.
     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.
@@ -270,30 +423,88 @@ export function driveWsConnection({ raw, req, route, app, codec, log, auth = nul
 
   log.debug?.({ connId: conn.id, path: route.path, ns: route.ns }, 'ws.connect enter')
 
+  // type 별 payload 스키마 검증 함수 맵 (M2, router.ws 에서 사전 컴파일). 없으면 검증 없음.
+  const schemaValidators = route.schemaValidators ?? null
+
+  /** 프레임 1건 처리 시작 — fire-and-forget(각 메시지 독립 async 흐름). @param {string} frame */
+  const processFrame = (frame) => {
+    // 최외곽 가드 (L2): handleIncoming 은 내부에서 단계별 try/catch 하지만, 예기치 못한
+    // 동기 throw / reject 가 unhandledRejection 으로 새지 않도록 .catch 로 마무리한다.
+    handleIncoming({ conn, channel, codec, ctx, raw, frame, schemaValidators, log }).catch((err) => {
+      log.warn?.({ err, connId: conn.id }, 'ws handleIncoming unexpected error')
+    })
+  }
+
+  // onConnect 완료 전 도착한 프레임은 큐에 보관했다가 완료 후 도착 순서대로 처리한다 — 'message' 리스너는
+  // 동기 부착되고 onConnect 는 비동기라, 빠른 클라이언트의 첫 메시지가 채널 초기화(joinSession 등) 전에
+  // 디스패치되는 race 를 막는다. onConnect 실패 시 연결이 닫히므로 큐는 버린다.
+  let isConnectSettled = false
+  /** @type {string[]} */
+  let pendingFrames = []
+
   // onConnect — 실패 시 fail-closed. 복호화와 무관한 서버 내부 오류이므로 1011 (M3). silent 금지.
   Promise.resolve()
     .then(() => channel.onConnect(conn, ctx))
+    .then(() => {
+      isConnectSettled = true
+      const queued = pendingFrames
+      pendingFrames = []
+      for (const frame of queued) processFrame(frame)
+    })
     .catch((err) => {
       log.error?.({ err, connId: conn.id }, 'ws.onConnect threw — closing (1011)')
+      pendingFrames = [] // 연결이 닫히므로 대기 프레임은 처리하지 않는다.
       if (conn.isOpen) conn.close(CLOSE_CODE_INTERNAL_ERROR, 'onConnect failed')
     })
 
-  // type 별 payload 스키마 검증 함수 맵 (M2, router.ws 에서 사전 컴파일). 없으면 검증 없음.
-  const schemaValidators = route.schemaValidators ?? null
-
   raw.on('message', (data) => {
     // ws 는 Buffer | ArrayBuffer | Buffer[] 를 줄 수 있음. 텍스트 프레임만 처리 (바이너리는 후속 BINARY 타입).
     const frame = Array.isArray(data)
       ? Buffer.concat(data).toString('utf8')
       : data.toString('utf8')
-    // 최외곽 가드 (L2): handleIncoming 은 내부에서 단계별 try/catch 하지만, 예기치 못한
-    // 동기 throw / reject 가 unhandledRejection 으로 새지 않도록 .catch 로 마무리한다.
-    handleIncoming({ conn, channel, codec, ctx, raw, frame, schemaValidators, log }).catch((err) => {
-      log.warn?.({ err, connId: conn.id }, 'ws handleIncoming unexpected error')
-    })
+    if (!isConnectSettled) {
+      if (pendingFrames.length >= MAX_PENDING_FRAMES_BEFORE_CONNECT) {
+        // onConnect 가 끝나기 전에 큐 상한 도달 — 더 쌓으면 메모리 abuse 라 연결을 닫는다(1013).
+        log.warn?.({ connId: conn.id, queued: pendingFrames.length }, 'ws pre-connect frame queue overflow — closing (1013)')
+        pendingFrames = []
+        if (conn.isOpen) conn.close(CLOSE_CODE_SLOW_CONSUMER, 'pre-connect queue overflow')
+        return
+      }
+      pendingFrames.push(frame)
+      return
+    }
+    processFrame(frame)
   })
 
+  // liveness(ping/pong): 주기마다 ping 을 보내고 직전 주기의 pong 이 없으면 half-open 으로 보고
+  // terminate 한다 — 'close' 이벤트가 onDisconnect/untrack 정리를 그대로 트리거한다. opts.heartbeatMs=0 으로 끔.
+  const heartbeatMs = resolveWsHeartbeatMs(/** @type {any} */ (route.opts), log)
+  if (heartbeatMs > 0) {
+    let isAlive = true
+    raw.on('pong', () => {
+      isAlive = true
+    })
+    const pingTimer = setInterval(() => {
+      if (raw.readyState !== 1) return // 닫히는 중 — 'close' 가 곧 타이머를 정리한다.
+      if (!isAlive) {
+        log.warn?.({ connId: conn.id, heartbeatMs }, 'ws heartbeat timeout — terminating half-open connection')
+        raw.terminate()
+        return
+      }
+      isAlive = false
+      try {
+        raw.ping()
+      } catch (err) {
+        // 소켓이 닫히는 중이면 ping 실패 — 비치명적, close 가 뒤따른다 (이유+로그).
+        log.debug?.({ err, connId: conn.id }, 'ws ping send failed (socket closing)')
+      }
+    }, heartbeatMs)
+    if (typeof pingTimer.unref === 'function') pingTimer.unref()
+    raw.on('close', () => clearInterval(pingTimer))
+  }
+
   raw.on('close', (code, reasonBuf) => {
+    untrackWsSendBudget(conn)
     app._untrackWsConn?.(conn)
     const reason = Buffer.isBuffer(reasonBuf) ? reasonBuf.toString('utf8') : String(reasonBuf ?? '')
     log.debug?.({ connId: conn.id, code, reason }, 'ws.disconnect')
@@ -396,11 +607,11 @@ async function handleIncoming({ conn, channel, codec, ctx, raw, frame, schemaVal
     return
   }
 
-  // 2) envelope 파싱 + 검증. 실패 → error envelope 응답(연결 유지 — 비치명적).
+  // 2) envelope 파싱 + 검증 — 이 연결에서 협상된 버전 기준. 실패 → error envelope 응답(연결 유지 — 비치명적).
   /** @type {{ type: string, id: string }} */
   let msg
   try {
-    msg = /** @type {{ type: string, id: string }} */ (parseWsMessage(plain))
+    msg = /** @type {{ type: string, id: string }} */ (parseWsMessage(plain, { version: conn.protocolVersion }))
   } catch (err) {
     log.warn?.({ err, connId: conn.id }, 'ws invalid envelope')
     if (conn.isOpen) {

package/src/index.js

@@ -115,7 +115,7 @@ export { MegaAspDecryptError, ASP_RULES } from './lib/asp/errors.js'
 export { normalizeAspConfig } from './lib/asp/config.js'
 
 // Bridge ↔ Hub 12-타입 프로토콜 (ADR-033/059/097)
-export { MegaWsHub, DEFAULT_HEARTBEAT_MS, runWsHubCli } from './cli/ws-hub.js'
+export { MegaWsHub, DEFAULT_HEARTBEAT_MS, runWsHubCli } from './lib/ws-hub.js'
 export { MegaHubLink } from './core/hub-link.js'
 // WS per-message deflate 압축 (ADR-078)
 export { buildPerMessageDeflate, checkCompressionConfig, COMPRESSION_DEFAULTS } from './core/ws-compression.js'

package/src/lib/hub-protocol.js

@@ -61,6 +61,30 @@ export const HUB_MESSAGE_TYPES = Object.freeze({
 /** 12 개 wire `type` 문자열 집합 (빠른 소속 판별용). @type {ReadonlySet<string>} */
 export const HUB_TYPE_SET = new Set(Object.values(HUB_MESSAGE_TYPES))
 
+/** bridge↔hub 프로토콜 현 버전. REGISTER/REGISTER_OK 의 `protocolVersion` 협상 기준(부재 = v1). */
+export const HUB_PROTOCOL_VERSION = 1
+
+/**
+ * 이 측이 지원하는 bridge↔hub 프로토콜 버전 목록. 버전은 선형 누적 계약 — vN 지원 = v1..vN 전부 지원.
+ * @type {ReadonlyArray<number>}
+ */
+export const SUPPORTED_HUB_PROTOCOL_VERSIONS = Object.freeze([HUB_PROTOCOL_VERSION])
+
+/**
+ * bridge 가 REGISTER 로 보낸 최대 지원 버전과 hub 지원 버전의 상호 최고 버전을 고른다.
+ * 선형 누적 계약(vN 지원 = v1..vN 지원)이라 `min(bridgeMax, hubMax)` 가 항상 유효한 상호 버전이다
+ * (v1 이 바닥이라 협상이 실패할 수 없다 — 부재/무효 입력은 v1).
+ *
+ * @param {unknown} requestedMax - bridge 의 `protocolVersion`(최대 지원 버전).
+ * @param {ReadonlyArray<number>} [supported] - 이 측 지원 버전 목록.
+ * @returns {number} 협상된 버전(>= 1).
+ */
+export function negotiateHubProtocolVersion(requestedMax, supported = SUPPORTED_HUB_PROTOCOL_VERSIONS) {
+  const ourMax = Math.max(...supported)
+  if (!Number.isInteger(requestedMax) || /** @type {number} */ (requestedMax) < 1) return HUB_PROTOCOL_VERSION
+  return Math.min(/** @type {number} */ (requestedMax), ourMax)
+}
+
 /**
  * bridge↔hub WebSocket close code 카탈로그 (ADR-098).
  *
@@ -107,6 +131,8 @@ export const HUB_PAYLOAD_SCHEMAS = Object.freeze({
       instanceId: { type: 'string', minLength: 1 },
       token: { type: 'string', minLength: 1 },
       capabilities: { type: 'array', items: { type: 'string' } },
+      // 버전 협상(옵션): bridge 의 최대 지원 버전. 부재 = v1(레거시 bridge — 협상 없이 v1 고정).
+      protocolVersion: { type: 'integer', minimum: 1 },
     },
     additionalProperties: false,
   },
@@ -117,6 +143,9 @@ export const HUB_PAYLOAD_SCHEMAS = Object.freeze({
       hubId: { type: 'string', minLength: 1 },
       acceptedAt: { type: 'integer' },
       heartbeatMs: { type: 'integer', minimum: 1 },
+      // 버전 협상 결과(옵션): hub 가 채택한 버전. bridge 가 REGISTER 에 protocolVersion 을 실었을
+      // 때만 회신(echo-on-request) — 레거시 bridge(strict 스키마)가 모르는 필드를 받지 않게 한다.
+      protocolVersion: { type: 'integer', minimum: 1 },
     },
     additionalProperties: false,
   },

package/src/lib/mega-circuit-breaker.js

@@ -72,8 +72,10 @@ export const CAPACITY_ERROR_CODE = 'ESEMLOCKED'
  * @property {number} [resetTimeout=30000] - open 상태 유지 시간(ms). 경과 후 halfOpen 으로 1회 프로빙.
  * @property {number} [rollingCountTimeout=10000] - 실패율 집계 롤링 윈도우 길이(ms).
  * @property {number} [rollingCountBuckets=10] - 롤링 윈도우를 나누는 버킷 수.
- * @property {number} [volumeThreshold=0] - 이 횟수만큼 호출이 쌓이기 전엔 실패율이 높아도 open 안 함
- *   (표본 부족으로 인한 조기 trip 방지). 0=비활성.
+ * @property {number} [volumeThreshold=5] - 롤링 윈도우에 이 횟수만큼 호출이 쌓이기 전엔 실패율이
+ *   높아도 open 안 함(표본 부족 조기 trip 방지). 0=비활성. ⚠️ opossum 정본값(0)과 다른 프레임워크
+ *   디폴트 — 0 이면 부팅 직후/저빈도 호출에서 **첫 실패 1건**이 실패율 100% 가 돼 즉시 30s 차단되는
+ *   풋건이라 5 로 올렸다. opossum 원 동작이 필요하면 명시적으로 0 을 지정.
  * @property {number} [capacity] - 동시 진행(in-flight) 호출 상한. 초과분은 `ESEMLOCKED` 로 즉시 거부.
  *   미지정=무제한.
  * @property {(err: any, ...args: any[]) => boolean} [errorFilter] - `true` 반환 시 그 에러는 **실패로 집계하지 않음**
@@ -149,7 +151,7 @@ export class MegaCircuitBreaker {
       resetTimeout = 30_000,
       rollingCountTimeout = 10_000,
       rollingCountBuckets = 10,
-      volumeThreshold = 0,
+      volumeThreshold = 5, // opossum 정본(0)과 의도적으로 다름 — 단일 실패 즉시 open 풋건 방지.
       capacity,
       errorFilter,
       name,

package/src/lib/mega-health.js

@@ -19,21 +19,40 @@
 
 import { MegaShutdown } from './mega-shutdown.js'
 
+/** 체크 1개의 기본 타임아웃(ms) — hung 체크가 readiness 응답을 무기한 막지 않게 한다. */
+export const DEFAULT_CHECK_TIMEOUT_MS = 5_000
+
+/** @type {Map<string, { fn: Function, timeoutMs: number }>} */
 const checks = new Map()
 
 /**
  * 헬스 체크 등록.
  * @param {string} name
  * @param {() => Promise<{ ok: boolean, [key: string]: any }> | { ok: boolean }} fn
+ * @param {{ timeoutMs?: number }} [opts] - 체크별 타임아웃(양의 정수 ms, 기본 {@link DEFAULT_CHECK_TIMEOUT_MS}).
  */
-export function register(name, fn) {
+export function register(name, fn, opts = {}) {
   if (typeof name !== 'string' || name.length === 0) {
     throw new Error('MegaHealth.register: name is required (string)')
   }
   if (typeof fn !== 'function') {
     throw new Error('MegaHealth.register: fn must be a function')
   }
-  checks.set(name, fn)
+  const timeoutMs =
+    Number.isInteger(opts.timeoutMs) && /** @type {number} */ (opts.timeoutMs) > 0
+      ? /** @type {number} */ (opts.timeoutMs)
+      : DEFAULT_CHECK_TIMEOUT_MS
+  checks.set(name, { fn, timeoutMs })
+}
+
+/**
+ * 등록된 체크 제거(이름 기준). 닫힌 자원(예: hub link)의 체크가 stale 클로저로 남지 않게
+ * 소유자가 register 와 짝맞춰 부른다.
+ * @param {string} name
+ * @returns {boolean} 제거됐으면 true(미등록 이름이면 false).
+ */
+export function unregister(name) {
+  return checks.delete(name)
 }
 
 /**
@@ -48,12 +67,24 @@ export async function checkAll() {
 
   const entries = [...checks.entries()]
   const results = await Promise.all(
-    entries.map(async ([name, fn]) => {
+    entries.map(async ([name, { fn, timeoutMs }]) => {
+      /** @type {NodeJS.Timeout | undefined} */
+      let timer
       try {
-        const result = await fn()
+        // 체크별 race — hung 체크 1개가 readiness 전체를 무기한 막지 않게 timeoutMs 에서 끊는다
+        // (probe timeout 으로 인한 연쇄 재시작 방지). 타임아웃은 해당 체크만 ok:false 처리.
+        const result = await Promise.race([
+          Promise.resolve(fn()),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`health check timed out after ${timeoutMs}ms`)), timeoutMs)
+            timer.unref?.()
+          }),
+        ])
         return [name, result?.ok === true ? result : { ok: false, ...result }]
       } catch (err) {
         return [name, { ok: false, error: err?.message ?? String(err) }]
+      } finally {
+        clearTimeout(timer)
       }
     }),
   )