@qzsy/dsh-bridge 0.0.0-stage → 2.18.0

package/lib/saas/tunnel-client.mjs

@@ -0,0 +1,695 @@
+// DSH Bridge - SaaS 隧道客户端（控制通道协议 v2）
+//
+// 契约见 docs/architecture/saas-tunnel.md §6（消息名/字段名不可擅自改名）与
+// packages/tunnel-protocol/src/index.ts（共享类型）：
+//   C→S 首帧 hello → S→C hello-ack(ok=true|false) → 之后沿用 v1 转发消息
+//   （request / response / response-start|chunk|end / ws-open|accept|frame|close / ping|pong）
+//   v2 新增：heartbeat / heartbeat-ack、route-update、drain
+//
+// 设计：继承 lib/tunnel-client.mjs 的 CustomTunnelClient，HTTP/WS 转发语义（含 32MB
+// 上限、gzip、session 投影剥离、Ping 自动 Pong）完全复用父类，本类只替换连接建立、
+// 心跳、重连与 v2 控制消息处理，避免两套转发实现漂移。
+
+import { WebSocket } from 'ws';
+import { CustomTunnelClient } from '../tunnel-client.mjs';
+
+export const SAAS_HEARTBEAT_INTERVAL_MS = 30_000;
+export const SAAS_HEARTBEAT_MAX_MISSED = 3;
+export const SAAS_HANDSHAKE_TIMEOUT_MS = 15_000;
+export const SAAS_RECONNECT_BASE_DELAY_MS = 1000;
+export const SAAS_RECONNECT_MAX_DELAY_MS = 60_000;
+export const SAAS_RECONNECT_MAX_ATTEMPTS = Number.POSITIVE_INFINITY;
+export const SAAS_DEFAULT_GATEWAY_PATH = '/_gw/connect';
+
+/** 控制通道关闭码：4001 认证失败 / 4003 已吊销 → 终态，不再重连（契约 §4.2）。 */
+export const SAAS_TERMINAL_CLOSE_CODES = new Set([4001, 4003]);
+
+/** hello-ack 失败码里的终态集合（quota 视为可重试）。 */
+export const SAAS_TERMINAL_ERROR_CODES = new Set(['auth_failed', 'revoked', 'bad_request', 'unsupported_version']);
+
+/** SaaS 隧道协议/连接错误。terminal=true 表示不应再自动重连。 */
+export class SaasTunnelError extends Error {
+  constructor(code, message, { terminal = false, closeCode = 0, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'SaasTunnelError';
+    this.code = code;
+    this.terminal = terminal;
+    this.closeCode = closeCode;
+  }
+}
+
+/**
+ * 拼接控制通道连接地址：{gatewayUrl}{gatewayPath}?device_token=<JWT>。
+ * 契约 §6 允许 query 或 Authorization 头传令牌，这里两者都带（兼容只认一种的网关）。
+ *
+ * @param {{gatewayUrl: string, gatewayPath?: string, deviceToken?: string}} options
+ * @returns {string}
+ * @throws {SaasTunnelError} 地址非法
+ */
+export function buildSaasConnectUrl({ gatewayUrl, gatewayPath = SAAS_DEFAULT_GATEWAY_PATH, deviceToken } = {}) {
+  let url;
+  try {
+    url = new URL(String(gatewayUrl ?? '').trim());
+  } catch {
+    throw new SaasTunnelError('invalid_gateway_url', `SaaS 网关连接地址不是合法 URL: ${gatewayUrl}`);
+  }
+  if (url.protocol === 'http:') url.protocol = 'ws:';
+  else if (url.protocol === 'https:') url.protocol = 'wss:';
+  else if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+    throw new SaasTunnelError('invalid_gateway_url', 'SaaS 网关连接地址只支持 ws/wss/http/https');
+  }
+  const path = String(gatewayPath ?? '') || SAAS_DEFAULT_GATEWAY_PATH;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  const basePath = url.pathname.replace(/\/+$/, '');
+  url.pathname = `${basePath}${normalizedPath}`.replace(/\/{2,}/g, '/');
+  url.search = '';
+  url.hash = '';
+  if (deviceToken) url.searchParams.set('device_token', deviceToken);
+  return url.toString();
+}
+
+/**
+ * 从 routes 里挑公网地址：优先 host 形态，其次第一条带 url 的路由。
+ * @param {Array<{kind?: string, url?: string}>|null|undefined} routes
+ * @returns {string|null}
+ */
+export function pickRoutePublicUrl(routes) {
+  if (!Array.isArray(routes)) return null;
+  const list = routes.filter((route) => route && typeof route === 'object');
+  const host = list.find((route) => route.kind === 'host' && typeof route.url === 'string' && route.url);
+  if (host) return host.url;
+  const any = list.find((route) => typeof route.url === 'string' && route.url);
+  return any ? any.url : null;
+}
+
+function normalizeDevicePlatform(value) {
+  const text = String(value ?? '').trim();
+  return text || 'unknown';
+}
+
+export class SaasTunnelClient extends CustomTunnelClient {
+  /**
+   * @param {object} options
+   * @param {string} options.gatewayUrl 数据面网关地址（token 接口返回的 gateway.url，或由控制面地址推导）
+   * @param {string} [options.gatewayPath] 控制通道路径，默认 /_gw/connect
+   * @param {() => Promise<string|{token: string, gateway?: object, tunnel?: object}>} [options.tokenProvider]
+   *   每次（重）连前取新短期令牌；返回对象时可用 gateway/tunnel 覆盖缓存
+   * @param {string} [options.deviceToken] 初始令牌（无 tokenProvider 时使用）
+   * @param {object} [options.deviceInfo] hello.device（name/platform/hostname/arch/pluginVersion/dshVersion）
+   * @param {object} [options.caps] hello.caps 覆盖项
+   * @param {'auto'|'v2'} [options.protocol] auto：兼容旧网关先发 ready 的 v1 降级；v2：严格等 hello-ack
+   * @param {number} [options.heartbeatIntervalMs] 心跳间隔（默认 30s）
+   * @param {number} [options.heartbeatMaxMissed] 连续缺失 ack 多少次判定失效（默认 3）
+   * @param {number} [options.reconnectBaseDelayMs]
+   * @param {number} [options.reconnectMaxDelayMs]
+   * @param {number} [options.maxReconnectAttempts] 默认无限（终态除外）
+   * @param {() => number} [options.random] 测试注入抖动随机源
+   * @param {Function} [options.onHelloAck]
+   * @param {Function} [options.onRouteUpdate]
+   * @param {Function} [options.onDrain]
+   * @param {Function} [options.onDrainComplete]
+   */
+  constructor({
+    gatewayUrl,
+    gatewayPath = SAAS_DEFAULT_GATEWAY_PATH,
+    tokenProvider,
+    deviceToken,
+    deviceInfo = {},
+    caps = {},
+    protocol = 'auto',
+    heartbeatIntervalMs = SAAS_HEARTBEAT_INTERVAL_MS,
+    heartbeatMaxMissed = SAAS_HEARTBEAT_MAX_MISSED,
+    reconnectBaseDelayMs = SAAS_RECONNECT_BASE_DELAY_MS,
+    reconnectMaxDelayMs = SAAS_RECONNECT_MAX_DELAY_MS,
+    maxReconnectAttempts = SAAS_RECONNECT_MAX_ATTEMPTS,
+    random = Math.random,
+    localPort,
+    internalTunnelSecret,
+    signal,
+    onStateChange,
+    logger,
+    sseStreaming = false,
+    onHelloAck,
+    onRouteUpdate,
+    onDrain,
+    onDrainComplete,
+  } = {}) {
+    super({
+      serverUrl: gatewayUrl,
+      accessToken: deviceToken,
+      localPort,
+      internalTunnelSecret,
+      signal,
+      onStateChange,
+      logger,
+      sseStreaming,
+    });
+    this.gatewayUrl = gatewayUrl ?? '';
+    this.gatewayPath = gatewayPath || SAAS_DEFAULT_GATEWAY_PATH;
+    if (typeof tokenProvider === 'function') {
+      this.tokenProvider = tokenProvider;
+    } else if (deviceToken) {
+      this.tokenProvider = async () => String(deviceToken);
+    } else {
+      this.tokenProvider = null;
+    }
+    this.deviceToken = deviceToken ?? null;
+    this.deviceInfo = deviceInfo ?? {};
+    this.caps = caps ?? {};
+    this.protocol = protocol === 'v2' ? 'v2' : 'auto';
+    this.protocolVersion = 2;
+    // 下限取 10ms 只服务于单测注入；生产配置在 lib/index.js 收敛到 >= 5s
+    this.heartbeatIntervalMs = Math.max(10, Number(heartbeatIntervalMs) || SAAS_HEARTBEAT_INTERVAL_MS);
+    this.heartbeatMaxMissed = Math.max(1, Number(heartbeatMaxMissed) || SAAS_HEARTBEAT_MAX_MISSED);
+    this.reconnectBaseDelayMs = Math.max(10, Number(reconnectBaseDelayMs) || SAAS_RECONNECT_BASE_DELAY_MS);
+    this.reconnectMaxDelayMs = Math.max(this.reconnectBaseDelayMs, Number(reconnectMaxDelayMs) || SAAS_RECONNECT_MAX_DELAY_MS);
+    this.maxReconnectAttempts = Number.isFinite(maxReconnectAttempts) ? Math.max(0, maxReconnectAttempts) : Number.POSITIVE_INFINITY;
+    this._random = typeof random === 'function' ? random : Math.random;
+
+    this.tunnel = null;
+    this.routes = [];
+    this.routeRev = 0;
+    this.limits = null;
+    this.features = null;
+    this.sessionId = null;
+    this.serverTime = null;
+    this.lastAckAt = null;
+    this.lastError = null;
+    this._missedHeartbeatAcks = 0;
+    this._awaitingHeartbeatAck = false;
+    this._requestsInFlight = new Set();
+    this._bytesIn = 0;
+    this._bytesOut = 0;
+    this._terminal = false;
+    this._draining = false;
+    this._drainFinished = false;
+    this._drainTimer = null;
+    this._drainDeadlineTimer = null;
+    this._connecting = false;
+    this._publicUrlLockedByRoutes = false;
+
+    this.onHelloAck = onHelloAck;
+    this.onRouteUpdate = onRouteUpdate;
+    this.onDrain = onDrain;
+    this.onDrainComplete = onDrainComplete;
+  }
+
+  /** 是否已进入终态（认证失败/吊销/协议拒绝）：终态后不再自动重连。 */
+  get terminal() {
+    return this._terminal;
+  }
+
+  /** 是否正在 drain 优雅退出。 */
+  get draining() {
+    return this._draining;
+  }
+
+  async connect() {
+    if (this.connected || this._connecting) return;
+    if (this.disconnecting || this._terminal) return;
+    this._connecting = true;
+    this._setState('connecting', '正在连接 SaaS 网关…');
+    try {
+      const tokenInfo = await this._acquireToken();
+      this.deviceToken = tokenInfo.token;
+      this.serverUrl = tokenInfo.gateway?.url || this.gatewayUrl;
+      await this._connectWebSocket();
+      this._startHeartbeat();
+      this.reconnectAttempts = 0;
+      this.lastError = null;
+      this.protocolVersion = this.protocolVersion || 2;
+      this._setState('ready', this.publicUrl ? `SaaS 隧道已建立 (${this.publicUrl})` : 'SaaS 隧道已建立');
+    } catch (err) {
+      this.connected = false;
+      this._stopHeartbeat();
+      const terminal = this._isTerminalError(err) || this._terminal;
+      const detail = err?.message ?? String(err);
+      this.lastError = detail;
+      if (terminal) {
+        this._terminal = true;
+        this._setState('error', detail);
+      } else if (this.disconnecting || this.signal?.aborted) {
+        this._setState('idle', '连接已取消');
+      } else {
+        this._scheduleReconnect(detail);
+      }
+      throw err;
+    } finally {
+      this._connecting = false;
+    }
+  }
+
+  _isTerminalError(err) {
+    if (!err) return false;
+    if (err.terminal === true) return true;
+    return SAAS_TERMINAL_ERROR_CODES.has(String(err.code ?? ''));
+  }
+
+  async _acquireToken() {
+    if (!this.tokenProvider) {
+      throw new SaasTunnelError('missing_device_credentials', 'SaaS 设备凭证缺失，请重新绑定设备', { terminal: true });
+    }
+    const result = await this.tokenProvider();
+    const token = typeof result === 'string' ? result : result?.token;
+    if (!token) {
+      throw new SaasTunnelError('missing_device_token', 'SaaS 设备令牌获取失败，请重新绑定设备', { terminal: true });
+    }
+    if (result && typeof result === 'object') {
+      if (result.gateway?.url) {
+        this.gatewayUrl = result.gateway.url;
+        this.serverUrl = result.gateway.url;
+      }
+      if (result.gateway?.path) this.gatewayPath = result.gateway.path;
+      if (result.tunnel) this.tunnel = result.tunnel;
+    }
+    return { token: String(token), gateway: { url: this.gatewayUrl, path: this.gatewayPath } };
+  }
+
+  _connectWebSocket() {
+    return new Promise((resolve, reject) => {
+      if (this.signal?.aborted) {
+        reject(new Error('Aborted'));
+        return;
+      }
+
+      let ws;
+      try {
+        ws = new WebSocket(buildSaasConnectUrl({
+          gatewayUrl: this.gatewayUrl,
+          gatewayPath: this.gatewayPath,
+          deviceToken: this.deviceToken,
+        }), {
+          handshakeTimeout: 10_000,
+          headers: this.deviceToken ? { authorization: `Bearer ${this.deviceToken}` } : undefined,
+          perMessageDeflate: {
+            clientNoContextTakeover: true,
+            serverNoContextTakeover: true,
+            clientMaxWindowBits: 15,
+            serverMaxWindowBits: 15,
+          },
+        });
+      } catch (err) {
+        reject(new SaasTunnelError('invalid_gateway_url', err?.message ?? String(err), { terminal: true, cause: err }));
+        return;
+      }
+      this.ws = ws;
+
+      let settled = false;
+      let handshakeTimer = null;
+      let handshakeHandler = null;
+      const cleanupHandshake = () => {
+        if (handshakeTimer) {
+          clearTimeout(handshakeTimer);
+          handshakeTimer = null;
+        }
+        if (handshakeHandler) {
+          ws.off('message', handshakeHandler);
+          handshakeHandler = null;
+        }
+        this.signal?.removeEventListener?.('abort', onAbort);
+      };
+      const settle = (err) => {
+        if (settled) return;
+        settled = true;
+        cleanupHandshake();
+        if (err) reject(err);
+        else resolve();
+      };
+      const onAbort = () => {
+        try { ws.terminate(); } catch {}
+        settle(new Error('Aborted'));
+      };
+      this.signal?.addEventListener?.('abort', onAbort, { once: true });
+
+      ws.on('open', () => {
+        this.logger?.info?.('SaaS tunnel WebSocket connected');
+        this._sendHello();
+      });
+
+      ws.on('message', (data) => this._handleMessage(data));
+
+      handshakeHandler = (data) => {
+        let msg;
+        try {
+          msg = JSON.parse(typeof data === 'string' ? data : data.toString());
+        } catch {
+          return;
+        }
+        if (msg?.type === 'hello-ack') {
+          if (msg.ok === false) {
+            const code = String(msg.error?.code ?? 'bad_request');
+            const message = String(msg.error?.message ?? '');
+            const detail = `SaaS 网关拒绝握手: ${message || code} (${code})`;
+            if (SAAS_TERMINAL_ERROR_CODES.has(code)) {
+              this._terminal = true;
+              this.lastError = detail;
+              this._setState('error', detail);
+              try { ws.terminate(); } catch {}
+              settle(new SaasTunnelError(code, detail, { terminal: true }));
+              return;
+            }
+            try { ws.terminate(); } catch {}
+            settle(new SaasTunnelError(code, detail));
+            return;
+          }
+          this._handleHelloAck(msg);
+          settle();
+          return;
+        }
+        if (msg?.type === 'ready' && !settled) {
+          if (this.protocol === 'v2') return;
+          // auto 兼容：老网关只发 ready（v1 行为）→ 按 v1 继续，不改写状态机
+          this.protocolVersion = 1;
+          this.publicUrl = String(msg.publicUrl ?? '') || this.publicUrl;
+          this.connected = true;
+          this.logger?.warn?.('SaaS tunnel ready without hello-ack, falling back to protocol v1');
+          settle();
+        }
+      };
+      ws.on('message', handshakeHandler);
+
+      ws.on('close', (code, reason) => {
+        this.connected = false;
+        this._stopHeartbeat();
+        this._cleanupLocalWs();
+        const reasonText = reason?.toString?.() ?? '';
+        if (SAAS_TERMINAL_CLOSE_CODES.has(code)) {
+          this._terminal = true;
+          const detail = `SaaS 网关关闭连接 (${code}${reasonText ? `: ${reasonText}` : ''})，请重新绑定设备`;
+          this.lastError = detail;
+          this._setState('error', detail);
+          settle(new SaasTunnelError('connection_closed', detail, { terminal: true, closeCode: code }));
+          return;
+        }
+        if (!settled) {
+          settle(new SaasTunnelError('connection_closed', `SaaS 网关在握手完成前断开 (code=${code})`, { closeCode: code }));
+          return;
+        }
+        if (this.signal?.aborted || this.disconnecting || this._draining) return;
+        this.logger?.warn?.('SaaS tunnel disconnected: code=%d, reason=%s', code, reasonText);
+        this.lastError = `SaaS 网关连接已断开 (code=${code})`;
+        this._scheduleReconnect(this.lastError);
+      });
+
+      ws.on('error', (err) => {
+        this.logger?.error?.('SaaS tunnel WebSocket error: %s', err?.message ?? err);
+        if (!settled) settle(err);
+      });
+
+      handshakeTimer = setTimeout(() => {
+        if (settled) return;
+        try { ws.terminate(); } catch {}
+        settle(new SaasTunnelError('handshake_timeout', 'SaaS 网关握手超时（15s 内未收到 hello-ack）'));
+      }, SAAS_HANDSHAKE_TIMEOUT_MS);
+    });
+  }
+
+  _sendHello() {
+    const device = {};
+    for (const key of ['name', 'platform', 'hostname', 'pluginVersion', 'dshVersion']) {
+      const value = this.deviceInfo?.[key];
+      if (value !== undefined && value !== null && String(value).trim()) device[key] = String(value).trim();
+    }
+    if (!device.name) device.name = device.hostname || 'DSH Bridge';
+    if (!device.platform) device.platform = normalizeDevicePlatform(undefined);
+    const hello = {
+      type: 'hello',
+      v: 2,
+      device,
+      caps: {
+        sseStreaming: Boolean(this.sseStreaming),
+        wsFrames: true,
+        maxResponseBytes: 32 * 1024 * 1024,
+        ...(this.caps ?? {}),
+      },
+      ts: Math.floor(Date.now() / 1000),
+    };
+    this.logger?.info?.('SaaS tunnel hello sent (device=%s)', device.name);
+    this._sendMessage(hello);
+  }
+
+  _handleHelloAck(msg) {
+    this.protocolVersion = Number(msg?.v) || 2;
+    this.sessionId = msg?.sessionId ?? null;
+    if (msg?.tunnel) {
+      this.tunnel = {
+        publicId: String(msg.tunnel.publicId ?? ''),
+        name: String(msg.tunnel.name ?? ''),
+      };
+    }
+    this.limits = msg?.limits ?? null;
+    this.features = msg?.features ?? null;
+    this.serverTime = msg?.serverTime ?? null;
+    if (this.limits?.heartbeatMs) {
+      this.heartbeatIntervalMs = Math.max(10, Number(this.limits.heartbeatMs) || this.heartbeatIntervalMs);
+    }
+    this._applyRoutes(msg?.routes);
+    this.connected = true;
+    this.reconnectAttempts = 0;
+    this.lastAckAt = Date.now();
+    this.onHelloAck?.(msg);
+    this.logger?.info?.('SaaS tunnel hello-ack ok (publicId=%s, routes=%d)', this.tunnel?.publicId ?? '', this.routes.length);
+  }
+
+  _applyRoutes(routes) {
+    const list = Array.isArray(routes) ? routes.filter((route) => route && typeof route === 'object') : [];
+    this.routes = list;
+    const hostRoute = list.find((route) => route.kind === 'host' && typeof route.url === 'string' && route.url);
+    const picked = hostRoute ?? list.find((route) => typeof route.url === 'string' && route.url);
+    if (picked) {
+      this.publicUrl = String(picked.url);
+      this._publicUrlLockedByRoutes = Boolean(hostRoute);
+    }
+    return list;
+  }
+
+  _handleMessage(data) {
+    let msg;
+    try {
+      msg = JSON.parse(typeof data === 'string' ? data : data.toString());
+    } catch (err) {
+      this.logger?.error?.('Failed to parse SaaS tunnel message: %s', err?.message ?? err);
+      return;
+    }
+    switch (msg?.type) {
+      case 'heartbeat-ack':
+        this._handleHeartbeatAck(msg);
+        return;
+      case 'route-update':
+        this._handleRouteUpdate(msg);
+        return;
+      case 'drain':
+        this._handleDrain(msg);
+        return;
+      case 'ping':
+        this._sendMessage({ type: 'pong', ts: Date.now() });
+        return;
+      case 'hello-ack':
+      case 'ready':
+      case 'pong':
+        // 握手由一次性 handler 负责；运行期重复的 hello-ack/ready 不改变已建立状态
+        if (msg.type === 'ready' && this.connected && !this._publicUrlLockedByRoutes) {
+          if (msg.publicUrl) this.publicUrl = String(msg.publicUrl);
+        }
+        return;
+      case 'request':
+        this._handleHttpRequest(msg);
+        return;
+      case 'ws-open':
+        this._handleWsOpen(msg);
+        return;
+      case 'ws-frame':
+        this._handleWsFrame(msg);
+        return;
+      case 'ws-close':
+        this._handleWsClose(msg);
+        return;
+      default:
+        // 未知 type 必须静默忽略（v1 前后兼容）
+        return;
+    }
+  }
+
+  _handleHeartbeatAck(msg) {
+    this._awaitingHeartbeatAck = false;
+    this._missedHeartbeatAcks = 0;
+    this.lastAckAt = Date.now();
+    if (msg?.serverTime) this.serverTime = msg.serverTime;
+    const actions = Array.isArray(msg?.actions) ? msg.actions : [];
+    if (actions.includes('drain') && !this._draining) {
+      this._startDrain({ deadline: Date.now() + this.heartbeatIntervalMs * 3 });
+    }
+  }
+
+  _handleRouteUpdate(msg) {
+    this.routeRev = Number(msg?.rev) || this.routeRev;
+    this._applyRoutes(msg?.routes);
+    this.logger?.info?.('SaaS tunnel route updated (rev=%s, publicUrl=%s)', this.routeRev, this.publicUrl ?? '');
+    this.onRouteUpdate?.({ routes: this.routes, rev: this.routeRev, publicUrl: this.publicUrl });
+  }
+
+  _handleDrain(msg) {
+    let deadline = Number(msg?.deadline);
+    if (!Number.isFinite(deadline) || deadline <= 0) deadline = Date.now() + this.heartbeatIntervalMs * 3;
+    else if (deadline < 1e12) deadline *= 1000; // 秒级时间戳
+    this._startDrain({ deadline });
+  }
+
+  _startDrain({ deadline } = {}) {
+    if (this._draining) return;
+    this._draining = true;
+    const deadlineMs = Number.isFinite(deadline) && deadline > 0 ? deadline : Date.now() + this.heartbeatIntervalMs * 3;
+    this._setState('draining', 'SaaS 网关正在下线，等待在途请求结束后断开');
+    this.onDrain?.({ deadline: deadlineMs });
+    this.logger?.info?.('SaaS tunnel draining (deadline=%s, inFlight=%d)', deadlineMs, this._requestsInFlight.size);
+    const poll = () => {
+      if (this._drainFinished) return;
+      if (this._requestsInFlight.size === 0 || Date.now() >= deadlineMs) {
+        this._finishDrain();
+        return;
+      }
+      const waitMs = Math.min(250, Math.max(20, deadlineMs - Date.now()));
+      this._drainTimer = setTimeout(poll, waitMs);
+    };
+    this._drainTimer = setTimeout(poll, 20);
+    this._drainDeadlineTimer = setTimeout(() => this._finishDrain(), Math.max(0, deadlineMs - Date.now()) + 1000);
+  }
+
+  _finishDrain() {
+    if (this._drainFinished) return;
+    this._drainFinished = true;
+    this._clearDrainTimers();
+    this.connected = false;
+    this._stopHeartbeat();
+    this._cleanupLocalWs();
+    this._requestsInFlight.clear();
+    const detail = 'SaaS 网关已下线（drain），隧道已优雅断开';
+    this.lastError = detail;
+    this._setState('closed', detail);
+    this.onDrainComplete?.({ detail });
+    try { this.ws?.close(1000, 'drain'); } catch { try { this.ws?.terminate(); } catch {} }
+  }
+
+  _clearDrainTimers() {
+    if (this._drainTimer) {
+      clearTimeout(this._drainTimer);
+      this._drainTimer = null;
+    }
+    if (this._drainDeadlineTimer) {
+      clearTimeout(this._drainDeadlineTimer);
+      this._drainDeadlineTimer = null;
+    }
+  }
+
+  // ── 转发语义复用父类，仅补计数/在途/drain 拒绝 ─────────────────────────
+  _handleHttpRequest(msg) {
+    if (this._draining) {
+      this._sendMessage({
+        type: 'response',
+        requestId: msg?.requestId,
+        statusCode: 503,
+        headers: { 'content-type': 'text/plain; charset=utf-8' },
+        body: Buffer.from('tunnel is draining').toString('base64'),
+      });
+      return;
+    }
+    if (msg?.requestId) this._requestsInFlight.add(msg.requestId);
+    if (typeof msg?.body === 'string' && msg.body) {
+      this._bytesIn += Math.floor((msg.body.length * 3) / 4);
+    }
+    super._handleHttpRequest(msg);
+  }
+
+  _handleWsOpen(msg) {
+    if (this._draining) {
+      this._sendMessage({
+        type: 'ws-accept',
+        wsId: msg?.wsId,
+        statusCode: 503,
+        statusMessage: 'Service Unavailable',
+        replyHeaders: { 'content-type': 'text/plain' },
+      });
+      return;
+    }
+    super._handleWsOpen(msg);
+  }
+
+  _sendMessage(msg) {
+    if (msg && typeof msg === 'object') {
+      if ((msg.type === 'response' || msg.type === 'response-end') && msg.requestId) {
+        this._requestsInFlight.delete(msg.requestId);
+      }
+      if (typeof msg.body === 'string' && msg.body) {
+        this._bytesOut += Math.floor((msg.body.length * 3) / 4);
+      }
+      if (typeof msg.data === 'string' && msg.data) {
+        this._bytesOut += Math.floor((msg.data.length * 3) / 4);
+      }
+    }
+    super._sendMessage(msg);
+  }
+
+  _heartbeatState() {
+    return {
+      requestsInFlight: this._requestsInFlight.size,
+      wsOpen: this.localWsSockets.size,
+      bytesIn: this._bytesIn,
+      bytesOut: this._bytesOut,
+      ...(this.lastError ? { lastError: String(this.lastError).slice(0, 500) } : {}),
+    };
+  }
+
+  _heartbeatTick() {
+    if (!this.connected || this._draining) return;
+    if (this._awaitingHeartbeatAck) {
+      this._missedHeartbeatAcks += 1;
+      if (this._missedHeartbeatAcks >= this.heartbeatMaxMissed) {
+        const detail = `SaaS 网关心跳连续 ${this._missedHeartbeatAcks} 次未确认，主动重连`;
+        this.lastError = detail;
+        this._setState('reconnecting', detail);
+        this._stopHeartbeat();
+        try { this.ws?.terminate(); } catch {}
+        return;
+      }
+    }
+    this._awaitingHeartbeatAck = true;
+    this._sendMessage({ type: 'heartbeat', ts: Date.now(), state: this._heartbeatState() });
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this._missedHeartbeatAcks = 0;
+    this._awaitingHeartbeatAck = false;
+    this.heartbeatTimer = setInterval(() => this._heartbeatTick(), this.heartbeatIntervalMs);
+    this._heartbeatTick();
+  }
+
+  _scheduleReconnect(reason) {
+    if (this.signal?.aborted || this.disconnecting || this._terminal || this._draining) return;
+    if (this.reconnectTimer) return;
+    if (Number.isFinite(this.maxReconnectAttempts) && this.reconnectAttempts >= this.maxReconnectAttempts) {
+      const detail = `SaaS 隧道重连已达上限 (${this.maxReconnectAttempts} 次)`;
+      this.lastError = detail;
+      this._setState('error', detail);
+      return;
+    }
+    this.reconnectAttempts += 1;
+    const attempt = this.reconnectAttempts;
+    const baseDelay = Math.min(this.reconnectBaseDelayMs * 2 ** (attempt - 1), this.reconnectMaxDelayMs);
+    const jitter = 0.75 + this._random() * 0.5;
+    const delay = Math.max(50, Math.round(baseDelay * jitter));
+    const seconds = Math.round((delay / 1000) * 10) / 10;
+    this._setState('reconnecting', `SaaS 隧道断开${reason ? `：${reason}` : ''}，${seconds}s 后重连（第 ${attempt} 次）`);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.connect().catch(() => {});
+    }, delay);
+  }
+
+  disconnect() {
+    this._clearDrainTimers();
+    this._drainFinished = true;
+    this._requestsInFlight.clear();
+    super.disconnect();
+  }
+}