Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { isPeerResetRetryableInvoke, bypassInvokeScheduling, resolveInvokePriority } from './invokePolicy.js';
import { InvokeScheduler } from './invokeScheduler.js';
import { SessionMessageReuse } from './sessionMessageReuse.js';
import {
InboundInvokeTransferOptions,
InvokeResultCache,
encodeInvokeResultTransfer,
type DeviceLinkTransferCodec,
} from './invokeTransfer.js';
import { decodeScopedEnvelope, encodeScopedEnvelope, type ScopeSupport } from './providerShareEnvelope.js';
import { isProviderSharePeer, parseProviderSharePeer } from './providerSharePeer.js';
import { isSharedTaskPeer } from './sharedTaskPeer.js';
import { PROVIDER_SHARE_RELAY_CAPABILITY, PROVIDER_SHARE_DIRECT_SIGNAL_CAPABILITY, ROUTED_KINDS, SHARED_TASK_RELAY_CAPABILITY } from '@cindy/device-link-protocol';
import {
requestSessionTagCatalog,
decodeSessionTagCatalog,
decodeModelSpeedPayload,
encodeModelSpeedPayload,
} from './sessionListTransport.js';
import { CongestionSendBudget } from './congestionSendBudget.js';
import { PUSH_FORWARD_ALLOWLIST, REMOTE_INVOKE_ALLOWLIST } from './allowlist.js';
import {
PROTOCOL_VERSION,
MAX_FRAME_BYTES,
SERVER_CAPABILITY_NOTIFY,
DeviceLinkError,
isScopedPeer,
type Envelope,
type HelloPayload,
type HelloAckPayload,
type NotifyPayload,
type PresenceSetPayload,
type PresenceSnapshot,
type RelayErrorPayload,
type LinkOpenPayload,
type InvokePayload,
type InvokeResultPayload,
type LinkAcceptPayload,
type LinkCloseReason,
type LinkClosePayload,
} from './protocol.js';
import {
DEVICE_LINK_CAPABILITY_RELIABLE_LINK_CONFIRM,
DEVICE_LINK_CAPABILITY_RELIABLE_TRANSPORT,
DEVICE_LINK_CAPABILITY_TRANSPORT_TIMEOUT_CLOSE,
DEVICE_LINK_TRANSPORT_ACK_CHANNEL,
MAX_TRANSPORT_CHUNK_BYTES,
MAX_TRANSPORT_PENDING_BYTES,
MAX_TRANSPORT_PENDING_MESSAGES,
MAX_TRANSPORT_REASSEMBLIES,
MAX_TRANSPORT_REASSEMBLY_BYTES,
MAX_TRANSPORT_SEQUENCE_WINDOW,
MAX_TRANSPORT_WEBSOCKET_BUFFERED_BYTES,
TRANSPORT_MAX_RETRY_ATTEMPTS,
TRANSPORT_PENDING_PUSH_MAX_AGE_MS,
TRANSPORT_RETRY_INTERVAL_MS,
TRANSPORT_RETRY_PASS_BUDGET,
decodeTransportJson,
encodeReliableFrames,
isTransportSkipPayload,
makeTransportAck,
makeTransportSkipPayload,
parseTransportAck,
parseTransportPayload,
reliableRetryDelayMs,
retransmitBaseMs,
updateRetransmitEstimate,
updateDeliveryEstimate,
byteLength,
type RetransmitEstimate,
} from './transport.js';
import { PLUGIN_SYNC_CHANNEL } from './pluginSyncProtocol.js';
import { RELAY_AUTH_CHANNEL, relayAuthHandshake } from './selfHostedRelayAuth.js';
import { DIRECT_LINK_CAPABILITY, DIRECT_LINK_SIGNAL, PROVIDER_SHARE_DIRECT_CAPABILITY, DirectLinkNegotiator, parseDirectSignal,
type DirectRuntime } from './directNegotiation.js';
import { MAKER_EVENT_BATCH_CHANNEL } from './topics.js';
import {
DIRECT_PATH_HIGH_WATER_BYTES,
PROVIDER_SHARE_DIRECT_LEASE_MS,
type DeviceLinkDirectChannel,
type DeviceLinkDirectCloseReason,
type DeviceLinkDirectPathHandle,
type DeviceLinkPeerPath,
type DeviceLinkPeerPathChanged,
} from './directPath.js';
/** Budget measurement: physical wire envelope size regardless of relay announcement. */
const ALL_SCOPES: ScopeSupport = { sharedTask: true, providerShare: true };
const DUPLICATE_CONNECTION_CLOSE_CODE = 4409;
/** RFC 6455 1013 Try Again Later:relay 因拥塞主动断连(如 inbound backpressure)。 */
const RELAY_TRY_AGAIN_LATER_CLOSE_CODE = 1013;
/**
* latest-wins 腾位适用的**可驱逐通道白名单**(review 三轮收敛:contacts-sync
* 黑名单 → 白名单 → 收缩到单通道)。push 单 FIFO 上混着三类语义,只有第一类
* 可以参与传输层 latest-wins:
*
* - 自相似有损事件流(本表:maker:event 及其微批帧):流内每帧价值均匀且整流
* 已是契约——旧语义拥塞时本就丢**最新**帧(admission 拒收后 forwardPush 按
* best-effort 放弃),换成丢最旧不引入新的损失面;转录内容由受保护的
* local-db:messages:created + 控制端消息对账自愈,会话运行态由受保护的
* status / activity 通道承载。微批帧(MAKER_EVENT_BATCH_CHANNEL)与逐帧
* **必须同档**:它只是同一事件流的聚合体,漏登记会让启用微批的控制端在拥塞
* 时退回 BACKPRESSURE 风暴(正是微批要消除的那一个)。
* - 键控/终态快照(sessions:activity、maker:input:projection):看似「镜像」
* 但**不满足跨帧可替代**——快照按 sessionId 键控,会话的 completed/error
* 收尾快照是该键的最后一帧,被其它键/其它通道的洪峰驱逐后不会再有后继帧
* 补偿;sessions:activity 的 staging(dispatch 层 latest-wins)在 sendPush
* 成功后即删暂存、不再重试,link 不重连 reseed 也不会跑,驱逐 = 手机端
* 永远显示 running(review 第三轮)。传输层不做同键比较(head-only 前缀
* 约束下同键驱逐在多会话混流时够不着队头,机制无效),这类通道整体回到
* 原背压语义,由各自上游的整流/重试契约保证送达。
* - 不可合并事件/流控数据(local-db:messages:created、确认卡、fs-watch、
* contacts-sync 分片等):静默驱逐 = UI 永久漏事件或传输永久拼不出。
*
* 新增 push 通道默认**不可驱逐**(fail-closed);要进本表必须论证「流内自
* 相似、无键控终态、丢帧可由受保护通道自愈」三点。
*/
const COALESCIBLE_PUSH_CHANNELS: ReadonlySet<string> = new Set([
'maker:event',
MAKER_EVENT_BATCH_CHANNEL,
]);
/** push 拥塞驱逐告警的 per-peer 聚合窗口:洪峰期逐条 warn 本身就是新的风暴。 */
const PUSH_ADMISSION_DROP_LOG_INTERVAL_MS = 5_000;
/** 单个 peer 的路由账本上限;满时拒绝新发送,绝不淘汰仍可能收到错误的旧记录。 */
const MAX_OUTBOUND_ROUTE_IDS_PER_PEER = 1_024;
/** 全 client 的硬上限;达到后同样以背压停发,不用别的 peer 的记录换空间。 */
const MAX_OUTBOUND_ROUTE_IDS_TOTAL = 16_384;
/** 同一逻辑帧跨 link generation 的记录上限;同代重发用计数压缩。 */
const MAX_OUTBOUND_ROUTE_GENERATION_RUNS_PER_ID = 256;
/** 已结算记录不占发送额度;仅保留近期代次供迟到 relay-error 归属。 */
const MAX_SETTLED_OUTBOUND_ROUTE_IDS_PER_PEER = 1_024;
const MAX_SETTLED_OUTBOUND_ROUTE_IDS_TOTAL = 16_384;
/** Signals are best-effort, but their route errors must never tear down a reliable link. */
const MAX_PROVIDER_SHARE_SIGNAL_ROUTE_IDS = 16_384;
const PROVIDER_SHARE_SIGNAL_ROUTE_TTL_MS = 2 * 60_000;
/**
* 该 push channel 是否属于可驱逐档(latest-wins 腾位的唯一判据入口)。
* 导出供上层断言「新增的聚合/整流 channel 已与其源 channel 同档」——漏登记会让
* 拥塞时退回 BACKPRESSURE 风暴,而这类漏登记只有对着判据本身断言才拦得住。
*/
export function isCoalesciblePushChannel(channel: string): boolean {
return COALESCIBLE_PUSH_CHANNELS.has(channel);
}
function isCoalesciblePushEnvelope(env: Envelope): boolean {
if (env.kind !== 'push') return false;
const payload = env.payload as { channel?: unknown } | undefined;
return typeof payload?.channel === 'string'
&& isCoalesciblePushChannel(payload.channel);
}
/** 连续握手超时达到该次数后,握手窗口翻倍(见 armHandshakeTimeout)。 */
const HANDSHAKE_TIMEOUT_WIDEN_AFTER = 2;
/** 「link 未就绪收到可靠帧」通知的 per-peer 节流(见 onReliableFrameBeforeLink)。 */
const STALE_LINK_NOTIFY_THROTTLE_MS = 30_000;
const SLOW_REQUEST_WARN_MS = 1_000;
/** Local transport admission must not consume a remote handler's response budget. */
const REQUEST_SEND_WAIT_MAX_MS = 10_000;
// Stop bulk writes well before the native socket's hard limit. Control envelopes
// retain the hard-limit headroom; healthy sockets that drain immediately stay unpaced.
const SOCKET_DATA_HIGH_WATER_BYTES = 512 * 1024;
const SOCKET_DATA_LOW_WATER_BYTES = 128 * 1024;
const SOCKET_CONTROL_RESERVE_BYTES = 64 * 1024;
const SOCKET_SEND_CREDIT_BYTES = 64 * 1024;
/**
* 接收端累计 ACK 的推进粒度。整批 drain 完成前完全不 ACK 会让发送端把
* 已成功处理的前缀也等在慢 handler 后面。小批量 ACK 让发送端及时释放
* 窗口;不提前确认尚未处理的消息,也不改变发送端的重试间隔与预算。
*/
const RELIABLE_ACK_BATCH_MESSAGES = 2;
const RELIABLE_ACK_BATCH_BYTES = 256 * 1024;
const RECOVERY_TRACE_WINDOW_MS = 30_000;
// Allow slow relay -> controller delivery before duplicating an entire message.
// With the default 2s tick this allows 8KiB/s, capped at 120s per attempt. Small
// messages retain their existing retry cadence; dead peers still exhaust retries.
const RELIABLE_RETRY_BYTES_PER_INTERVAL = 16 * 1024;
const RELIABLE_RETRY_MAX_SIZE_INTERVALS = 60;
/** 连续三次握手成功后仍没撑过稳定期,才把普通抖动升级为可见问题。 */
const SHORT_LIVED_STREAK_LIMIT = 3;
const MAX_LEGACY_INBOUND_FRAMES = 128;
const MAX_LEGACY_INBOUND_BYTES = 16 * 1024 * 1024;
const MAX_PENDING_INBOUND_LINK_OFFERS = 64;
const MAX_UNLINKED_LEGACY_RESPONSE_IDS = 128;
type DeviceLinkCrypto = {
randomUUID?: () => string;
getRandomValues?: <T extends Uint8Array>(array: T) => T;
};
function createRequestId(): string {
const cryptoLike = (globalThis as { crypto?: DeviceLinkCrypto }).crypto;
if (typeof cryptoLike?.randomUUID === 'function') {
return cryptoLike.randomUUID();
}
if (typeof cryptoLike?.getRandomValues === 'function') {
const bytes = cryptoLike.getRandomValues(new Uint8Array(16));
bytes[6] = (bytes[6] & 0x0f) | 0x40;
bytes[8] = (bytes[8] & 0x3f) | 0x80;
return uuidFromBytes(bytes);
}
return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
const n = Math.floor(Math.random() * 16);
return (c === 'x' ? n : (n & 0x3) | 0x8).toString(16);
});
}
function uuidFromBytes(bytes: Uint8Array): string {
const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
}
/**
* DeviceLinkClient —— 设备端到 relay(apps/server)的 WS 客户端状态机。
*
* 职责:
* - 连接生命周期:connect → hello 握手 → online;断线指数退避重连(1s → 30s)
* - 应用层心跳:online 后每 20s 发 ping;连续 2 个周期无 pong 视为僵死,强制重连
* - 请求配对:invoke / link-open 按 id 关联响应,超时 reject(INVOKE_TIMEOUT)
* - 入站分发:presence-changed / 隧道帧(invoke / link-open / link-close / push)
* 通过回调交给 host;响应帧(invoke-result / link-accept / relay-error)优先匹配 pending 请求
*
* Electron-agnostic:WebSocket 实现、token、设备信息全部由 host 注入。
*/
// ─── host 注入契约 ────────────────────────────────────────────────────────────
/** ws 库风格的最小 socket 接口(host 注入 ctor;测试注入 fake) */
export interface WsLike {
send(data: string): void;
close(code?: number, reason?: string): void;
terminate?(): void;
/** browser / ws 都提供的发送缓冲字节数;缺省表示 host 无法观测。 */
readonly bufferedAmount?: number;
on(event: 'open', cb: () => void): void;
on(event: 'message', cb: (data: { toString(): string }) => void): void;
on(event: 'close', cb: (code: number, reason?: unknown) => void): void;
on(event: 'error', cb: (err: Error) => void): void;
}
/**
* 创建一条带鉴权 header 的 ws 连接。允许返回 Promise —— host 建连前可能要先做异步
* 准备(如 desktop 现取系统代理拿 http agent)。
*/
export type WsFactory = (
url: string,
headers: Record<string, string>,
) => WsLike | Promise<WsLike>;
export interface DeviceLinkLogger {
debug(...args: unknown[]): void;
info(...args: unknown[]): void;
warn(...args: unknown[]): void;
error(...args: unknown[]): void;
}
/** WebSocket 升级的认证方案,见 `DeviceLinkClientOptions.authorizationScheme`。 */
export type DeviceLinkAuthorizationScheme = 'Bearer' | 'ProviderShareGuest' | 'CindyRelay';
/**
* 自建中转的设备签名钩子(docs/self-hosted-relay-plan.md §16,实现见 selfHostedRelayAuth.ts)。
* `sign` 返回要附在经中转转发的对端帧上的 `auth`;`verify` 返回 false 的入站对端帧直接丢弃。
*/
export interface DeviceLinkFrameAuth {
sign(frame: Readonly<Envelope>): unknown;
verify(frame: Readonly<Record<string, unknown>>): boolean;
/** 稳定身份用于隔离账号切换前的待发消息;认证交换不创建远控链路。 */
peerChallenge?: {
session: object;
state(deviceId: string): 'ready' | 'needed' | 'unknown';
};
}
interface RelayChallengeQueue {
session: object;
id: string;
startedAt: number;
startedMonotonicAt: number;
lastProbeAt: number;
timer: ReturnType<typeof setTimeout> | null;
frames: Map<string, { env: Envelope; bytes: number; pending?: PendingRequest }>;
}
export interface DeviceLinkClientOptions {
/** Host WebRTC adapter. Both peers must opt in; unavailable/old hosts keep using relay. */
directRuntime?: DirectRuntime;
/** relay 的完整 ws(s) URL,如 wss://host/api/device-link/ws */
getWsUrl(): string;
/** 每次(重)连前取新鲜 token;null = 当前无登录态,跳过本轮并按退避重试 */
getToken(): Promise<string | null>;
/**
* WebSocket 升级的认证方案。默认 `Bearer`(账号 Access Token);供应商分享的跨区域受邀者
* 连接对方区域时用 `ProviderShareGuest`(只限分享的凭证,契约 §6.3);连接自建中转用
* `CindyRelay`(加入中转时拿到的设备凭证,绝不发送账号 token,见 docs/self-hosted-relay-plan.md §5.2)。
* 传函数时每次建连前取值:host 在官方中转与自建中转之间切换时,方案与 getToken 必须同一轮一致。
*/
authorizationScheme?: DeviceLinkAuthorizationScheme | (() => DeviceLinkAuthorizationScheme);
/**
* 自建中转的设备签名。每帧取值:返回 null(官方中转)时不签名也不核对,wire 行为与旧版完全相同。
* host 在官方与自建中转之间切换时与 `getToken` / `authorizationScheme` 同一轮生效。
*/
frameAuth?: () => DeviceLinkFrameAuth | null;
/** 每次(重)连时的 hello payload(host 持有 deviceName / 开关 / busy 的真相) */
getHello(): HelloPayload;
createWebSocket: WsFactory;
logger?: DeviceLinkLogger;
/**
* 可靠传输对单个 peer 重试耗尽后的故障半径。
*
* - `legacy`(默认):保留既有兼容行为。无法通过已协商的
* `transport-timeout` 瞬时重置 peer 时,重建整条 relay 连接。
* - `isolate-peer`:只复位该 peer 并通过 `onPeerTransportReset` 通知 host
* 使用既有 `link-open` 恢复;不关闭共享 WSS,也不发送旧对端不理解的新
* wire 值。仅适合能独立重开每个出站 peer 的纯控制端(当前为 Mobile)。
*
* 这是 additive、host opt-in 的本地策略;Desktop 不传时行为完全不变。
*/
peerFailurePolicy?: DeviceLinkPeerFailurePolicy;
/**
* Peer 可靠传输复位时,是否让幂等的本地数据库读请求快速失败给 host,
* 由 host 重开 link 后最多重试一次。写请求和长执行请求不走这条路径。
*/
peerResetReadRetry?: boolean;
/**
* invoke 结果传输编码(gzip 与内容标签,见 invokeTransfer.ts)。控制端提供
* gunzipBase64 才声明可解 gzip;被控端提供 gzipBase64 / contentTag 才编码。
* 不传时 wire 行为与旧版完全相同。
*/
transferCodec?: DeviceLinkTransferCodec;
/** Optional local counters; no content/identities, never part of delivery decisions. */
invokeMetrics?: {
enabled(): boolean;
record(event: { channel: string; phase: 'sent' | 'result'; payloadBytes?: number;
notModified?: boolean; gzip?: boolean }): void;
};
/** 测试注入:覆盖重连/心跳的时间参数 */
timing?: Partial<DeviceLinkTiming>;
}
export type DeviceLinkPeerFailurePolicy = 'legacy' | 'isolate-peer';
export interface DeviceLinkTiming {
reconnectBaseMs: number;
reconnectMaxMs: number;
/**
* hello-ack 之后必须稳定在线一小段时间才把退避清零。
* 否则同 deviceId 的重复连接风暴会变成 1s 固定频率重连,持续顶掉彼此。
*/
reconnectStableResetMs: number;
pingIntervalMs: number;
/** 连续无 pong 判定僵死的周期数;入站业务流量会把这组计数清零。 */
pongMissLimit: number;
/** invoke / link-open 默认等待响应时长 */
requestTimeoutMs: number;
/**
* getToken 的等待上限。token 刷新可能走网络(移动端弱网下可能长时间无响应),
* 不设上限时 connect 会卡在 connecting 且没有任何重连计时器兜底。
*/
getTokenTimeoutMs: number;
/**
* 从 socket 创建到 hello-ack 的握手上限。弱网下 TCP/TLS 升级可能挂起
* OS 级时长(几十秒),超限直接判失败走退避重连,而不是无限 connecting。
*/
handshakeTimeoutMs: number;
/** 可靠消息未收到累计 ACK 时的重发间隔。 */
transportRetryIntervalMs: number;
/** 单个连接世代内的最大发送次数;耗尽后主动重连并在新世代继续。 */
transportMaxRetryAttempts: number;
/**
* 单趟恢复/重发帧预算(理由与线上证据见 TRANSPORT_RETRY_PASS_BUDGET)。
* 定时重发、link 重建 replay、恢复期内的首发共用;不再给 replay 无限额度。
*/
transportRetryPassBudget: number;
/** presence fire-and-forget 帧命中 WebSocket 背压后的合并重试间隔。 */
presenceRetryIntervalMs: number;
/**
* link 断开状态下可靠 pending 的最长滞留时间;超过即整队放弃。
* 防死锁兜底:link-accept/link-open 丢失时,冻结的满队列会把之后所有
* invoke-result 顶成 BACKPRESSURE(2026-08-03 线上实锤:被控端队列冻结
* 30+ 分钟,每个执行成功的结果都进 outbox 等 120s 过期丢弃)。滞留超过
* 该阈值说明这不是「短断线等重放」而是链路重建失败,pending 里的 push
* 由重连 resync 补偿,invoke-result 的原请求方早已超时,整队放弃无损。
*/
stalledLinkPendingMaxAgeMs: number;
/**
* relay 主动拥塞断连(close 1013 Try Again Later,如 inbound backpressure)
* 后的重连冷却下限:连续第 N 次拥塞断连后,下一次重连至少等
* min(congestionBackoffBaseMs × 2^(N-1), congestionBackoffMaxMs),与普通
* 退避取 max。普通退避在稳定在线(reconnectStableResetMs)后归零,而拥塞
* 断连恰恰常发生在「在线很久 → 出站洪峰 → 被踢」之后——若冷却随稳定期
* 归零,客户端会以 1s 级节奏反复「重连 → 全量重放洪峰 → 再被踢」
* (2026-08-08 线上:两次 1013 间隔仅 15s,第二条连接只活了 7s)。
* 连续拥塞计数只在稳定在线满 congestionStableResetMs 后清零——现场 1013
* 间隔常是数分钟,若与 10s 的普通稳定窗共用,streak 永远回 1。
*/
congestionBackoffBaseMs: number;
congestionBackoffMaxMs: number;
/**
* 拥塞连击清零所需的稳定在线时长。与 reconnectStableResetMs 刻意分开:
* 普通退避 10s 即可恢复快速重连;拥塞冷却必须跨过现场 3–8 分钟一踢的间隔。
*/
congestionStableResetMs: number;
}
const DEFAULT_TIMING: DeviceLinkTiming = {
reconnectBaseMs: 1_000,
reconnectMaxMs: 30_000,
reconnectStableResetMs: 10_000,
pingIntervalMs: 20_000,
// 允许弱网在一个额外周期内恢复;真正无响应仍由连续 miss + 无入站流量判定。
pongMissLimit: 3,
requestTimeoutMs: 30_000,
getTokenTimeoutMs: 15_000,
handshakeTimeoutMs: 15_000,
transportRetryIntervalMs: TRANSPORT_RETRY_INTERVAL_MS,
transportMaxRetryAttempts: TRANSPORT_MAX_RETRY_ATTEMPTS,
transportRetryPassBudget: TRANSPORT_RETRY_PASS_BUDGET,
presenceRetryIntervalMs: 500,
stalledLinkPendingMaxAgeMs: 60_000,
congestionBackoffBaseMs: 5_000,
congestionBackoffMaxMs: 30_000,
congestionStableResetMs: 15 * 60_000,
};
/**
* 单趟帧预算的规范化:`Partial<DeviceLinkTiming>` 很容易把字段「可选值直塞」成
* undefined,object spread 会**覆盖**默认值,于是 Math.max(1, undefined) = NaN、
* `framesLeft <= 0` 恒为 false —— 预算被静默关掉,悄悄退回「一趟灌完整窗口」
* (copilot review)。非有限值 / ≤0 一律回退到常量默认,并向下取整。
*/
function normalizeRetryPassBudget(value: number | undefined): number {
if (typeof value !== 'number' || !Number.isFinite(value)) return TRANSPORT_RETRY_PASS_BUDGET;
const floored = Math.floor(value);
return floored >= 1 ? floored : TRANSPORT_RETRY_PASS_BUDGET;
}
function normalizeTransportRetryInterval(value: number | undefined): number {
if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
return TRANSPORT_RETRY_INTERVAL_MS;
}
return value;
}
function normalizeTransportRetryAttempts(value: number | undefined): number {
if (typeof value !== 'number' || !Number.isFinite(value)) return TRANSPORT_MAX_RETRY_ATTEMPTS;
const floored = Math.floor(value);
return floored >= 1 ? floored : TRANSPORT_MAX_RETRY_ATTEMPTS;
}
function normalizeCongestionStableResetMs(value: number | undefined): number {
if (typeof value !== 'number' || !Number.isFinite(value)) {
return DEFAULT_TIMING.congestionStableResetMs;
}
const floored = Math.floor(value);
return floored >= 1 ? floored : DEFAULT_TIMING.congestionStableResetMs;
}
/**
* 重连延迟计算(包内部工具,为确定性单测保持具名导出;**不属于稳定公共
* API 面**,外部不应依赖):普通指数退避与拥塞冷却下限取 max,再做向下抖动
* (0.7x–1.0x,与 scheduleReconnect 既有抖动语义一致)。
* 入参钳制(review P2,防误用产生 NaN/负延迟):attempt / congestionCloseStreak
* 取整并夹到 ≥0(非有限值按 0),random 夹到 [0,1];streak=0 表示无拥塞信号。
*/
export function computeReconnectDelayMs(input: {
attempt: number;
congestionCloseStreak: number;
reconnectBaseMs: number;
reconnectMaxMs: number;
congestionBackoffBaseMs: number;
congestionBackoffMaxMs: number;
random: number;
}): number {
const attempt = Number.isFinite(input.attempt) ? Math.max(0, Math.floor(input.attempt)) : 0;
const streak = Number.isFinite(input.congestionCloseStreak)
? Math.max(0, Math.floor(input.congestionCloseStreak))
: 0;
const random = Number.isFinite(input.random) ? Math.min(Math.max(input.random, 0), 1) : 0;
const base = Math.min(
input.reconnectBaseMs * 2 ** attempt,
input.reconnectMaxMs,
);
const congestionFloor = streak > 0
? Math.min(
input.congestionBackoffBaseMs * 2 ** (streak - 1),
input.congestionBackoffMaxMs,
)
: 0;
return Math.round(Math.max(base, congestionFloor) * (0.7 + random * 0.3));
}
export type DeviceLinkStatus = 'stopped' | 'connecting' | 'online';
/**
* 连接层异常分类 —— 只覆盖「用户可感知、可指导行动」的握手/链路失败。
* 普通网络断线/抖动不产生 issue(UI 已有 connecting 态兜底),避免 banner 噪音。
*
* 背景:DeviceLinkStatus 三态没有 error 态,鉴权失败(401)、被顶号(4409)、
* 版本不符(4400)等失败在状态机上都表现为无限 connecting,用户看不到真实原因。
* 这里以 additive 旁路通道暴露分类结果,不改动三态语义(两端既有消费零影响)。
*/
export type DeviceLinkConnectionIssueKind =
/** WS upgrade 被 401 拒绝:token 失效 / 已在别处登出 */
| 'auth-failed'
/** 4410:设备登记已被同账号另一台设备移除。 */
| 'device-removed'
/** 4409:同 deviceId 的新连接顶掉了本连接 */
| 'replaced'
/** 4429:同账号连接数超限 */
| 'too-many-connections'
/** 协议版本不一致(server 4400 拒绝 / 客户端 hello-ack 校验) */
| 'version-mismatch'
/** 连续多次握手成功后又在稳定期内断开。 */
| 'unstable';
export interface DeviceLinkConnectionIssue {
kind: DeviceLinkConnectionIssueKind;
/** ws close code(如 4409);非 close 场景(hello-ack 校验)缺省 */
closeCode?: number;
/** 原始 reason / socket error message,供日志诊断;不建议直接展示给用户 */
detail?: string;
/** unix ms */
at: number;
}
/**
* Peer route lifecycle signal for host-side active-state cleanup.
*
* `DEVICE_OFFLINE` is a routing fact, not a request-level error only: the host
* must release the peer's active controller projection while retaining its
* remembered recovery intent. The connection epoch lets hosts ignore a late
* signal from an older WebSocket generation.
*/
export interface DeviceLinkPeerRouteStateChanged {
deviceId: string;
state: 'offline';
connectionEpoch: number;
/** 本地已接受的 peer link 代次;同一 WebSocket 内重开也会递增。 */
linkGeneration: number;
}
/**
* 单个 peer 的可靠传输已在本地复位。Host 应作废该 peer 的内容就绪证据;
* 出站隔离策略由 host 重建,入站方向仍通知对端重开。
*
* 该事件不是 relay/WSS 断线信号;其它 peer 必须继续收发。代次字段供 host
* 丢弃排队期间已经过期的恢复任务。`seq` 只用于诊断,不代表业务请求 id。
*/
export interface DeviceLinkPeerTransportReset {
deviceId: string;
reason: 'ack-timeout';
connectionEpoch: number;
linkGeneration: number;
seq: number;
}
/**
* 从断连信息分类连接问题。返回 null = 普通断线(网络抖动 / 服务重启 / 4401 token
* 轮换),按既有退避重连兜底即可,不打扰用户。
*
* 401 场景两端 ws 实现都不给 close code(升级失败统一 1006),只能靠 socket error
* message 匹配:Node ws 是 "Unexpected server response: 401",RN 是
* "Expected HTTP 101 response but was '401 Unauthorized'"。
*/
export function classifyConnectionIssue(
code?: number,
reason?: string,
socketErrorMessage?: string | null,
): DeviceLinkConnectionIssueKind | null {
if (code === 4410) return 'device-removed';
if (code === 4409) return 'replaced';
if (code === 4429) return 'too-many-connections';
if (code === 4400 && /version/i.test(reason ?? '')) return 'version-mismatch';
const detail = `${reason ?? ''} ${socketErrorMessage ?? ''}`;
if (/\b401\b|unauthorized/i.test(detail)) return 'auth-failed';
return null;
}
/** 入站隧道帧(由 host 处理:被控端 dispatch invoke;控制端消费 push 等) */
export type InboundFrameHandler = (env: Envelope) => unknown | Promise<unknown>;
interface PendingRequest {
/** Timers may be suspended; retire an overdue request before replaying its payload. */
expireIfOverdue(): boolean;
/** First successful socket write starts the response budget; never a delivery receipt. */
noteFirstWrite?: () => void;
hasWritten(): boolean;
resolve(env: Envelope): void;
reject(err: DeviceLinkError): void;
timer: ReturnType<typeof setTimeout>;
/** 期望的响应 kind —— 配对时除 id 外还要 kind 一致,挡 id 撞但 kind 不符的帧。 */
expectKind: 'invoke-result' | 'link-accept';
/** link-open 的目标设备;显式关闭时据此取消仍在等待的 accept。 */
dst?: string;
/** 可靠 invoke 未 ACK 时可跨 relay 短断线继续等;其它请求立即失败。 */
reliableDst?: string;
/** 请求真正发出时所属的 peer link 代次,供迟到 relay-error 归属。 */
linkGeneration?: number;
/** peer reset 时让 host 快速结束本次等待,由 host 重开后决定是否重试。 */
retryAfterPeerReset?: () => void;
/** 仅自建中转建链可在对端启动挑战更新后重送;沿用原 id、签名身份与请求期限。 */
relayLinkRetry?: { envelope: Envelope; session: object };
}
function isPeerResetRetryableRead(env: Omit<Envelope, 'id'>): boolean {
if (env.kind !== 'invoke') return false;
const payload = env.payload as InvokePayload | undefined;
return typeof payload?.channel === 'string' && isPeerResetRetryableInvoke(payload.channel, payload.args);
}
interface PendingReliableMessage {
seq: number;
/** 保留逻辑信封,重放时按当前最早 pending seq 刷新 wrapper.baseSeq。 */
envelope: Envelope;
/** 按 baseSeq=seq 预留的最坏 wire 大小,用于严格限制 pending 内存。 */
bytes: number;
attempts: number;
lastSentAt: number;
sent: boolean;
/** 入队时刻(monotonicNow 单调时钟);push 帧按 TRANSPORT_PENDING_PUSH_MAX_AGE_MS 判定过期。 */
enqueuedAt: number;
/** 认证身份切换后,旧业务不能用新身份重新签名发送。 */
relaySigningSession?: object;
/**
* 本轮(attempts 归零后)首次真正写出的时刻(monotonicNow)。enqueuedAt 可能早于
* 发送(link 未就绪时排队),判断「对端有过 ACK 机会却没回」必须从首发算起。
*/
firstSentAt?: number;
/** Last observed gate, diagnostics only; never controls transport scheduling. */
lastBlockedBy?: 'link' | 'receive-window' | 'recovery-ack' | 'relay-budget' | 'socket' | 'socket-budget' | 'pass-budget'
| 'direct-buffer';
/** 最近一次物理写出走的路径;直连失效时据此把仍未确认的帧改走 relay。 */
path?: DeviceLinkPeerPath;
}
type ReliableSendPhase = 'down' | 'awaiting-confirm' | 'ready';
interface ReliableResumePlan {
duplicateOpen: boolean;
resumedLink: boolean;
enterRecovery: boolean;
}
interface PendingLinkConfirmation {
requestId: string;
/** accept 声明的接收基线减一;低于它说明对端尚未真正安装本代基线。 */
minimumAckSeq: number;
resume: ReliableResumePlan;
/** 入站确认尚未完成时,撤销入站方向应恢复此前仍存续的本地发送状态。 */
previousSendPhase: 'down' | 'ready';
timer: ReturnType<typeof setTimeout> | null;
}
interface OutboundLinkConfirmationAck {
requestId: string;
streamId: string;
attempts: number;
timer: ReturnType<typeof setTimeout> | null;
}
/** Bounded, per-link diagnostics only; never used to decide delivery or retries. */
interface RecoveryTrace {
startedAt: number;
connectionEpoch: number;
requestId: string;
stages: Set<string>;
ackProgressLogs: number;
replayThroughSeq: number | null;
}
interface PeerTransportState {
streamId: string;
remoteStreamId: string | null;
remoteBaseSeq: number;
nextSeq: number;
reliable: boolean;
/** 本机可靠 stream 是否已被对端确认可接收;只控制 local → remote 发送。 */
sendPhase: ReliableSendPhase;
/** 本机是否已提交对端 stream 基线;只控制 remote → local 接收。 */
receiveReady: boolean;
/** 新版入站 accept 等待对端回显 request id;新 offer 会原子替换旧代。 */
pendingLinkConfirmation: PendingLinkConfirmation | null;
/** 本机已处理出站 accept 后的有界确认 ACK 重发;只由对应确认 ACK 或代际复位撤销。 */
outboundLinkConfirmationAck: OutboundLinkConfirmationAck | null;
explicitlyClosed: boolean;
/**
* 该 peer 当前是否有**活动的入站控制方向**(对方作为控制端被本机 accept
* 且尚未永久关闭)。可靠重试耗尽的止损分级依据:被控端同一条 relay 连接
* 服务多个控制端,只重置超时 peer 的 link;纯控制端(恒 false)维持整连接
* 重连兼作恢复探测。
*
* 生命周期:
* - 置位:sendLinkAccept(接受入站 link-open)。
* - 撤销:永久关闭——收到对端永久 link-close(user/toggle-off/shutdown/
* revoked 及未知新值)或本地 closeLink。入站方向被用户明确关闭后,出站
* 重试耗尽不得再发 transport-timeout 诱使对端自动重开已关闭的控制方向。
* - **不撤销**:transport-timeout(瞬时重置,方向仍活动)与出站 link-accept
* (互控时两方向共享本状态,出站握手不得覆盖仍活动的入站方向)。
* 方向歧义处(如本地 closeLink 区分不了方向)一律保守撤销:代价只是回到
* 整连接重连语义(升级前行为),而错误的 true 会违背用户关闭意图。
*/
linkAcceptedInbound: boolean;
/**
* 本机是否已显式结束**出站**控制方向(closeLink direction='outbound')。
* 迟到 transport-timeout 的拦截依据:只有本机不再主动控制对方时才吞帧;
* 入站方向的撤权/踢控制端(direction='inbound')不置位——互控时仍存续的
* 主动控制方向必须保留可恢复。openLink(意图续新)与收到 link-accept 时清除。
*/
outboundExplicitlyClosed: boolean;
/** 对端是否声明理解 transport-timeout 的瞬时重置语义(能力协商,见 transport.ts)。 */
supportsTransportTimeoutClose: boolean;
/** 显式关闭后收到的 allowlisted legacy invoke;只放行与 requestId 配对的一次回程。 */
unlinkedLegacyResponseIds: Set<string>;
pending: Map<number, PendingReliableMessage>;
pendingBytes: number;
retryTimer: ReturnType<typeof setInterval> | null;
receive: Map<string, ReceiveStreamState>;
highestAckSeq: number;
lastReplayEpoch: number;
/** 上次真正 replay 时对端的 stream。对端重启换 stream 时不能当重复 open。 */
lastReplayRemoteStreamId: string | null;
/** Latest duplicate accept whose confirmation may prove a receive gap. */
duplicateOpenRepair: { requestId: string; headSeq: number; throughSeq: number } | null;
/** ACK-paced repair, bounded to the backlog captured by the accepted open. */
confirmedGapRepair: { awaitingSeq: number; throughSeq: number } | null;
/** One extra repair per sequence, retained across link resets of this stream. */
lastDuplicateOpenRepairSeq: number;
lastDuplicateOpenRepairAt: number;
/**
* 恢复探测:link 刚恢复或刚被 DEVICE_OFFLINE 刹停后为 true。
* 此间出站不超过 transportRetryPassBudget,直到收到可靠 ACK。
*/
recoveryNeedsAck: boolean;
/** 本轮恢复探测已写出的帧数(含 replay 与恢复期内首发)。 */
recoveryFramesSent: number;
/** ACK round-trip estimate for this peer; survives link resets on the same network path. */
rtt: RetransmitEstimate;
recoveryTrace: RecoveryTrace | null;
/** latest-wins 腾位驱逐的聚合计数(自上次告警起),仅服务日志聚合。 */
pushAdmissionDropCount: number;
/** 上次输出 latest-wins 驱逐告警的单调时刻;0 表示从未输出。 */
pushAdmissionDropLogAt: number;
/** 同一 relay WebSocket 内每次接受 link-open/link-accept 都递增。 */
linkGeneration: number;
/**
* 最近一条可靠帧从哪条路径到达。累计 ACK 原路返回:对端已因直连异常改走
* relay 时,ACK 不能继续投进可能已失效的直连通道。
*/
lastInboundPath: DeviceLinkPeerPath;
/** 直连尚未写出时的缓冲进展;持续不下降也要切回 relay,不能只等待已发送帧的 ACK。 */
directBufferWait?: { channel: DeviceLinkDirectChannel; bytes: number; since: number };
}
interface PendingInboundLinkOffer {
requestId: string;
capabilities?: readonly string[];
transportStreamId?: string;
transportBaseSeq?: number;
}
interface ReceiveAssembly {
/** Local monotonic time of the first fragment; diagnostics only. */
receivedAt: number;
kind: Envelope['kind'];
id?: string;
src?: string;
dst?: string;
total: number;
totalBytes: number;
chunks: Map<number, string>;
bytes: number;
}
interface ReceiveStreamState {
lastDeliveredSeq: number;
requestedBaseSeq: number;
deliveringSeq: number | null;
assemblies: Map<number, ReceiveAssembly>;
ready: Map<number, { env: Envelope; json: string; receivedAt: number; readyAt: number }>;
bufferedBytes: number;
drain: Promise<void> | null;
/** drain 已在途时又有新帧入队;当前轮结束前必须再检查一次队头。 */
drainRequested: boolean;
}
// ─── 客户端实现 ───────────────────────────────────────────────────────────────
export class DeviceLinkClient {
private readonly invokeScheduler = new InvokeScheduler((id) => {
const peer = this.peerTransport.get(id);
return (this.ws?.bufferedAmount ?? 0) > SOCKET_DATA_LOW_WATER_BYTES
|| (peer?.pendingBytes ?? 0) > SOCKET_DATA_LOW_WATER_BYTES
|| (peer?.pending.size ?? 0) >= MAX_TRANSPORT_REASSEMBLIES / 2;
});
private readonly opts: DeviceLinkClientOptions;
private readonly timing: DeviceLinkTiming;
private readonly log: DeviceLinkLogger;
private ws: WsLike | null = null;
private status: DeviceLinkStatus = 'stopped';
private stopped = true;
private reconnectAttempt = 0;
/**
* 连续 relay 拥塞断连(1013)计数,驱动重连冷却下限(computeReconnectDelayMs)。
* 与 reconnectAttempt 生命周期刻意不同:attempt 在稳定在线后归零以恢复快速
* 重连,本计数只在稳定在线满 congestionStableResetMs 后清零——拥塞信号不因
* 「重连握手成功」或短稳定窗而失效,否则现场数分钟一踢时 streak 永远是 1。
* connectNow / restartConnection(用户显式等待的前台恢复/唤醒)清 attempt
* 但不清本计数:立即重连可以,但若再被踢,冷却按更深一档生效。
*/
private congestionCloseStreak = 0;
private readonly congestionSendBudget = new CongestionSendBudget();
private localSendPressure = false;
private readonly localSendBudget = new CongestionSendBudget();
private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
private reconnectStableTimer: ReturnType<typeof setTimeout> | null = null;
private congestionStableTimer: ReturnType<typeof setTimeout> | null = null;
private handshakeTimer: ReturnType<typeof setTimeout> | null = null;
/** 连续握手超时次数;任一次 hello-ack 上线即复位(驱动握手窗口自适应放宽)。 */
private handshakeTimeoutStreak = 0;
private pingTimer: ReturnType<typeof setInterval> | null = null;
private pongMisses = 0;
/** 最近一次收到任何有效 relay 帧的时刻;避免把有业务流量的 socket 误判为僵死。 */
private lastInboundAt = 0;
/**
* 最近一次收到任一对端经 relay 转发的隧道帧(含可靠 ACK)的时刻。与 lastInboundAt
* 分开:relay 自身的 pong / presence 只证明到 relay 的上行活着,证明不了转发方向。
* 仅供 isRelayWideReliableStall 判定「所有对端同时沉默」。
*/
private lastPeerInboundAt = 0;
private networkChangeTimer: ReturnType<typeof setTimeout> | null = null;
private networkProbeTimer: ReturnType<typeof setTimeout> | null = null;
private networkProbeStartedAt = 0;
private networkChangeHintedAt = 0;
private networkProbeNextAllowedAt = 0;
private connectionStartedAt = 0;
/**
* Wall-clock deadline of the current attempt's active watchdog (token wait, then
* each handshake window). Unlike timers it keeps counting through app suspension.
*/
private connectAttemptDeadlineWallAt = 0;
/** 当前连接的代号,用于丢弃过期 socket 的事件回调 */
private connEpoch = 0;
/** 本轮连接的最后一条 socket error message(升级失败 401 只在 error 事件里可见) */
private lastSocketErrorMessage: string | null = null;
/** 最近一次分类出的连接问题;online 清除,普通断线保留(重连中 banner 不闪) */
private connectionIssue: DeviceLinkConnectionIssue | null = null;
/** 当前连接第一次进入 online 的时刻;用于断开诊断和短命连接判定。 */
private onlineSinceAt: number | null = null;
/** 连续「握手成功但没撑过稳定期」次数;稳定在线后清零。 */
private shortLivedStreak = 0;
/** 最近一次 hello-ack 声明的 server 能力集(老 server 无该字段 = 空集) */
private serverCapabilities: readonly string[] = [];
/** 最近一次 hello-ack 回的本设备 deviceId(深链等场景需要自我标识) */
private selfDeviceId: string | null = null;
private readonly pending = new Map<string, PendingRequest>();
private readonly relayChallenges = new Map<string, RelayChallengeQueue>();
private relayChallengeBytes = 0;
private relayChallengeFrames = 0;
/**
* 每个控制端/被控端各自维护一个 stream。stream 在 relay 重连时保留,
* 这样未 ACK 的消息可以在重新 openLink 后继续重发;旧 stream 不会混入
* 新 peer,因为接收端按 streamId 独立去重。
*/
private readonly peerTransport = new Map<string, PeerTransportState>();
/** 入站 link-open 只记录提议;host 真正 sendLinkAccept 后才提交能力/stream 基线。 */
private readonly pendingInboundLinkOffers = new Map<string, PendingInboundLinkOffer>();
/** transport-timeout 重置通知的待重发计时器(per dst,有界重试)。 */
private readonly timeoutCloseNotifyTimers = new Map<string, ReturnType<typeof setTimeout>>();
/** 只串行旧协议业务帧;pong / ACK / 可靠 stream 各自独立,不被慢 handler 堵住。 */
private legacyInboundChain: Promise<void> | null = null;
private legacyInboundFrames = 0;
private legacyInboundBytes = 0;
/** 断线/stop 后旧 handler 可能永不 settle;新连接必须与其队列 bookkeeping 隔离。 */
private legacyInboundGeneration = 0;
/** presence 是覆盖语义;背压时只保留每个字段的最新值,避免异常逃逸或无界排队。 */
private pendingPresence: PresenceSetPayload | null = null;
private presenceRetryTimer: ReturnType<typeof setTimeout> | null = null;
// —— host 订阅 ——
private statusHandlers = new Set<(s: DeviceLinkStatus) => void>();
/** 收到「link 未就绪」可靠帧的通知(30s/peer 节流);host 据此主动重建控制链路。 */
private staleLinkHandlers = new Set<(deviceId: string) => unknown>();
private staleLinkNotifiedAt = new Map<string, number>();
private presenceHandlers = new Set<(snap: PresenceSnapshot) => void>();
private frameHandlers = new Set<InboundFrameHandler>();
private peerStreamAcceptedHandlers = new Set<(peer: string, streamId: string) => void>();
private issueHandlers = new Set<(issue: DeviceLinkConnectionIssue | null) => void>();
private peerRouteStateHandlers = new Set<
(change: DeviceLinkPeerRouteStateChanged) => void
>();
private peerTransportResetHandlers = new Set<
(change: DeviceLinkPeerTransportReset) => void
>();
/** Avoid emitting the same authoritative route failure once per queued frame. */
private peerOfflineNotifiedGeneration = new Map<
string,
{ connectionEpoch: number; linkGeneration: number }
>();
/**
* relay-error 回带原帧 id;据此把迟到错误归回消息发出时的 peer link 代次。
* 未决记录受硬上限保护并参与发送背压;成功确认后直接释放,无法确认交付的
* best-effort / 超时帧移入不占发送额度的近期历史,迟到错误仍能按原代次归属。
* 跨 socket 时由 resetLinkStateForReconnect 清空;两份账本都不进入 wire protocol。
*/
private outboundRouteGenerationByPeer = new Map<
string,
Map<string, Array<{ linkGeneration: number; count: number }>>
>();
private settledOutboundRouteGenerationByPeer = new Map<
string,
Map<string, Array<{ linkGeneration: number; count: number }>>
>();
/** Signal request id -> scoped peer, retained for this socket's relay-error correlation. */
private readonly providerShareSignalRouteIds = new Map<string, { dst: string; expiresAt: number }>();
/**
* 每台同账号设备至多一条直连通道(见 directPath.ts)。只承载已建立可靠链路上的
* 数据面帧;没有通道或通道失效时,同一批帧照常走 relay。
*/
private readonly directPaths = new Map<string, DeviceLinkDirectChannel>();
private readonly directPeerSupport = new Set<string>();
/** Relay-authenticated provider-share path leases never survive process/account replacement. */
private readonly providerShareDirectLeases = new Map<string, {
wallUntil: number; monotonicUntil: number; timer: ReturnType<typeof setTimeout>;
}>();
/** Local scoped address learned from the relay, not from an untrusted direct frame. */
private readonly providerShareLocalAddresses = new Map<string, string>();
private readonly directNegotiator?: DirectLinkNegotiator;
private peerPathHandlers = new Set<(change: DeviceLinkPeerPathChanged) => void>();
constructor(opts: DeviceLinkClientOptions) {
this.opts = opts;
if (opts.directRuntime) this.directNegotiator = new DirectLinkNegotiator({
runtime: opts.directRuntime,
identity: () => this.selfDeviceId,
peerDeviceId: (id) => parseProviderSharePeer(id)?.deviceId ?? (isScopedPeer(id) ? null : id),
canSignal: (peer) => this.status === 'online'
&& (!isProviderSharePeer(peer) || this.hasServerCapability(PROVIDER_SHARE_DIRECT_SIGNAL_CAPABILITY)),
streams: (id) => {
const peer = this.peerTransport.get(id);
return !this.stopped && (!isScopedPeer(id) || this.hasProviderShareDirectLease(id))
&& this.directPeerSupport.has(id) && peer?.reliable && peer.receiveReady
&& this.isPeerSendReady(peer) && peer.remoteStreamId
? { local: peer.streamId, remote: peer.remoteStreamId } : null;
},
id: createRequestId,
signal: (dst, payload) => {
// Signaling is a control plane: never put SDP or close notices onto the direct path.
const scoped = isProviderSharePeer(dst);
const now = performance.now();
while (this.providerShareSignalRouteIds.size) {
const first = this.providerShareSignalRouteIds.entries().next().value!;
if (first[1].expiresAt > now) break;
this.providerShareSignalRouteIds.delete(first[0]);
}
if (scoped && (!this.hasServerCapability(PROVIDER_SHARE_DIRECT_SIGNAL_CAPABILITY)
|| this.providerShareSignalRouteIds.size >= MAX_PROVIDER_SHARE_SIGNAL_ROUTE_IDS)) return;
const id = scoped ? createRequestId() : undefined;
if (id) this.providerShareSignalRouteIds.set(id, { dst, expiresAt: now + PROVIDER_SHARE_SIGNAL_ROUTE_TTL_MS });
try {
this.sendBestEffortRoutedEnvelope({ v: PROTOCOL_VERSION, kind: 'push', id, dst,
payload: { channel: DIRECT_LINK_SIGNAL, payload } });
} catch (err) {
if (id) this.providerShareSignalRouteIds.delete(id);
throw err;
}
},
attach: (id, channel) => this.attachDirectPath(id, channel),
});
this.invokeResultCache = new InvokeResultCache(opts.transferCodec);
this.timing = { ...DEFAULT_TIMING, ...opts.timing };
this.log = opts.logger ?? {
debug: () => {},
info: () => {},
warn: () => {},
error: () => {},
};
}
// ─── 生命周期 ───────────────────────────────────────────────────────────────
start(): void {
if (!this.stopped) return;
this.stopped = false;
this.reconnectAttempt = 0;
// 全新生命周期(登录/切号后 start):不背上一世代的拥塞冷却。
this.congestionCloseStreak = 0;
void this.connect('start');
}
/**
* 立即重连:清掉挂起的退避计时器并把退避计数归零,马上发起一次连接。
*
* 供"用户正在等"的场景(如移动端回到前台)opt-in,绕开指数退避——
* 不改默认退避曲线(桌面端断线重连仍走 scheduleReconnect 的 1s→30s)。
* 已 online 时为空操作,不打断健康连接;stopped 时等价于 start()。
*
* 拥塞冷却例外(review P1):relay 刚以 1013 拥塞断连、冷却计时器在跑时,
* 默认**不** un-park——事故形态下恰是在途请求经 waitUntilOnline → connectNow
* 把每次 1013 后的冷却清掉,「重连 → 重放洪峰 → 再被踢」的循环因此掐不断。
* 只有显式用户意图(移动端回前台)传 overrideCongestionCooldown 保留立即重连;
* 被 park 的调用方等冷却计时器到点自然重连(封顶 congestionBackoffMaxMs)。
*/
connectNow(
reason = 'connect-now',
opts?: { overrideCongestionCooldown?: boolean; keepInFlightAttempt?: boolean },
): void {
// online 时强制重建请用 restartConnection —— 它才是「半开假活」场景的入口,
// 且已包含 resetLinkStateForReconnect(此处曾有一个等价的 { force } 分支,
// 生产代码从未使用,只有测试在调,故收敛为单一入口)。
if (this.connectionIssue?.kind === 'device-removed') return;
if (this.status === 'online') return;
// A foreground flicker (Face ID, notification, Control Center) re-fires this
// within seconds. Restarting a handshake that is still inside its window only
// throws away the progress made on a slow link (2026-10-12 in-flight Wi-Fi:
// 5 of 5 such restarts discarded a 1–3s old attempt). Wall time covers app
// suspension, so an attempt that sat frozen in the background is restarted.
if (
opts?.keepInFlightAttempt
&& this.status === 'connecting'
&& !this.reconnectTimer
&& Date.now() < this.connectAttemptDeadlineWallAt
) {
this.log.debug(`connectNow(${reason}) kept in-flight connect attempt`);
return;
}
if (this.stopped) {
// stopped → 等价 start():全新生命周期不背上一世代的拥塞冷却(review P1,
// 与 start() 的清零语义对齐)。
this.congestionCloseStreak = 0;
} else if (
this.congestionCloseStreak > 0
&& this.reconnectTimer
&& !opts?.overrideCongestionCooldown
) {
this.log.debug(
`connectNow(${reason}) parked: congestion cool-down active (streak=${this.congestionCloseStreak})`,
);
return;
}
this.stopped = false;
this.reconnectAttempt = 0;
if (this.reconnectTimer) {
clearTimeout(this.reconnectTimer);
this.reconnectTimer = null;
}
void this.connect(reason);
}
/**
* 强制重建连接:与 connectNow 的区别是 **online 也重建**。
*
* 供「当前 socket 大概率已经半开假活」的场景(系统睡眠唤醒)使用:睡眠期间
* TCP 对端早已消失,但本端没收到 close/error、心跳也未累计到判死,状态机仍是
* online —— connectNow 会直接返回,唤醒后的请求继续写进失效 socket 黑洞约一个
* 判死周期(~45s)。这里无条件走 connect():它自带丢弃旧 socket、fail 掉
* in-flight 请求、epoch 递增的完整语义;真在线时代价只是一次 1-2s 的重连抖动,
* 对刚唤醒的空闲会话可接受。stopped 时不拉起(生命周期仍归 start/stop 管)。
*/
restartConnection(reason = 'restart-connection'): void {
if (this.stopped) return;
this.reconnectAttempt = 0;
if (this.reconnectTimer) {
clearTimeout(this.reconnectTimer);
this.reconnectTimer = null;
}
// 主动重建必须复用被动断线的链路层复位:半开期间收发方向仍可能残留 ready,
// 不复位会让 host 侧跳过 openLink、旧 stream 帧在新 socket 上被对端丢弃。
this.resetLinkStateForReconnect();
void this.connect(reason);
}
/** Network changes are hints, not proof of failure. Probe the shared relay,
* never an individual peer; any valid inbound frame keeps the socket alive.
* Repeated hints coalesce without postponing detection indefinitely. Foreground
* and explicit network transitions bypass the successful-probe cooldown. */
notifyNetworkChanged(options?: { urgent?: boolean }): void {
if (this.stopped || this.networkProbeTimer) return;
this.networkChangeHintedAt = this.monotonicNow();
if (this.networkChangeTimer) {
if (!options?.urgent) return;
clearTimeout(this.networkChangeTimer);
}
const delay = options?.urgent ? 0 : Math.max(
500,
this.networkProbeNextAllowedAt - this.networkChangeHintedAt,
);
this.networkChangeTimer = setTimeout(() => {
this.networkChangeTimer = null;
if (this.stopped) return;
if (this.status !== 'online') {
// Do not interrupt a handshake or bypass relay 1013 cool-down.
if (this.reconnectTimer) this.connectNow('network-change');
return;
}
// Activity after the latest hint already proves this relay is reachable.
// Do not compare Wi-Fi labels: switching access points can keep them equal.
if (this.lastInboundAt > this.networkChangeHintedAt) return;
const epoch = this.connEpoch;
const socket = this.ws;
const startedAt = this.monotonicNow();
this.networkProbeStartedAt = startedAt;
// A network hint cannot narrow the existing weak-network latency envelope.
// Allow at least the normal 15s handshake tolerance (or a larger override)
// before discarding a shared socket.
this.networkProbeTimer = setTimeout(() => {
this.networkProbeTimer = null;
if (this.stopped || this.connEpoch !== epoch || this.ws !== socket) return;
this.log.info(`network probe timed out (elapsedMs=${this.monotonicNow() - startedAt})`);
this.restartConnection('network-probe-timeout');
}, Math.max(DEFAULT_TIMING.handshakeTimeoutMs, this.timing.handshakeTimeoutMs));
try {
this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'ping' });
} catch {
// A full send buffer is not proof of a dead relay. Allow inbound traffic
// to settle the same bounded probe rather than tearing down immediately.
this.log.debug('network probe send deferred; waiting for inbound activity');
}
}, delay);
}
/** A peer timeout is inconclusive when even the shared relay has gone quiet.
* Use the existing bounded, single-flight network probe before blaming a peer.
* Any valid relay traffic settles that probe; one silent peer cannot reset a
* shared connection that is still serving other peers. */
confirmRelayForPeerTimeout(): boolean {
if (this.status !== 'online') return false;
if (this.monotonicNow() - this.lastInboundAt <= this.timing.pingIntervalMs) return true;
this.notifyNetworkChanged({ urgent: true });
return false;
}
private clearNetworkProbe(): void {
if (this.networkChangeTimer) clearTimeout(this.networkChangeTimer);
if (this.networkProbeTimer) clearTimeout(this.networkProbeTimer);
this.networkChangeTimer = null;
this.networkProbeTimer = null;
this.networkProbeNextAllowedAt = 0;
}
/**
* 有界等待连接就绪。online 立即 resolve;否则订阅状态变化,在 timeoutMs 内
* 等到 online 就 resolve,超时 / stopped 则 reject(NOT_CONNECTED)。
*
* Desktop/Mobile 请求等待时可打断普通退避,促成一次立即重连;
* 已在途的握手和 relay 1013 拥塞冷却仍保留。
* 已 stopped 时不自动拉起连接
* (start/stop 仍由宿主生命周期掌管),直接快速失败让上层感知。
*/
waitUntilOnline(timeoutMs?: number): Promise<void> {
if (this.status === 'online') return Promise.resolve();
if (this.stopped) {
return Promise.reject(new DeviceLinkError('NOT_CONNECTED', 'client stopped'));
}
// Only un-park a pending retry; concurrent waiters keep the in-flight handshake.
if (this.reconnectTimer) this.connectNow('wait-until-online');
const timeout = timeoutMs ?? this.timing.requestTimeoutMs;
return new Promise<void>((resolve, reject) => {
let off: (() => void) | null = null;
const settle = (fn: () => void): void => {
if (off) {
off();
off = null;
}
clearTimeout(timer);
fn();
};
const timer = setTimeout(() => {
settle(() => reject(new DeviceLinkError('NOT_CONNECTED', `not online within ${timeout}ms`)));
}, timeout);
off = this.onStatusChange((s) => {
if (s === 'online') settle(resolve);
else if (s === 'stopped') {
settle(() => reject(new DeviceLinkError('NOT_CONNECTED', 'client stopped')));
}
});
});
}
stop(): void {
this.messageReuse.clear();
this.invokeResultCache.clear();
this.inboundInvokeTransfer.clear();
if (this.stopped) return;
this.stopped = true;
this.clearTimers();
this.handshakeTimeoutStreak = 0;
this.failAllPending(new DeviceLinkError('NOT_CONNECTED', 'client stopped'));
// 登出、切账号与设备被移除都经由 stop:直连通道绑定的是旧账号下的身份,不能留给下一次 start。
for (const [deviceId, channel] of this.directPaths) this.closeDirectChannel(deviceId, channel, 'stopped');
this.directPaths.clear();
this.clearPeerTransport();
this.congestionSendBudget.reset();
this.localSendPressure = false;
this.localSendBudget.reset();
this.pendingInboundLinkOffers.clear();
this.staleLinkNotifiedAt.clear();
this.resetLegacyInboundQueue();
this.clearPendingPresence();
const ws = this.ws;
this.ws = null;
this.connEpoch++;
if (ws) {
try {
ws.close(1000, 'client stopped');
} catch {
ws.terminate?.();
}
}
this.log.info(
`device-link stopped by host (onlineForMs=${
this.onlineSinceAt === null ? 'never-online' : Math.max(0, Date.now() - this.onlineSinceAt)
})`,
);
this.onlineSinceAt = null;
this.shortLivedStreak = 0;
// 主动停止(登出 / 退后台)清掉遗留 issue,避免下次启动前 UI 挂着过期原因
this.setConnectionIssue(null);
this.setStatus('stopped');
}
getStatus(): DeviceLinkStatus {
return this.status;
}
/** Verified outbound handshake, before recovered business frames are delivered. */
onPeerStreamAccepted(cb: (peer: string, streamId: string) => void): () => void {
this.peerStreamAcceptedHandlers.add(cb);
return () => this.peerStreamAcceptedHandlers.delete(cb);
}
/** 目标设备是否已完成 link-open / link-accept,可安全进入 streaming tier。 */
isLinkReady(dst: string): boolean {
const peer = this.peerTransport.get(dst);
return !!peer && this.isPeerSendReady(peer) && peer.receiveReady;
}
/** Even unlinked reads queue behind a previously negotiated reliable link. */
needsLinkRecovery(dst: string): boolean {
const peer = this.peerTransport.get(dst);
return !!peer?.reliable && !this.isPeerSendReady(peer);
}
/** Mirror admission only: listing-only/legacy peers need no bidirectional link. */
canSendPush(dst: string): boolean {
if (this.status !== 'online') return false;
const peer = this.peerTransport.get(dst);
return !peer || !peer.reliable || this.isPeerSendReady(peer);
}
/**
* 本机是否有仍在等该设备回包的**业务**请求(invoke,等 invoke-result)。
*
* 供 host 判定「本机确实在控制该设备」这个**方向**:订阅快照是常态判据,但订阅
* 可能先于在途请求被退掉(用户关掉最后一个会话视图而请求还没回包)。此时迟到的
* 可靠 invoke-result —— 尤其大结果无法回退成单帧 legacy —— 仍需要重开链路才能
* 交付,否则只能一路丢弃到请求超时。
*
* 刻意**排除协议请求**(link-open,等 link-accept):
* - 那不是业务意图的证据。用户在 openLink 等 accept 期间关掉最后一个远程会话
* 窗口时,退订只清订阅引用、不会取消在途的 link-open;把它算作证据会让之后的
* before-link 帧继续重开链路,对端接受就凭空多出非用户发起的受控横幅
* (review P1)。
* - 更根本地,host 的重开动作本身就是发 link-open;把它算进来会自我论证,
* 形成「重开在途 → 因此有权重开」的闭环。
*
* 只反映**出站**方向:pending 里只有本机发起、正在等对端响应的请求;对端控制本机
* 的入站请求不在其中,所以不会把「纯被控端方向」误判成可重开。
*/
hasPendingRequestsTo(dst: string): boolean {
for (const request of this.pending.values()) {
if (request.dst === dst && request.expectKind === 'invoke-result') return true;
}
return false;
}
/**
* 本机是否已显式结束对该设备的**出站**控制(closeLink direction='outbound')。
*
* 供 host 一票否决自动重开:用户显式断开后,残留的在途请求(尤其走 legacy 路径、
* 不在可靠 pending 里因而不被 abandonReliablePending 清掉的那些)与残留订阅都不该
* 再把链路拉起来 —— 否则对端会再次出现非用户发起的受控横幅(review P1)。
*
* 只反映出站方向:入站撤权 / 踢控制端(direction='inbound')不置位,互控时仍存续
* 的主动控制方向保持可恢复。`openLink`(意图续新)与收到 link-accept 时自动清除。
*/
isOutboundExplicitlyClosed(dst: string): boolean {
return this.peerTransport.get(dst)?.outboundExplicitlyClosed === true;
}
onStatusChange(cb: (s: DeviceLinkStatus) => void): () => void {
this.statusHandlers.add(cb);
return () => this.statusHandlers.delete(cb);
}
/** Current WebSocket connection generation; useful for host-side stale-event guards. */
getConnectionEpoch(): number {
return this.connEpoch;
}
/** Current accepted link generation for one peer within the WebSocket lifecycle. */
getPeerLinkGeneration(deviceId: string): number {
return this.peerTransport.get(deviceId)?.linkGeneration ?? 0;
}
/** Subscribe to typed peer route lifecycle changes (currently authoritative offline). */
onPeerRouteStateChanged(
cb: (change: DeviceLinkPeerRouteStateChanged) => void,
): () => void {
this.peerRouteStateHandlers.add(cb);
return () => this.peerRouteStateHandlers.delete(cb);
}
/** 订阅单 peer 可靠传输复位;host 恢复只能影响 `change.deviceId`。 */
onPeerTransportReset(
cb: (change: DeviceLinkPeerTransportReset) => void,
): () => void {
this.peerTransportResetHandlers.add(cb);
return () => this.peerTransportResetHandlers.delete(cb);
}
getConnectionIssue(): DeviceLinkConnectionIssue | null {
return this.connectionIssue;
}
/** 订阅连接问题变化(null = 已恢复/清除)。同类问题重复发生只更新时间戳、不重复通知。 */
onConnectionIssue(cb: (issue: DeviceLinkConnectionIssue | null) => void): () => void {
this.issueHandlers.add(cb);
return () => this.issueHandlers.delete(cb);
}
onPresenceChanged(cb: (snap: PresenceSnapshot) => void): () => void {
this.presenceHandlers.add(cb);
return () => this.presenceHandlers.delete(cb);
}
/**
* 接入一条到同账号设备的直连通道(直连优先、中继兜底,见 directPath.ts)。
*
* 通道只承载该设备已建立可靠链路上的数据面帧与 ACK;link 控制帧、跨账号范围
* 与未协商可靠传输的对端始终走 relay。通道断开、写入失败或经它发出的帧过期
* 未确认时,客户端关闭通道,把仍未确认的帧经 relay 重发;接收端按 seq 去重,
* 不会重复执行。同一设备再次接入会替换旧通道。
*/
attachDirectPath(deviceId: string, channel: DeviceLinkDirectChannel): DeviceLinkDirectPathHandle {
const isActive = (): boolean => this.directPaths.get(deviceId) === channel;
const handle: DeviceLinkDirectPathHandle = {
receive: (text) => {
if (isActive()) this.handleDirectFrame(deviceId, text);
},
drained: () => {
if (isActive()) this.retryPending(deviceId, { ignoreInterval: false, onlyUnsent: true });
},
closed: () => {
if (isActive()) this.detachDirectPath(deviceId, 'channel-closed');
},
isActive,
};
if (this.stopped || !deviceId || deviceId === this.selfDeviceId
|| (isScopedPeer(deviceId) && !this.hasProviderShareDirectLease(deviceId))) {
this.closeDirectChannel(deviceId, channel, 'not-eligible');
return handle;
}
this.detachDirectPath(deviceId, 'replaced');
this.directPaths.set(deviceId, channel);
this.log.info(`device-link direct path attached dst=${deviceId.slice(0, 8)}`);
this.emitPeerPathChanged({ deviceId, path: 'direct' });
return handle;
}
/** 该设备的数据面路径:接入了直连通道即为 'direct'(链路就绪后启用),否则走 relay。 */
getPeerPath(deviceId: string): DeviceLinkPeerPath {
return this.usableDirectPath(deviceId) ? 'direct' : 'relay';
}
/** Existing, leased data path usable while the relay is reconnecting. */
hasOfflineDirectPath(deviceId: string): boolean {
return !!this.usableDirectPath(deviceId) && isProviderSharePeer(deviceId)
&& this.isLinkReady(deviceId);
}
private hasProviderShareDirectLease(deviceId: string): boolean {
if (!isProviderSharePeer(deviceId)) return false;
const lease = this.providerShareDirectLeases.get(deviceId);
if (!lease) return false;
if (Date.now() < lease.wallUntil && this.monotonicNow() < lease.monotonicUntil) return true;
this.expireProviderShareDirectLease(deviceId);
return false;
}
private usableDirectPath(deviceId: string): DeviceLinkDirectChannel | null {
if (isScopedPeer(deviceId) && !this.hasProviderShareDirectLease(deviceId)) return null;
return this.directPaths.get(deviceId) ?? null;
}
private issueProviderShareDirectLease(deviceId: string): void {
if (!isProviderSharePeer(deviceId) || !this.directPeerSupport.has(deviceId)
|| !this.providerShareLocalAddresses.has(deviceId)) return;
this.clearProviderShareDirectLease(deviceId);
const wallUntil = Date.now() + PROVIDER_SHARE_DIRECT_LEASE_MS;
const monotonicUntil = this.monotonicNow() + PROVIDER_SHARE_DIRECT_LEASE_MS;
const timer = setTimeout(() => this.expireProviderShareDirectLease(deviceId), PROVIDER_SHARE_DIRECT_LEASE_MS);
(timer as { unref?: () => void }).unref?.();
this.providerShareDirectLeases.set(deviceId, { wallUntil, monotonicUntil, timer });
}
private clearProviderShareDirectLease(deviceId: string): void {
const lease = this.providerShareDirectLeases.get(deviceId);
if (lease) clearTimeout(lease.timer);
this.providerShareDirectLeases.delete(deviceId);
}
private expireProviderShareDirectLease(deviceId: string): void {
this.clearProviderShareDirectLease(deviceId);
this.detachDirectPath(deviceId, 'link-closed');
if (this.status !== 'online') {
const peer = this.peerTransport.get(deviceId);
if (peer) this.markPeerLinkDown(peer);
}
}
/** 订阅直连与 relay 之间的切换;平台据此在切回 relay 后安排重新建立直连。 */
onPeerPathChanged(cb: (change: DeviceLinkPeerPathChanged) => void): () => void {
this.peerPathHandlers.add(cb);
return () => this.peerPathHandlers.delete(cb);
}
private notifyPeerRouteOffline(deviceId: string, linkGeneration: number): void {
const notified = this.peerOfflineNotifiedGeneration.get(deviceId);
if (
notified?.connectionEpoch === this.connEpoch
&& notified.linkGeneration === linkGeneration
) {
return;
}
this.peerOfflineNotifiedGeneration.set(deviceId, {
connectionEpoch: this.connEpoch,
linkGeneration,
});
if (this.peerRouteStateHandlers.size === 0) return;
const change: DeviceLinkPeerRouteStateChanged = {
deviceId,
state: 'offline',
connectionEpoch: this.connEpoch,
linkGeneration,
};
for (const cb of this.peerRouteStateHandlers) {
try {
cb(change);
} catch (err) {
this.log.error('device-link peer route state handler failed', err);
}
}
}
private notifyPeerTransportReset(
deviceId: string,
seq: number,
linkGeneration: number,
): void {
if (this.peerTransportResetHandlers.size === 0) return;
const change: DeviceLinkPeerTransportReset = {
deviceId,
reason: 'ack-timeout',
connectionEpoch: this.connEpoch,
linkGeneration,
seq,
};
for (const cb of this.peerTransportResetHandlers) {
try {
cb(change);
} catch (err) {
this.log.error('device-link peer transport reset handler failed', err);
}
}
}
private markPeerRouteOnline(deviceId: string, linkGeneration?: number): number {
const peer = this.getPeerTransport(deviceId);
peer.linkGeneration = linkGeneration ?? peer.linkGeneration + 1;
this.peerOfflineNotifiedGeneration.delete(deviceId);
return peer.linkGeneration;
}
/** 订阅入站隧道帧(invoke / link-open / link-close / push / 未配对的响应帧) */
onFrame(cb: InboundFrameHandler): () => void {
this.frameHandlers.add(cb);
return () => this.frameHandlers.delete(cb);
}
/**
* 订阅「收到某设备的可靠帧但本端 link 未就绪」通知(同一设备 30s 节流)。
* 控制端 host 据此主动重建控制链路(openLink),打破「发送端等 ACK、
* 接收端等 link」的相互死锁;被控端 host 忽略即可(link 重建由控制端发起)。
*
* 这是该事件的**唯一**出口(#1418 与 #1449 曾各自实现一条,同一代码点双发、
* 两套节流参数)。刻意只报 deviceId、不附带 peer 的 explicitlyClosed:那是双向
* 共享位(互控时对端仅关闭它控制本机的方向也会置位),不能用来判断本机的出站
* 方向该不该恢复 —— 方向判据在 host 侧(是否持有该设备的出站订阅)。
* Return false when the host has no recovery intent; ignored notifications
* do not consume the per-peer throttle. Other return values mean handled.
*/
onReliableFrameBeforeLink(cb: (deviceId: string) => unknown): () => void {
this.staleLinkHandlers.add(cb);
return () => this.staleLinkHandlers.delete(cb);
}
private notifyReliableFrameBeforeLink(deviceId: string): void {
if (this.staleLinkHandlers.size === 0) return;
const now = this.monotonicNow();
const last = this.staleLinkNotifiedAt.get(deviceId);
if (last !== undefined && now - last < STALE_LINK_NOTIFY_THROTTLE_MS) return;
// A stale frame may arrive before the host has any outbound intent (for
// example while a fresh owner is taking over). Do not consume the
// per-peer throttle in that case: a later invoke/subscribe would
// otherwise be unable to wake the host until the full throttle window
// elapsed and could time out while the peer's reliable result is held.
let handled = false;
for (const cb of this.staleLinkHandlers) {
try {
if (cb(deviceId) !== false) handled = true;
} catch (err) {
this.log.error('reliable-frame-before-link handler threw', err);
}
}
if (handled) this.staleLinkNotifiedAt.set(deviceId, now);
}
// ─── 出站 API ───────────────────────────────────────────────────────────────
/** 部分更新本机 presence(开关 / busy);离线时静默忽略(重连时 hello 会带全量) */
sendPresence(patch: PresenceSetPayload): void {
if (this.status !== 'online') return;
this.pendingPresence = { ...this.pendingPresence, ...patch };
this.flushPendingPresence();
}
/** 最近一次 hello-ack 声明的 server 能力(如 SERVER_CAPABILITY_NOTIFY);老 server = 空集。 */
/** Cross-account scopes this relay has announced; scoped frames are only sent after announcement. */
private scopeSupport(): ScopeSupport {
return {
sharedTask: this.hasServerCapability(SHARED_TASK_RELAY_CAPABILITY),
providerShare: this.hasServerCapability(PROVIDER_SHARE_RELAY_CAPABILITY),
};
}
hasServerCapability(capability: string): boolean {
return this.serverCapabilities.includes(capability);
}
/** 最近一次 hello-ack 回的本设备 deviceId(未上线过为 null)。 */
getSelfDeviceId(): string | null {
return this.selfDeviceId;
}
/**
* 请求 server 给本账号已注册推送 token 的移动设备发系统推送(fire-and-forget)。
* 返回是否真的发出:离线或 server 未声明 notify capability 时静默跳过返回 false
* (旧 server 对未知 kind 是静默黑洞,capability gate 是本地协议包的兼容要求)。
* 失败(RATE_LIMITED / BAD_REQUEST)由 relay-error 帧回报,经 onFrame 交 host 记日志。
*/
sendNotify(payload: NotifyPayload): boolean {
if (this.status !== 'online') return false;
if (!this.serverCapabilities.includes(SERVER_CAPABILITY_NOTIFY)) return false;
this.sendEnvelope({
v: PROTOCOL_VERSION,
kind: 'notify',
id: createRequestId(),
payload,
});
return true;
}
/** 控制端:向目标设备发起 link-open,等待 link-accept */
async openLink(dst: string, payload: unknown, timeoutMs?: number): Promise<LinkAcceptPayload> {
// 主动开链 = 控制意图续新:清除出站关闭标记,后续 transport-timeout 恢复照常。
this.getPeerTransport(dst).outboundExplicitlyClosed = false;
const linkPayload = this.addLocalCapabilities(dst, payload);
const env = await this.request(
{ v: PROTOCOL_VERSION, kind: 'link-open', dst, payload: linkPayload },
'link-accept',
timeoutMs,
);
// link-accept 在 dispatchEnvelope 中已经原子提交收发方向并只重放一次;
// 这里不要重复 replay,否则每次重开都会立刻把全部 pending 再发第二遍并消耗重试预算。
return env.payload as LinkAcceptPayload;
}
/**
* 任一端:解除控制链路(fire-and-forget)。
*
* `direction` 声明本次关闭的是哪个控制方向(PeerTransportState 按 deviceId
* 共享两方向,互控时必须区分):
* - 'outbound'(默认):本机主动结束**控制对方**(closeRemoteLink / mobile 断开)。
* 置 outboundExplicitlyClosed —— 此后迟到的 transport-timeout 被拦截,
* 不再自动重建用户关掉的控制链。
* - 'inbound':本机结束**对方对本机的控制**(撤权/踢控制端)。不碰
* outboundExplicitlyClosed —— 若本机仍在主动控制对方,对方发来的
* transport-timeout 仍应触发重建,保留可恢复的主动控制方向。
*/
closeLink(
dst: string,
reason: LinkCloseReason,
direction: 'outbound' | 'inbound' = 'outbound',
): void {
// 本地永久关闭必须同步撤销已排期的 transport-timeout 重试通知:否则迟到
// 的回调会在链路已关闭后补发瞬时重置帧,诱使对端重开用户已关掉的控制方向。
this.cancelTimeoutCloseNotify(dst);
this.pendingInboundLinkOffers.delete(dst);
const peer = this.peerTransport.get(dst);
if (direction === 'inbound') {
if (isProviderSharePeer(dst)) {
this.clearProviderShareDirectLease(dst);
this.detachDirectPath(dst, 'link-closed');
}
// 入站方向关闭(撤权/踢控制端):PeerTransportState 按 deviceId 共享两个
// 方向,互控时仍存续的**出站**可靠层不得陪葬——不置 explicitlyClosed、
// 不拆 reliable/stream、不清 pending、不 reject 在途请求与出站 openLink 等待,
// 否则本机仍在进行的主动控制会立刻吃到 LINK_NOT_OPEN、在途调用被丢。
// 只撤销入站语义:活动入站标记(后续重试耗尽回退整连接重连,升级前
// 语义)并通知对端。纯被控场景(无出站活动)下保留的传输层状态无害:
// dispatch 已清订阅,不会再有新流量灌入。
if (peer) {
// 撤销入站控制方向必须同步取消该方向的确认超时。否则旧 timer
// 会在撤权后继续调用 handleReliableRetryExhausted,误拆共享 relay。
// 若此前已有可用的出站控制方向,恢复原 send phase,不把互控链路一起降级。
this.cancelPendingLinkConfirmation(dst, peer, true);
peer.linkAcceptedInbound = false;
}
} else {
this.cancelRelayQueuedControl(dst);
this.rejectPendingLinkOpen(
dst,
'LINK_NOT_OPEN',
`control link closed locally (${reason})`,
);
if (peer) {
this.markPeerLinkDown(peer);
peer.explicitlyClosed = true;
peer.unlinkedLegacyResponseIds.clear();
// 本地显式关闭同样撤销活动入站标记(与收到永久 link-close 对称):
// 保守撤销的代价只是回到整连接重连语义(安全侧),而保留错误的 true
// 会让 transport-timeout 重开用户已关闭的控制方向。
peer.linkAcceptedInbound = false;
peer.outboundExplicitlyClosed = true;
// 显式关闭只撤掉 streaming 可靠层。listing / topic 控制帧仍不依赖
// link-open,后续应回退到 legacy,而不是被统一挡成 LINK_NOT_OPEN。
peer.reliable = false;
peer.remoteStreamId = null;
peer.remoteBaseSeq = 1;
peer.receive.clear();
this.abandonReliablePending(dst, `control link closed locally (${reason})`);
}
}
// 撤权或断开都不保留直连:之后的数据面只能在 relay 重新建链(并复验授权)后恢复。
this.detachDirectPath(dst, 'link-closed');
// 显式关闭的本地语义不能依赖 relay 当前可写;离线时只跳过通知,
// 已经清掉的可靠 pending 也绝不能在下一次 openLink 后复活。
if (this.status !== 'online') return;
try {
this.sendBestEffortRoutedEnvelope({
v: PROTOCOL_VERSION,
kind: 'link-close',
dst,
payload: { reason } satisfies LinkClosePayload,
});
} catch (err) {
// fire-and-forget:通知失败只记日志,不能把已经完成的本地断链重新暴露成失败。
this.log.debug(`link-close notification failed for ${dst.slice(0, 8)}`, err);
}
}
/** 控制端:远程 invoke,等待 invoke-result */
async invoke(
dst: string,
payload: InvokePayload,
timeoutMs?: number,
options?: { preSend?: () => void; background?: boolean },
): Promise<InvokeResultPayload> {
if (this.status !== 'online' && !this.hasOfflineDirectPath(dst)) {
throw new DeviceLinkError('NOT_CONNECTED', 'not connected to relay');
}
const send = async () => {
// Admission may wait: validate caller ownership/cancellation after dequeue,
// synchronously before creating the request or retaining a transport frame.
options?.preSend?.();
if (resolveInvokePriority(payload.channel, options?.background) === 'background'
&& (this.networkProbeTimer || this.networkChangeTimer)) {
throw new DeviceLinkError('BACKPRESSURE', 'background refresh paused while checking relay connectivity');
}
// Prepare at dispatch, not when joining the admission queue. Earlier
// reads may have filled the existing cache while this one was waiting.
const reuse = this.messageReuse.prepare(dst, payload);
const tagged = requestSessionTagCatalog(reuse.payload);
const transfer = isScopedPeer(dst) ? null : this.invokeResultCache.prepare(dst, tagged);
const env = await this.request(
{ v: PROTOCOL_VERSION, kind: 'invoke', dst, payload: transfer?.payload ?? tagged },
'invoke-result',
timeoutMs,
);
this.reportInvokeMetric(payload.channel, env.payload as InvokeResultPayload);
const result = transfer
? transfer.decode(env.payload as InvokeResultPayload)
: env.payload as InvokeResultPayload;
return result.ok
? {
...result,
result: reuse.decode(decodeModelSpeedPayload(payload.channel, decodeSessionTagCatalog(payload.channel, result.result))),
}
: result;
};
const queuedAt = this.monotonicNow();
return (bypassInvokeScheduling(payload) ? send() : this.invokeScheduler.run(
dst, resolveInvokePriority(payload.channel, options?.background),
Math.min(timeoutMs ?? this.timing.requestTimeoutMs, 30_000), send,
)).catch((error: unknown) => {
if (error instanceof DeviceLinkError && error.code === 'BACKPRESSURE' && !error.inFlight) {
this.log.debug(`device-link invoke admission failed dst=${dst.slice(0, 8)} channel=${payload.channel} priority=${resolveInvokePriority(payload.channel, options?.background)} elapsedMs=${Math.round(this.monotonicNow() - queuedAt)} reason=${error.message}`);
}
throw error;
});
}
/** 被控端:回 invoke-result(对应入站 invoke 的 id) */
sendInvokeResult(dst: string, requestId: string, payload: InvokeResultPayload): void {
const transfer = this.opts.transferCodec ? this.inboundInvokeTransfer.get(dst, requestId) : undefined;
if (transfer) payload = encodeInvokeResultTransfer(transfer, payload, this.opts.transferCodec!);
const peer = this.peerTransport.get(dst);
const env: Envelope = { v: PROTOCOL_VERSION, kind: 'invoke-result', id: requestId, dst, payload };
// 死锁绕行:relay 在线但控制链路未就绪时,result 不能只进可靠队列等一个可能永远
// 不来的 link-accept(2026-08-03 线上实锤:队列冻结 30+ 分钟,每个执行成功的
// 结果都等 120s 过期丢弃),改为 legacy 裸帧即时直发 —— 控制端按 id 配对
// 不依赖可靠层。同时先保留有界可靠副本:原 invoke 可能已 ACK,若直发时
// 对端刚好离线,请求不会重发,必须能在 link 重建后补回结果。
// 超过单帧上限的大 result 只靠可靠层分片。重复结果按 requestId 配对,
// 不会重新执行原操作;副本仍受原队列容量、过期和重放预算约束。
if (peer?.reliable && !this.isPeerSendReady(peer) && this.status === 'online') {
try {
this.sendPeerEnvelope(env);
} catch (err) {
if (!(err instanceof DeviceLinkError && err.code === 'BACKPRESSURE')) throw err;
// 保留副本不能堵住既有死锁绕行;容量耗尽时仍尝试直发,不扩容或驱逐 live 帧。
try {
this.sendBestEffortRoutedEnvelope(env);
} catch (directError) {
// 可分片的大结果只是不适合裸帧;保留队列拥塞错误,让上层 outbox 重试原结果。
if (directError instanceof DeviceLinkError && directError.code === 'PAYLOAD_TOO_LARGE') throw err;
throw directError;
}
peer.unlinkedLegacyResponseIds.delete(requestId);
return;
}
try {
this.sendBestEffortRoutedEnvelope(env);
peer.unlinkedLegacyResponseIds.delete(requestId);
} catch (err) {
if (!(err instanceof DeviceLinkError && err.code === 'PAYLOAD_TOO_LARGE')) {
this.log.debug('unlinked result direct send failed; reliable copy retained', err);
}
}
return;
}
const allowClosedLegacyResponse = peer?.unlinkedLegacyResponseIds.has(requestId) === true;
this.sendPeerEnvelope(env, allowClosedLegacyResponse);
if (allowClosedLegacyResponse) peer?.unlinkedLegacyResponseIds.delete(requestId);
}
/** 被控端:回 link-accept */
sendLinkAccept(dst: string, requestId: string, payload: LinkAcceptPayload): void {
// 只有控制端在 link-open 明确声明过能力时才回显;否则新被控端若
// 单方面包 transport,旧控制端会把 wrapper 当成普通 InvokeResult/Push。
const offer = this.pendingInboundLinkOffers.get(dst);
const matchingOffer = offer?.requestId === requestId ? offer : undefined;
const peerSupportsReliable = (
Array.isArray(matchingOffer?.capabilities)
&& matchingOffer.capabilities.includes(DEVICE_LINK_CAPABILITY_RELIABLE_TRANSPORT)
);
const peerSupportsLinkConfirm = (
peerSupportsReliable
&& matchingOffer!.capabilities!.includes(DEVICE_LINK_CAPABILITY_RELIABLE_LINK_CONFIRM)
);
const peer = this.getPeerTransport(dst);
// 建链即丢弃队头连续的可丢弃前缀(push 不分新旧 + skip 占位):让 accept
// 携带的 transportBaseSeq 直接跳过它们,对端从一开始就不等这些 seq,随后的
// 重放不再灌回离线期间堆积的实时镜像,紧随建链而来的 invoke-result 成为最
// 早可交付的 live seq(v0.1.25 线上曾出现建链后 250ms invoke-result 仍被离
// 线期间堆满的 push 重放洪峰挤在后面,控制端的存活探测因此超时,熔断持续
// open)。
if (peerSupportsReliable) {
this.dropDiscardablePendingPrefix(dst, peer, false, 'before link re-establishment replay');
}
this.beginRecoveryTrace(dst, requestId);
const linkGeneration = peer.linkGeneration + 1;
const linkAcceptId = this.sendRoutedEnvelope({
v: PROTOCOL_VERSION,
kind: 'link-accept',
id: requestId,
dst,
payload: {
...payload,
...(peerSupportsReliable
? {
capabilities: this.mergeCapabilities(payload?.capabilities, [
DEVICE_LINK_CAPABILITY_RELIABLE_TRANSPORT,
...(this.directNegotiator && (!isScopedPeer(dst)
|| (isProviderSharePeer(dst) && matchingOffer?.capabilities?.includes(PROVIDER_SHARE_DIRECT_CAPABILITY)))
? [DIRECT_LINK_CAPABILITY] : []),
...(this.directNegotiator && isProviderSharePeer(dst)
&& matchingOffer?.capabilities?.includes(PROVIDER_SHARE_DIRECT_CAPABILITY)
? [PROVIDER_SHARE_DIRECT_CAPABILITY] : []),
...(peerSupportsLinkConfirm
? [DEVICE_LINK_CAPABILITY_RELIABLE_LINK_CONFIRM]
: []),
]),
transportStreamId: peer.streamId,
transportBaseSeq: this.getTransportBaseSeq(peer),
}
: {}),
},
}, linkGeneration);
this.markPeerRouteOnline(dst, linkGeneration);
this.logRecoveryStage(dst, 'link-accept-sent');
if (!peerSupportsLinkConfirm && linkAcceptId) {
// 旧端没有可等待的 confirmation;accept 是不可重放的单次控制帧,发送后
// 不把它变成永久历史配额;近期迟到错误仍可按原代次归属。
this.settleOutboundRouteAttemptsForId(dst, linkAcceptId);
}
if (matchingOffer) {
this.pendingInboundLinkOffers.delete(dst);
this.setPeerCapabilities(
dst,
matchingOffer.capabilities,
matchingOffer.transportStreamId,
matchingOffer.transportBaseSeq,
);
if (peerSupportsReliable) this.issueProviderShareDirectLease(dst);
}
peer.linkAcceptedInbound = true;
peer.duplicateOpenRepair = null;
if (peerSupportsReliable) {
const resume = this.planReliableSendResume(peer);
this.commitReliableReceiveReady(dst, peer);
if (peerSupportsLinkConfirm) {
this.beginReliableLinkConfirmation(dst, peer, requestId, resume);
} else {
// 旧端没有确认能力:保留 v1 的即时 ready / replay 语义,保证独立升级。
this.commitReliableSendResume(dst, peer, resume);
}
}
}
/** 被控端:广播转发 push 帧(fire-and-forget;失败由上层缓冲策略兜底) */
sendPush(
dst: string,
channel: string,
payload: unknown,
ownerStamp?: import('./protocol.js').PushOwnerStamp,
): void {
payload = encodeModelSpeedPayload(channel, payload);
if (this.status !== 'online' && !this.hasOfflineDirectPath(dst)) return;
const pushPayload = {
channel,
payload,
...(ownerStamp ? { ownerStamp } : {}),
};
if (channel === DEVICE_LINK_TRANSPORT_ACK_CHANNEL) {
this.sendBestEffortRoutedEnvelope({
v: PROTOCOL_VERSION,
kind: 'push',
dst,
payload: pushPayload,
});
return;
}
this.sendPeerEnvelope({ v: PROTOCOL_VERSION, kind: 'push', dst, payload: pushPayload });
}
/**
* 指定 peer 可靠发送队列中未确认的逻辑消息数(0 = 无积压或未建立可靠传输)。
* 供上层做**软背压**:可整流的状态镜像流量(如会话活动快照)在窗口
* (MAX_TRANSPORT_PENDING_MESSAGES)被占满、BACKPRESSURE 变成硬失败之前提前停手,
* 给 invoke-result 等控制面帧留出余量。只读,不改变任何传输状态。
*/
getReliableSendQueueDepth(dst: string): number {
return this.peerTransport.get(dst)?.pending.size ?? 0;
}
// ─── 内部:请求配对 ─────────────────────────────────────────────────────────
private reportInvokeMetric(channel: string, result?: InvokeResultPayload): void {
try {
if (!this.opts.invokeMetrics?.enabled()) return;
this.opts.invokeMetrics.record(result === undefined ? { channel, phase: 'sent' } : {
channel, phase: 'result', payloadBytes: byteLength(JSON.stringify(result)),
notModified: result.ok && result.transfer?.notModified === true,
gzip: result.ok && typeof result.transfer?.gzipBase64 === 'string',
});
} catch { /* Diagnostics must never affect delivery or response decoding. */ }
}
/** 发送请求帧并等待同 id 响应;同 id relay-error 转成 DeviceLinkError reject */
private request(
env: Omit<Envelope, 'id'>,
expectKind: 'invoke-result' | 'link-accept',
timeoutMs?: number,
allowPeerResetRetry = true,
): Promise<Envelope> {
if (this.status !== 'online' && !(env.kind === 'invoke' && env.dst && this.hasOfflineDirectPath(env.dst))) {
return Promise.reject(new DeviceLinkError('NOT_CONNECTED', 'not connected to relay'));
}
const id = createRequestId();
const timeout = timeoutMs ?? this.timing.requestTimeoutMs;
const startedAt = Date.now();
const startedMonotonicAt = this.monotonicNow();
let firstWriteAt: number | undefined;
const sendWaitMs = env.kind === 'invoke' ? Math.min(timeout, REQUEST_SEND_WAIT_MAX_MS) : timeout;
let deadlineMonotonicAt = startedMonotonicAt + sendWaitMs;
let deadlineWallAt = startedAt + sendWaitMs;
const requestDescription = `${this.describeRequest(env, expectKind)} request=${id.slice(0, 8)}`;
const logFinished = (outcome: 'ok' | 'timeout' | 'error', err?: DeviceLinkError): void => {
const elapsedMs = Math.max(0, Math.round(this.monotonicNow() - startedMonotonicAt));
const wallElapsedMs = Math.max(0, Date.now() - startedAt);
const stages = firstWriteAt === undefined ? ' firstWrite=none'
: ` firstWriteWaitMs=${Math.round(firstWriteAt - startedMonotonicAt)}`
+ ` afterFirstWriteMs=${Math.round(this.monotonicNow() - firstWriteAt)}`;
if (outcome === 'timeout') {
this.log.warn(`device-link request timeout ${requestDescription} elapsed=${elapsedMs}ms${stages} wallElapsedMs=${wallElapsedMs}`);
return;
}
if (outcome === 'error') {
if (err?.code !== 'NOT_CONNECTED' || elapsedMs >= SLOW_REQUEST_WARN_MS) {
this.log.debug(
`device-link request failed ${requestDescription} code=${err?.code ?? 'UNKNOWN'} elapsed=${elapsedMs}ms${stages}`,
);
}
return;
}
if (elapsedMs >= SLOW_REQUEST_WARN_MS) {
this.log.debug(`device-link request slow ${requestDescription} elapsed=${elapsedMs}ms${stages}`);
}
};
return new Promise<Envelope>((resolve, reject) => {
const expire = () => {
if (!this.pending.delete(id)) return;
clearTimeout(timer);
if (env.dst) this.settleOutboundRouteAttemptsForId(env.dst, id);
if (env.dst && env.kind === 'invoke') this.dropReliablePendingForRequest(env.dst, id);
logFinished('timeout');
// No physical write is local backpressure, not evidence against the peer.
const err = firstWriteAt === undefined
? new DeviceLinkError('BACKPRESSURE', `request expired before socket write within ${sendWaitMs}ms`)
: new DeviceLinkError('INVOKE_TIMEOUT', `no ${expectKind} within ${timeout}ms after first socket write`);
err.inFlight = firstWriteAt !== undefined;
reject(err);
};
let timer = setTimeout(expire, sendWaitMs);
const pendingRequest: PendingRequest = {
expireIfOverdue: () => {
// Some native monotonic clocks pause in deep sleep. Either elapsed
// clock reaching the budget retires this request: wall time covers
// suspension, monotonic time covers wall-clock rollback. A forward
// wall correction may expire early, but must not replay stale writes.
if (this.monotonicNow() < deadlineMonotonicAt
&& Date.now() < deadlineWallAt) return false;
expire();
return true;
},
noteFirstWrite: () => {
if (firstWriteAt !== undefined) return;
firstWriteAt = this.monotonicNow();
if (env.kind === 'invoke') this.reportInvokeMetric((env.payload as InvokePayload).channel);
// Only the first write can move the deadline. Replays and partial writes
// cannot extend it; total transport lifetime is at most sendWaitMs + timeout.
deadlineMonotonicAt = Math.min(firstWriteAt + timeout, startedMonotonicAt + sendWaitMs + timeout);
deadlineWallAt = Math.min(Date.now() + timeout, startedAt + sendWaitMs + timeout);
clearTimeout(timer);
timer = setTimeout(expire, Math.max(0, Math.min(
deadlineMonotonicAt - this.monotonicNow(), deadlineWallAt - Date.now(),
)));
pendingRequest.timer = timer;
},
hasWritten: () => firstWriteAt !== undefined,
resolve: (frame) => {
clearTimeout(timer);
logFinished('ok');
resolve(frame);
},
reject: (err) => {
clearTimeout(timer);
// Batch failures can share an error, but each request has its own
// delivery status (including partial writes). Never mutate the shared error.
const failure = new DeviceLinkError(err.code, err.message);
failure.inFlight = firstWriteAt !== undefined;
logFinished('error', failure);
reject(failure);
},
timer,
expectKind,
dst: env.dst,
linkGeneration: env.dst ? this.getPeerLinkGeneration(env.dst) : undefined,
};
const relaySigningSession = this.opts.frameAuth?.()?.peerChallenge?.session;
if (env.kind === 'link-open' && relaySigningSession) {
pendingRequest.relayLinkRetry = { envelope: { ...env, id }, session: relaySigningSession };
}
this.pending.set(id, pendingRequest);
if (
allowPeerResetRetry
&& this.opts.peerResetReadRetry === true
&& env.dst
&& isPeerResetRetryableRead(env)
) {
pendingRequest.retryAfterPeerReset = () => {
if (this.pending.get(id) !== pendingRequest) return;
this.pending.delete(id);
clearTimeout(timer);
this.settleOutboundRouteAttemptsForId(env.dst!, id);
this.dropReliablePendingForRequest(env.dst!, id);
this.log.info(
`device-link request peer-reset fast-fail ${requestDescription}`
+ ` action=host-retry-once previousRequest=${id.slice(0, 8)}`,
);
const err = new DeviceLinkError(
'PEER_RESET',
`peer link reset before ${expectKind}; host may retry this read once`,
);
pendingRequest.reject(err);
};
}
try {
const outbound = { ...env, id };
if (outbound.kind === 'link-open' && outbound.dst) this.beginRecoveryTrace(outbound.dst, id);
if (outbound.kind === 'invoke' && outbound.dst) {
const reliable = this.sendPeerEnvelope(outbound);
if (reliable) {
const pending = this.pending.get(id);
if (pending) pending.reliableDst = outbound.dst;
}
} else {
this.sendRoutedEnvelope(outbound);
if (outbound.kind === 'link-open' && outbound.dst) this.logRecoveryStage(outbound.dst, 'link-open-sent');
}
} catch (err) {
this.pending.delete(id);
clearTimeout(timer);
const deviceLinkErr =
err instanceof DeviceLinkError
? err
: new DeviceLinkError('INTERNAL', err instanceof Error ? err.message : String(err));
pendingRequest.reject(deviceLinkErr);
}
});
}
private describeRequest(env: Omit<Envelope, 'id'>, expectKind: 'invoke-result' | 'link-accept'): string {
const dst = env.dst ? env.dst.slice(0, 8) : 'unknown';
const channel = env.kind === 'invoke' ? (env.payload as InvokePayload | undefined)?.channel : env.kind;
return `kind=${env.kind} channel=${channel ?? 'unknown'} dst=${dst} expect=${expectKind}`;
}
private failAllPending(err: DeviceLinkError): void {
this.invokeScheduler.clear(err);
for (const pending of this.pending.values()) {
pending.reject(err);
}
this.pending.clear();
}
private failNonReliablePending(err: DeviceLinkError): void {
this.invokeScheduler.clear(err);
for (const [id, pending] of this.pending) {
if (pending.reliableDst && pending.hasWritten()) continue;
this.pending.delete(id);
if (pending.reliableDst) this.dropReliablePendingForRequest(pending.reliableDst, id);
pending.reject(err);
}
}
/**
* ACK 耗尽 / transport-timeout 只说明当前 peer link 不再可用;对幂等读请求,
* 继续等原 requestTimeoutMs 会把恢复阶段前的 12 秒完整暴露给用户。先结束旧
* request,再由 Desktop 的既有 link recovery 重开并最多提交一次新 request id。
*/
private retryReadRequestsAfterPeerReset(dst: string, seq: number): void {
const candidates = [...this.pending.values()].filter((pending) => (
pending.dst === dst
&& pending.expectKind === 'invoke-result'
&& pending.retryAfterPeerReset
));
if (candidates.length === 0) {
this.log.debug(
`device-link peer-reset no retryable read request dst=${dst.slice(0, 8)} seq=${seq}`,
);
return;
}
for (const pending of candidates) {
this.log.info(
`device-link peer-reset fast-fail read request dst=${dst.slice(0, 8)}`
+ ` seq=${seq} action=retry-once`,
);
pending.retryAfterPeerReset?.();
}
}
private dropReliablePendingForRequest(dst: string, requestId: string): void {
const peer = this.peerTransport.get(dst);
if (!peer) return;
for (const [seq, pending] of peer.pending) {
if (pending.envelope.id !== requestId) continue;
const skipEnvelope: Envelope = {
...pending.envelope,
payload: makeTransportSkipPayload(),
};
const skipBytes = this.measureReservedReliableBytes(skipEnvelope, peer.streamId, seq);
peer.pendingBytes += skipBytes - pending.bytes;
pending.envelope = skipEnvelope;
pending.bytes = skipBytes;
resetReliableSendRound(pending);
pending.sent = false;
// **定向**发这一帧,不借道 retryPending:后者从队头遍历,skip 前面若压着超过预算的
// pending,预算会在到达它之前用完 —— 注释说的「立刻发」就没发生,而接收端正等这个
// seq,后面的可靠消息会一直阻塞(codex P2 第二轮)。skip payload 是单帧,不涉及预算;
// 其余 pending 照旧由定时趟次按预算推进。生成 skip 不证明对端可达,所以这里也不顺带
// 触发无预算重放。
this.sendSkipPlaceholderNow(dst, peer, pending);
return;
}
}
/**
* 立刻发出一个 skip 占位帧(超时 / 永久帧错误后替换原消息用)。前置条件与 retryPending
* 同源;失败只记 debug —— 它本就是 best-effort 的解堵动作,发不出去时由定时趟次接棒。
*/
private sendSkipPlaceholderNow(
dst: string,
peer: PeerTransportState,
pending: PendingReliableMessage,
): void {
if (!peer.reliable || !this.isPeerSendReady(peer) || this.stopped
|| (this.status !== 'online' && !this.hasOfflineDirectPath(dst))) return;
try {
this.sendReliableFrames(peer, pending);
} catch (err) {
this.log.debug(`reliable transport skip placeholder send failed for ${dst.slice(0, 8)}`, err);
}
}
// ─── 内部:连接管理 ─────────────────────────────────────────────────────────
private async connect(reason: string): Promise<void> {
if (this.stopped) return;
this.clearNetworkProbe();
this.resetLegacyInboundQueue();
this.connectionStartedAt = this.monotonicNow();
this.connectAttemptDeadlineWallAt = Date.now() + this.timing.getTokenTimeoutMs + this.effectiveHandshakeTimeoutMs();
this.setStatus('connecting');
const epoch = ++this.connEpoch;
this.lastSocketErrorMessage = null;
this.log.debug(`connecting (reason=${reason})`);
// 关掉可能残留的上一条 socket:getToken await 与 scheduleReconnect 竞态下 this.ws
// 可能仍持半开旧连接,epoch 守卫只忽略其回调、不回收 socket。这里显式关闭防泄漏。
const prev = this.ws;
this.ws = null;
if (prev) {
// 客户端主动重建丢弃在用 socket:旧 socket 的 close 事件被 epoch 守卫屏蔽,不经过
// handleDisconnect——若不在此 fail 掉 in-flight 请求,它们会一直挂到 requestTimeoutMs
// (默认 30s)才超时,用户侧表现为长时间空白干等。语义对齐心跳判死 / 正常断连:
// 立刻 fail(带 inFlight 标记),让上层快速重试。这条 INFO 同时是排障锚点:
// 此路径此前没有任何日志痕迹,连接翻覆时无法与「真实断连重连」区分。
this.log.info(
`discarding live socket for reconnect (reason=${reason}, pending=${this.pending.size}, onlineForMs=${
this.onlineSinceAt === null ? 'never-online' : Math.max(0, Date.now() - this.onlineSinceAt)
})`,
);
this.onlineSinceAt = null;
try {
prev.close(1000, 'reconnecting');
} catch {
prev.terminate?.();
}
this.failNonReliablePending(
new DeviceLinkError('NOT_CONNECTED', `connection restarted (${reason})`),
);
}
let token: string | null = null;
try {
// token 刷新可能走网络:必须有上限,否则弱网下 connect 卡在 connecting
// 且没有任何重连计时器兜底(connectNow 也救不回来,因为 reconnectTimer 为 null)。
token = await withTimeout(
this.opts.getToken(),
this.timing.getTokenTimeoutMs,
'getToken timed out',
);
} catch (err) {
this.log.warn('getToken failed', err);
}
if (this.stopped || epoch !== this.connEpoch) return;
if (!token) {
// 无登录态:按退避节奏静默重试(登录完成后 host 也可直接 restart)
this.scheduleReconnect();
return;
}
let ws: WsLike;
try {
const scheme = typeof this.opts.authorizationScheme === 'function'
? this.opts.authorizationScheme()
: this.opts.authorizationScheme;
ws = await this.opts.createWebSocket(this.opts.getWsUrl(), {
authorization: `${scheme ?? 'Bearer'} ${token}`,
});
} catch (err) {
// 异步工厂可能在更新的一轮 connect 已经起来之后才 reject —— 那是过期尝试的失败,
// 不能据此改状态或排重连(scheduleReconnect 的 connect() 会顶掉那条更新的、
// 可能健康的连接)。与工厂成功分支用同一道 stopped/epoch 闸(review 2026-07-27 P1)。
if (this.stopped || epoch !== this.connEpoch) {
this.log.debug?.('stale createWebSocket rejection ignored', err);
return;
}
this.log.warn('createWebSocket failed', err);
this.scheduleReconnect();
return;
}
// 工厂可能是异步的(host 建连前要准备代理 agent 等):期间可能已 stop 或换了
// 连接世代 —— 那这条 socket 是孤儿,关掉再退,别挂到 this.ws 上。
if (this.stopped || epoch !== this.connEpoch) {
try {
// 必须先挂 error 监听再 close:孤儿 socket 大概率还在 CONNECTING,close() 会让
// ws 异步 emit 'error'(如 "WebSocket was closed before the connection was
// established"),而 EventEmitter 对无监听的 'error' 是直接抛 —— 那会变成主进程
// 的未捕获异常(review 2026-07-27 P1)。
ws.on('error', () => {});
ws.close();
} catch (err) {
this.log.debug?.('closing orphan websocket failed', err);
}
return;
}
this.ws = ws;
this.localSendPressure = false;
this.localSendBudget.reset();
this.armHandshakeTimeout(epoch);
ws.on('open', () => {
if (epoch !== this.connEpoch) return;
// TCP/TLS upgrade made progress. Give hello/ack its own bounded RTT window;
// a slow upgrade must not consume almost all of the application handshake budget.
this.armHandshakeTimeout(epoch);
// 进站第一帧必须是 hello
this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'hello', payload: this.opts.getHello() });
});
ws.on('message', (data) => {
if (epoch !== this.connEpoch) return;
try {
this.handleMessage(data.toString());
} catch (err) {
this.log.error('device-link inbound frame failed', err);
}
});
ws.on('close', (code, reason) => {
if (epoch !== this.connEpoch) return;
const reasonText = closeReasonToString(reason);
this.handleDisconnect(code, reasonText);
});
ws.on('error', (err) => {
if (epoch !== this.connEpoch) return;
// 升级失败(如 401)两端 ws 都不给 close code,只有这条 message 可辨因;
// 记下来供随后 close 事件里的 classifyConnectionIssue 使用。
this.lastSocketErrorMessage = err.message;
this.log.warn('relay connection error', err.message);
// close 事件随后到达,统一在 close 里处理重连
});
}
/**
* 连接世代切换时的链路层复位:link 状态、可靠重试计时器、入站 offer、legacy 队列
* 与跨世代 presence patch。可靠 pending **保留**(等 link 重建后按原 seq 重放)。
* handleDisconnect(被动断线)与 restartConnection(主动重建)共用 —— 主动重建
* 若跳过这段,旧收发 ready 会让 host 侧误以为 link 仍在、跳过 openLink,
* 随后用旧 stream 在新 socket 上发帧被对端当未建链帧丢弃(review P2)。
*/
private resetLinkStateForReconnect(): void {
// hello 会从 host 读取完整最新状态;旧连接上尚未发出的覆盖型 patch 不跨世代重放。
this.clearPendingPresence();
// 旧 socket 的 relay-error 已被 connection epoch 守卫隔离,不可能再合法到达;
// 保留它的物理发送记录只会让新连接重放产生的错误先消费旧代次,误判为 stale。
this.outboundRouteGenerationByPeer.clear();
this.settledOutboundRouteGenerationByPeer.clear();
this.providerShareSignalRouteIds.clear();
for (const [deviceId, peer] of this.peerTransport) {
// An authenticated direct provider-share path has an independent, bounded lease.
if (this.hasOfflineDirectPath(deviceId)) continue;
this.markPeerLinkDown(peer);
peer.recoveryNeedsAck = true;
peer.recoveryFramesSent = 0;
if (peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
}
this.pendingInboundLinkOffers.clear();
this.resetLegacyInboundQueue();
}
private handleDisconnect(code?: number, reason?: string): void {
const onlineForMs =
this.onlineSinceAt === null ? null : Math.max(0, Date.now() - this.onlineSinceAt);
this.log.info(
`device-link disconnected (code=${code ?? 'n/a'}, reason=${reason || 'n/a'}, onlineForMs=${
onlineForMs ?? 'never-online'
})`,
);
this.trackShortLivedConnection(onlineForMs, code, reason);
this.onlineSinceAt = null;
this.clearTimers();
this.ws = null;
this.resetLinkStateForReconnect();
this.failNonReliablePending(new DeviceLinkError('NOT_CONNECTED', 'relay connection lost'));
if (this.stopped) return;
if (code === 4410) {
this.stop();
this.setConnectionIssue({ kind: 'device-removed', closeCode: code, at: Date.now() });
return;
}
if (code === DUPLICATE_CONNECTION_CLOSE_CODE) {
this.log.warn(
`relay replaced this device connection; keeping reconnect backoff warm${reason ? ` (${reason})` : ''}`,
);
}
if (code === RELAY_TRY_AGAIN_LATER_CLOSE_CODE) {
this.congestionCloseStreak++;
this.log.warn(
`relay signalled congestion (close=1013${reason ? `, ${reason}` : ''}); reconnect cool-down engaged (streak=${this.congestionCloseStreak})`,
);
}
// 可分类的失败(鉴权/顶号/超限/版本)记为 issue 供 UI 展示原因;普通断线
// 不产生也不清除 issue —— 401 重连风暴里穿插的网络失败不该把原因洗掉。
const kind = classifyConnectionIssue(code, reason, this.lastSocketErrorMessage);
if (kind) {
this.setConnectionIssue({
kind,
closeCode: code,
detail: reason || this.lastSocketErrorMessage || undefined,
at: Date.now(),
});
}
this.scheduleReconnect();
}
/**
* 握手 watchdog:socket 创建后若在握手窗口内没等到 hello-ack(online),
* 强制关掉这条连接走退避重连。覆盖两类弱网挂起:TCP/TLS 升级挂死(open 不来)、
* upgrade 成功但 hello-ack 丢失。
*
* 窗口自适应:连续 HANDSHAKE_TIMEOUT_WIDEN_AFTER 次握手超时后窗口翻倍(封顶 2×)。
* 高 RTT 链路(实测网络响应性可达 ~10s)上 DNS + TCP + TLS + upgrade + hello 可能
* 恰好超过默认窗口,固定窗口会把「慢但能通」判成永远连不上;翻倍只在连续失败后
* 生效,一次成功上线即复位,不拖慢正常网络下对真死链的判定。
*/
private armHandshakeTimeout(epoch: number): void {
if (this.handshakeTimer) clearTimeout(this.handshakeTimer);
const timeoutMs = this.effectiveHandshakeTimeoutMs();
// keepInFlightAttempt judges by the same deadline the watchdog enforces.
this.connectAttemptDeadlineWallAt = Date.now() + timeoutMs;
this.handshakeTimer = setTimeout(() => {
this.handshakeTimer = null;
if (this.stopped || epoch !== this.connEpoch || this.status === 'online') return;
this.handshakeTimeoutStreak++;
this.log.warn(
`handshake not completed within ${timeoutMs}ms, forcing reconnect (streak=${this.handshakeTimeoutStreak})`,
);
const ws = this.ws;
this.ws = null;
this.connEpoch++;
closeOrTerminate(ws);
this.handleDisconnect(1006, 'handshake timeout');
}, timeoutMs);
}
private effectiveHandshakeTimeoutMs(): number {
return this.handshakeTimeoutStreak >= HANDSHAKE_TIMEOUT_WIDEN_AFTER
? this.timing.handshakeTimeoutMs * 2
: this.timing.handshakeTimeoutMs;
}
private scheduleReconnect(): void {
if (this.stopped || this.reconnectTimer) return;
// 普通指数退避与拥塞冷却下限取 max;向下抖动(0.7x–1.0x)打散同 deviceId
// 双连风暴 / 服务重启后的全端齐步重连,上界不变,文档承诺的最大退避
// (reconnectMaxMs / congestionBackoffMaxMs)仍然成立。
const delay = computeReconnectDelayMs({
attempt: this.reconnectAttempt,
congestionCloseStreak: this.congestionCloseStreak,
reconnectBaseMs: this.timing.reconnectBaseMs,
reconnectMaxMs: this.timing.reconnectMaxMs,
congestionBackoffBaseMs: this.timing.congestionBackoffBaseMs,
congestionBackoffMaxMs: this.timing.congestionBackoffMaxMs,
random: Math.random(),
});
this.reconnectAttempt++;
this.setStatus('connecting');
this.log.debug(
`scheduling device-link reconnect in ${delay}ms (attempt=${this.reconnectAttempt}, congestionStreak=${this.congestionCloseStreak})`,
);
this.reconnectTimer = setTimeout(() => {
this.reconnectTimer = null;
void this.connect('backoff-reconnect');
}, delay);
}
private startHeartbeat(): void {
// 防重复 hello-ack 泄漏旧 interval:重复进入先清掉上一个 ping timer 再重建。
if (this.pingTimer) {
clearInterval(this.pingTimer);
this.pingTimer = null;
}
this.pongMisses = 0;
this.lastInboundAt = this.monotonicNow();
this.pingTimer = setInterval(() => {
if (this.status !== 'online') return;
const now = this.monotonicNow();
// pong 之外的有效入站帧同样证明 relay/socket 仍在工作。弱网下 pong
// 可能丢在业务帧之后,不能因为单独的心跳计数把共享连接整条拆掉。
if (now - this.lastInboundAt <= this.timing.pingIntervalMs) {
this.pongMisses = 0;
}
this.pongMisses++;
// Timer phase must not shorten the idle budget after a valid frame.
// Keep the missed-ping gate too: a delayed JS timer alone is not evidence
// that multiple probes actually went unanswered.
const idleBudgetMs = this.timing.pingIntervalMs * (this.timing.pongMissLimit + 1);
if (this.pongMisses > this.timing.pongMissLimit && now - this.lastInboundAt >= idleBudgetMs) {
this.log.warn(
`heartbeat lost, forcing reconnect (misses=${this.pongMisses}, idleForMs=${now - this.lastInboundAt})`,
);
const ws = this.ws;
this.ws = null;
this.connEpoch++;
// RN 的 WebSocket 没有 terminate:必须 fallback 到 close(),否则半开死
// socket 被原样遗留(handleDisconnect 只清 this.ws 引用),弱网反复
// 断连会累积泄漏 socket 与事件回调。
closeOrTerminate(ws);
this.handleDisconnect(1006, 'heartbeat lost');
return;
}
try {
this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'ping' });
} catch {
// 发送失败交给 close 流程
}
}, this.timing.pingIntervalMs);
}
private clearTimers(): void {
this.clearNetworkProbe();
for (const peer of this.relayChallenges.keys()) this.clearRelayChallenge(peer);
if (this.reconnectTimer) {
clearTimeout(this.reconnectTimer);
this.reconnectTimer = null;
}
if (this.reconnectStableTimer) {
clearTimeout(this.reconnectStableTimer);
this.reconnectStableTimer = null;
}
if (this.congestionStableTimer) {
clearTimeout(this.congestionStableTimer);
this.congestionStableTimer = null;
}
if (this.handshakeTimer) {
clearTimeout(this.handshakeTimer);
this.handshakeTimer = null;
}
if (this.pingTimer) {
clearInterval(this.pingTimer);
this.pingTimer = null;
}
if (this.presenceRetryTimer) {
clearTimeout(this.presenceRetryTimer);
this.presenceRetryTimer = null;
}
}
private flushPendingPresence(): void {
if (!this.pendingPresence || this.status !== 'online') return;
const patch = this.pendingPresence;
try {
this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'presence-set', payload: patch });
if (this.pendingPresence === patch) this.pendingPresence = null;
} catch (err) {
if (
err instanceof DeviceLinkError
&& (err.code === 'BACKPRESSURE' || err.code === 'NOT_CONNECTED')
) {
if (err.code === 'BACKPRESSURE') this.schedulePresenceRetry();
else this.clearPendingPresence();
return;
}
throw err;
}
}
private schedulePresenceRetry(): void {
if (this.presenceRetryTimer || !this.pendingPresence) return;
this.presenceRetryTimer = setTimeout(() => {
this.presenceRetryTimer = null;
this.flushPendingPresence();
}, this.timing.presenceRetryIntervalMs);
(this.presenceRetryTimer as unknown as { unref?: () => void }).unref?.();
}
private clearPendingPresence(): void {
this.pendingPresence = null;
if (!this.presenceRetryTimer) return;
clearTimeout(this.presenceRetryTimer);
this.presenceRetryTimer = null;
}
// ─── 内部:入站分发 ─────────────────────────────────────────────────────────
private handleMessage(raw: string): void {
let parsed: unknown;
try {
parsed = JSON.parse(raw) as unknown;
} catch {
this.log.warn('dropping unparseable frame');
return;
}
if (!isKnownInboundEnvelope(parsed)) {
this.log.warn('dropping invalid device-link frame');
return;
}
// 自建中转:对端帧必须带发送设备的有效签名(在任何解码与分发之前核对,中转改不了内容)。
const frameAuth = this.opts.frameAuth?.();
if (typeof parsed.src === 'string' && ROUTED_KINDS.has(parsed.kind)) {
if (frameAuth && !frameAuth.verify(parsed as unknown as Record<string, unknown>)) {
this.noteRejectedSignature(parsed.src, parsed.kind);
// 冷启动证书尚未就绪时也只发有界认证探测;未验签业务仍直接丢弃。
// 与设备证书相同的短 ID 边界,避免任意长来源占据探测队列。
if (parsed.src.length > 0 && parsed.src.length <= 256 && frameAuth.peerChallenge
&& frameAuth.peerChallenge.state(parsed.src) !== 'ready') {
try { this.probeRelayChallenge(parsed.src, this.ensureRelayChallenge(parsed.src, frameAuth)); }
catch { /* 认证重试有界;失败不触发共享 socket 重连。 */ }
}
return;
}
}
const env = decodeScopedEnvelope(parsed, this.scopeSupport());
if (!env) { this.log.warn('dropping invalid device-link routing scope'); return; }
const validForHeartbeat = isValidInboundEnvelope(env);
// 畸形 invoke / link-close 仍须进入 Desktop 业务层:前者生成结构化拒绝,后者
// 走既有 fail-generic 的 peer teardown;但两者都不能因此喂活 heartbeat。
// 其它已知 kind 的非法 payload 直接丢弃。
if (!validForHeartbeat && env.kind !== 'invoke' && env.kind !== 'link-close') {
this.log.warn(`dropping invalid device-link frame kind=${env.kind}`);
return;
}
if (validForHeartbeat) {
this.lastInboundAt = this.monotonicNow();
if (env.src && ROUTED_KINDS.has(env.kind)) this.lastPeerInboundAt = this.lastInboundAt;
if (this.networkProbeTimer) {
clearTimeout(this.networkProbeTimer);
this.networkProbeTimer = null;
this.networkProbeNextAllowedAt = this.lastInboundAt + 3_000;
this.log.debug(`network probe confirmed relay activity (elapsedMs=${Math.max(0, this.lastInboundAt - this.networkProbeStartedAt)})`);
}
}
if (frameAuth?.peerChallenge && env.src && ROUTED_KINDS.has(env.kind)) {
const handshake = relayAuthHandshake(env);
if (handshake === 'request') {
// 只回送认证证明,不调用业务 handler,也不改变 remoteControlEnabled 或订阅。
try {
this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'push', id: env.id, dst: env.src,
payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'response' } } });
} catch { /* 对端会在自己的预算内重试。 */ }
this.recoverRelayLinkOpen(env.src, frameAuth);
return;
}
if (handshake === 'response') {
if (frameAuth.peerChallenge.state(env.src) === 'ready') this.flushRelayChallenge(env.src, frameAuth);
return;
}
}
const ack = parseTransportAck(env);
if (ack) {
if (env.src) {
this.handleTransportAck(env.src, ack.streamId, ack.ackSeq, ack.linkRequestId);
}
return;
}
const transport = this.ingestTransportEnvelope(env);
if (transport.handled) {
void transport.result?.catch((err) => {
this.log.error('device-link reliable frame failed', err);
});
return;
}
if (isLegacyBusinessFrame(env.kind)) {
this.enqueueLegacyEnvelope(env);
return;
}
const result = this.dispatchEnvelope(env);
if (isPromiseLike(result)) {
void Promise.resolve(result).catch((err) => {
this.log.error('device-link control frame failed', err);
});
}
}
private enqueueLegacyEnvelope(env: Envelope): void {
const frameBytes = byteLength(JSON.stringify(env));
if (
this.legacyInboundFrames >= MAX_LEGACY_INBOUND_FRAMES
|| this.legacyInboundBytes + frameBytes > MAX_LEGACY_INBOUND_BYTES
) {
this.log.warn(
`dropping legacy device-link frame under backpressure kind=${env.kind} queued=${this.legacyInboundFrames}`,
);
return;
}
const epoch = this.connEpoch;
const generation = this.legacyInboundGeneration;
const run = async (): Promise<void> => {
if (
this.stopped
|| epoch !== this.connEpoch
|| generation !== this.legacyInboundGeneration
) return;
await this.dispatchEnvelope(env);
};
this.legacyInboundFrames++;
this.legacyInboundBytes += frameBytes;
if (this.legacyInboundChain) {
this.trackLegacyInbound(this.legacyInboundChain.then(run, run), frameBytes, generation);
return;
}
try {
const result = this.dispatchEnvelope(env);
if (isPromiseLike(result)) {
this.trackLegacyInbound(
Promise.resolve(result).then(() => undefined),
frameBytes,
generation,
);
} else if (generation === this.legacyInboundGeneration) {
this.legacyInboundFrames--;
this.legacyInboundBytes -= frameBytes;
}
} catch (err) {
if (generation === this.legacyInboundGeneration) {
this.legacyInboundFrames--;
this.legacyInboundBytes -= frameBytes;
}
this.log.error('device-link legacy frame failed', err);
}
}
private trackLegacyInbound(
task: Promise<void>,
frameBytes: number,
generation: number,
): void {
const tracked = task
.catch((err) => {
this.log.error('device-link legacy frame failed', err);
})
.finally(() => {
if (generation !== this.legacyInboundGeneration) return;
this.legacyInboundFrames--;
this.legacyInboundBytes -= frameBytes;
if (this.legacyInboundChain === tracked) this.legacyInboundChain = null;
});
this.legacyInboundChain = tracked;
}
private resetLegacyInboundQueue(): void {
this.legacyInboundGeneration++;
this.legacyInboundChain = null;
this.legacyInboundFrames = 0;
this.legacyInboundBytes = 0;
}
private dispatchEnvelope(env: Envelope): boolean | Promise<boolean> {
if ((env.kind === 'link-open' || env.kind === 'link-accept') && env.src && env.dst) {
const remote = parseProviderSharePeer(env.src);
const local = parseProviderSharePeer(env.dst);
if (remote && local && remote.shareId === local.shareId && remote.role !== local.role
&& local.deviceId === this.selfDeviceId) this.providerShareLocalAddresses.set(env.src, env.dst);
}
switch (env.kind) {
case 'hello-ack': {
const ack = env.payload as HelloAckPayload;
// 协议版本不一致:隧道帧语义可能漂移,不要进 online。关连接,由退避重连兜底
// (等任一端升级到一致版本)。服务端通常已在 hello 阶段以 VERSION_MISMATCH 拒绝,
// 此处是 hello-ack 路径的防御性二道闸。
if (
typeof ack?.serverProtocolVersion === 'number' &&
ack.serverProtocolVersion !== PROTOCOL_VERSION
) {
this.log.error(
`device-link protocol mismatch: server v${ack.serverProtocolVersion}, client v${PROTOCOL_VERSION}; staying offline`,
);
// 客户端主动断开时本地 close 事件的 code 未必回传 4400,这里直接记 issue
this.setConnectionIssue({
kind: 'version-mismatch',
detail: `server v${ack.serverProtocolVersion}, client v${PROTOCOL_VERSION}`,
at: Date.now(),
});
this.ws?.close(4400, 'protocol version mismatch');
return true; // close 事件经 epoch 校验后走 handleDisconnect → 退避重连
}
// unstable 描述的是跨连接的抖动模式,不能在每次短暂握手成功时清掉;
// 只有稳定在线满一个稳定期才算恢复。
if (this.connectionIssue?.kind !== 'unstable') this.setConnectionIssue(null);
this.serverCapabilities = Array.isArray(ack?.capabilities)
? ack.capabilities.filter((c): c is string => typeof c === 'string')
: [];
if (typeof ack?.deviceId === 'string' && ack.deviceId) {
this.selfDeviceId = ack.deviceId;
}
if (this.handshakeTimer) {
clearTimeout(this.handshakeTimer);
this.handshakeTimer = null;
}
this.handshakeTimeoutStreak = 0;
const wasOnline = this.status === 'online';
this.setStatus('online');
if (!wasOnline) this.onlineSinceAt = Date.now();
this.armReconnectStableReset();
this.armCongestionStableReset();
this.startHeartbeat();
// 重复 hello-ack(已在线还收到 ack)单独判别:这不是新连接,而是 relay 在同一条
// socket 上重发(relay 侧恢复 / 迁移)。若与真实重连共用同一条 online 日志,
// 连接翻覆排障时会误判为多次重连(手机端无落盘日志,现场只有这一条线索)。
if (wasOnline) {
this.log.info(`duplicate hello-ack while already online (protocol=v${ack.serverProtocolVersion})`);
} else {
this.log.info(`device-link online (protocol=v${ack.serverProtocolVersion}, elapsedMs=${Math.max(0, this.monotonicNow() - this.connectionStartedAt)})`);
}
return true;
}
case 'pong':
this.pongMisses = 0;
return true;
case 'presence-changed': {
const snap = env.payload as PresenceSnapshot;
// 在线与账号归属以 relay 为准:对端离开 relay(含被移出账号)即撤下直连。
if (snap.online === false) this.detachDirectPath(snap.deviceId, 'peer-offline');
for (const cb of this.presenceHandlers) {
try {
cb(snap);
} catch (err) {
this.log.error('presence handler threw', err);
}
}
return true;
}
case 'invoke-result':
case 'link-accept': {
// 配对要 id + kind 双重命中:仅 id 撞而 kind 不符(如 invoke-result 撞到一个
// 等 link-accept 的 pending)的帧不得错误 resolve —— 留它超时,本帧当未知帧交 host。
const p = env.id ? this.pending.get(env.id) : undefined;
// A request ID alone cannot authorize a reply from another device or task scope.
if (p?.dst && env.src !== p.dst) return true;
if (p && p.expectKind === env.kind) {
if (env.kind === 'link-accept' && env.src) {
const accepted = env.payload as LinkAcceptPayload | undefined;
this.setPeerCapabilities(
env.src,
accepted?.capabilities,
accepted?.transportStreamId,
accepted?.transportBaseSeq,
'outbound-accept',
);
this.issueProviderShareDirectLease(env.src);
const peer = this.getPeerTransport(env.src);
const acceptedLinkGeneration = this.markPeerRouteOnline(env.src);
this.logRecoveryStage(env.src, 'link-accept-received', ` baseSeq=${peer.remoteBaseSeq}`);
// 这是本机先发送 link-open、对端收到后才可能返回的 accept。relay 对同一
// 来源连接严格按发送顺序处理,因此任何更早物理发送若会产生 route error,
// 错误必然排在这次 accept 之前;走到这里仍无错误的旧代记录就是已成功路由
// 但未收到 transport ACK 的尝试。重放前清掉它们,避免当前代真实错误被
// FIFO 错归给旧代。入站 link-open 的 sendLinkAccept 当下来自另一条来源
// 连接、尚不具备此屏障;仅新版 confirmation ACK 到达后再做同类清理。
this.discardOutboundRouteAttemptsBeforeGeneration(
env.src,
acceptedLinkGeneration,
);
peer.outboundExplicitlyClosed = false;
// 注意:不得在此将 linkAcceptedInbound 改回 false。互控场景下本机可能
// 既是对端的被控端(入站已 accept)又是其控制端(本帧 accept 出站
// link),两个方向共享同一份 PeerTransportState——覆盖会让入站方向
// 的重试耗尽误拆整条共享 relay(字段注释有完整语义)。
if (peer.reliable) {
if (env.src === p.dst && peer.remoteStreamId) {
for (const cb of this.peerStreamAcceptedHandlers) {
try { cb(env.src, peer.remoteStreamId); }
catch (error) { this.log.error('peer stream accepted handler threw', error); }
}
}
const resume = this.planReliableSendResume(peer);
this.commitReliableReceiveReady(env.src, peer);
this.commitReliableSendResume(env.src, peer, resume);
if (
Array.isArray(accepted?.capabilities)
&& accepted.capabilities.includes(DEVICE_LINK_CAPABILITY_RELIABLE_LINK_CONFIRM)
&& env.id
) {
this.sendReliableLinkConfirmation(env.src, env.id, peer);
}
}
}
if (p.dst && env.id) this.discardOutboundRouteAttemptsForId(p.dst, env.id);
this.pending.delete(env.id!);
if (env.kind === 'invoke-result' && env.src) this.logRecoveryStage(env.src, 'first-response-received');
p.resolve(env);
return true;
}
return this.emitFrame(env);
}
case 'relay-error': {
const payload = env.payload as RelayErrorPayload;
// During a rolling deploy, a newer ingress can advertise signaling while an
// older provider-share relay hop still rejects the scoped push. It is only
// this best-effort signal that failed, not the already-open reliable link.
if (env.id && env.providerShare !== undefined && payload.dst
&& this.providerShareSignalRouteIds.get(env.id)?.dst === payload.dst) {
this.providerShareSignalRouteIds.delete(env.id);
this.discardOutboundRouteAttemptsForId(payload.dst, env.id);
return true;
}
const terminalRouteFailure = (
payload.code === 'DEVICE_OFFLINE'
|| payload.code === 'REMOTE_DISABLED'
);
const pending = env.id ? this.pending.get(env.id) : undefined;
if (pending && ((payload.dst !== undefined && payload.dst !== pending.dst)
|| (isSharedTaskPeer(pending.dst) && env.sharedTask === undefined)
|| (isProviderSharePeer(pending.dst) && env.providerShare === undefined))) return true;
const routeDeviceId = payload.dst ?? pending?.dst;
const rememberedGeneration = env.id
? this.consumeOutboundRouteGeneration(env.id, routeDeviceId)
: undefined;
// 所有 routed frame 都在物理发送前登记。未决记录会在成功结算后转入
// 不占发送额度的近期历史;transport ACK 则确认逻辑 seq 已交付并释放记录。
// ACK / relay-error 都没有物理 attempt id,重试又复用同一逻辑 id:ACK 后再来的
// 同 id 错误无法区分「旧发送迟到」与「后续重试失败」。此时 fail-stale 忽略,
// 避免拆掉刚恢复的新 link 或让已在对端执行的 invoke 向用户报失败;精确关联需要
// wire 携带物理发送标识,由分层传输任务继续处理。
// 若两份账本都查不到且没有 legacy request generation,不回退成当前代拆 link。
const releasedOrSettledRouteError = !!env.id
&& rememberedGeneration === undefined
&& (pending?.reliableDst !== undefined || pending?.linkGeneration === undefined);
const routeLinkGeneration = rememberedGeneration
?? (pending?.reliableDst ? undefined : pending?.linkGeneration)
?? (routeDeviceId ? this.getPeerLinkGeneration(routeDeviceId) : 0);
const stalePeerRouteError = !!routeDeviceId
&& (
releasedOrSettledRouteError
|| routeLinkGeneration < this.getPeerLinkGeneration(routeDeviceId)
);
// DEVICE_OFFLINE is a peer route transition, not merely a rejected
// request. Emit it before the pending fast path so the host cannot
// miss it when the relay error is paired with an in-flight request.
if (payload.code === 'DEVICE_OFFLINE' && routeDeviceId && !releasedOrSettledRouteError) {
this.notifyPeerRouteOffline(routeDeviceId, routeLinkGeneration);
}
// 同一个可靠 invoke 会在 peer link 重开后用原 request id 重放。旧代物理发送的
// terminal route error 可能晚于新代重放到达;它只负责消费上面的路由代次记录,
// 不能 reject 当前逻辑请求或把当前重放帧改成 skip,否则调用方会先看到失败、
// 而对端稍后仍可能执行成功。当前代错误仍走下方既有 fail-closed 收口。
if (pending?.reliableDst && terminalRouteFailure && stalePeerRouteError) {
return true;
}
if (env.id && pending) {
const p = pending;
this.pending.delete(env.id);
if (routeDeviceId) this.discardOutboundRouteAttemptsForId(routeDeviceId, env.id);
// relay-error 代表原 invoke 没有交付到 peer。若它占用了可靠 stream 的 seq,
// 不能只 reject 上层后把原请求留到重连重放,否则一个已向用户报错的写操作
// 可能稍后突然执行。永久断链错误丢弃该 peer 全部 pending、靠下次握手 baseSeq
// 跨过;其它单帧错误改成同 seq skip。
if (p.reliableDst) {
if (terminalRouteFailure && !stalePeerRouteError) {
this.markPeerLinkDown(this.getPeerTransport(p.reliableDst));
this.abandonReliablePending(
p.reliableDst,
`relay rejected reliable link (${payload.code})`,
);
} else {
this.dropReliablePendingForRequest(p.reliableDst, env.id);
}
}
p.reject(new DeviceLinkError(payload.code, payload.message));
return true;
}
if (payload.dst && terminalRouteFailure && !stalePeerRouteError) {
const peer = this.getPeerTransport(payload.dst);
this.markPeerLinkDown(peer);
peer.recoveryNeedsAck = true;
peer.recoveryFramesSent = 0;
if (peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
// 没有本地 PendingRequest 的可靠帧是 invoke-result / push。目标瞬时离线时
// 必须保留它们,等下一次 link-open 后重放;否则原 invoke 已在请求方向 ACK,
// 控制端不会再发一次,已完成结果会永久丢失。显式 link-close 仍会清掉 pending。
} else if (
env.id
&& payload.dst
&& (payload.code === 'BAD_REQUEST' || payload.code === 'PAYLOAD_TOO_LARGE')
) {
// invoke-result 没有本地 PendingRequest,但仍带原 request id。永久性帧错误
// 也要把对应 seq 换成 skip,否则它会耗尽重试并拖着整条 relay 反复重连。
this.dropReliablePendingForRequest(payload.dst, env.id);
}
// 连接级(无 pending id)的 VERSION_MISMATCH:server 在 hello 阶段拒绝时先发
// 这帧再 close(4400)。在这里直接记 issue,分类不依赖 close reason 文本——
// close code 4400 同时承载 invalid frame / invalid envelope 等语义,reason
// 又可能被中间层截断,这条帧是版本不符最可靠的信号。
if (payload.code === 'VERSION_MISMATCH') {
this.setConnectionIssue({
kind: 'version-mismatch',
detail: payload.message,
at: Date.now(),
});
}
this.log.warn(
`relay-error: [${payload.code}] ${payload.message}`
+ (payload.dst ? ` dst=${payload.dst.slice(0, 8)}` : ''),
);
return this.emitFrame(env);
}
default:
// 隧道帧(invoke / link-open / link-close / push)交给 host
if (env.kind === 'link-open' && env.src) {
const open = env.payload as LinkOpenPayload | undefined;
if (env.id) {
this.rememberInboundLinkOffer(env.src, {
requestId: env.id,
capabilities: open?.capabilities,
transportStreamId: open?.transportStreamId,
transportBaseSeq: open?.transportBaseSeq,
});
}
} else if (env.kind === 'link-close' && env.src) {
const close = env.payload as LinkClosePayload | undefined;
if (close?.reason === 'transport-timeout') {
// 本地已显式关闭该链路(closeLink 置了 explicitlyClosed):我们的永久
// link-close 可能因背压/发送异常未送达,对端为保留消息耗尽重试后
// 发来瞬时重置。本机已无主动控制意图,拦截不交 app 层——否则
// desktop 会 openRemoteLink/mobile 会 rehydrate,把用户刚关闭的控制链
// 重新建起。吞帧即稳态:对端通知重试自行终止,其保留 pending 等待
// 将来显式重开或其自身清理路径回收。
const existing = this.peerTransport.get(env.src);
// 按控制方向判断:只有本机已显式结束**出站**控制(closeRemoteLink /
// mobile 断开)才吞帧。入站方向的撤权(revokeController →
// closeLink('revoked','inbound'))也会置共享的 explicitlyClosed,但本机
// 可能仍在主动控制对方——若据此吞帧,存续的主动控制方向永不恢复。
if (existing?.outboundExplicitlyClosed) {
this.log.debug(
`ignoring late transport-timeout from ${env.src.slice(0, 8)} after local outbound close`,
);
return true;
}
// 对端(被控端)对本机的可靠重试耗尽,做了 peer 级瞬时重置。这不是
// 永久关闭:不置 explicitlyClosed、不拆可靠层、不拒在途请求——保留
// stream 与 pending,重新 link-open/link-accept 后按 reconnect-continuity
// 语义同 seq 续传,在途 invoke-result 仍可送达(超时由各请求自身的
// requestTimeout 兕底)。帧照常交给 app 层:mobile 据此立即发起 rehydrate,
// desktop 控制端据此立即重新 openLink(见各自 link-close 处理)。
const peer = this.getPeerTransport(env.src);
this.markPeerLinkDown(peer);
this.retryReadRequestsAfterPeerReset(env.src, 0);
if (peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
return this.emitFrame(env);
}
this.pendingInboundLinkOffers.delete(env.src);
this.rejectPendingLinkOpen(
env.src,
close?.reason === 'revoked' ? 'ACCESS_REVOKED' : 'LINK_NOT_OPEN',
close?.reason === 'revoked'
? 'access revoked by target device'
: 'control link closed by peer',
);
const peer = this.getPeerTransport(env.src);
this.markPeerLinkDown(peer);
peer.explicitlyClosed = true;
peer.unlinkedLegacyResponseIds.clear();
// 收到永久关闭同样撤销已排期的 transport-timeout 重试通知(与本地
// closeLink 对称):链路已死,迟到通知只会诱使对端重开已关闭的方向。
this.cancelTimeoutCloseNotify(env.src);
// 永久关闭同时撤销「当前活动入站方向」标记:互控时入站方向被对方
// 用户明确关闭后,后续出站方向的重试耗尽不得再误判为「仍有活动
// 入站」而发 transport-timeout——那会让对端自动重开用户已关掉的控制
// 方向。回到整连接重连语义是安全侧;对方重新 link-open 时
// sendLinkAccept 会重新置位;transport-timeout(瞬时重置)不走本分支
// 也不清此标记。
peer.linkAcceptedInbound = false;
// 对端关闭与本地 closeLink 语义对称:撤掉 streaming 可靠层,
// 后续不依赖 link-open 的 listing/control invoke 可回退 legacy。
peer.reliable = false;
peer.remoteStreamId = null;
peer.remoteBaseSeq = 1;
peer.receive.clear();
this.abandonReliablePending(env.src, 'control link closed by peer');
this.detachDirectPath(env.src, 'link-closed');
} else if (
env.kind === 'invoke'
&& env.src
&& env.id
&& isUnlinkedLegacyEnvelope(env)
) {
const peer = this.getPeerTransport(env.src);
if (peer.explicitlyClosed && !this.isPeerLinkReady(peer)) {
this.rememberUnlinkedLegacyResponse(peer, env.id);
}
}
return this.emitFrame(env);
}
}
/**
* 可靠传输 wrapper 的接收端状态机:
* - 同一 stream 只按 seq 连续交付;
* - 缺片、乱序和重复只进入有界缓存,不会直接污染 host;
* - 只有 host handler 真正成功后才推进累计 ACK;
* - handler 失败时保留当前消息并停止后续交付,等待有限重发。
*/
private ingestTransportEnvelope(
env: Envelope,
path: DeviceLinkPeerPath = 'relay',
): { handled: false } | { handled: true; result?: Promise<void> } {
const parsed = parseTransportPayload(env.payload);
if (!parsed || !env.src || !isReliableKind(env.kind)) return { handled: false };
const peer = this.getPeerTransport(env.src);
if (!peer.reliable || !peer.receiveReady) {
// 可靠业务帧只在双方完成 link-open/link-accept 能力协商后接收。断线后迟到的
// pub/sub 帧可能被投到同 deviceId 的新进程;提前执行会绕过新基线并重复副作用。
// 不回 ACK,让仍存活的发送端在链路重新建立后按同 seq 重放。
this.log.debug(`dropping reliable payload before link is ready from ${env.src.slice(0, 8)}`);
// 但发送端还在按可靠流发帧 = 它认为链路该通而本端没有 link ——
// 光靠沉默丢弃两边会互等(死锁的另一半)。节流通知 host,由控制端
// 决定是否主动重新 link-open 让双方 stream 重新对齐。
this.notifyReliableFrameBeforeLink(env.src);
return { handled: true };
}
if (peer.remoteStreamId && peer.remoteStreamId !== parsed.meta.streamId) {
this.log.debug(
`dropping stale reliable stream from ${env.src.slice(0, 8)} expected=${peer.remoteStreamId.slice(0, 8)} got=${parsed.meta.streamId.slice(0, 8)}`,
);
return { handled: true };
}
if (!peer.remoteStreamId) peer.remoteStreamId = parsed.meta.streamId;
peer.lastInboundPath = path;
const { meta } = parsed;
this.logRecoveryStage(env.src, 'first-reliable-receive', ` seq=${meta.seq} baseSeq=${meta.baseSeq ?? 1}`);
const stream = this.getReceiveStream(
peer,
meta.streamId,
Math.max(peer.remoteBaseSeq, meta.baseSeq ?? 1),
);
// Only emitted on an existing rejection path; never log payload contents.
const describeRejectedFrame = (): string =>
`src=${env.src?.slice(0, 8)} stream=${meta.streamId.slice(0, 8)} seq=${meta.seq}`
+ ` request=${typeof env.id === 'string' ? env.id.slice(0, 8) : 'none'} kind=${env.kind}`
+ ` next=${stream.lastDeliveredSeq + 1} delivering=${stream.deliveringSeq ?? 'none'}`
+ ` ready=${stream.ready.size} assemblies=${stream.assemblies.size} bufferedBytes=${stream.bufferedBytes}`;
const isSkip = !meta.segment && (() => {
try {
return isTransportSkipPayload(decodeTransportJson(parsed.data));
} catch {
return false;
}
})();
if (meta.seq <= stream.lastDeliveredSeq) {
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
return { handled: true };
}
if (meta.seq > stream.lastDeliveredSeq + MAX_TRANSPORT_SEQUENCE_WINDOW) {
this.log.warn(`dropping reliable payload reason=receive_window ${describeRejectedFrame()}`);
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
return { handled: true };
}
if (stream.ready.has(meta.seq) && !isSkip) {
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
const result = this.drainTransportStream(env.src, meta.streamId, stream);
return { handled: true, result };
}
const segment = meta.segment;
if (!segment) {
const bytes = byteLength(parsed.data);
if (isSkip) {
this.removeReceiveEntry(stream, meta.seq);
} else if (stream.assemblies.has(meta.seq)) {
// 同一 seq 只有 timeout / relay-error 生成的 skip 允许从分片消息改成
// 单帧。其它 shape 变化保留原重组,避免混入不一致 payload。
this.log.warn(`dropping reliable payload with changed segment shape seq=${meta.seq}`);
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
return { handled: true };
}
const rejection = bytes > MAX_TRANSPORT_CHUNK_BYTES ? 'chunk_too_large'
: !this.ensureReceiveCapacity(stream, meta.seq, bytes) ? 'receive_capacity_exceeded' : null;
if (rejection) {
this.log.warn(`dropping reliable payload reason=${rejection} ${describeRejectedFrame()} incomingBytes=${bytes}`);
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
return { handled: true };
}
try {
decodeTransportJson(parsed.data);
} catch {
this.log.warn(`dropping invalid reliable payload seq=${meta.seq}`);
return { handled: true };
}
const receivedAt = this.monotonicNow();
stream.ready.set(meta.seq, { env, json: parsed.data, receivedAt, readyAt: receivedAt });
stream.bufferedBytes += bytes;
} else {
if (segment.totalBytes > MAX_TRANSPORT_REASSEMBLY_BYTES) {
this.log.warn(`dropping oversized reliable reassembly seq=${meta.seq}`);
return { handled: true };
}
const current = stream.assemblies.get(meta.seq);
const assembly = current ?? {
receivedAt: this.monotonicNow(),
kind: env.kind,
id: env.id,
src: env.src,
dst: env.dst,
total: segment.total,
totalBytes: segment.totalBytes,
chunks: new Map<number, string>(),
bytes: 0,
};
if (
assembly.kind !== env.kind ||
assembly.id !== env.id ||
assembly.src !== env.src ||
assembly.dst !== env.dst ||
assembly.total !== segment.total ||
assembly.totalBytes !== segment.totalBytes
) {
stream.bufferedBytes -= assembly.bytes;
stream.assemblies.delete(meta.seq);
this.log.warn(`dropping reliable payload with changed segment metadata seq=${meta.seq}`);
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
return { handled: true };
}
if (!assembly.chunks.has(segment.index)) {
const bytes = byteLength(parsed.data);
const rejection = bytes > MAX_TRANSPORT_CHUNK_BYTES ? 'chunk_too_large'
: assembly.bytes + bytes > assembly.totalBytes ? 'declared_size_exceeded'
: !this.ensureReceiveCapacity(stream, meta.seq, bytes, true) ? 'receive_capacity_exceeded' : null;
if (rejection) {
this.log.warn(`dropping reliable payload reason=${rejection} ${describeRejectedFrame()}`
+ ` incomingBytes=${bytes} assembledBytes=${assembly.bytes} declaredBytes=${assembly.totalBytes}`
+ ` segment=${segment.index}/${segment.total}`);
this.removeReceiveEntry(stream, meta.seq);
return { handled: true };
}
assembly.chunks.set(segment.index, parsed.data);
assembly.bytes += bytes;
stream.bufferedBytes += bytes;
}
stream.assemblies.set(meta.seq, assembly);
if (assembly.chunks.size === assembly.total) {
const json = Array.from({ length: assembly.total }, (_, index) => assembly.chunks.get(index) ?? '').join('');
stream.assemblies.delete(meta.seq);
try {
decodeTransportJson(json, assembly.totalBytes);
} catch {
stream.bufferedBytes -= assembly.bytes;
this.log.warn(`dropping invalid reliable reassembly seq=${meta.seq}`);
this.sendTransportAck(env.src, meta.streamId, stream.lastDeliveredSeq);
return { handled: true };
}
stream.ready.set(meta.seq, { env, json, receivedAt: assembly.receivedAt, readyAt: this.monotonicNow() });
}
}
const result = this.drainTransportStream(env.src, meta.streamId, stream);
return { handled: true, result };
}
private drainTransportStream(
src: string,
streamId: string,
stream: ReceiveStreamState,
): Promise<void> {
if (stream.drain) {
stream.drainRequested = true;
return stream.drain;
}
const drain = async (): Promise<void> => {
let deliveredSinceAck = 0;
let deliveredBytesSinceAck = 0;
let lastAckSentSeq = stream.lastDeliveredSeq;
let sentAck = false;
do {
stream.drainRequested = false;
this.applyReceiveStreamBase(stream);
while (stream.ready.has(stream.lastDeliveredSeq + 1)) {
if (!this.isReceiveStreamActive(src, streamId, stream)) break;
const nextSeq = stream.lastDeliveredSeq + 1;
const ready = stream.ready.get(nextSeq)!;
let logical: Envelope;
try {
const payload = decodeTransportJson(ready.json);
logical = { ...ready.env, payload };
} catch {
this.log.warn(`dropping reliable payload decode failure seq=${nextSeq}`);
break;
}
stream.deliveringSeq = nextSeq;
const assemblyMs = Math.round(ready.readyAt - ready.receivedAt);
const orderedWaitMs = Math.round(this.monotonicNow() - ready.readyAt);
if ((logical.kind === 'invoke' || logical.kind === 'invoke-result')
&& (assemblyMs >= 250 || orderedWaitMs >= 250)) {
this.log.debug(`device-link receive timing kind=${logical.kind} request=${logical.id?.slice(0, 8) ?? 'none'}`
+ ` src=${src.slice(0, 8)} seq=${nextSeq}`
+ ` assemblyMs=${assemblyMs} orderedWaitMs=${orderedWaitMs}`);
}
let handled: boolean;
try {
handled = isTransportSkipPayload(logical.payload)
? true
: await this.dispatchEnvelope(logical);
} finally {
stream.deliveringSeq = null;
}
if (!handled) {
this.applyReceiveStreamBase(stream);
if (stream.lastDeliveredSeq >= nextSeq) continue;
this.log.warn(`reliable payload handler failed seq=${nextSeq}; waiting for retry`);
break;
}
stream.ready.delete(nextSeq);
const deliveredBytes = byteLength(ready.json);
stream.bufferedBytes -= deliveredBytes;
stream.lastDeliveredSeq = nextSeq;
this.applyReceiveStreamBase(stream);
deliveredSinceAck += 1;
deliveredBytesSinceAck += deliveredBytes;
if (
(deliveredSinceAck >= RELIABLE_ACK_BATCH_MESSAGES
|| deliveredBytesSinceAck >= RELIABLE_ACK_BATCH_BYTES)
&& this.isReceiveStreamActive(src, streamId, stream)
) {
if (this.sendTransportAck(src, streamId, stream.lastDeliveredSeq)) {
lastAckSentSeq = stream.lastDeliveredSeq;
sentAck = true;
}
deliveredSinceAck = 0;
deliveredBytesSinceAck = 0;
}
}
} while (stream.drainRequested);
if (
this.isReceiveStreamActive(src, streamId, stream)
&& (!sentAck || stream.lastDeliveredSeq !== lastAckSentSeq)
) {
this.sendTransportAck(src, streamId, stream.lastDeliveredSeq);
}
};
// 先把 drain Promise 登记到 stream,再进微任务执行。否则空队列的 drain
// 会同步跑完、随后才写入一个已 resolved 的 Promise;同一事件循环里紧接着
// 到达的队头帧只会标记 drainRequested,却没有活着的循环再消费它。
const task = Promise.resolve().then(drain).finally(() => {
if (stream.drain === task) stream.drain = null;
});
stream.drain = task;
return task;
}
private readonly messageReuse = new SessionMessageReuse();
private readonly invokeResultCache: InvokeResultCache;
private readonly inboundInvokeTransfer = new InboundInvokeTransferOptions();
private emitFrame(env: Envelope): boolean | Promise<boolean> {
if (env.kind === 'push' && (env.payload as { channel?: string })?.channel === DIRECT_LINK_SIGNAL) {
const signal = parseDirectSignal((env.payload as { payload?: unknown }).payload);
if (signal && env.src && (!isScopedPeer(env.src) || this.hasProviderShareDirectLease(env.src))) {
this.directNegotiator?.receive(env.src, signal);
}
return true;
}
if (env.kind === 'invoke' && env.src && env.id && !isScopedPeer(env.src)) {
this.inboundInvokeTransfer.record(env.src, env.id, env.payload);
}
if (env.kind === 'push' && env.src) {
const push = env.payload as { channel: string; payload: unknown };
const decoded = decodeModelSpeedPayload(push.channel, push.payload);
if (decoded !== push.payload) env = { ...env, payload: { ...push, payload: decoded } };
this.messageReuse.receive(env.src!, push.channel, decoded);
}
let ok = true;
let chain: Promise<void> | null = null;
for (const cb of this.frameHandlers) {
const run = (): void | Promise<void> => {
try {
const result = cb(env);
if (isPromiseLike(result)) {
return Promise.resolve(result).then(
() => undefined,
(err) => {
this.log.error('frame handler threw', err);
ok = false;
},
);
}
} catch (err) {
this.log.error('frame handler threw', err);
ok = false;
}
};
if (chain) {
chain = chain.then(run);
} else {
const result = run();
if (isPromiseLike(result)) chain = result;
}
}
return chain ? chain.then(() => ok) : ok;
}
/**
* Complete messages occupy the bounded sequence window, not unfinished
* reassembly slots. Recovery can deliver a full window before a missing
* prefix; sharing the 16-assembly limit drops valid replies until their
* byte-paced retry (often after the invoke timeout).
* 接收缓存满时优先保住当前队头。否则未来 seq 占满槽位或字节预算后,
* 用来补缺口的分片/skip 也进不来,累计 ACK 将永久停住。
*/
private ensureReceiveCapacity(
stream: ReceiveStreamState,
seq: number,
additionalBytes: number,
assembling = false,
): boolean {
const fits = (): boolean => {
const hasSlot = stream.ready.has(seq) || stream.assemblies.has(seq);
const slots = stream.ready.size + stream.assemblies.size + (hasSlot ? 0 : 1);
const assemblies = stream.assemblies.size
+ (assembling && !stream.assemblies.has(seq) ? 1 : 0);
return (
slots <= MAX_TRANSPORT_SEQUENCE_WINDOW
&& assemblies <= MAX_TRANSPORT_REASSEMBLIES
&& stream.bufferedBytes + additionalBytes <= MAX_TRANSPORT_REASSEMBLY_BYTES
);
};
if (fits()) return true;
if (seq !== stream.lastDeliveredSeq + 1) return false;
while (!fits()) {
const futureSeqs = [
...stream.ready.keys(),
...stream.assemblies.keys(),
].filter((bufferedSeq) => bufferedSeq > seq);
if (futureSeqs.length === 0) return false;
this.removeReceiveEntry(stream, Math.max(...futureSeqs));
}
return true;
}
private removeReceiveEntry(stream: ReceiveStreamState, seq: number): void {
const assembly = stream.assemblies.get(seq);
if (assembly) {
stream.assemblies.delete(seq);
stream.bufferedBytes -= assembly.bytes;
}
const ready = stream.ready.get(seq);
if (ready) {
stream.ready.delete(seq);
stream.bufferedBytes -= byteLength(ready.json);
}
}
private isReceiveStreamActive(
src: string,
streamId: string,
stream: ReceiveStreamState,
): boolean {
const peer = this.peerTransport.get(src);
return (
!!peer
&& peer.reliable
&& peer.receiveReady
&& peer.remoteStreamId === streamId
&& peer.receive.get(streamId) === stream
);
}
private sendPeerEnvelope(env: Envelope, allowClosedLegacyResponse = false): boolean {
if (!env.dst || !isReliableKind(env.kind)) {
this.sendBestEffortRoutedEnvelope(env);
return false;
}
const routedEnv: Envelope = env.id ? env : { ...env, id: createRequestId() };
const peer = this.getPeerTransport(env.dst);
if (
peer.explicitlyClosed
&& !this.isPeerSendReady(peer)
&& !isUnlinkedLegacyEnvelope(env)
&& !allowClosedLegacyResponse
) {
throw new DeviceLinkError('LINK_NOT_OPEN', 'control link is closed');
}
if (!peer.reliable) {
this.sendRoutedEnvelope(routedEnv);
if (!this.pending.has(routedEnv.id!)) {
this.settleOutboundRouteAttemptsForId(env.dst, routedEnv.id!);
}
return false;
}
// 死锁兜底:link 断开状态下 pending 冻结(不重试、不清理,只等 link 重建),
// 若 link-accept/link-open 丢失则永远等不到,满队列把所有新帧顶成 BACKPRESSURE。
// 队头滞留超过阈值即整队放弃 —— push 由重连 resync 补偿,invoke-result 的
// 原请求方早已超时;放弃后 baseSeq 前移,对端按新基线跳过这些 seq。
if (!this.isPeerSendReady(peer) && peer.pending.size > 0) {
const oldest = peer.pending.values().next().value as PendingReliableMessage | undefined;
if (
oldest
&& this.monotonicNow() - oldest.enqueuedAt > this.timing.stalledLinkPendingMaxAgeMs
) {
this.log.warn(
`abandoning ${peer.pending.size} stalled reliable frame(s) for peer ${env.dst.slice(0, 8)} (link down > ${this.timing.stalledLinkPendingMaxAgeMs}ms)`,
);
this.abandonReliablePending(env.dst, 'reliable link stalled; pending abandoned');
}
}
const seq = peer.nextSeq;
let frames: Envelope[];
let reservedBytes: number;
try {
frames = encodeReliableFrames(
routedEnv,
peer.streamId,
seq,
this.getTransportBaseSeq(peer),
);
reservedBytes = this.measurePendingReservation(routedEnv, peer.streamId, seq);
} catch (err) {
throw new DeviceLinkError(
'PAYLOAD_TOO_LARGE',
err instanceof Error ? err.message : String(err),
);
}
const hasPendingCapacity = (): boolean => (
peer.pending.size < MAX_TRANSPORT_PENDING_MESSAGES
&& peer.pendingBytes + reservedBytes <= MAX_TRANSPORT_PENDING_BYTES
);
// socket 容量预检只服务「本轮会写出」的帧。恢复期被 hold 的消息只进
// pending,不碰共享 ws;其它 peer 占满 send buffer 不得让它 BACKPRESSURE。
// 真会发送时仍在驱逐/腾位之前预检(旧 P1:先驱逐再拒会清空镜像历史)。
const additionalFrames = Math.max(1, frames.length);
const previousBaseSeq = this.getTransportBaseSeq(peer);
// 走直连的帧不占 relay 的拥塞预算与 socket 缓冲。
const viaDirect = this.directChannelForSend(env.dst, peer) !== null;
const willSendNow = this.isPeerSendReady(peer)
// Admission may evict a discardable prefix and move this message into
// the window. Preserve the socket preflight before that mutation.
&& (!this.isOutsideReceiveWindow(peer, seq) || !hasPendingCapacity())
&& !this.shouldHoldRecoverySend(peer, additionalFrames)
&& (viaDirect || this.congestionCloseStreak === 0 || this.congestionSendBudget.canTake(
env.dst, additionalFrames, this.getReadyReliablePeers(env.dst), this.monotonicNow(),
));
if (willSendNow && !viaDirect) {
this.assertWebSocketCapacity(this.measureReliableFrames(frames));
}
if (!hasPendingCapacity()) {
if (routedEnv.kind === 'invoke-result') {
// invoke-result 是控制端确认被控端存活的唯一凭据,绝不能被堆积的可丢弃
// 帧饿死:丢弃整个队头可丢弃前缀(fresh push 一并放弃——单 FIFO 无法同时
// 做到 push 无损与 result 抢占),让 result 成为最早可交付的 live seq。
this.dropDiscardablePendingPrefix(env.dst, peer, false, 'to make room for invoke-result');
} else if (routedEnv.kind === 'push' && isCoalesciblePushEnvelope(routedEnv)) {
// 可合并镜像 push(COALESCIBLE_PUSH_CHANNELS)是尽力而为的状态镜像
// (控制端重连/回前台会整体 resync + 重新订阅)。拥塞即对端未在 ACK:
// 2026-08-07 线上该形态一小时内 5168 次连续 BACKPRESSURE(maker:event),
// 镜像状态一条都没交付,只放大重试风暴。latest-wins:只从队头驱逐最旧
// 的可合并镜像帧直到放得下(剩余镜像历史保留,对端恢复后仍可交付最新
// 状态);队头是 live 帧或白名单外 push 时无位可让,维持原 BACKPRESSURE
// 语义。只删队头 → baseSeq 单调前移,无 seq 空洞。
this.dropOldestDiscardableForPushAdmission(env.dst, peer, reservedBytes);
} else {
// live invoke 与白名单外 push(不可合并事件流/流控数据,见
// COALESCIBLE_PUSH_CHANNELS 注释)的入队压力只做 TTL 兜底清扫:过期
// push 已无实时价值,先出队腾位;新鲜 push 不互相驱逐(这两类帧不能
// 以丢镜像为代价抢占)。
this.dropDiscardablePendingPrefix(env.dst, peer, true, 'after pending push TTL expiry');
}
}
if (!hasPendingCapacity()) {
throw new DeviceLinkError(
'BACKPRESSURE',
`reliable transport buffer is full for peer ${env.dst.slice(0, 8)}`,
);
}
// link 暂未恢复时帧先进入有界 pending,等 link-open/link-accept 后再发
// (ws 容量已在驱逐前预检)。
const pending: PendingReliableMessage = {
seq,
envelope: routedEnv,
bytes: reservedBytes,
attempts: 0,
lastSentAt: 0,
sent: false,
enqueuedAt: this.monotonicNow(),
relaySigningSession: this.opts.frameAuth?.()?.peerChallenge?.session,
lastBlockedBy: willSendNow ? undefined : !this.isPeerSendReady(peer) ? 'link'
: this.isOutsideReceiveWindow(peer, seq) ? 'receive-window'
: this.shouldHoldRecoverySend(peer, additionalFrames) ? 'recovery-ack' : 'relay-budget',
};
peer.pending.set(seq, pending);
peer.pendingBytes += reservedBytes;
peer.nextSeq = seq + 1;
if (willSendNow) {
try {
const sentFrames = this.sendReliableFrames(peer, pending);
this.noteRecoveryFrames(peer, sentFrames);
} catch (err) {
// 容量预检后的 ws.send 仍可能因 socket 竞态失败。完全未写入时安全回滚;
// 已部分写入则保留同 seq 等待重放,调用方继续等待,不制造重复请求。
if (!pending.sent) {
peer.pending.delete(seq);
peer.pendingBytes -= reservedBytes;
if (peer.nextSeq === seq + 1) peer.nextSeq = seq;
throw err;
}
this.log.debug(`reliable transport initial send interrupted for ${env.dst.slice(0, 8)}`, err);
}
}
if (this.isPeerSendReady(peer)) {
if (this.getTransportBaseSeq(peer) !== previousBaseSeq) {
this.retryPending(env.dst, { ignoreInterval: false, onlyUnsent: true });
}
this.ensureRetryTimer(env.dst);
}
return true;
}
/**
* 实际写进 ws 的**帧**数(一条逻辑消息可能分多帧)。
* 一分片都没写出才抛;中途竞态只返回已上网的帧数,让恢复预算能结算部分突发。
*/
private sendReliableFrames(peer: PeerTransportState, pending: PendingReliableMessage): number {
const frameAuth = this.opts.frameAuth?.();
if (pending.relaySigningSession !== frameAuth?.peerChallenge?.session) {
pending.relaySigningSession = frameAuth?.peerChallenge?.session;
const id = pending.envelope.id!;
const request = this.pending.get(id);
if (request) {
this.pending.delete(id);
request.reject(new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
}
this.dropReliablePendingForRequest(pending.envelope.dst!, id);
return 0;
}
// A resume/ACK callback can run before the overdue timeout callback. The
// existing timeout path substitutes a skip at the same sequence number;
// never retransmit an expired command just because its timer ran late.
if (pending.envelope.kind === 'invoke' && pending.envelope.id
&& this.pending.get(pending.envelope.id)?.expireIfOverdue()) return 0;
if (!pending.sent && this.isOutsideReceiveWindow(peer, pending.seq)) {
pending.lastBlockedBy = 'receive-window';
return 0;
}
const frames = encodeReliableFrames(
pending.envelope,
peer.streamId,
pending.seq,
this.getTransportBaseSeq(peer),
);
const wireBytes = this.measureReliableFrames(frames);
const direct = this.directChannelForSend(pending.envelope.dst!, peer);
if (direct) {
const sentDirect = this.sendReliableFramesDirect(peer, pending, frames, wireBytes, direct);
// null: 一帧都没写进直连且通道已撤下,本次立即改走 relay。
if (sentDirect !== null) return sentDirect;
// 撤下通道可能把更早的 direct 帧也恢复成未发送。先由 detach 安排的恢复
// 从队头推进 ACK,不能让当前短尾帧抢占 relay 探测预算,卡住缺失的大队头。
const head = peer.pending.values().next().value;
if (head && head !== pending && !head.sent) return 0;
}
if (this.status !== 'online') {
pending.lastBlockedBy = 'socket';
return 0;
}
if (frameAuth?.peerChallenge && frameAuth.peerChallenge.state(pending.envelope.dst!) !== 'ready') {
// 逻辑消息保留在已有可靠 pending;分片不能挤进认证队列或被误记为物理已发送。
const dst = pending.envelope.dst!;
this.probeRelayChallenge(dst, this.ensureRelayChallenge(dst, frameAuth));
pending.lastBlockedBy = 'link';
return 0;
}
const peers = this.getReadyReliablePeers(pending.envelope.dst!);
const budgetNow = this.monotonicNow();
const congestionBudget = this.congestionCloseStreak > 0 ? this.congestionSendBudget : null;
if (congestionBudget && !congestionBudget.canTake(
pending.envelope.dst!, frames.length, peers, budgetNow,
)) { pending.lastBlockedBy = 'relay-budget'; return 0; }
// Keep hard-cap errors unchanged. Soft pressure only delays the existing
// bounded reliable queue, without consuming attempts or changing sequence IDs.
this.assertWebSocketCapacity(wireBytes);
if (!this.canWriteReliableBytes(wireBytes)) { pending.lastBlockedBy = 'socket'; return 0; }
const localBudget = this.localSendPressure ? this.localSendBudget : null;
const byteCredits = Math.ceil(wireBytes / SOCKET_SEND_CREDIT_BYTES);
if (localBudget && !localBudget.canTake(
pending.envelope.dst!, byteCredits, peers, budgetNow,
)) { pending.lastBlockedBy = 'socket-budget'; return 0; }
if (congestionBudget) {
if (!congestionBudget.take(
pending.envelope.dst!, frames.length, peers, budgetNow,
)) { pending.lastBlockedBy = 'relay-budget'; return 0; }
}
if (localBudget && !localBudget.take(pending.envelope.dst!, byteCredits, peers, budgetNow)) {
congestionBudget?.refund(pending.envelope.dst!, frames.length);
pending.lastBlockedBy = 'socket-budget';
return 0;
}
let sent = 0;
let writtenBytes = 0;
try {
this.assertWebSocketCapacity(wireBytes);
for (const frame of frames) {
// pending 可在 link down 时入队,并在后续 link generation 才首次上网;
// 路由错误必须归属每次真实物理发送,而不是逻辑消息的入队代次。
this.sendRoutedEnvelope(frame, peer.linkGeneration, true);
writtenBytes += byteLength(JSON.stringify(encodeScopedEnvelope(frame, ALL_SCOPES)));
pending.sent = true;
sent += 1;
}
} catch (err) {
if (sent === 0) throw err;
this.log.debug(
`reliable transport send interrupted after ${sent} frame(s) for seq=${pending.seq}`,
err,
);
} finally {
congestionBudget?.refund(pending.envelope.dst!, frames.length - sent);
localBudget?.refund(pending.envelope.dst!, byteCredits - Math.ceil(writtenBytes / SOCKET_SEND_CREDIT_BYTES));
this.noteReliableWrite(peer, pending, sent, 'relay');
}
return sent;
}
/** 一次物理写出(relay 或直连)之后的统一记账。 */
private noteReliableWrite(
peer: PeerTransportState,
pending: PendingReliableMessage,
sent: number,
path: DeviceLinkPeerPath,
): void {
if (sent <= 0) return;
const ageMs = Math.round(this.monotonicNow() - pending.enqueuedAt);
if ((pending.envelope.kind === 'invoke' || pending.envelope.kind === 'invoke-result')
&& (ageMs >= 250 || pending.attempts > 0)) {
this.log.debug(`device-link send timing kind=${pending.envelope.kind} request=${pending.envelope.id?.slice(0, 8) ?? 'none'}`
+ ` dst=${pending.envelope.dst!.slice(0, 8)} seq=${pending.seq} path=${path}`
+ ` ${pending.attempts === 0 ? 'queueMs' : 'ageMs'}=${ageMs}`
+ ` attempt=${pending.attempts + 1} frames=${sent} bytes=${pending.bytes}`
+ ` pending=${peer.pending.size} congestion=${this.congestionCloseStreak}`
+ ` lastBlockedBy=${pending.lastBlockedBy ?? 'none'} socketBufferedBytes=${this.ws?.bufferedAmount ?? 0}`);
}
pending.lastBlockedBy = undefined;
pending.sent = true;
pending.path = path;
if (pending.attempts === 0) pending.firstSentAt = this.monotonicNow();
pending.attempts++;
pending.lastSentAt = Date.now();
this.logRecoveryStage(pending.envelope.dst!, 'first-reliable-write', ` seq=${pending.seq} frames=${sent}`);
if (pending.envelope.kind === 'invoke-result') {
this.logRecoveryStage(pending.envelope.dst!, 'first-response-write', ` seq=${pending.seq} frames=${sent}`);
}
}
// ─── 内部:直连选路(直连优先、中继兜底) ─────────────────────────────────────
/** 可靠帧此刻能否走直连:双方已提交可靠链路、本机发送方向就绪且接入了通道。 */
private directChannelForSend(dst: string, peer: PeerTransportState): DeviceLinkDirectChannel | null {
if (!peer.reliable || !this.isPeerSendReady(peer)) return null;
return this.usableDirectPath(dst);
}
/**
* 经直连写出一条可靠消息的全部分片。返回 null 表示一帧都没写出且通道已撤下,
* 调用方改走 relay;返回 0 表示暂缓发送或部分写入后已安排从队头恢复。
*/
private sendReliableFramesDirect(
peer: PeerTransportState,
pending: PendingReliableMessage,
frames: readonly Envelope[],
wireBytes: number,
channel: DeviceLinkDirectChannel,
): number | null {
const dst = pending.envelope.dst!;
const buffered = channel.bufferedAmount ?? 0;
// 与 relay 一致:缓冲排空后单条大消息总能发出,不会被软上限永久卡住。
if (buffered > 0 && buffered + wireBytes > DIRECT_PATH_HIGH_WATER_BYTES) {
const now = this.monotonicNow();
const waiting = peer.directBufferWait;
if (!waiting || waiting.channel !== channel || buffered < waiting.bytes) {
peer.directBufferWait = { channel, bytes: buffered, since: now };
} else {
waiting.bytes = buffered;
if (now - waiting.since >= retransmitBaseMs(peer.rtt, this.timing.transportRetryIntervalMs)) {
this.detachDirectPath(dst, 'buffer-timeout');
return null;
}
}
pending.lastBlockedBy = 'direct-buffer';
return 0;
}
peer.directBufferWait = undefined;
let sent = 0;
for (const frame of frames) {
try {
channel.send(JSON.stringify(frame));
} catch (err) {
this.log.debug(`device-link direct send failed dst=${dst.slice(0, 8)} seq=${pending.seq} frames=${sent}`, err);
break;
}
sent += 1;
}
if (sent === 0) {
this.detachDirectPath(dst, 'send-failed');
return null;
}
if (pending.envelope.id) this.pending.get(pending.envelope.id)?.noteFirstWrite?.();
this.noteReliableWrite(peer, pending, sent, 'direct');
// 只写出部分分片:整条消息改由 relay 从头重发,接收端丢弃重复分片。
if (sent < frames.length) {
this.detachDirectPath(dst, 'send-failed');
// 这些片已属于撤下的直连,不能再计入新一轮 relay 的恢复预算。
return 0;
}
return sent;
}
/**
* 撤下直连并切回 relay。经直连写出、仍未确认的消息恢复为未发送,按 relay 的
* 恢复预算重发(先发一批探测,收到 ACK 再继续)。只作用于这一台设备:不重连
* relay、不重建链路、不影响其它设备的链路与在途请求。
*/
private detachDirectPath(deviceId: string, reason: DeviceLinkDirectCloseReason): void {
if (reason === 'link-closed' || reason === 'peer-offline' || reason === 'stopped') {
this.directNegotiator?.forget(deviceId);
}
const channel = this.directPaths.get(deviceId);
if (!channel) return;
this.directPaths.delete(deviceId);
this.closeDirectChannel(deviceId, channel, reason);
const peer = this.peerTransport.get(deviceId);
let resent = 0;
if (peer) {
peer.directBufferWait = undefined;
peer.lastInboundPath = 'relay';
for (const pending of peer.pending.values()) {
if (pending.path !== 'direct') continue;
pending.path = undefined;
pending.sent = false;
resetReliableSendRound(pending);
resent += 1;
}
if (resent > 0) {
peer.recoveryNeedsAck = true;
peer.recoveryFramesSent = 0;
}
}
const message = `device-link direct path closed dst=${deviceId.slice(0, 8)} reason=${reason} resendViaRelay=${resent}`;
if (reason === 'ack-timeout' || reason === 'buffer-timeout' || reason === 'send-failed') this.log.warn(message);
else this.log.info(message);
this.emitPeerPathChanged({ deviceId, path: 'relay', reason, ...(resent > 0 ? { resent } : {}) });
if (resent === 0) return;
// 调用方可能正处于 retryPending / sendPeerEnvelope 中:下一个微任务再重放,避免重入。
// 只补发仍未发送的:调用方当轮已经改走 relay 发出的帧不再复制一份。
void Promise.resolve().then(() => {
this.retryPending(deviceId, { ignoreInterval: false, onlyUnsent: true });
const current = this.peerTransport.get(deviceId);
if (current?.reliable && this.isPeerSendReady(current) && current.pending.size > 0) {
this.ensureRetryTimer(deviceId);
}
});
}
private closeDirectChannel(
deviceId: string,
channel: DeviceLinkDirectChannel,
reason: DeviceLinkDirectCloseReason,
): void {
try {
channel.close(reason);
} catch (err) {
this.log.debug(`device-link direct path close failed dst=${deviceId.slice(0, 8)}`, err);
}
}
private emitPeerPathChanged(change: DeviceLinkPeerPathChanged): void {
for (const cb of this.peerPathHandlers) {
try {
cb(change);
} catch (err) {
this.log.error('device-link peer path handler failed', err);
}
}
}
/**
* 直连入站:只接受同账号对端发给本机的可靠数据面帧与累计 ACK。来源取自通道
* 绑定的设备,不信任帧内 src;跨账号范围、link 控制帧与非可靠帧一律丢弃(它们
* 只走 relay)。不刷新 relay 心跳:直连有流量不能掩盖 relay 已经失联。
*/
private handleDirectFrame(deviceId: string, text: string): void {
if (this.stopped) return;
const self = this.selfDeviceId;
const sharePeer = parseProviderSharePeer(deviceId);
const localAddress = sharePeer && this.hasProviderShareDirectLease(deviceId)
? this.providerShareLocalAddresses.get(deviceId) : undefined;
if (isScopedPeer(deviceId) && !localAddress) return;
let parsed: unknown;
try {
if (byteLength(text) > MAX_FRAME_BYTES) throw new Error('direct frame too large');
parsed = JSON.parse(text) as unknown;
} catch {
this.log.warn(`dropping invalid direct frame from ${deviceId.slice(0, 8)}`);
return;
}
if (
!isRecord(parsed)
|| parsed.v !== PROTOCOL_VERSION
|| typeof parsed.kind !== 'string'
|| !isReliableKind(parsed.kind as Envelope['kind'])
|| parsed.sharedTask !== undefined
|| parsed.providerShare !== undefined
|| !self
|| parsed.dst !== (localAddress ?? self)
|| (parsed.id !== undefined && typeof parsed.id !== 'string')
) {
this.log.warn(`dropping disallowed direct frame from ${deviceId.slice(0, 8)}`);
return;
}
const env: Envelope = {
v: PROTOCOL_VERSION,
kind: parsed.kind as Envelope['kind'],
...(typeof parsed.id === 'string' ? { id: parsed.id } : {}),
src: deviceId,
dst: localAddress ?? self,
payload: parsed.payload,
};
if (!isValidInboundEnvelope(env)) {
this.log.warn(`dropping invalid direct frame kind=${env.kind} from ${deviceId.slice(0, 8)}`);
return;
}
const ack = parseTransportAck(env);
if (ack) {
// 链路确认 ACK 属于控制面,只认 relay;直连上的确认只按普通累计 ACK 处理。
this.handleTransportAck(deviceId, ack.streamId, ack.ackSeq);
return;
}
// The relay enforces this direction for provider shares. A direct channel
// must enforce it again before any reliable payload reaches dispatch.
if (sharePeer && !(sharePeer.role === 'guest' ? env.kind === 'invoke'
: env.kind === 'invoke-result' || env.kind === 'push')) return;
if (!parseTransportPayload(env.payload)) {
this.log.warn(`dropping non-reliable direct frame kind=${env.kind} from ${deviceId.slice(0, 8)}`);
return;
}
const transport = this.ingestTransportEnvelope(env, 'direct');
if (transport.handled) {
void transport.result?.catch((err) => {
this.log.error('device-link reliable frame failed', err);
});
}
}
private canWriteReliableBytes(bytes: number): boolean {
const buffered = this.ws?.bufferedAmount ?? 0;
const pressured = buffered > SOCKET_DATA_LOW_WATER_BYTES
&& (this.localSendPressure || buffered + bytes > SOCKET_DATA_HIGH_WATER_BYTES);
if (pressured !== this.localSendPressure) {
this.localSendPressure = pressured;
if (!pressured) this.localSendBudget.reset();
// Reuse the existing drain timer, accelerate only while the socket is slow.
for (const [id, state] of this.peerTransport) {
if (!state.retryTimer) continue;
clearInterval(state.retryTimer);
state.retryTimer = null;
this.ensureRetryTimer(id);
}
}
// Chunks are sent atomically. A maximum-size message must be able to progress
// once the socket drains, even though it exceeds the ordinary data watermark.
return buffered + bytes <= SOCKET_DATA_HIGH_WATER_BYTES
|| (buffered <= SOCKET_DATA_LOW_WATER_BYTES
&& buffered + bytes <= MAX_TRANSPORT_WEBSOCKET_BUFFERED_BYTES - SOCKET_CONTROL_RESERVE_BYTES);
}
private isOutsideReceiveWindow(peer: PeerTransportState, seq: number): boolean {
// Keep future messages at the sender until cumulative ACK advances. A
// receiver has only this many reassembly/ready slots; sending 64 pending
// messages into 16 slots can discard a large response, then block the stream
// for its entire byte-paced retry interval. Prefix eviction advances this
// same base, so skipped/discardable messages cannot strand the window.
return seq - this.getTransportBaseSeq(peer) >= MAX_TRANSPORT_REASSEMBLIES;
}
private getReadyReliablePeers(target: string): string[] {
return [...this.peerTransport.entries()]
// Include the initial target before enqueue; unacknowledged data still needs retries.
.filter(([id, peer]) => peer.reliable && this.isPeerSendReady(peer)
&& (id === target || peer.pending.size > 0))
.map(([id]) => id);
}
private measureReliableFrames(frames: readonly Envelope[]): number {
// Budget the physical wire envelope, not the local scoped connection handle.
return frames.reduce((sum, frame) => sum + byteLength(JSON.stringify(encodeScopedEnvelope(frame, ALL_SCOPES))), 0);
}
/**
* baseSeq 永远不大于当前 seq,因此按 baseSeq=seq 编码就是该 pending
* 可能占用的最大 wrapper 大小。这样 ACK 推进基线后动态重编码也不会突破
* 已批准的 pendingBytes 上限。
*/
private measureReservedReliableBytes(env: Envelope, streamId: string, seq: number): number {
return this.measureReliableFrames(encodeReliableFrames(env, streamId, seq, seq));
}
private measurePendingReservation(env: Envelope, streamId: string, seq: number): number {
const originalBytes = this.measureReservedReliableBytes(env, streamId, seq);
if (env.kind !== 'invoke' || !env.id || !env.dst) return originalBytes;
const skipBytes = this.measureReservedReliableBytes({
v: PROTOCOL_VERSION,
kind: 'invoke',
id: env.id,
dst: env.dst,
payload: makeTransportSkipPayload(),
}, streamId, seq);
return Math.max(originalBytes, skipBytes);
}
private rejectedSignatureLogAt = 0;
private rejectedSignatureCount = 0;
/** 签名不对的帧可能成批出现(时钟不准、证书未同步),日志按分钟汇总。 */
private noteRejectedSignature(src: string, kind: string): void {
this.rejectedSignatureCount++;
const now = Date.now();
if (now - this.rejectedSignatureLogAt < 60_000) return;
this.log.warn(
`dropping device-link frame without a valid device signature src=${src.slice(0, 8)} kind=${kind} count=${this.rejectedSignatureCount}`,
);
this.rejectedSignatureLogAt = now;
this.rejectedSignatureCount = 0;
}
private recoverRelayLinkOpen(dst: string, auth: DeviceLinkFrameAuth): void {
const challenge = auth.peerChallenge;
if (!challenge || challenge.state(dst) === 'ready') return;
for (const [id, pending] of this.pending) {
const retry = pending.relayLinkRetry;
if (!retry || pending.dst !== dst || !pending.hasWritten() || pending.expireIfOverdue()) continue;
if (retry.session !== challenge.session) {
this.pending.delete(id);
this.settleOutboundRouteAttemptsForId(dst, id);
pending.reject(new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
continue;
}
try {
// 先进入原有认证队列,双方挑战确认后再重签发送;首次写入时间不变,不延长预算。
this.sendRoutedEnvelope(retry.envelope, pending.linkGeneration);
} catch { /* 保留原请求期限;不扩大到共享 socket 或业务写请求的重试。 */ }
}
}
private ensureRelayChallenge(dst: string, auth: DeviceLinkFrameAuth): RelayChallengeQueue {
const session = auth.peerChallenge!.session;
let queue = this.relayChallenges.get(dst);
if (queue && queue.session !== session) {
this.clearRelayChallenge(dst, new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
queue = undefined;
}
if (queue) return queue;
if (this.relayChallenges.size >= 32) throw new DeviceLinkError('BACKPRESSURE', 'relay authentication queue is full');
queue = { session, id: createRequestId(), startedAt: Date.now(), startedMonotonicAt: this.monotonicNow(),
lastProbeAt: -Infinity, timer: null, frames: new Map() };
this.relayChallenges.set(dst, queue);
const retry = () => {
queue!.timer = null;
if (this.relayChallenges.get(dst) !== queue) return;
const current = this.opts.frameAuth?.();
if (current?.peerChallenge?.session !== session) {
this.clearRelayChallenge(dst, new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
return;
}
if (Date.now() - queue!.startedAt >= this.timing.requestTimeoutMs
|| this.monotonicNow() - queue!.startedMonotonicAt >= this.timing.requestTimeoutMs) {
this.clearRelayChallenge(dst, new DeviceLinkError('BACKPRESSURE', 'relay authentication timed out before socket write'));
return;
}
try { this.probeRelayChallenge(dst, queue!); } catch { /* 有界预算内再试。 */ }
if (this.relayChallenges.get(dst) !== queue) return;
queue!.timer = setTimeout(retry, Math.min(1_000, Math.max(100, this.timing.transportRetryIntervalMs)));
};
queue.timer = setTimeout(retry, Math.min(1_000, Math.max(100, this.timing.transportRetryIntervalMs)));
return queue;
}
private probeRelayChallenge(dst: string, queue: RelayChallengeQueue): void {
if (this.monotonicNow() - queue.lastProbeAt < 100) return;
queue.lastProbeAt = this.monotonicNow();
this.sendEnvelope({ v: PROTOCOL_VERSION, kind: 'push', id: queue.id, dst,
payload: { channel: RELAY_AUTH_CHANNEL, payload: { type: 'request' } } });
}
private clearRelayChallenge(dst: string, error?: DeviceLinkError): RelayChallengeQueue | undefined {
const queue = this.relayChallenges.get(dst);
if (!queue) return;
this.relayChallenges.delete(dst);
if (queue.timer) clearTimeout(queue.timer);
for (const { env, bytes, pending } of queue.frames.values()) {
this.relayChallengeBytes -= bytes;
this.relayChallengeFrames--;
if (error && pending && env.id && this.pending.get(env.id) === pending) {
this.pending.delete(env.id);
this.settleOutboundRouteAttemptsForId(dst, env.id);
this.dropReliablePendingForRequest(dst, env.id);
pending.reject(error);
}
}
return queue;
}
private cancelRelayQueuedControl(dst: string): void {
const queue = this.relayChallenges.get(dst);
if (!queue) return;
for (const [key, { env, bytes, pending }] of queue.frames) {
if (isUnlinkedLegacyEnvelope(env)) continue;
queue.frames.delete(key);
this.relayChallengeBytes -= bytes;
this.relayChallengeFrames--;
if (env.id) this.settleOutboundRouteAttemptsForId(dst, env.id);
if (pending && env.id && this.pending.get(env.id) === pending) {
this.pending.delete(env.id);
pending.reject(new DeviceLinkError('LINK_NOT_OPEN', 'control link closed before socket write'));
}
}
}
private flushRelayChallenge(dst: string, auth: DeviceLinkFrameAuth): void {
const queue = this.relayChallenges.get(dst);
if (!queue) return;
if (queue.session !== auth.peerChallenge?.session) {
this.clearRelayChallenge(dst, new DeviceLinkError('NOT_CONNECTED', 'relay signing identity changed'));
return;
}
this.clearRelayChallenge(dst);
for (const { env, pending } of queue.frames.values()) {
// 超时的写请求绝不能因迟到的认证响应在后台继续发送。
if (pending && (this.pending.get(env.id!) !== pending || pending.expireIfOverdue?.())) continue;
try {
if (this.sendEnvelope(env)) pending?.noteFirstWrite?.();
} catch (error) {
if (pending && this.pending.get(env.id!) === pending) {
this.pending.delete(env.id!);
this.settleOutboundRouteAttemptsForId(dst, env.id!);
this.dropReliablePendingForRequest(dst, env.id!);
pending.reject(error instanceof DeviceLinkError ? error : new DeviceLinkError('NOT_CONNECTED', 'socket write failed'));
}
}
}
this.retryPending(dst, { ignoreInterval: false, onlyUnsent: true });
}
private sendEnvelope(env: Envelope, allowAuthenticationQueue = true): boolean {
const ws = this.ws;
if (!ws) throw new DeviceLinkError('NOT_CONNECTED', 'no active connection');
let wire = encodeScopedEnvelope(env, this.scopeSupport());
if (wire.dst && ROUTED_KINDS.has(wire.kind)) {
const frameAuth = this.opts.frameAuth?.();
if (frameAuth?.peerChallenge && !relayAuthHandshake(wire) && frameAuth.peerChallenge.state(wire.dst) !== 'ready') {
const bytes = byteLength(JSON.stringify(wire));
if (bytes > MAX_FRAME_BYTES) throw new DeviceLinkError('PAYLOAD_TOO_LARGE', 'frame exceeds relay authentication budget');
const queue = this.ensureRelayChallenge(wire.dst, frameAuth);
if (!allowAuthenticationQueue) {
this.probeRelayChallenge(wire.dst, queue);
return false;
}
const key = `${wire.kind}:${wire.id ?? ''}`;
if (!queue.frames.has(key)) {
if (this.relayChallengeFrames >= 256 || this.relayChallengeBytes + bytes > 2 * MAX_FRAME_BYTES) {
throw new DeviceLinkError('BACKPRESSURE', 'relay authentication queue is full');
}
queue.frames.set(key, { env, bytes, pending: env.id ? this.pending.get(env.id) : undefined });
this.relayChallengeFrames++;
this.relayChallengeBytes += bytes;
}
this.probeRelayChallenge(wire.dst, queue);
return false;
}
const auth = frameAuth?.sign(wire);
if (auth !== undefined) wire = { ...wire, auth } as Envelope;
}
const text = JSON.stringify(wire);
// 按 UTF-8 字节数判定,与服务端 MAX_FRAME_BYTES(Buffer.byteLength)一致。
// 用 text.length(UTF-16 码元)会与服务端不符:CJK 等多字节内容客户端自检通过、
// 服务端却 PAYLOAD_TOO_LARGE 丢帧,invoke 只能等 30s 超时而非快速失败。
const frameBytes = byteLength(text);
if (frameBytes > MAX_FRAME_BYTES) {
throw new DeviceLinkError('PAYLOAD_TOO_LARGE', `frame exceeds ${MAX_FRAME_BYTES} bytes`);
}
// ws / browser WebSocket 都会在 send() 后把数据放入内部缓冲。没有这个
// 观察点的 RN 实现仍由可靠消息的有界 pending buffer 兜底;有这个观察点
// 时提前拒绝,避免弱网下 native socket 持续吃内存。
this.assertWebSocketCapacity(frameBytes);
ws.send(text);
return true;
}
private sendRoutedEnvelope(env: Envelope, linkGeneration?: number, requirePhysicalWrite = false): string | undefined {
if (!env.dst) {
this.sendEnvelope(env);
return env.id;
}
const routed: Envelope = env.id ? env : { ...env, id: createRequestId() };
const generation = linkGeneration ?? this.getPeerLinkGeneration(env.dst);
this.rememberOutboundRouteGeneration(routed.id!, env.dst, generation);
try {
const written = this.sendEnvelope(routed, !requirePhysicalWrite);
if (written) this.pending.get(routed.id!)?.noteFirstWrite?.();
else if (requirePhysicalWrite) throw new DeviceLinkError('BACKPRESSURE', 'awaiting relay authentication');
} catch (err) {
this.rollbackOutboundRouteGeneration(routed.id!, env.dst, generation);
throw err;
}
return routed.id;
}
private sendBestEffortRoutedEnvelope(env: Envelope, linkGeneration?: number): void {
const routedId = this.sendRoutedEnvelope(env, linkGeneration);
if (env.dst && routedId) this.settleOutboundRouteAttemptsForId(env.dst, routedId);
}
private rememberOutboundRouteGeneration(
id: string,
deviceId: string,
linkGeneration: number,
): void {
let peerAttempts = this.outboundRouteGenerationByPeer.get(deviceId);
const generationRuns = peerAttempts?.get(id);
if (!generationRuns) {
const totalIds = Array.from(this.outboundRouteGenerationByPeer.values()).reduce(
(sum, attempts) => sum + attempts.size,
0,
);
if (
(peerAttempts?.size ?? 0) >= MAX_OUTBOUND_ROUTE_IDS_PER_PEER
|| totalIds >= MAX_OUTBOUND_ROUTE_IDS_TOTAL
) {
throw new DeviceLinkError(
'BACKPRESSURE',
`route attempt history is full for peer ${deviceId.slice(0, 8)}`,
);
}
if (!peerAttempts) {
peerAttempts = new Map();
this.outboundRouteGenerationByPeer.set(deviceId, peerAttempts);
}
peerAttempts.set(id, [{ linkGeneration, count: 1 }]);
return;
}
const latest = generationRuns.at(-1);
if (latest?.linkGeneration === linkGeneration) {
latest.count += 1;
return;
}
if (generationRuns.length >= MAX_OUTBOUND_ROUTE_GENERATION_RUNS_PER_ID) {
throw new DeviceLinkError(
'BACKPRESSURE',
`route generation history is full for peer ${deviceId.slice(0, 8)}`,
);
}
generationRuns.push({ linkGeneration, count: 1 });
}
private consumeOutboundRouteGeneration(id: string, deviceId?: string): number | undefined {
const ledgers = [
this.settledOutboundRouteGenerationByPeer,
this.outboundRouteGenerationByPeer,
];
let resolvedDeviceId = deviceId;
let owningLedger: typeof this.outboundRouteGenerationByPeer | undefined;
let peerAttempts: Map<string, Array<{ linkGeneration: number; count: number }>> | undefined;
for (const ledger of ledgers) {
if (resolvedDeviceId) {
const candidate = ledger.get(resolvedDeviceId);
if (candidate?.has(id)) {
owningLedger = ledger;
peerAttempts = candidate;
break;
}
continue;
}
for (const [candidateDeviceId, candidateAttempts] of ledger) {
if (!candidateAttempts.has(id)) continue;
resolvedDeviceId = candidateDeviceId;
owningLedger = ledger;
peerAttempts = candidateAttempts;
break;
}
if (peerAttempts) break;
}
const generationRuns = peerAttempts?.get(id);
const first = generationRuns?.[0];
if (
!owningLedger
|| !peerAttempts
|| !generationRuns
|| !first
|| !resolvedDeviceId
) return undefined;
const linkGeneration = first.linkGeneration;
first.count -= 1;
if (first.count === 0) generationRuns.shift();
if (generationRuns.length === 0) peerAttempts.delete(id);
if (peerAttempts.size === 0) owningLedger.delete(resolvedDeviceId);
return linkGeneration;
}
private discardOutboundRouteAttemptsBeforeGeneration(
deviceId: string,
minimumGeneration: number,
): void {
for (const ledger of [
this.outboundRouteGenerationByPeer,
this.settledOutboundRouteGenerationByPeer,
]) {
const peerAttempts = ledger.get(deviceId);
if (!peerAttempts) continue;
for (const [id, generationRuns] of peerAttempts) {
const retained = generationRuns.filter(
(run) => run.linkGeneration >= minimumGeneration,
);
if (retained.length === 0) {
peerAttempts.delete(id);
} else if (retained.length !== generationRuns.length) {
peerAttempts.set(id, retained);
}
}
if (peerAttempts.size === 0) ledger.delete(deviceId);
}
}
private discardOutboundRouteAttemptsForId(deviceId: string, id: string): void {
for (const ledger of [
this.outboundRouteGenerationByPeer,
this.settledOutboundRouteGenerationByPeer,
]) {
const peerAttempts = ledger.get(deviceId);
if (!peerAttempts) continue;
peerAttempts.delete(id);
if (peerAttempts.size === 0) ledger.delete(deviceId);
}
}
private settleOutboundRouteAttemptsForId(deviceId: string, id: string): void {
const activePeerAttempts = this.outboundRouteGenerationByPeer.get(deviceId);
const activeRuns = activePeerAttempts?.get(id);
if (!activePeerAttempts || !activeRuns) return;
activePeerAttempts.delete(id);
if (activePeerAttempts.size === 0) this.outboundRouteGenerationByPeer.delete(deviceId);
let settledPeerAttempts = this.settledOutboundRouteGenerationByPeer.get(deviceId);
if (!settledPeerAttempts) {
settledPeerAttempts = new Map();
this.settledOutboundRouteGenerationByPeer.set(deviceId, settledPeerAttempts);
}
const settledRuns = settledPeerAttempts.get(id) ?? [];
for (const run of activeRuns) {
const latest = settledRuns.at(-1);
if (latest?.linkGeneration === run.linkGeneration) {
latest.count += run.count;
} else {
settledRuns.push({ ...run });
}
}
while (settledRuns.length > MAX_OUTBOUND_ROUTE_GENERATION_RUNS_PER_ID) {
settledRuns.shift();
}
// Map 插入顺序作为 LRU;已结算历史只用于识别迟到错误,不参与发送背压。
settledPeerAttempts.delete(id);
settledPeerAttempts.set(id, settledRuns);
this.trimSettledOutboundRouteHistory();
}
private trimSettledOutboundRouteHistory(): void {
for (const [deviceId, peerAttempts] of this.settledOutboundRouteGenerationByPeer) {
while (peerAttempts.size > MAX_SETTLED_OUTBOUND_ROUTE_IDS_PER_PEER) {
const oldestId = peerAttempts.keys().next().value as string | undefined;
if (!oldestId) break;
peerAttempts.delete(oldestId);
}
if (peerAttempts.size === 0) this.settledOutboundRouteGenerationByPeer.delete(deviceId);
}
let totalIds = Array.from(this.settledOutboundRouteGenerationByPeer.values()).reduce(
(sum, attempts) => sum + attempts.size,
0,
);
if (totalIds <= MAX_SETTLED_OUTBOUND_ROUTE_IDS_TOTAL) return;
for (const [deviceId, peerAttempts] of this.settledOutboundRouteGenerationByPeer) {
while (peerAttempts.size > 0 && totalIds > MAX_SETTLED_OUTBOUND_ROUTE_IDS_TOTAL) {
const oldestId = peerAttempts.keys().next().value as string | undefined;
if (!oldestId) break;
peerAttempts.delete(oldestId);
totalIds -= 1;
}
if (peerAttempts.size === 0) this.settledOutboundRouteGenerationByPeer.delete(deviceId);
if (totalIds <= MAX_SETTLED_OUTBOUND_ROUTE_IDS_TOTAL) break;
}
}
private rollbackOutboundRouteGeneration(
id: string,
deviceId: string,
linkGeneration: number,
): void {
const peerAttempts = this.outboundRouteGenerationByPeer.get(deviceId);
const generationRuns = peerAttempts?.get(id);
const latest = generationRuns?.at(-1);
if (!peerAttempts || !generationRuns || latest?.linkGeneration !== linkGeneration) return;
latest.count -= 1;
if (latest.count === 0) generationRuns.pop();
if (generationRuns.length === 0) peerAttempts.delete(id);
if (peerAttempts.size === 0) this.outboundRouteGenerationByPeer.delete(deviceId);
}
private assertWebSocketCapacity(additionalBytes: number): void {
const ws = this.ws;
if (!ws) throw new DeviceLinkError('NOT_CONNECTED', 'no active connection');
if (
typeof ws.bufferedAmount === 'number'
&& ws.bufferedAmount + additionalBytes > MAX_TRANSPORT_WEBSOCKET_BUFFERED_BYTES
) {
throw new DeviceLinkError('BACKPRESSURE', 'websocket send buffer is full');
}
}
private isPeerSendReady(peer: PeerTransportState): boolean {
return peer.sendPhase === 'ready';
}
private isPeerLinkReady(peer: PeerTransportState): boolean {
return this.isPeerSendReady(peer) && peer.receiveReady;
}
private markPeerLinkDown(peer: PeerTransportState): void {
for (const [id, state] of this.peerTransport) if (state === peer) {
this.detachDirectPath(id, 'link-closed');
this.clearProviderShareDirectLease(id);
this.providerShareLocalAddresses.delete(id);
break;
}
peer.duplicateOpenRepair = null;
peer.confirmedGapRepair = null;
if (peer.pendingLinkConfirmation?.timer) {
clearTimeout(peer.pendingLinkConfirmation.timer);
}
if (peer.outboundLinkConfirmationAck?.timer) {
clearTimeout(peer.outboundLinkConfirmationAck.timer);
}
peer.sendPhase = 'down';
peer.receiveReady = false;
peer.pendingLinkConfirmation = null;
peer.outboundLinkConfirmationAck = null;
peer.directBufferWait = undefined;
peer.lastInboundPath = 'relay';
}
private getPeerTransport(dst: string): PeerTransportState {
let peer = this.peerTransport.get(dst);
if (!peer) {
peer = {
streamId: createRequestId(),
remoteStreamId: null,
remoteBaseSeq: 1,
nextSeq: 1,
reliable: false,
sendPhase: 'down',
receiveReady: false,
pendingLinkConfirmation: null,
outboundLinkConfirmationAck: null,
explicitlyClosed: false,
linkAcceptedInbound: false,
outboundExplicitlyClosed: false,
supportsTransportTimeoutClose: false,
unlinkedLegacyResponseIds: new Set(),
pending: new Map(),
pendingBytes: 0,
retryTimer: null,
receive: new Map(),
highestAckSeq: 0,
lastReplayEpoch: this.connEpoch,
lastReplayRemoteStreamId: null,
duplicateOpenRepair: null,
confirmedGapRepair: null,
lastDuplicateOpenRepairSeq: 0,
lastDuplicateOpenRepairAt: Number.NEGATIVE_INFINITY,
recoveryNeedsAck: false,
recoveryFramesSent: 0,
rtt: { srttMs: null, rttVarMs: 0 },
recoveryTrace: null,
pushAdmissionDropCount: 0,
pushAdmissionDropLogAt: 0,
linkGeneration: 0,
lastInboundPath: 'relay',
};
this.peerTransport.set(dst, peer);
}
return peer;
}
private rememberUnlinkedLegacyResponse(peer: PeerTransportState, requestId: string): void {
peer.unlinkedLegacyResponseIds.delete(requestId);
peer.unlinkedLegacyResponseIds.add(requestId);
while (peer.unlinkedLegacyResponseIds.size > MAX_UNLINKED_LEGACY_RESPONSE_IDS) {
const oldest = peer.unlinkedLegacyResponseIds.values().next().value as string | undefined;
if (!oldest) break;
peer.unlinkedLegacyResponseIds.delete(oldest);
}
}
private getReceiveStream(
peer: PeerTransportState,
streamId: string,
baseSeq = 1,
): ReceiveStreamState {
let stream = peer.receive.get(streamId);
if (!stream) {
if (peer.receive.size >= MAX_TRANSPORT_REASSEMBLIES) {
const oldest = peer.receive.keys().next().value as string | undefined;
if (oldest) peer.receive.delete(oldest);
}
stream = {
lastDeliveredSeq: Math.max(0, baseSeq - 1),
requestedBaseSeq: baseSeq,
deliveringSeq: null,
assemblies: new Map(),
ready: new Map(),
bufferedBytes: 0,
drain: null,
drainRequested: false,
};
peer.receive.set(streamId, stream);
} else {
this.advanceReceiveStreamBase(stream, baseSeq);
}
return stream;
}
private advanceReceiveStreamBase(stream: ReceiveStreamState, baseSeq: number): void {
stream.requestedBaseSeq = Math.max(stream.requestedBaseSeq, baseSeq);
this.applyReceiveStreamBase(stream);
}
private applyReceiveStreamBase(stream: ReceiveStreamState): void {
const baseSeq = stream.requestedBaseSeq;
const target = Math.max(0, baseSeq - 1);
if (target <= stream.lastDeliveredSeq) return;
// 已进入 host 的副作用无法取消;等本轮 settle 后再跨过。尚未开始或曾失败
// 留在 ready 队头的消息可以安全按发送端新基线丢弃。
if (stream.deliveringSeq !== null && stream.deliveringSeq < baseSeq) return;
for (const [seq, assembly] of stream.assemblies) {
if (seq >= baseSeq) continue;
stream.assemblies.delete(seq);
stream.bufferedBytes -= assembly.bytes;
}
for (const [seq, ready] of stream.ready) {
if (seq >= baseSeq) continue;
stream.ready.delete(seq);
stream.bufferedBytes -= byteLength(ready.json);
}
stream.lastDeliveredSeq = target;
}
private resumeReceiveStreams(src: string, peer: PeerTransportState): void {
for (const [streamId, stream] of peer.receive) {
this.applyReceiveStreamBase(stream);
if (!stream.ready.has(stream.lastDeliveredSeq + 1)) continue;
void this.drainTransportStream(src, streamId, stream).catch((err) => {
this.log.error('device-link reliable stream resume failed', err);
});
}
}
private setPeerCapabilities(
dst: string,
capabilities?: readonly string[],
remoteStreamId?: string,
remoteBaseSeq?: number,
source: 'inbound-open' | 'outbound-accept' = 'inbound-open',
): void {
const peer = this.getPeerTransport(dst);
if (this.directNegotiator && capabilities?.includes(DIRECT_LINK_CAPABILITY)
&& (!isScopedPeer(dst) || (isProviderSharePeer(dst)
&& capabilities.includes(PROVIDER_SHARE_DIRECT_CAPABILITY)))) {
this.directPeerSupport.add(dst);
} else {
this.directPeerSupport.delete(dst);
this.directNegotiator?.forget(dst);
if (isProviderSharePeer(dst)) this.clearProviderShareDirectLease(dst);
this.detachDirectPath(dst, 'not-eligible');
}
const reliable = (
Array.isArray(capabilities)
&& capabilities.includes(DEVICE_LINK_CAPABILITY_RELIABLE_TRANSPORT)
);
// supportsTransportTimeoutClose 只跟随**入站 link-open**的声明:它刷新的是
// 「对端作为控制端能否理解 transport-timeout」。出站 openLink 换回的
// link-accept 由对端 sendLinkAccept 生成,生产形态只回显 reliable 能力——
// 互控场景下若让它覆盖,会把入站方向已协商到的 true 清掉,入站重试耗尽
// 退回拆整条共享 relay。入站方向的重新声明(含对端降级为旧版后的
// 不再声明)仍正常刷新,降级安全。
if (source === 'inbound-open') {
peer.supportsTransportTimeoutClose = (
Array.isArray(capabilities)
&& capabilities.includes(DEVICE_LINK_CAPABILITY_TRANSPORT_TIMEOUT_CLOSE)
);
}
const nextRemoteStreamId = reliable && typeof remoteStreamId === 'string' && remoteStreamId
? remoteStreamId
: null;
const nextRemoteBaseSeq = reliable && Number.isSafeInteger(remoteBaseSeq) && remoteBaseSeq! > 0
? remoteBaseSeq!
: 1;
if (peer.remoteStreamId !== nextRemoteStreamId) {
this.directNegotiator?.forget(dst);
this.detachDirectPath(dst, 'link-closed');
peer.receive.clear();
peer.duplicateOpenRepair = null;
peer.confirmedGapRepair = null;
}
if (peer.reliable && !reliable) {
this.abandonReliablePending(dst, 'peer no longer supports reliable transport');
}
if (!reliable) {
this.markPeerLinkDown(peer);
} else {
// capability 只描述提议/accept;真正接收 ready 由对应握手提交点置位。
peer.receiveReady = false;
}
peer.reliable = reliable;
peer.explicitlyClosed = false;
peer.remoteStreamId = nextRemoteStreamId;
peer.remoteBaseSeq = nextRemoteBaseSeq;
if (nextRemoteStreamId) {
this.getReceiveStream(peer, nextRemoteStreamId, nextRemoteBaseSeq);
}
}
private addLocalCapabilities(dst: string, payload: unknown): unknown {
if (!isRecord(payload)) return payload;
// link-open 的 payload 是端到端对象;对未知旧 shape 不强行包一层,
// 但已有 capabilities 时保留其它能力并去重。
if (!('controllerName' in payload) && !('protocolVersion' in payload)) return payload;
return {
...payload,
capabilities: this.mergeCapabilities(payload.capabilities, [
DEVICE_LINK_CAPABILITY_RELIABLE_LINK_CONFIRM,
DEVICE_LINK_CAPABILITY_RELIABLE_TRANSPORT,
DEVICE_LINK_CAPABILITY_TRANSPORT_TIMEOUT_CLOSE,
...(this.directNegotiator && (!isScopedPeer(dst) || isProviderSharePeer(dst))
? [DIRECT_LINK_CAPABILITY] : []),
...(this.directNegotiator && isProviderSharePeer(dst) ? [PROVIDER_SHARE_DIRECT_CAPABILITY] : []),
]),
transportStreamId: typeof payload.transportStreamId === 'string'
? payload.transportStreamId
: this.getPeerTransport(dst).streamId,
transportBaseSeq: this.getTransportBaseSeq(this.getPeerTransport(dst)),
};
}
private getTransportBaseSeq(peer: PeerTransportState): number {
return peer.pending.keys().next().value as number | undefined
?? peer.nextSeq;
}
private mergeCapabilities(
current: unknown,
additions: readonly string[],
): string[] {
const result = Array.isArray(current)
? current.filter((value): value is string => typeof value === 'string')
: [];
for (const addition of additions) {
if (!result.includes(addition)) result.push(addition);
}
return result;
}
private sendTransportAck(
dst: string,
streamId: string,
ackSeq: number,
linkRequestId?: string,
): boolean {
const pendingConfirmation = this.peerTransport.get(dst)?.outboundLinkConfirmationAck;
const effectiveLinkRequestId = linkRequestId ?? (
pendingConfirmation?.streamId === streamId
? pendingConfirmation.requestId
: undefined
);
const ack = makeTransportAck(dst, streamId, ackSeq, effectiveLinkRequestId);
// 累计 ACK 原路返回;链路确认 ACK 属于控制面,始终走 relay。
const direct = !effectiveLinkRequestId && this.peerTransport.get(dst)?.lastInboundPath === 'direct'
? this.usableDirectPath(dst)
: undefined;
if (direct) {
try {
direct.send(JSON.stringify(ack));
this.logRecoveryStage(dst, 'ack-sent', ` receiveStream=${streamId.slice(0, 8)} ack=${ackSeq}`, false);
return true;
} catch (err) {
this.log.debug(`reliable transport direct ACK send failed dst=${dst.slice(0, 8)}`, err);
this.detachDirectPath(dst, 'send-failed');
}
}
try {
this.sendBestEffortRoutedEnvelope(ack);
this.logRecoveryStage(dst, 'ack-sent', ` receiveStream=${streamId.slice(0, 8)} ack=${ackSeq}`, false);
return true;
} catch (err) {
this.log.debug(
`reliable transport ACK send failed dst=${dst.slice(0, 8)}`
+ ` stream=${streamId.slice(0, 8)} ack=${ackSeq} conn=${this.connEpoch}`,
err,
);
return false;
}
}
private sendReliableLinkConfirmation(
dst: string,
requestId: string,
peer: PeerTransportState,
): void {
if (!peer.receiveReady || !peer.remoteStreamId) return;
this.getReceiveStream(peer, peer.remoteStreamId, peer.remoteBaseSeq);
if (peer.outboundLinkConfirmationAck?.timer) {
clearTimeout(peer.outboundLinkConfirmationAck.timer);
}
peer.outboundLinkConfirmationAck = {
requestId,
streamId: peer.remoteStreamId,
attempts: 0,
timer: null,
};
this.retryReliableLinkConfirmation(dst, peer);
}
private retryReliableLinkConfirmation(dst: string, peer: PeerTransportState): void {
const confirmation = peer.outboundLinkConfirmationAck;
if (
!confirmation
|| this.stopped
|| this.status !== 'online'
|| !peer.receiveReady
|| peer.remoteStreamId !== confirmation.streamId
) {
return;
}
// link-accept 可能在旧可靠帧仍执行时推进 requestedBaseSeq;此时
// applyReceiveStreamBase 会延迟提交,首次确认看到的 lastDeliveredSeq
// 不是最终基线。每次重试必须从活动 stream 重新读取,不能复用快照。
const stream = this.getReceiveStream(peer, confirmation.streamId, peer.remoteBaseSeq);
confirmation.attempts += 1;
this.sendTransportAck(
dst,
confirmation.streamId,
stream.lastDeliveredSeq,
confirmation.requestId,
);
if (confirmation.attempts >= normalizeTransportRetryAttempts(this.timing.transportMaxRetryAttempts)) {
confirmation.timer = null;
return;
}
confirmation.timer = setTimeout(() => {
confirmation.timer = null;
if (peer.outboundLinkConfirmationAck !== confirmation) return;
this.retryReliableLinkConfirmation(dst, peer);
}, normalizeTransportRetryInterval(this.timing.transportRetryIntervalMs));
}
private handleTransportAck(
src: string,
streamId: string,
ackSeq: number,
linkRequestId?: string,
): void {
const peer = this.peerTransport.get(src);
if (!peer || !peer.reliable || peer.streamId !== streamId) return;
const confirmation = peer.pendingLinkConfirmation;
if (
peer.sendPhase === 'awaiting-confirm'
&& confirmation
&& linkRequestId === confirmation.requestId
&& ackSeq >= confirmation.minimumAckSeq
&& ackSeq <= peer.nextSeq - 1
) {
this.log.info(
`device-link recovery dst=${src.slice(0, 8)} trigger=link-confirm-ack`
+ ` stream=${peer.streamId.slice(0, 8)} request=${confirmation.requestId.slice(0, 8)}`
+ ` ack=${ackSeq} conn=${this.connEpoch}`,
);
this.logRecoveryStage(src, 'link-confirm-received', ` ack=${ackSeq}`);
// 新版入站重建的带 request id ACK 是 local → remote 的因果屏障:对端已经
// 收到本代 link-accept,旧代成功路由却未 ACK 的尝试不会再产生 relay-error。
// 必须在重放前淘汰旧代记录,否则当前重放真实失败会 FIFO 消费旧代并被当
// stale。旧端没有 confirmation 能力时没有这个证据,继续保留原兼容路径。
this.discardOutboundRouteAttemptsBeforeGeneration(src, peer.linkGeneration);
this.discardOutboundRouteAttemptsForId(src, confirmation.requestId);
this.commitReliableSendResume(src, peer, confirmation.resume);
}
if (!this.isPeerSendReady(peer)) return;
this.repairConfirmedReceiveGap(src, peer, ackSeq, linkRequestId);
// 迟到/陈旧 ACK 幂等无害(含指向已被驱逐 seq 的 ACK):驱逐后该 seq 已不在
// map 里,累计删除循环遇到更高的队头 live seq 直接 break,不会误删、不抛错、
// 不错误推进状态;高于 nextSeq-1 的未知 ACK 与倒退的 ACK 直接忽略。
if (ackSeq > peer.nextSeq - 1 || ackSeq <= peer.highestAckSeq) return;
peer.highestAckSeq = ackSeq;
this.logRecoveryStage(src, 'ack-received', ` ack=${ackSeq}`, false);
let rttSample: number | null = null;
const acknowledgedAt = this.monotonicNow();
let deliveryStartedAt = acknowledgedAt;
let deliveryBytes = 0;
let deliverySampleValid = true;
for (const [seq, pending] of peer.pending) {
if (seq > ackSeq) break;
if (pending.envelope.id) {
this.discardOutboundRouteAttemptsForId(src, pending.envelope.id);
}
// Measured from the first write of this round (replay restarts it), so a
// slow link still yields samples after its frames were retried; the latest
// message in the ACK gives the tightest one. Large messages measure
// transfer time, which byte pacing already covers.
if (pending.firstSentAt !== undefined && pending.bytes <= RELIABLE_RETRY_BYTES_PER_INTERVAL) {
rttSample = this.monotonicNow() - pending.firstSentAt;
}
if (pending.firstSentAt !== undefined && pending.attempts === 1) {
deliveryStartedAt = Math.min(deliveryStartedAt, pending.firstSentAt);
deliveryBytes += pending.bytes;
} else {
deliverySampleValid = false;
}
peer.pending.delete(seq);
peer.pendingBytes -= pending.bytes;
}
// A cumulative ACK measures the whole acknowledged burst. Sampling its
// tail separately counts time spent delivering preceding messages as slowness.
// Retransmitted batches have ambiguous timing and cannot teach delivery pace.
if (deliverySampleValid) {
updateDeliveryEstimate(peer.rtt, deliveryBytes, acknowledgedAt - deliveryStartedAt);
}
if (rttSample !== null) updateRetransmitEstimate(peer.rtt, rttSample);
if (peer.recoveryNeedsAck) {
peer.confirmedGapRepair = null;
peer.recoveryNeedsAck = false;
peer.recoveryFramesSent = 0;
this.logRecoveryStage(src, 'recovery-probe-acked', ` ack=${ackSeq}`);
// Lift the probe budget only. The recovery pass just wrote the head
// frames; resending them before their retry delay doubles the replay on
// the slow links that caused the reset (a link-confirm ACK lands within
// milliseconds of that pass).
this.retryPending(src, { ignoreInterval: false });
} else {
const repair = peer.confirmedGapRepair;
if (repair && ackSeq >= repair.awaitingSeq) {
this.sendConfirmedGapHead(src, peer, repair.throughSeq);
}
// Release locally queued first sends promptly, without replaying already
// in-flight large responses every time a partial ACK arrives.
this.retryPending(src, { ignoreInterval: false, onlyUnsent: true });
}
if (peer.recoveryTrace?.replayThroughSeq !== null
&& peer.recoveryTrace?.replayThroughSeq !== undefined
&& ackSeq >= peer.recoveryTrace.replayThroughSeq) {
this.logRecoveryStage(src, 'replay-backlog-acked', ` ack=${ackSeq}`);
}
if (peer.pending.size === 0 && peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
}
/** A controller can reconnect without changing its reliable stream or our
* relay epoch. Its current accept confirmation can still report a missing
* head. Repair one head at a time, advancing only after its cumulative ACK,
* bounded to the captured backlog and one extra copy per sequence. Normal
* ACKs and legacy peers cannot start this path. Slow heads may get a copy. */
private repairConfirmedReceiveGap(
dst: string,
peer: PeerTransportState,
ackSeq: number,
linkRequestId?: string,
): void {
const repair = peer.duplicateOpenRepair;
if (!repair || repair.requestId !== linkRequestId) return;
peer.duplicateOpenRepair = null;
if (peer.confirmedGapRepair) return; // Repeated opens cannot extend the snapshot.
const head = peer.pending.values().next().value;
const now = this.monotonicNow();
if (!head?.sent || head.seq !== repair.headSeq
|| ackSeq !== head.seq - 1 || ackSeq < peer.highestAckSeq
|| now - peer.lastDuplicateOpenRepairAt < normalizeTransportRetryInterval(this.timing.transportRetryIntervalMs)) return;
this.sendConfirmedGapHead(dst, peer, repair.throughSeq);
}
private sendConfirmedGapHead(dst: string, peer: PeerTransportState, throughSeq: number): void {
// A blocked/oversize head falls back to the existing retry/drain policy.
// It must not allow a later ACK or duplicate open to spend a fresh budget.
peer.confirmedGapRepair = null;
const head = peer.pending.values().next().value;
const frameCount = head ? this.estimateReliableFrameCount(head) : 0;
if (!head?.sent || head.seq > throughSeq
|| peer.lastDuplicateOpenRepairSeq >= head.seq
|| head.attempts >= this.timing.transportMaxRetryAttempts
|| frameCount > this.recoveryPassBudget()
|| this.shouldHoldRecoverySend(peer, frameCount)) return;
try {
const frames = this.sendReliableFrames(peer, head);
if (frames === 0) return; // Existing retry/drain owns local backpressure.
peer.lastDuplicateOpenRepairSeq = head.seq;
peer.lastDuplicateOpenRepairAt = this.monotonicNow();
if (head.seq < throughSeq) peer.confirmedGapRepair = { awaitingSeq: head.seq, throughSeq };
this.noteRecoveryFrames(peer, frames);
this.log.debug(`device-link confirmed gap repair dst=${dst.slice(0, 8)} seq=${head.seq} frames=${frames}`);
} catch (err) {
this.log.debug(`device-link confirmed gap repair deferred dst=${dst.slice(0, 8)}`, err);
}
}
/**
* 单调时钟。pending 帧的滞留时长(TTL)必须用不受墙钟校正影响的时源计量:
* Date.now() 在系统时间被向前校正超过 TRANSPORT_PENDING_PUSH_MAX_AGE_MS 时,
* 会把刚入队的 push 误判为过期。测试通过 stub 本方法模拟老化。
*/
private monotonicNow(): number {
return performance.now();
}
private beginRecoveryTrace(dst: string, requestId: string): void {
this.getPeerTransport(dst).recoveryTrace = {
startedAt: this.monotonicNow(),
connectionEpoch: this.connEpoch,
requestId,
stages: new Set(),
ackProgressLogs: 0,
replayThroughSeq: null,
};
}
/** Stage names and details are local transport metadata, never business payloads. */
private logRecoveryStage(dst: string, stage: string, detail = '', once = true): void {
const peer = this.peerTransport.get(dst);
const trace = peer?.recoveryTrace;
if (!peer || !trace) return;
const elapsedMs = Math.max(0, this.monotonicNow() - trace.startedAt);
if (trace.connectionEpoch !== this.connEpoch || elapsedMs > RECOVERY_TRACE_WINDOW_MS) {
peer.recoveryTrace = null;
return;
}
if (once) {
if (trace.stages.has(stage)) return;
trace.stages.add(stage);
} else {
// ACKs in steady traffic must not become a per-frame logging stream.
if (trace.ackProgressLogs >= 8) return;
trace.ackProgressLogs++;
}
this.log.debug(
`device-link recovery-stage dst=${dst.slice(0, 8)} stage=${stage}`
+ ` elapsedMs=${elapsedMs.toFixed(1)} request=${trace.requestId.slice(0, 8)}`
+ ` conn=${this.connEpoch} link=${peer.linkGeneration}`
+ ` pending=${peer.pending.size}/${peer.pendingBytes}${detail}`,
);
}
/**
* 可丢弃帧判据(重连重放与 invoke-result 腾位两条路径共用的不变量;
* push latest-wins 腾位用更窄的白名单判据,见
* dropOldestDiscardableForPushAdmission):
* best-effort push,以及 timeout / relay-error 后被 dropReliablePendingForRequest
* 换成 transport-skip 占位 payload 的帧——其外层 kind 仍是原 invoke /
* invoke-result,但已无任何业务副作用。两者都可以通过推进 baseSeq 让接收端
* 整体跳过;live invoke / invoke-result 永不可丢弃,是丢弃前缀的边界。
*/
private isDiscardablePending(pending: PendingReliableMessage): boolean {
return (
pending.envelope.kind === 'push'
|| isTransportSkipPayload(pending.envelope.payload)
);
}
/**
* 丢弃 pending 队头连续的可丢弃前缀。只能从队头连续删除:队头出队后
* baseSeq(最小 pending seq)随之前移,后续帧携带的 baseSeq 会让接收端整体
* 跳过这些 seq;若删除中段条目则会留下 seq 空洞,接收端累计 ACK 永久停住。
*
* expiredOnly=true 只删过期 push(skip 占位没有任何交付价值,始终可删),
* 用于普通入队压力下的兜底清扫;expiredOnly=false 丢弃整个可丢弃前缀
* (fresh push 一并放弃),用于重连重放前与 invoke-result 腾位——保证剩余
* 队头就是最早的 live 帧,invoke-result 不会排在任何可丢弃帧之后。
*
* 不变量的作用域(刻意从窄):「result 成为最早可交付的 live seq」只在两个
* 清扫时点成立——重连重放写入 socket 之前、新帧入队之前。已写进 WebSocket
* FIFO 的帧无法撤回,本方法不承诺全时态抢占;队头是 live 帧时前缀为空,
* 维持原 BACKPRESSURE 语义。这也是单 FIFO 的固有极限:live 帧之后的 push
* 不可跨越(会留 seq 空洞),例如 [push, live-invoke, push…] 只能丢掉第一段,
* result 仍排在 live-invoke 之后——「push 无损」与「result 抢占」在单流上
* 不可兼得(需独立优先 stream 才能同时满足)。
*
* 终止性与计数:每轮迭代要么删除当前队头、要么 break(队头 live / 未过期),
* 至多 pending.size 轮;removePendingEntry 同步扣减 pendingBytes 并在队空时
* 回收 retryTimer,不产生计数漂移。只触碰参数 peer(按 dst 隔离)的缓冲。
*
* 数据完整性:被丢弃的 push 不是静默丢数据——push 是尽力而为的状态镜像,
* 控制端在重连/回前台时会整体 resync + 重新订阅(mobile 侧 reconnect
* reseed),最新状态由下一次全量拉取补偿。传输层没有 push 的离线持久队列
* (invoke-result 的 outbox 在 host 层且与 push 无关),驱逐回填既无宿主也无
* 必要,故不做。
*/
private dropDiscardablePendingPrefix(
dst: string,
peer: PeerTransportState,
expiredOnly: boolean,
reason: string,
): number {
const now = this.monotonicNow();
let dropped = 0;
for (const [seq, pending] of peer.pending) {
if (!this.isDiscardablePending(pending)) break;
if (
expiredOnly
&& pending.envelope.kind === 'push'
&& now - pending.enqueuedAt < TRANSPORT_PENDING_PUSH_MAX_AGE_MS
) break;
this.removePendingEntry(peer, seq, pending);
dropped += 1;
}
if (dropped > 0) {
this.log.warn(
`dropped ${dropped} discardable pending frame(s) (best-effort push / transport-skip) for peer ${dst.slice(0, 8)} ${reason}`,
);
}
return dropped;
}
private removePendingEntry(
peer: PeerTransportState,
seq: number,
pending: PendingReliableMessage,
): void {
// A reliable frame can be evicted without ever receiving a transport ACK
// (latest-wins / TTL / skip-prefix cleanup). Keep its physical-send
// generations in the bounded settled ledger so a delayed relay error can
// still be classified, while releasing the active 1024-ID send budget.
if (pending.envelope.dst && pending.envelope.id) {
this.settleOutboundRouteAttemptsForId(pending.envelope.dst, pending.envelope.id);
}
peer.pending.delete(seq);
peer.pendingBytes -= pending.bytes;
if (peer.pending.size === 0 && peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
}
/**
* push 入队的拥塞腾位(latest-wins):只从队头连续移除最旧的可驱逐帧,直到
* 放得下新帧或队头变成不可驱逐帧。与 dropDiscardablePendingPrefix 的区别是「按需
* 腾位」而非「整段前缀丢弃」:对端只是暂时未 ACK 时,队列里较新的镜像历史保留
* 下来,恢复后仍能交付;被驱逐的最旧镜像由控制端 resync 补偿,不是静默丢数据。
*
* 可驱逐判据比 isDiscardablePending 更窄(白名单,fail-closed):只有
* COALESCIBLE_PUSH_CHANNELS 里的镜像 push 与 transport-skip 占位可被驱逐。
* 白名单外的 push(不可合并事件流如 local-db:messages:created、确认卡、
* 以 BACKPRESSURE 为流控信号的 contacts-sync 分片)被静默驱逐时 link 并未
* 断开、reconnect reseed 不会跑,等价于 UI 永久漏事件或传输永久拼不出——
* 它们与 live invoke/invoke-result 一样是腾位边界。队头不可驱逐时无位可让
* (跨过会制造 seq 空洞),调用方按容量复检结果维持原 BACKPRESSURE 语义。
* 只删队头 → baseSeq 单调前移,接收端按新基线整体跳过被驱逐 seq,无空洞、
* 不挂累计 ACK。
*
* 生产反例(2026-08-07,P0 度量实锤):对端停 ACK 时新鲜 push 之间互相背压,
* 每条新 push 都抛 BACKPRESSURE,一小时 5168 次(maker:event),镜像零交付。
* 告警按 peer 聚合(PUSH_ADMISSION_DROP_LOG_INTERVAL_MS 窗口):洪峰期驱逐
* 逐条 warn 会把 5168 次背压风暴换成 5168 行日志风暴(review P2)。
*/
private dropOldestDiscardableForPushAdmission(
dst: string,
peer: PeerTransportState,
reservedBytes: number,
): number {
let dropped = 0;
while (
peer.pending.size >= MAX_TRANSPORT_PENDING_MESSAGES
|| peer.pendingBytes + reservedBytes > MAX_TRANSPORT_PENDING_BYTES
) {
const head = peer.pending.entries().next();
if (head.done) break;
const [seq, pending] = head.value;
if (
!isTransportSkipPayload(pending.envelope.payload)
&& !isCoalesciblePushEnvelope(pending.envelope)
) break;
this.removePendingEntry(peer, seq, pending);
dropped += 1;
}
if (dropped > 0) {
peer.pushAdmissionDropCount += dropped;
const now = this.monotonicNow();
// 首次驱逐(lastLogAt=0)立即告警,之后按窗口聚合——单调时钟起点接近 0,
// 纯差值判据会把进程早期的首次驱逐静默吞掉。
if (
peer.pushAdmissionDropLogAt === 0
|| now - peer.pushAdmissionDropLogAt >= PUSH_ADMISSION_DROP_LOG_INTERVAL_MS
) {
this.log.warn(
`dropped ${peer.pushAdmissionDropCount} oldest discardable pending frame(s) for peer ${dst.slice(0, 8)} latest-wins push admission (aggregated since last report)`,
);
peer.pushAdmissionDropCount = 0;
peer.pushAdmissionDropLogAt = now;
}
}
return dropped;
}
private ensureRetryTimer(dst: string): void {
const peer = this.getPeerTransport(dst);
if (peer.retryTimer) return;
peer.retryTimer = setInterval(
() => this.retryPending(dst, { ignoreInterval: false }),
this.congestionCloseStreak > 0 || this.localSendPressure
? Math.min(250, this.timing.transportRetryIntervalMs)
: this.timing.transportRetryIntervalMs,
);
}
/**
* 一趟重发。
*
* @param opts.ignoreInterval 忽略 transportRetryIntervalMs 的最小间隔,本趟立刻发。
* 单趟额度一律走 remainingRecoveryBudget,不再接受无限额度。
*/
private retryPending(
dst: string,
opts: { ignoreInterval: boolean; onlyUnsent?: boolean },
): void {
const peer = this.peerTransport.get(dst);
if (
!peer
|| !peer.reliable
|| !this.isPeerSendReady(peer)
|| this.stopped
|| (this.status !== 'online' && !this.hasOfflineDirectPath(dst))
) return;
const now = Date.now();
// pending 是按 seq 递增插入的 Map,迭代天然旧→新 —— 正是累计 ACK 需要推进的顺序。
// 对端长期不 ACK 时预算会一直压在队头那几条上,这**不是饥饿**而是正确形状:接收端
// 在拿到队头之前无法消费后面的 seq,重发队尾是无效工作。队头被累计 ACK 掉、窗口
// 前移之后,后面的消息自然轮到(有交错用例锚定这两段行为)。
//
// 预算按**帧**计而不是按逻辑消息计:压垮 relay 的是帧数,而一条 4MB 消息会被分成
// 32 片,按消息计数会让 8 条预算放出 ~256 帧,等于没限(greptile P1)。
//
// 本趟实际上限是 **max(预算, 队头那一条消息的分片数)**,不是预算本身:
// - 非队头的大消息**发送前**就按预估分片数拦下(不许挤爆本趟),留到下一趟;
// - 队头那一条无法再压 —— 分片不能跨趟拆(接收端按 seq 整条重组),而它又必须先送
// 到(累计 ACK 不推进,后面的 seq 谁也消费不了)。
//
// **队头那条的溢出已定案不再压(review 两轮的结论,不要再往这里加游标)**:要压它就得
// 引入 per-message 分片游标 + 跨趟续传进度,那是可靠层新机制(重试从游标续发还是从 0
// 重发?attempts/lastSentAt 按消息还是按片记?游标与累计 ACK / baseSeq 推进如何互不
// 矛盾?跨连接世代是否保留?)。而且它是用「大消息交付延迟 ×N 趟」换「突发再小一点」
// ——32 片消息在预算 8 下要 4 趟 = 8s,而它是队头,后面所有 seq 都在等它,对健康但慢的
// peer 是净损失。量级上也不是主要矛盾:线上那 449 条的形状是几 KB 级 maker:event 塞满
// 64 槽窗口(最大簇 213),本上限已把它压到 ≤8;「队头恰好 4MB」时溢出是 ≤32,仍低于
// 引发事故的量级。真出现这种负载时日志会给出真实形状,届时按证据设计,不先建机制。
const budget = this.recoveryPassBudget();
let framesSpent = 0;
const head = peer.pending.values().next().value;
for (const pending of peer.pending.values()) {
// Expiry must precede retry exhaustion too: suspension is a request
// timeout, not evidence that the peer's transport has failed.
if (pending.envelope.kind === 'invoke' && pending.envelope.id
&& this.pending.get(pending.envelope.id)?.expireIfOverdue()) continue;
if (opts.onlyUnsent && pending.sent) continue;
// Cumulative ACK cannot confirm a tail while a byte-paced head is still
// missing. Allow one early tail retry to fill the receiver's buffer, but
// do not burn its whole retry budget (and reset this healthy slow link)
// before the head has finished. ACK removal naturally releases this hold;
// genuine link recovery still replays immediately via ignoreInterval.
if (
!opts.ignoreInterval
&& head
&& pending !== head
&& head.bytes > RELIABLE_RETRY_BYTES_PER_INTERVAL
&& pending.attempts >= Math.min(2, this.timing.transportMaxRetryAttempts)
) continue;
// A local ws write is not a delivery receipt: relay -> mobile can still be
// transmitting a large response even with bufferedAmount=0. A 200KB page
// took ~18s on Android's 256Kbit/s high-latency link; 2/4/8s backoff still
// queued several full copies before its first ACK. Include a bounded byte
// budget, retaining immediate replay when a new connection/link resumes.
const sizeIntervals = Math.min(
RELIABLE_RETRY_MAX_SIZE_INTERVALS,
Math.ceil(pending.bytes / RELIABLE_RETRY_BYTES_PER_INTERVAL),
);
// 直连无 ACK 时要及时换路:relay 的大消息字节退避可能长于调用方超时,
// 不能让单条大结果在失效直连上等满退避期才尝试健康的 relay。
const retryDelayMs = pending.path === 'direct'
? retransmitBaseMs(peer.rtt, this.timing.transportRetryIntervalMs)
: reliableRetryDelayMs(
peer.rtt,
this.timing.transportRetryIntervalMs,
sizeIntervals,
pending.attempts,
pending.bytes,
);
if (pending.sent && !opts.ignoreInterval && now - pending.lastSentAt < retryDelayMs) {
// A large head frame may still be inside its byte-based cooldown while
// a later small request is already eligible. Cumulative ACK cannot
// advance past the head, but one early retry lets the receiver buffer
// the later frame without exhausting its budget behind that head.
continue;
}
if (pending.path === 'direct' && pending.sent && !opts.ignoreInterval) {
// 经直连写出的帧到了重发期限仍未确认:直连已不可信,撤下并改走 relay。
// 这些帧恢复为未发送、重试次数从零计,直连的失败不消耗 relay 的重试预算。
this.detachDirectPath(dst, 'ack-timeout');
// 本轮可能在非队头短帧处超时;让 detach 的微任务从最早未确认帧重启恢复。
return;
}
if (pending.attempts >= this.timing.transportMaxRetryAttempts) {
this.handleReliableRetryExhausted(dst, pending.seq);
return;
}
const admittingNew = !pending.sent;
// 回退后队头可能尚未发送,而后面的 relay 帧仍在途。累计 ACK 不能越过
// 缺失队头,尾帧不可能释放预算;必须允许队头整条发出,再等 ACK 推进。
if (admittingNew && pending !== head
&& this.shouldHoldRecoverySend(peer, this.estimateReliableFrameCount(pending))) {
pending.lastBlockedBy = 'recovery-ack';
break;
}
// 发送前先按预估分片数结算:已经发过东西、且这一条会超预算时,把它留到下一趟。
// 用预估而非真实编码结果是刻意的 —— 这是流控决策,不需要精确,重新编码一条 4MB
// 消息只为数分片数不划算;发送后再用真实帧数扣减。
if (framesSpent > 0 && framesSpent + this.estimateReliableFrameCount(pending) > budget) {
pending.lastBlockedBy = 'pass-budget';
break;
}
let sentFrames = 0;
try {
const previousAttempts = pending.attempts;
const sinceSendMs = now - pending.lastSentAt;
sentFrames = this.sendReliableFrames(peer, pending);
if (sentFrames > 0 && pending === head && previousAttempts > 0 && pending.bytes > RELIABLE_RETRY_BYTES_PER_INTERVAL) {
this.log.debug(`reliable head retry dst=${dst.slice(0, 8)} seq=${pending.seq}`
+ ` request=${pending.envelope.id?.slice(0, 8) ?? 'none'} bytes=${pending.bytes}`
+ ` attempts=${previousAttempts} sinceSendMs=${sinceSendMs} frames=${sentFrames}`
+ ` pending=${peer.pending.size} ack=${peer.highestAckSeq}`);
}
} catch (err) {
this.log.debug(`reliable transport retry failed for ${dst.slice(0, 8)}`, err);
break;
}
if (sentFrames === 0) break; // Paced locally: no attempt/ACK failure has occurred.
framesSpent += sentFrames;
// 首趟恢复 replay(ignoreInterval)要把已在途的探针也记进预算,
// 否则 sent===true 的重放不占额度,新入队帧还能再灌一整批。
// 后续定时重发只给新帧记账,同一批探针可继续重传。
if (admittingNew || (peer.recoveryNeedsAck && opts.ignoreInterval)) {
this.noteRecoveryFrames(peer, sentFrames);
}
if (framesSpent >= budget) break;
}
}
/**
* 预估一条 pending 消息会写出多少帧(流控用,不要求精确)。`pending.bytes` 是入队时
* 量好的保留字节数,按分片上限向上取整即可;真实帧数由 sendReliableFrames 返回。
*/
private estimateReliableFrameCount(pending: PendingReliableMessage): number {
return Math.max(1, Math.ceil(pending.bytes / MAX_TRANSPORT_CHUNK_BYTES));
}
private recoveryPassBudget(): number {
return normalizeRetryPassBudget(this.timing.transportRetryPassBudget);
}
private remainingRecoveryBudget(peer: PeerTransportState): number {
const budget = this.recoveryPassBudget();
if (!peer.recoveryNeedsAck) return budget;
return Math.max(0, budget - peer.recoveryFramesSent);
}
private hasOutstandingRecoveryProbe(peer: PeerTransportState): boolean {
for (const pending of peer.pending.values()) {
if (pending.sent) return true;
}
return false;
}
private shouldHoldRecoverySend(peer: PeerTransportState, additionalFrames = 1): boolean {
if (!peer.recoveryNeedsAck) return false;
// hold 的前提是已有在途探针能换来 ACK。latest-wins / TTL 清掉全部已发探针后,
// 若仍按 recoveryFramesSent 卡住,队列只剩未发帧,恢复态永远解不开。
if (!this.hasOutstandingRecoveryProbe(peer)) return false;
const remaining = this.remainingRecoveryBudget(peer);
if (remaining <= 0) return true;
return additionalFrames > remaining;
}
private noteRecoveryFrames(peer: PeerTransportState, frames: number): void {
if (!peer.recoveryNeedsAck || frames <= 0) return;
peer.recoveryFramesSent += frames;
}
private planReliableSendResume(peer: PeerTransportState): ReliableResumePlan {
const wasReady = this.isPeerSendReady(peer);
const streamChanged = peer.lastReplayRemoteStreamId !== peer.remoteStreamId;
const duplicateOpen = wasReady && !streamChanged && peer.lastReplayEpoch === this.connEpoch;
const hadPriorResume = peer.lastReplayRemoteStreamId !== null;
const resumedLink = !wasReady || streamChanged;
return {
duplicateOpen,
resumedLink,
enterRecovery: resumedLink
&& (hadPriorResume || peer.pending.size > 0 || peer.recoveryNeedsAck),
};
}
private commitReliableReceiveReady(dst: string, peer: PeerTransportState): void {
peer.receiveReady = true;
this.logRecoveryStage(dst, 'receive-ready', ` baseSeq=${peer.remoteBaseSeq}`);
this.staleLinkNotifiedAt.delete(dst);
this.resumeReceiveStreams(dst, peer);
}
private beginReliableLinkConfirmation(
dst: string,
peer: PeerTransportState,
requestId: string,
resume: ReliableResumePlan,
): void {
const previousConfirmation = peer.pendingLinkConfirmation;
// 同 stream 重复 open:发送方向已经 ready 时绝不能再打回 awaiting-confirm,
// 否则 ACK/重试被暂停,pending 只涨不消,对端超时后再 open,形成死循环。
if (resume.duplicateOpen && this.isPeerSendReady(peer)) {
const head = peer.pending.values().next().value;
let throughSeq = 0;
for (const pending of peer.pending.values()) {
if (!pending.sent) break;
throughSeq = pending.seq;
}
peer.duplicateOpenRepair = head?.sent ? { requestId, headSeq: head.seq, throughSeq } : null;
// sendLinkAccept 已把这次 accept 记进 active 路由账本;确认分支才会
// discard。这里保持 ready、不进 awaiting-confirm,但仍要结算该记录,
// 否则每次重复 open 泄漏一条,满 1024 后后续 accept 全 BACKPRESSURE。
this.settleOutboundRouteAttemptsForId(dst, requestId);
if (peer.pending.size > 0) this.ensureRetryTimer(dst);
this.logRecoverySend(dst, peer, 'link-replay', true);
return;
}
if (previousConfirmation?.timer) {
clearTimeout(previousConfirmation.timer);
}
// 连续的 inbound open 可能在上一代仍 awaiting-confirm 时替换确认对象。
// 此时 sendPhase 不能代表替换前的健康 outbound 方向,应沿用旧确认保存的
// previousSendPhase,否则撤销新一代 inbound 时会把原本 ready 的方向降成 down。
const previousSendPhase: 'down' | 'ready' = previousConfirmation?.previousSendPhase
?? (peer.sendPhase === 'ready' ? 'ready' : 'down');
peer.sendPhase = 'awaiting-confirm';
const confirmation: PendingLinkConfirmation = {
requestId,
minimumAckSeq: this.getTransportBaseSeq(peer) - 1,
resume,
previousSendPhase,
timer: null,
};
peer.pendingLinkConfirmation = confirmation;
if (peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
this.log.info(
`device-link recovery dst=${dst.slice(0, 8)} trigger=await-link-confirm`
+ ` pending=${peer.pending.size}/${peer.pendingBytes}`
+ ` stream=${peer.streamId.slice(0, 8)} request=${requestId.slice(0, 8)}`
+ ` conn=${this.connEpoch}`,
);
const attempts = normalizeTransportRetryAttempts(this.timing.transportMaxRetryAttempts);
// Accept + confirmation crosses the same slow path as a handshake. Keep a
// cold-path allowance and reuse the peer RTT estimate once available; this
// single timer stays bounded and retains the existing recovery policy.
const confirmationTimeoutMs = Math.max(
this.timing.handshakeTimeoutMs * 2,
retransmitBaseMs(peer.rtt, normalizeTransportRetryInterval(this.timing.transportRetryIntervalMs)) * attempts,
);
confirmation.timer = setTimeout(() => {
confirmation.timer = null;
if (
peer.pendingLinkConfirmation !== confirmation
|| peer.sendPhase !== 'awaiting-confirm'
|| this.stopped
|| this.status !== 'online'
) {
return;
}
this.log.warn(
`device-link link confirmation timeout for ${dst.slice(0, 8)}`
+ ` request=${requestId.slice(0, 8)}; resetting peer link`,
);
this.handleReliableRetryExhausted(dst, confirmation.minimumAckSeq);
}, confirmationTimeoutMs);
}
/**
* 只提交 local → remote 发送方向。新版入站 accept 必须先经过带 request id
* 的 ACK 确认;旧端与本机处理到的出站 accept 直接调用本方法。
*/
private commitReliableSendResume(
dst: string,
peer: PeerTransportState,
resume: ReliableResumePlan,
): void {
if (peer.pendingLinkConfirmation?.timer) {
clearTimeout(peer.pendingLinkConfirmation.timer);
}
peer.sendPhase = 'ready';
peer.pendingLinkConfirmation = null;
// Defer until this handshake commits; negotiation never occupies the reliable FIFO.
void Promise.resolve().then(() => this.directNegotiator?.ready(dst));
this.logRecoveryStage(dst, 'send-ready');
this.cancelTimeoutCloseNotify(dst);
if (resume.duplicateOpen) {
// 同连接同 stream 的重复 open 仍可能带着未确认的可靠帧。确认阶段
// 会先清掉旧 retryTimer;不能因为这是 duplicate open 就让 pending 永久
// 停在队列里。这里不做全量 replay,只恢复原有有界重试计时器。
if (peer.pending.size > 0) this.ensureRetryTimer(dst);
this.logRecoverySend(dst, peer, 'link-replay', true);
return;
}
peer.lastReplayEpoch = this.connEpoch;
peer.lastReplayRemoteStreamId = peer.remoteStreamId;
peer.confirmedGapRepair = null;
// 真正恢复不依赖当时队列是否有积压:abandon / transport-timeout 可能已清空
// pending。首次建链(还没 resume 过)保持原语义,空队列不进探测。
if (resume.enterRecovery) {
peer.recoveryNeedsAck = true;
peer.recoveryFramesSent = 0;
}
this.replayPending(dst, resume.resumedLink);
}
private logRecoverySend(
dst: string,
peer: PeerTransportState,
trigger: 'link-replay',
duplicateOpen: boolean,
): void {
this.log.info(
`device-link recovery dst=${dst.slice(0, 8)} trigger=${trigger}`
+ ` pending=${peer.pending.size}/${peer.pendingBytes}`
+ ` recoveryFrames=${peer.recoveryFramesSent}/${this.recoveryPassBudget()}`
+ ` needsAck=${peer.recoveryNeedsAck} duplicateOpen=${duplicateOpen}`
+ ` stream=${peer.streamId.slice(0, 8)} conn=${this.connEpoch}`,
);
}
private replayPending(dst: string, resumedLink = false): void {
const peer = this.peerTransport.get(dst);
if (!peer || !peer.reliable || !this.isPeerSendReady(peer) || peer.pending.size === 0) return;
// 重放前先丢弃队头连续的可丢弃前缀(push 不分新旧 + skip 占位):重放一旦把
// 它们写进 WebSocket FIFO 就无法撤回,之后的 invoke-result 驱逐救不回已发出
// 的帧,接收端仍会按 seq 顺序先消化整段重放洪峰。丢弃后重放的第一帧就是最
// 早的 live 帧。
this.dropDiscardablePendingPrefix(dst, peer, false, 'before link re-establishment replay');
if (peer.pending.size === 0) return;
if (resumedLink || peer.lastReplayEpoch !== this.connEpoch) {
peer.lastReplayEpoch = this.connEpoch;
for (const pending of peer.pending.values()) resetReliableSendRound(pending);
}
if (peer.recoveryTrace) peer.recoveryTrace.replayThroughSeq = peer.nextSeq - 1;
this.retryPending(dst, { ignoreInterval: true });
this.logRecoveryStage(dst, 'first-replay-pass', ` frames=${peer.recoveryFramesSent}`);
this.ensureRetryTimer(dst);
this.logRecoverySend(dst, peer, 'link-replay', false);
}
/**
* 可靠重试耗尽的**止损分级**:
*
* - 入站接受的 link(本机是被控端,同一条 relay 连接服务多个控制端):只重置
* 该 peer 的 link,不炸整条 relay 连接。v0.1.26 线上:一台休眠 iPhone 的 ACK
* 耗尽单日把整条 relay 连接强拆 38 次,其它 peer(另一台手机 / 飞书 hook)全部
* 陪葬,重连风暴又放大成订阅风暴。重置语义:
* - 收发方向复位 + 停重试计时器;**不清 pending**——live invoke-result 等
* 下次 link-accept 后按原 seq 重放(陈旧 push 前缀由重放前清扫丢弃),
* 不丢在途回包,也不碰 dispatch 层的去重缓存与订阅状态;
* - best-effort 发 link-close(transport-timeout):存活但卡流的对端在
* 接收端按**瞬时重置**处理(不置 explicitlyClosed、不拒在途请求,见
* dispatchEnvelope 的 link-close 分支),并由 app 层立即重建:mobile
* 触发 rehydrate,desktop 控制端重新 openLink;真休眠的对端收不到
* 该帧,唤醒后自会 rehydrate → link-open。
* - 出站发起的 link(本机是控制端):默认维持原语义——整连接重连兼作恢复
* 探测;Mobile 可显式选择 `peerFailurePolicy='isolate-peer'`,改为只复位
* 该 peer 并通知 host 独立 openLink。该路径不发任何新 wire 值,所以目标
* Desktop 无需同步升级。
*/
private handleReliableRetryExhausted(dst: string, seq: number): void {
if (this.stopped || this.status !== 'online') return;
const peer = this.peerTransport.get(dst);
// retry callback 与显式 close/stop 竞态时 peer 可能已经被回收。Mobile 的
// 隔离策略不能把迟到计时器升级成连接级重建;默认策略仍保留历史语义。
if (!peer) {
if (this.opts.peerFailurePolicy !== 'isolate-peer') {
this.forceReconnectForReliableTimeout(dst, seq);
}
return;
}
// 能力门:旧控制端(未声明 transport-timeout-close-v1)把未知 reason 当永久
// 关闭且不会自动重开——relay/presence 保持在线时订阅与在途请求会静默挂死。
// 对这类对端保留整连接重连的兼容恢复路径(presence 闪断触发其既有 rehydrate)。
if (
(!peer.linkAcceptedInbound || !peer.supportsTransportTimeoutClose)
&& this.opts.peerFailurePolicy !== 'isolate-peer'
) {
this.forceReconnectForReliableTimeout(dst, seq);
return;
}
if (this.isRelayWideReliableStall(dst, peer)) {
this.log.warn(
`reliable transport ACK timeout on multiple silent peers; relay connection looks stalled, forcing reconnect`
+ ` ${this.describeReliableTimeout(dst, seq, peer)}`
+ ` peerSilenceMs=${Math.round(this.monotonicNow() - this.lastPeerInboundAt)}`,
);
this.dropRelayConnection('reliable transport stalled on all peers');
return;
}
this.log.warn(
`reliable transport ACK timeout; resetting peer link (relay connection kept alive)`
+ ` ${this.describeReliableTimeout(dst, seq, peer)}`,
);
this.markPeerLinkDown(peer);
this.retryReadRequestsAfterPeerReset(dst, seq);
if (peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
// 已协商瞬时关闭语义的入站控制方向仍通知对端主动重开。Mobile 的纯出站
// 隔离路径不发送 transport-timeout:旧 Desktop 可能把未知 reason 当永久
// 关闭;host 收到本地事件后用所有版本都支持的 link-open 恢复。
if (peer.linkAcceptedInbound && peer.supportsTransportTimeoutClose) {
this.notifyTransportTimeoutClose(dst, 1);
}
// Both directions share this peer state during mutual control. Notify local
// views even when the remote controller owns reopening the inbound link.
this.notifyPeerTransportReset(dst, seq, peer.linkGeneration);
}
/**
* transport-timeout 重置通知的投递与有界重试。
*
* relay 保持在线意味着没有 presence/重连事件可依赖——若本地发送因 WebSocket
* 背压/异常失败就放弃,存活但卡流的对端永远收不到重建信号,保留的 pending
* 会无限停滞。故失败时按 transportRetryIntervalMs 退避重发,上限
* transportMaxRetryAttempts 次;重试回调中任一成立即停:对端已重开
* (发送方向确认 ready,由确认 ACK 取消)、relay 已断开(断线重连路径接管
* 恢复,presence 闪断会触发对端 rehydrate)、client 已 stop。耗尽后放弃本地
* 重试:对端若存活,其后续请求超时/自身重试耗尽会走它自己的恢复路径;若
* 休眠,唤醒重连即重开。两条兜底都不拆共享 relay 连接、不丢保留的 pending。
*/
private notifyTransportTimeoutClose(dst: string, attempt: number): void {
try {
this.sendBestEffortRoutedEnvelope({
v: PROTOCOL_VERSION,
kind: 'link-close',
dst,
payload: { reason: 'transport-timeout' } satisfies LinkClosePayload,
});
this.cancelTimeoutCloseNotify(dst);
} catch (err) {
this.log.debug(
`transport-timeout link-close notification failed for ${dst.slice(0, 8)} (attempt ${attempt})`,
err,
);
if (attempt >= this.timing.transportMaxRetryAttempts) {
this.cancelTimeoutCloseNotify(dst);
return;
}
this.scheduleTimeoutCloseNotifyRetry(dst, attempt + 1);
}
}
private scheduleTimeoutCloseNotifyRetry(dst: string, attempt: number): void {
this.cancelTimeoutCloseNotify(dst);
const timer = setTimeout(() => {
this.timeoutCloseNotifyTimers.delete(dst);
// 发送前全量复验:排期到触发之间状态可能已变(永久关闭、对端重开、
// 能力失效、relay 断开、stop)——任一不满足即终止,不补发迟到的瞬时
// 重置帧(它会诱使对端 rehydrate/reopen 用户已关闭的控制方向)。
if (this.stopped || this.status !== 'online') return;
const peer = this.peerTransport.get(dst);
if (
!peer
|| this.isPeerSendReady(peer) // 对端已确认重开,通知不再需要
|| peer.explicitlyClosed // 已进入永久关闭态
|| !peer.linkAcceptedInbound // 活动入站方向已被撤销
|| !peer.supportsTransportTimeoutClose // 能力已失效(对端降级重声明)
) {
return;
}
this.notifyTransportTimeoutClose(dst, attempt);
}, this.timing.transportRetryIntervalMs);
this.timeoutCloseNotifyTimers.set(dst, timer);
}
private cancelTimeoutCloseNotify(dst: string): void {
const timer = this.timeoutCloseNotifyTimers.get(dst);
if (timer) {
clearTimeout(timer);
this.timeoutCloseNotifyTimers.delete(dst);
}
}
private cancelPendingLinkConfirmation(
dst: string,
peer: PeerTransportState,
restorePreviousSendPhase: boolean,
): void {
const confirmation = peer.pendingLinkConfirmation;
if (!confirmation) return;
if (confirmation.timer) clearTimeout(confirmation.timer);
peer.pendingLinkConfirmation = null;
if (restorePreviousSendPhase && peer.sendPhase === 'awaiting-confirm') {
peer.sendPhase = confirmation.previousSendPhase;
if (peer.sendPhase === 'ready' && peer.pending.size > 0) {
this.ensureRetryTimer(dst);
}
}
}
private forceReconnectForReliableTimeout(dst: string, seq: number): void {
if (this.stopped || this.status !== 'online') return;
const peer = this.peerTransport.get(dst);
this.log.warn(
`reliable transport ACK timeout; forcing reconnect`
+ ` ${this.describeReliableTimeout(dst, seq, peer)}`,
);
this.dropRelayConnection('reliable transport retry exhausted');
}
private dropRelayConnection(reason: string): void {
const ws = this.ws;
this.ws = null;
this.connEpoch++;
closeOrTerminate(ws);
this.handleDisconnect(1006, reason);
}
/**
* 单个 peer 停止 ACK 是该 peer 的故障(手机退后台休眠最常见),默认只复位该 peer。
* 但 relay 连接也可能进入「上行仍通、转发方向卡死」的半僵状态:pong 照常到达,
* heartbeat 判活,所有对端的帧与 ACK 却都到不了(2026-10-05 线上:桌面端对 5 个
* 对端在同一毫秒 ACK 超时,约 80s 后才自行恢复,期间手机持续显示「电脑端未响应」)。
* 此时逐个复位 peer 无济于事,故障在连接层,恢复动作也应在连接层。
*
* 重建连接会打断**每一个**已就绪 peer,所以必须每一个都拿得出卡死证据,判定刻意从严:
* - 自本 peer 队头首发以来,没有收到**任何**对端转发来的帧(含 ACK);
* - 其余每个已就绪 peer 都有队头,且同样首发后无任何对端入站、已经历过多轮重发;
* - 这样的其余 peer 至少一个(单 peer 时无从区分对端休眠与连接卡死)。
* 任一已就绪 peer 缺少证据(空闲无待确认帧,或正在正常 ACK)时,仍只复位本 peer:
* 两台手机同时休眠时,空闲但健康的第三个 peer 不会被连带断链。入站方向仍活动的
* 旧版(非可靠传输)控制端无从取证,同样按缺少证据处理。
*/
private isRelayWideReliableStall(dst: string, peer: PeerTransportState): boolean {
// 与首发同一时刻到达的入站帧不可能是对它的应答,所以取 <=。
// 经直连发出的队头不能证明 relay 卡住:它的应答不经 relay,沉默只说明直连有问题。
const silentSince = (head: PendingReliableMessage | undefined): boolean => (
head?.sent === true
&& head.path !== 'direct'
&& head.firstSentAt !== undefined
&& this.lastPeerInboundAt <= head.firstSentAt
);
const ownHead = peer.pending.values().next().value as PendingReliableMessage | undefined;
if (!silentSince(ownHead)) return false;
const minAttempts = Math.min(3, this.timing.transportMaxRetryAttempts);
let stalledOthers = 0;
for (const [otherId, other] of this.peerTransport) {
if (otherId === dst) continue;
// 未协商可靠传输的旧控制端没有队头可供取证;只要其入站控制方向仍活动,
// 就视为缺少卡死证据,不得被整连接重建连带断开。
if (!other.reliable) {
if (other.linkAcceptedInbound) return false;
continue;
}
if (!this.isPeerSendReady(other)) continue;
const head = other.pending.values().next().value as PendingReliableMessage | undefined;
if (!silentSince(head) || head!.attempts < minAttempts) return false;
stalledOthers += 1;
}
return stalledOthers > 0;
}
/**
* Final timeout evidence only: no payload or full device identifiers. This
* separates "ACK never advanced" from an ACK send exception and records the
* exact peer/link phase without adding a warning on every 2s retry tick.
*/
private describeReliableTimeout(
dst: string,
seq: number,
peer: PeerTransportState | undefined,
): string {
if (!peer) {
return `dst=${dst.slice(0, 8)} seq=${seq} peer=missing conn=${this.connEpoch}`;
}
const pending = peer.pending.get(seq)
?? (peer.pending.values().next().value as PendingReliableMessage | undefined);
const ageMs = pending
? Math.max(0, Math.round(this.monotonicNow() - pending.enqueuedAt))
: -1;
const rawChannel = (pending?.envelope.payload as { channel?: unknown } | undefined)?.channel;
const channel = typeof rawChannel === 'string'
&& (PUSH_FORWARD_ALLOWLIST.has(rawChannel) || REMOTE_INVOKE_ALLOWLIST.has(rawChannel))
? rawChannel : 'unknown';
return `dst=${dst.slice(0, 8)} seq=${seq}`
+ ` kind=${pending?.envelope.kind ?? 'missing'}`
+ ` channel=${channel}`
+ ` request=${pending?.envelope.id?.slice(0, 8) ?? 'none'}`
+ ` attempts=${pending?.attempts ?? -1} sent=${pending?.sent ?? false} ageMs=${ageMs}`
+ ` pending=${peer.pending.size}/${peer.pendingBytes}`
+ ` ack=${peer.highestAckSeq} next=${peer.nextSeq}`
+ ` send=${peer.sendPhase} receive=${peer.receiveReady}`
+ ` stream=${peer.streamId.slice(0, 8)}`
+ ` remoteStream=${peer.remoteStreamId?.slice(0, 8) ?? 'none'}`
+ ` recovery=${peer.recoveryNeedsAck}/${peer.recoveryFramesSent}`
+ ` conn=${this.connEpoch}`;
}
private abandonReliablePending(dst: string, message: string): void {
this.invokeScheduler.cancel(dst, new DeviceLinkError('NOT_CONNECTED', message));
const peer = this.peerTransport.get(dst);
if (peer) {
if (peer.retryTimer) {
clearInterval(peer.retryTimer);
peer.retryTimer = null;
}
for (const pending of peer.pending.values()) {
if (pending.envelope.id) {
this.settleOutboundRouteAttemptsForId(dst, pending.envelope.id);
}
}
peer.pending.clear();
peer.pendingBytes = 0;
}
const err = new DeviceLinkError('NOT_CONNECTED', message);
for (const [id, pending] of this.pending) {
if (pending.reliableDst !== dst) continue;
this.pending.delete(id);
pending.reject(err);
}
}
private rejectPendingLinkOpen(
dst: string,
code: 'LINK_NOT_OPEN' | 'ACCESS_REVOKED',
message: string,
): void {
for (const [id, pending] of this.pending) {
if (pending.expectKind !== 'link-accept' || pending.dst !== dst) continue;
this.pending.delete(id);
this.settleOutboundRouteAttemptsForId(dst, id);
pending.reject(new DeviceLinkError(code, message));
}
}
private clearPeerTransport(): void {
this.directNegotiator?.clear();
this.directPeerSupport.clear();
for (const id of this.providerShareDirectLeases.keys()) this.clearProviderShareDirectLease(id);
this.providerShareLocalAddresses.clear();
this.opts.directRuntime?.suspend?.();
for (const peer of this.peerTransport.values()) {
if (peer.retryTimer) clearInterval(peer.retryTimer);
if (peer.pendingLinkConfirmation?.timer) clearTimeout(peer.pendingLinkConfirmation.timer);
if (peer.outboundLinkConfirmationAck?.timer) {
clearTimeout(peer.outboundLinkConfirmationAck.timer);
}
}
this.peerTransport.clear();
this.peerOfflineNotifiedGeneration.clear();
this.outboundRouteGenerationByPeer.clear();
this.settledOutboundRouteGenerationByPeer.clear();
this.providerShareSignalRouteIds.clear();
for (const timer of this.timeoutCloseNotifyTimers.values()) clearTimeout(timer);
this.timeoutCloseNotifyTimers.clear();
}
private rememberInboundLinkOffer(src: string, offer: PendingInboundLinkOffer): void {
this.pendingInboundLinkOffers.delete(src);
this.pendingInboundLinkOffers.set(src, offer);
while (this.pendingInboundLinkOffers.size > MAX_PENDING_INBOUND_LINK_OFFERS) {
const oldest = this.pendingInboundLinkOffers.keys().next().value as string | undefined;
if (!oldest) break;
this.pendingInboundLinkOffers.delete(oldest);
}
}
private setConnectionIssue(issue: DeviceLinkConnectionIssue | null): void {
const prev = this.connectionIssue;
if (prev === issue) return;
if (prev && issue && prev.kind === issue.kind) {
// 同类问题重复发生(401 每轮重连都触发):静默更新详情,不重复打扰订阅者
this.connectionIssue = issue;
return;
}
this.connectionIssue = issue;
for (const cb of this.issueHandlers) {
try {
cb(issue);
} catch (err) {
this.log.error('connection issue handler threw', err);
}
}
}
private setStatus(s: DeviceLinkStatus): void {
if (this.status === s) return;
this.status = s;
for (const cb of this.statusHandlers) {
try {
cb(s);
} catch (err) {
this.log.error('status handler threw', err);
}
}
}
/**
* 普通网络切换不应打扰用户;连续多次「连上就掉」才暴露 unstable。
* 主动 stop 不经过这里,具体的鉴权/顶号/版本问题会在调用方随后覆盖本分类。
*/
private trackShortLivedConnection(
onlineForMs: number | null,
code?: number,
reason?: string,
): void {
if (this.stopped || onlineForMs === null) return;
if (onlineForMs >= this.timing.reconnectStableResetMs) {
this.shortLivedStreak = 0;
return;
}
this.shortLivedStreak++;
if (this.shortLivedStreak < SHORT_LIVED_STREAK_LIMIT) return;
this.log.warn(
`device-link keeps dropping after handshake (${this.shortLivedStreak} in a row, lastOnlineForMs=${onlineForMs}, code=${
code ?? 'n/a'
})`,
);
this.setConnectionIssue({
kind: 'unstable',
closeCode: code,
detail: `${this.shortLivedStreak} short-lived connections; last ${onlineForMs}ms${
reason ? ` (${reason})` : ''
}`,
at: Date.now(),
});
}
private armReconnectStableReset(): void {
if (this.reconnectStableTimer) clearTimeout(this.reconnectStableTimer);
this.reconnectStableTimer = setTimeout(() => {
this.reconnectStableTimer = null;
if (this.stopped || this.status !== 'online') return;
this.reconnectAttempt = 0;
this.shortLivedStreak = 0;
if (this.connectionIssue?.kind === 'unstable') this.setConnectionIssue(null);
}, this.timing.reconnectStableResetMs);
}
private armCongestionStableReset(): void {
if (this.congestionStableTimer) clearTimeout(this.congestionStableTimer);
if (this.congestionCloseStreak <= 0) {
this.congestionStableTimer = null;
return;
}
this.congestionStableTimer = setTimeout(() => {
this.congestionStableTimer = null;
if (this.stopped || this.status !== 'online') return;
this.congestionCloseStreak = 0;
}, normalizeCongestionStableResetMs(this.timing.congestionStableResetMs));
}
}
function closeReasonToString(reason: unknown): string {
if (!reason) return '';
if (typeof reason === 'string') return reason;
const text = String(reason);
return text === '[object Object]' ? '' : text;
}
const DEVICE_LINK_ENVELOPE_KINDS: ReadonlySet<string> = new Set([
'hello',
'hello-ack',
'presence-set',
'presence-changed',
'ping',
'pong',
'notify',
'link-open',
'link-accept',
'link-close',
'invoke',
'invoke-result',
'push',
'relay-error',
]);
function isKnownInboundEnvelope(value: unknown): value is Envelope {
if (!isRecord(value) || value.v !== PROTOCOL_VERSION || typeof value.kind !== 'string') {
return false;
}
return DEVICE_LINK_ENVELOPE_KINDS.has(value.kind);
}
/**
* 入站帧的轻量 heartbeat 活性校验。它不复制完整隧道协议 validator,只拦截会让
* heartbeat 误判为“仍有流量”的明显坏帧;业务分发仍由各自 handler 负责。
*/
function isValidInboundEnvelope(value: Envelope): boolean {
const payload = value.payload;
// 可靠传输帧把原业务 payload 包在 transport marker/data 中;该形状由
// parseTransportPayload 负责完整校验,不能再按 legacy channel/payload 解释。
if (isReliableKind(value.kind)) {
const parsed = parseTransportPayload(payload);
if (parsed !== null) {
if (value.kind !== 'invoke') return true;
// reliable invoke 仍要有 relay 注入的源设备和请求 id;缺任一项时
// ingestTransportEnvelope / Desktop dispatch 都无法把它当作可处理请求。
// 这类帧不能仅凭内层 channel/args 把坏连接喂活。
if (
typeof value.src !== 'string'
|| value.src.length === 0
|| typeof value.id !== 'string'
|| value.id.length === 0
) return false;
// 分片的 data 只是完整 JSON 文本的一段,不能在此处单独解析;transport
// 元数据已经证明 relay/socket 正在工作,重组后的完整 payload 再由接收
// 状态机做 JSON 与业务分发校验。
if (parsed.meta.segment) return true;
try {
const inner = decodeTransportJson(parsed.data);
return isRecord(inner)
&& typeof inner.channel === 'string'
&& Array.isArray(inner.args);
} catch {
return false;
}
}
}
// `isReliableKind` above narrows the union on its non-transport fallback path;
// switch on the wire string here so legacy invoke/push/result payloads remain
// eligible for their existing business-layer validation.
switch (value.kind as string) {
case 'ping':
case 'pong':
return payload === undefined || payload === null;
case 'hello-ack':
return isRecord(payload)
&& typeof payload.serverProtocolVersion === 'number'
&& Number.isFinite(payload.serverProtocolVersion)
&& typeof payload.deviceId === 'string'
&& payload.deviceId.length > 0
&& typeof payload.userId === 'string'
&& payload.userId.length > 0;
case 'presence-changed':
return isRecord(payload)
&& typeof payload.deviceId === 'string'
&& payload.deviceId.length > 0
&& typeof payload.online === 'boolean';
case 'relay-error':
return isRecord(payload)
&& typeof payload.code === 'string'
&& typeof payload.message === 'string';
case 'invoke':
// Desktop dispatch requires relay-injected src + request id before it can
// deliver an invoke. A legacy-looking frame without either identifier is
// therefore not usable inbound activity and must not keep a dead socket online.
return typeof value.src === 'string'
&& value.src.length > 0
&& typeof value.id === 'string'
&& value.id.length > 0
&& isRecord(payload)
&& typeof payload.channel === 'string'
&& Array.isArray(payload.args);
case 'invoke-result':
if (!isRecord(payload) || typeof payload.ok !== 'boolean') return false;
if (payload.ok) return true;
return isRecord(payload.error)
&& typeof payload.error.code === 'string'
&& typeof payload.error.message === 'string';
case 'push':
return isRecord(payload)
&& typeof payload.channel === 'string'
&& Object.prototype.hasOwnProperty.call(payload, 'payload');
case 'link-open':
return isRecord(payload)
&& typeof payload.controllerName === 'string'
&& typeof payload.protocolVersion === 'number'
&& Number.isFinite(payload.protocolVersion)
&& typeof payload.appVersion === 'string';
case 'link-accept':
return isRecord(payload)
&& typeof payload.appVersion === 'string'
&& typeof payload.allowlistHash === 'string';
case 'link-close':
return isRecord(payload) && typeof payload.reason === 'string';
case 'presence-set':
return isRecord(payload)
&& (payload.remoteControlEnabled === undefined
|| typeof payload.remoteControlEnabled === 'boolean')
&& (payload.busy === undefined || typeof payload.busy === 'boolean');
case 'notify':
return isRecord(payload)
&& typeof payload.category === 'string'
&& typeof payload.title === 'string'
&& typeof payload.deepLink === 'string'
&& typeof payload.collapseId === 'string';
case 'hello':
return isRecord(payload);
default:
return false;
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === 'object' && value !== null && !Array.isArray(value);
}
/**
* Start a new send round. firstSentAt belongs to the round: a message the peer
* acknowledges before it is written again in this round (ACK lost across a
* reconnect) must not turn the offline gap into an RTT sample.
*/
function resetReliableSendRound(pending: PendingReliableMessage): void {
pending.attempts = 0;
pending.lastSentAt = 0;
pending.firstSentAt = undefined;
}
function isReliableKind(kind: Envelope['kind']): kind is 'invoke' | 'invoke-result' | 'push' {
return kind === 'invoke' || kind === 'invoke-result' || kind === 'push';
}
/**
* 这些调用属于 listing/control tier,不需要 streaming link-open。
* 显式 closeLink() 只应撤掉可靠 streaming 层;列表刷新、能力探针、词典
* 快照和 topic 订阅仍要沿用旧 envelope 路径,兼容 link-open 之前的既有语义。
*/
const UNLINKED_LEGACY_INVOKE_CHANNELS = new Set([
'device-link:subscribe',
'device-link:unsubscribe',
'device-link:voice:dictionary:get',
'maker:provider:list',
'maker:get-capabilities',
'maker:get-new-maker-defaults',
'maker:list-active',
'maker:list-available-agents',
'maker:list-agent-commands',
'maker:list-agent-skills',
'local-db:sessions:list',
'local-db:sessions:get',
'local-db:history:messages',
'local-db:messages:list',
'local-db:messages:view',
'local-db:messages:work-details',
'local-db:messages:view-intent',
'local-db:messages:around',
'local-db:messages:around-client-id',
'local-db:messages:estimatedSessionValue',
'local-db:recent-workdirs:list',
'local-db:sessions:interrupted-pending',
'maker:git-safety:get',
]);
const UNLINKED_LEGACY_PUSH_CHANNELS = new Set([
// Same-account encrypted sync does not require an open remote-control link.
// The Desktop plugin-sync receiver still checks owner, revocation and capability.
PLUGIN_SYNC_CHANNEL,
'device-link:voice:dictionary:snapshot',
]);
function isUnlinkedLegacyEnvelope(env: Envelope): boolean {
const payload = env.payload as { channel?: unknown } | undefined;
if (typeof payload?.channel !== 'string') return false;
if (env.kind === 'invoke') return UNLINKED_LEGACY_INVOKE_CHANNELS.has(payload.channel);
if (env.kind === 'push') return UNLINKED_LEGACY_PUSH_CHANNELS.has(payload.channel);
return false;
}
function isLegacyBusinessFrame(kind: Envelope['kind']): boolean {
return (
kind === 'invoke'
|| kind === 'push'
|| kind === 'link-open'
|| kind === 'link-close'
);
}
function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
return (
typeof value === 'object'
&& value !== null
&& 'then' in value
&& typeof (value as { then?: unknown }).then === 'function'
);
}
/** 立即回收 socket:优先 terminate(硬断);无 terminate 实现(RN WebSocket)时退回 close。 */
function closeOrTerminate(ws: WsLike | null): void {
if (!ws) return;
try {
if (ws.terminate) ws.terminate();
else ws.close();
} catch {
// 已断开的 socket 上 close/terminate 可能抛,忽略
}
}
/** 给 promise 加超时上限;超时后 reject,原 promise 的最终结果被忽略。 */
function withTimeout<T>(p: Promise<T>, ms: number, message: string): Promise<T> {
return new Promise<T>((resolve, reject) => {
const timer = setTimeout(() => reject(new Error(message)), ms);
p.then(
(v) => {
clearTimeout(timer);
resolve(v);
},
(err) => {
clearTimeout(timer);
reject(err);
},
);
});
}