mega-framework 0.1.0

package/src/core/hub-link.js

@@ -0,0 +1,552 @@
+// @ts-check
+/**
+ * MegaHubLink — bridge(=mega server) 측 hub 연결 클라이언트 (ADR-033/059/097/098).
+ *
+ * bridge 가 `mega ws-hub`(Hub) 에 **plaintext + Bearer** WebSocket 으로 붙어 12-타입 프로토콜
+ * (lib/hub-protocol.js)을 주고받는다. ASP 는 클라↔bridge 구간에서만 종단하므로(ADR-059) 이
+ * 링크엔 암호화가 없다 — 인증은 Bearer 토큰(핸드셰이크 헤더 + REGISTER payload).
+ *
+ * # 라이프사이클
+ *   connect() → ws open → `hub.register` 송신 → hub 가 `hub.register_ok` 응답 → resolve.
+ *   register 이후 heartbeat 루프 시작(`heartbeatMs` 주기, application-level, ADR-033). 수신
+ *   메시지는 type 별 핸들러로 디스패치({@link MegaHubLink#on}).
+ *
+ * # 재연결 (ADR-098)
+ *   `retry` 옵션을 주면 (1) 최초 connect() 실패 시 지수 백오프 재시도, (2) **등록 후 연결이
+ *   끊기면**(hub 재시작·drain 4503·네트워크 단절) 자동으로 재연결을 시도한다({@link MegaRetry}).
+ *   재연결 성공 시 {@link MegaHubLink.EVENTS}.RECONNECTED 이벤트를 emit 하므로, 상위(MegaApp)가
+ *   presence(JOIN)를 재동기화할 수 있다 — hub 는 절단 시점 presence 를 잃기 때문(at-most-once).
+ *   `retry` 미지정 시 본래 동작 — 끊기면 통지만 하고 재연결하지 않는다.
+ *
+ * # fail-closed (ADR-084)
+ *   register 전 hub.error / close → connect() reject. 수신 프레임이 hub 프로토콜 위반이면
+ *   silent 무시 금지 — warn 로그 후 드롭(연결은 유지, 비치명적).
+ *
+ * @module core/hub-link
+ */
+import { WebSocket } from 'ws'
+import {
+  HUB_MESSAGE_TYPES,
+  CLOSE_CODE_DRAIN,
+  createHubMessage,
+  parseHubMessage,
+} from '../lib/hub-protocol.js'
+import { withRetry } from '../lib/mega-retry.js'
+import { buildPerMessageDeflate } from './ws-compression.js'
+
+const T = HUB_MESSAGE_TYPES
+
+/**
+ * 재시도해도 결과가 같은 치명적 등록 실패(인증 거부 등) — `fatal` 마킹으로 백오프를 즉시 멈춘다.
+ * 일시적 실패(네트워크·타임아웃)는 일반 Error 라 재시도된다.
+ */
+class HubRegistrationError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message)
+    this.name = 'HubRegistrationError'
+    /** @type {boolean} shouldRetry 가 false 를 반환하게 하는 마커. */
+    this.fatal = true
+  }
+}
+
+/** withRetry 공통 shouldRetry — fatal(인증 거부 등) 이면 재시도 중단. @param {{error: any}} ctx */
+const retryUnlessFatal = (ctx) => !ctx?.error?.fatal
+
+export class MegaHubLink {
+  /**
+   * 링크 라이프사이클 이벤트 (wire 타입과 충돌하지 않도록 `link.*` reserved). {@link MegaHubLink#on}
+   * 으로 구독한다. **핸들러 인자는 이벤트마다 다르다**(L-2):
+   *   - `RECONNECTED`     → `{ hubId: string }` — 재연결 성공(새 등록 완료). hubId 는 새 hub 의 식별자.
+   *   - `DISCONNECTED`    → `{ code: number, reason: string, isDrain: boolean }` — 등록 후 절단.
+   *     `isDrain` 은 close code 가 4503(DRAIN)인지(다른 hub 로 회전 신호, ADR-098).
+   *   - `RECONNECT_FAILED`→ `{ error: Error }` — 재연결 재시도 소진(더 이상 자동 재시도 없음).
+   * @type {Readonly<{ RECONNECTED: string, DISCONNECTED: string, RECONNECT_FAILED: string }>}
+   */
+  static EVENTS = Object.freeze({
+    RECONNECTED: 'link.reconnected',
+    DISCONNECTED: 'link.disconnected',
+    RECONNECT_FAILED: 'link.reconnect_failed',
+  })
+
+  /**
+   * @param {Object} [opts]
+   * @param {string} [opts.url] - hub URL (예: 'ws://hub1.internal:19991/_hub'). 누락 시 throw.
+   * @param {string} [opts.token] - Bearer 토큰 (wsHub.acceptedTokens 중 하나). 누락 시 throw.
+   * @param {string} [opts.bridgeId] - 운영 식별자 (예: 'main-1'). 누락 시 throw.
+   * @param {string} [opts.instanceId] - REGISTER instanceId. 기본 bridgeId.
+   * @param {string[]} [opts.capabilities] - 선언 capability 목록. 기본 [].
+   * @param {import('../lib/mega-retry.js').MegaRetryOptions} [opts.retry] - 지정 시 재연결 활성(ADR-098).
+   *   `{ retries, minTimeout, maxTimeout, factor, jitter }`. 미지정 → 재연결 끔(기본 동작).
+   * @param {number} [opts.connectTimeoutMs=10000] - register_ok 미수신 시 attempt reject 까지(M4).
+   * @param {import('./ws-compression.js').WsCompressionConfig} [opts.compression] - Bridge↔Hub link
+   *   per-message deflate 압축(ADR-078). Global `wsHub.compression` 블록과 동일
+   *   스키마 — hub 서버와 양쪽이 협상해야 활성(RFC 7692). 디폴트 OFF. 잘못된 값은 즉시 throw.
+   * @param {{ warn?: Function, debug?: Function, info?: Function, error?: Function }} [opts.logger]
+   * @param {typeof import('ws').WebSocket} [opts.WebSocketCtor] - 테스트 주입용 ws 생성자.
+   */
+  constructor({ url, token, bridgeId, instanceId, capabilities, retry, connectTimeoutMs, compression, logger, WebSocketCtor } = {}) {
+    if (typeof url !== 'string' || url.length === 0) {
+      throw new Error('MegaHubLink: url is required (MegaBridgeHubConfig.url).')
+    }
+    if (typeof token !== 'string' || token.length === 0) {
+      throw new Error('MegaHubLink: token is required (Bearer, ADR-059).')
+    }
+    if (typeof bridgeId !== 'string' || bridgeId.length === 0) {
+      throw new Error('MegaHubLink: bridgeId is required.')
+    }
+    this._url = url
+    this._token = token
+    this._bridgeId = bridgeId
+    this._instanceId = typeof instanceId === 'string' && instanceId.length > 0 ? instanceId : bridgeId
+    this._capabilities = Array.isArray(capabilities) ? [...capabilities] : []
+    this._log = logger ?? null
+    this._WS = WebSocketCtor ?? WebSocket
+    /** 재연결 옵션 (없으면 재연결 비활성). @type {import('../lib/mega-retry.js').MegaRetryOptions | null} */
+    this._retry = retry && typeof retry === 'object' ? retry : null
+    /** 한 attempt 의 register_ok 대기 한도(M4). reconnect 에서도 동일 적용. @type {number} */
+    this._connectTimeoutMs = Number.isFinite(connectTimeoutMs) ? Number(connectTimeoutMs) : 10_000
+    // Bridge↔Hub link 압축(ADR-078). enabled=false → false. 잘못된 값은 생성자에서 즉시 throw.
+    /** @type {false | Object} ws 클라이언트 perMessageDeflate 로 전달(_connectOnce). */
+    this._perMessageDeflate = buildPerMessageDeflate(compression, 'wsHub.compression')
+
+    /** @type {import('ws').WebSocket | null} */
+    this._ws = null
+    /** @type {boolean} register_ok 수신 여부. */
+    this._isRegistered = false
+    /** @type {string | null} hub 가 부여한 hubId. */
+    this._hubId = null
+    /** @type {number} register_ok 의 heartbeatMs(0 이면 heartbeat 끔). */
+    this._heartbeatMs = 0
+    /** @type {ReturnType<typeof setInterval> | null} */
+    this._hbTimer = null
+    /** type(wire)/lifecycle event → 핸들러 집합. @type {Map<string, Set<Function>>} */
+    this._handlers = new Map()
+    /** close() 로 의도적으로 닫는 중인지 — true 면 자동 재연결하지 않는다. @type {boolean} */
+    this._isClosing = false
+    /** 재연결 진행 중 가드(중복 reconnect 방지). @type {boolean} */
+    this._isReconnecting = false
+    /** close() 가 진행 중인 재시도(백오프 대기)를 취소하기 위한 컨트롤러. @type {AbortController | null} */
+    this._abort = null
+  }
+
+  /** hub 가 부여한 hubId (register 전엔 null). */
+  get hubId() {
+    return this._hubId
+  }
+
+  /** register_ok 를 받아 사용 가능한 상태인지. */
+  get isRegistered() {
+    return this._isRegistered
+  }
+
+  /** 소켓이 OPEN(=1) 인지. */
+  get isOpen() {
+    return this._ws?.readyState === 1
+  }
+
+  /** 재연결이 활성(retry 옵션 지정)인지. */
+  get canReconnect() {
+    return this._retry !== null
+  }
+
+  /**
+   * 수신 메시지/라이프사이클 핸들러 등록. 같은 type 에 여러 개 등록 가능(모두 호출).
+   * @param {string} wireType - {@link HUB_MESSAGE_TYPES} 의 값(`hub.broadcast` 등) 또는
+   *   {@link MegaHubLink.EVENTS} 의 라이프사이클 이벤트(`link.*`).
+   * @param {(msg: Object) => void} handler
+   * @returns {this}
+   */
+  on(wireType, handler) {
+    let set = this._handlers.get(wireType)
+    if (!set) {
+      set = new Set()
+      this._handlers.set(wireType, set)
+    }
+    set.add(handler)
+    return this
+  }
+
+  /**
+   * hub 연결 + REGISTER 핸드셰이크. register_ok 수신 시 resolve.
+   *
+   * `retry` 옵션이 있으면 최초 연결도 지수 백오프로 재시도한다(ADR-098). 없으면 단발 시도.
+   *
+   * @param {Object} [opts]
+   * @param {number} [opts.connectTimeoutMs] - register_ok 대기 한도 override(M4). **이 값은 인스턴스에
+   *   저장되어(`this._connectTimeoutMs`) 이후 자동 재연결 attempt 에도 동일하게 적용된다** — 이 한 번의
+   *   connect() 에만 적용되는 것이 아니다(L-1). 재연결마다 같은 타임아웃을 쓰는 동작은 의도된 것이다.
+   * @returns {Promise<{ hubId: string, heartbeatMs: number }>}
+   * @throws register 전 에러/종료/타임아웃(재시도 소진 포함) 시 reject.
+   */
+  async connect({ connectTimeoutMs } = {}) {
+    this._isClosing = false
+    const timeout = Number.isFinite(connectTimeoutMs) ? Number(connectTimeoutMs) : this._connectTimeoutMs
+    this._connectTimeoutMs = timeout
+    if (!this._retry) {
+      return this._connectOnce({ connectTimeoutMs: timeout })
+    }
+    // retry 활성 — 최초 연결도 백오프 재시도. AbortError(인증 실패 등) 는 재시도하지 않는다.
+    this._abort = new AbortController()
+    return withRetry(() => this._connectOnce({ connectTimeoutMs: timeout }), {
+      ...this._retry,
+      signal: this._abort.signal,
+      shouldRetry: retryUnlessFatal,
+      onFailedAttempt: (ctx) => {
+        this._log?.warn?.(
+          { bridgeId: this._bridgeId, attempt: ctx.attemptNumber, retriesLeft: ctx.retriesLeft },
+          'hub-link connect attempt failed — backing off',
+        )
+      },
+    })
+  }
+
+  /**
+   * 단일 연결 시도 — ws open → REGISTER → register_ok. 한 attempt 의 Promise 를 돌려준다.
+   * 재시도/재연결은 호출부({@link MegaHubLink#connect}/{@link MegaHubLink#_reconnect})가 감싼다.
+   *
+   * @param {{ connectTimeoutMs: number }} args
+   * @returns {Promise<{ hubId: string, heartbeatMs: number }>}
+   * @private
+   */
+  _connectOnce({ connectTimeoutMs }) {
+    return new Promise((resolve, reject) => {
+      // Bearer 는 핸드셰이크 Authorization 헤더 + REGISTER payload 양쪽에 싣는다(이중 안전).
+      // perMessageDeflate 는 ws 클라 기본이 true 이므로, 압축 OFF 면 명시적으로 false 를 넘겨
+      // 협상 자체를 끈다(ADR-078). enabled 면 build 한 옵션 객체를 그대로 전달.
+      const ws = new this._WS(this._url, /** @type {any} */ ({
+        headers: { authorization: `Bearer ${this._token}` },
+        perMessageDeflate: this._perMessageDeflate,
+      }))
+      this._ws = ws
+      let settled = false
+      /** 이 attempt 가 register_ok 로 resolve 됐는지 — 이후 close 가 "등록 후 절단"인지 판별. */
+      let didRegister = false
+      /** @type {ReturnType<typeof setTimeout> | null} */
+      let timer = null
+
+      /** register 결과 1회 확정 — settle 시 타임아웃 타이머도 정리(M4). @param {(v:any)=>void} done @param {any} val */
+      const finish = (done, val) => {
+        if (settled) return
+        settled = true
+        if (timer) clearTimeout(timer)
+        done(val)
+      }
+
+      // 등록 타임아웃 — hub 가 무응답이면 소켓 닫고 reject(M4). 프로세스 종료 막지 않게 unref.
+      if (connectTimeoutMs > 0) {
+        timer = setTimeout(() => {
+          this._log?.warn?.({ bridgeId: this._bridgeId, connectTimeoutMs }, 'hub-link register timeout')
+          // reject 먼저 확정(settled=true) — 이어지는 ws.close 의 동기 'close' 이벤트가 다른 사유로
+          // settle 하지 않게 한다. close 는 소켓 정리용(이미 settled 라 close 핸들러는 no-op).
+          finish(reject, new Error('hub.register_timeout'))
+          if (ws.readyState <= 1) ws.close(1000, 'register timeout')
+        }, connectTimeoutMs)
+        timer.unref?.()
+      }
+
+      ws.on('open', () => {
+        this._log?.debug?.({ bridgeId: this._bridgeId, url: this._url }, 'hub-link open → REGISTER')
+        try {
+          this._sendEnvelope(
+            createHubMessage({
+              type: T.REGISTER,
+              payload: {
+                instanceId: this._instanceId,
+                token: this._token,
+                capabilities: this._capabilities,
+              },
+            }),
+          )
+        } catch (err) {
+          // REGISTER 송신 실패 = 연결 불가. fail-closed reject.
+          finish(reject, err instanceof Error ? err : new Error(String(err)))
+        }
+      })
+
+      ws.on('message', (data) => {
+        const frame = data.toString('utf8')
+        let msg
+        try {
+          msg = parseHubMessage(frame)
+        } catch (err) {
+          // hub 프로토콜 위반 프레임 — silent 금지. 드롭하되 연결은 유지(비치명적).
+          this._log?.warn?.({ err, bridgeId: this._bridgeId }, 'hub-link invalid frame dropped')
+          return
+        }
+        // register 핸드셰이크 단계: register_ok → resolve, error → reject.
+        if (!this._isRegistered) {
+          if (msg.type === T.REGISTER_OK) {
+            this._isRegistered = true
+            didRegister = true
+            this._hubId = msg.payload.hubId
+            this._heartbeatMs = msg.payload.heartbeatMs
+            this._startHeartbeat()
+            this._log?.info?.({ bridgeId: this._bridgeId, hubId: this._hubId }, 'hub-link registered')
+            finish(resolve, { hubId: this._hubId, heartbeatMs: this._heartbeatMs })
+            return
+          }
+          if (msg.type === T.ERROR) {
+            const code = msg.error?.code ?? 'hub.error'
+            this._log?.warn?.({ bridgeId: this._bridgeId, code }, 'hub-link registration rejected')
+            // 인증 실패 등 등록 거부는 재시도해도 같은 결과 — fatal 마킹으로 백오프 중단(ADR-098).
+            finish(reject, new HubRegistrationError(`hub registration failed: ${code}`))
+            ws.close()
+            return
+          }
+          // register 전 다른 타입은 규약 위반 — 드롭(연결 유지). resolve/reject 는 register_ok/error 만.
+          this._log?.warn?.({ bridgeId: this._bridgeId, type: msg.type }, 'hub-link pre-register message ignored')
+          return
+        }
+        this._dispatch(msg)
+      })
+
+      ws.on('error', (err) => {
+        if (!settled) {
+          finish(reject, err instanceof Error ? err : new Error(String(err)))
+        } else {
+          // 등록 후 소켓 에러 — 비치명적, close 가 뒤따른다. 로그만.
+          this._log?.warn?.({ err, bridgeId: this._bridgeId }, 'hub-link socket error')
+        }
+      })
+
+      ws.on('close', (code, reasonBuf) => {
+        this._stopHeartbeat()
+        const reason = Buffer.isBuffer(reasonBuf) ? reasonBuf.toString('utf8') : String(reasonBuf ?? '')
+        this._log?.debug?.({ bridgeId: this._bridgeId, code, reason }, 'hub-link closed')
+        if (!settled) {
+          // register 전 절단 — 이 attempt 실패. 재시도는 connect()/_reconnect 의 withRetry 가 처리.
+          finish(reject, new Error(`hub link closed before register (code ${code})`))
+          return
+        }
+        // 이미 settled. register_ok 로 resolve 된 뒤의 close = "등록 후 연결 절단".
+        if (didRegister) {
+          this._isRegistered = false
+          this._handleEstablishedClose(code, reason)
+        }
+      })
+    })
+  }
+
+  /**
+   * 등록 후 연결이 끊겼을 때 처리 — DISCONNECTED emit + (retry 활성·의도적 close 아님) 자동 재연결.
+   * @param {number} code - WS close code (4503=drain 등).
+   * @param {string} reason
+   * @private
+   */
+  _handleEstablishedClose(code, reason) {
+    const isDrain = code === CLOSE_CODE_DRAIN
+    this._log?.debug?.({ bridgeId: this._bridgeId, code, reason, isDrain }, 'hub-link disconnected')
+    this._emit(MegaHubLink.EVENTS.DISCONNECTED, { code, reason, isDrain })
+    if (this._retry && !this._isClosing) {
+      // drain(4503) 은 "다른 hub 로 재연결" 신호 — 현재는 같은 url 재시도(fallbackUrls 회전은 OQ).
+      void this._reconnect()
+    }
+  }
+
+  /**
+   * 자동 재연결 — 백오프로 _connectOnce 반복. 성공 시 RECONNECTED, 소진 시 RECONNECT_FAILED emit.
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _reconnect() {
+    if (this._isReconnecting) return
+    this._isReconnecting = true
+    this._abort = new AbortController()
+    try {
+      await withRetry(() => this._connectOnce({ connectTimeoutMs: this._connectTimeoutMs }), {
+        .../** @type {any} */ (this._retry),
+        signal: this._abort.signal,
+        shouldRetry: retryUnlessFatal,
+        onFailedAttempt: (ctx) => {
+          this._log?.warn?.(
+            { bridgeId: this._bridgeId, attempt: ctx.attemptNumber, retriesLeft: ctx.retriesLeft },
+            'hub-link reconnect attempt failed — backing off',
+          )
+        },
+      })
+      this._log?.info?.({ bridgeId: this._bridgeId, hubId: this._hubId }, 'hub-link reconnected')
+      this._emit(MegaHubLink.EVENTS.RECONNECTED, { hubId: this._hubId })
+    } catch (err) {
+      // 의도적 close 로 인한 abort 는 실패가 아님(조용히 종료). 그 외엔 재시도 소진 — 통지.
+      if (this._isClosing) {
+        this._log?.debug?.({ bridgeId: this._bridgeId }, 'hub-link reconnect aborted (closing)')
+      } else {
+        this._log?.error?.({ err, bridgeId: this._bridgeId }, 'hub-link reconnect exhausted')
+        this._emit(MegaHubLink.EVENTS.RECONNECT_FAILED, { error: err })
+      }
+    } finally {
+      this._isReconnecting = false
+    }
+  }
+
+  /**
+   * 사용자 접속 알림 (JOIN). presence 등록.
+   * @param {{ userId: string, sessionId: string, channels: string[], metadata?: Object }} entry
+   * @returns {void}
+   */
+  join(entry) {
+    this._send(T.JOIN, entry)
+  }
+
+  /**
+   * 단일 세션 종료 (LEAVE).
+   * @param {string} sessionId
+   * @returns {void}
+   */
+  leave(sessionId) {
+    this._send(T.LEAVE, { sessionId })
+  }
+
+  /**
+   * 다수 세션 일괄 종료 (BULK_LEAVE) — 여러 세션의 presence LEAVE 를 한 프레임으로 보낸다.
+   *
+   * 공개 API 다(프레임워크 내부는 현재 hub 의 bridge-gone 자동 감지에 의존해 직접 호출하지 않음).
+   * 다음 같은 **대량 정리** 상황에서 애플리케이션이 직접 호출한다:
+   *   - 대량 logout(한 사용자의 여러 세션을 한 번에 종료),
+   *   - 클라이언트 풀/탭 정리(연결 다수를 묶어 종료),
+   *   - bridge 가 자체 drain 으로 보유 세션을 능동적으로 비울 때(소켓 close 를 기다리지 않고 선통지).
+   * 세션 1건이면 {@link MegaHubLink#leave} 를 쓰는 편이 단순하다.
+   *
+   * @param {string[]} sessionIds
+   * @returns {void}
+   */
+  bulkLeave(sessionIds) {
+    this._send(T.BULK_LEAVE, { sessionIds })
+  }
+
+  /**
+   * 채널 전체 푸시 (BROADCAST). hub 가 가입 bridge 들에 fan-out.
+   * @param {{ ns: string, channel: string, message: Object, exceptSessionIds?: string[] }} payload
+   * @returns {void}
+   */
+  broadcast(payload) {
+    this._send(T.BROADCAST, payload)
+  }
+
+  /**
+   * 특정 사용자에게 직접 (DIRECT). hub 가 userId→sessionIds[] fan-out (ADR-035).
+   * @param {{ userId: string, message: Object }} payload
+   * @returns {void}
+   */
+  direct(payload) {
+    this._send(T.DIRECT, payload)
+  }
+
+  /**
+   * 세션 메타데이터 갱신 (METADATA) — 명시 필드만(ADR-059).
+   * @param {{ sessionId: string, metadata: Object }} payload
+   * @returns {void}
+   */
+  updateMetadata(payload) {
+    this._send(T.METADATA, payload)
+  }
+
+  /**
+   * 바이너리 메타 프레임 (BINARY). raw bytes 후속 프레임 전송은 본 Step 미포함(envelope 한정).
+   * @param {{ ref: string, mimeType: string, bytes: number }} payload
+   * @returns {void}
+   */
+  binary(payload) {
+    this._send(T.BINARY, payload)
+  }
+
+  /** 연결 종료 — 의도적 close 표시 + 진행 중 재연결 취소 + heartbeat 정리 후 소켓 close. */
+  close() {
+    this._isClosing = true
+    // 진행 중인 재시도(백오프 대기/최초 connect)를 취소한다(ADR-098). signal 은 다음 시도를 막는다.
+    this._abort?.abort(new Error('hub-link closing'))
+    this._stopHeartbeat()
+    if (this._ws && this._ws.readyState <= 1) this._ws.close(1000, 'bridge closing')
+  }
+
+  /**
+   * 타입별 송신 — register_ok 이후에만 허용. register 전 호출은 fail-closed throw.
+   * @param {string} type - wire type(`hub.*`).
+   * @param {Object} payload
+   * @returns {void}
+   * @private
+   */
+  _send(type, payload) {
+    if (!this._isRegistered) {
+      throw new Error(`MegaHubLink: cannot send '${type}' before register_ok.`)
+    }
+    this._sendEnvelope(createHubMessage({ type, payload }))
+  }
+
+  /**
+   * envelope 직렬화 후 소켓 송신.
+   * @param {Object} envelope
+   * @returns {void}
+   * @private
+   */
+  _sendEnvelope(envelope) {
+    if (this._ws?.readyState !== 1) {
+      throw new Error('MegaHubLink: socket is not open.')
+    }
+    this._ws.send(JSON.stringify(envelope))
+  }
+
+  /**
+   * 수신 메시지를 등록된 핸들러에 디스패치. 핸들러 throw 는 격리(다른 핸들러 보호).
+   * @param {import('../lib/hub-protocol.js').HubEnvelope} msg
+   * @returns {void}
+   * @private
+   */
+  _dispatch(msg) {
+    const set = this._handlers.get(msg.type)
+    if (!set || set.size === 0) {
+      this._log?.debug?.({ type: msg.type }, 'hub-link no handler for type')
+      return
+    }
+    for (const fn of set) {
+      try {
+        fn(msg)
+      } catch (err) {
+        // 한 핸들러 throw 가 나머지 디스패치를 막지 않도록 격리 + 로그.
+        this._log?.warn?.({ err, type: msg.type }, 'hub-link handler threw')
+      }
+    }
+  }
+
+  /**
+   * 라이프사이클 이벤트 emit (RECONNECTED 등). 디스패치와 같은 핸들러 맵을 쓰되 인자는 이벤트 데이터.
+   * @param {string} event - {@link MegaHubLink.EVENTS} 값.
+   * @param {Object} data
+   * @returns {void}
+   * @private
+   */
+  _emit(event, data) {
+    const set = this._handlers.get(event)
+    if (!set) return
+    for (const fn of set) {
+      try {
+        fn(data)
+      } catch (err) {
+        this._log?.warn?.({ err, event }, 'hub-link lifecycle handler threw')
+      }
+    }
+  }
+
+  /** heartbeat 루프 시작 (heartbeatMs>0 일 때만). 프로세스 종료 막지 않게 unref. @private */
+  _startHeartbeat() {
+    if (this._heartbeatMs <= 0) return
+    this._hbTimer = setInterval(() => {
+      try {
+        this._sendEnvelope(createHubMessage({ type: T.HEARTBEAT, payload: { at: Date.now() } }))
+      } catch (err) {
+        // 송신 실패 = 소켓 닫히는 중. 비치명적 — close 핸들러가 정리(이유+로그).
+        this._log?.debug?.({ err, bridgeId: this._bridgeId }, 'hub-link heartbeat send failed')
+      }
+    }, this._heartbeatMs)
+    this._hbTimer.unref?.()
+  }
+
+  /** heartbeat 루프 정지. @private */
+  _stopHeartbeat() {
+    if (this._hbTimer) {
+      clearInterval(this._hbTimer)
+      this._hbTimer = null
+    }
+  }
+}