im-rtc-call-engine 1.0.0

package/dist/signaling/resumeDeadline.js

@@ -0,0 +1,89 @@
+import { logger } from '../logger.js';
+/** 协议 §1.4 的恢复窗口：30 秒。**四端同一个值**，服务端的 `ResumeWindow` 也是它。 */
+export const RESUME_WINDOW_SEC = 30;
+/** 服务端判一条连接死掉要连续几个心跳周期收不到东西（§1.3）。 */
+export const SERVER_DEATH_PINGS = 3;
+/** 余量：跨过服务端窗口到期那一刻再收场，别跟它抢同一秒。 */
+export const GIVE_UP_GRACE_SEC = 5;
+/*
+ 断开多久之后可以断定「服务端那一侧的会话没了」。
+
+ # 为什么不是恢复窗口那 30 秒
+
+ 服务端的 30 秒**不是从我们断开的那一刻算起的**，是从**它自己察觉**的那一刻算起。
+ 而它靠读超时察觉：连续 3 个心跳周期收不到任何东西才判死（§1.3）。
+ 我们断开时距离上一帧最多一个心跳周期，所以最晚的到期时刻是
+ `断开 + 3×ping + 30s`——按默认 15 秒心跳就是 45 + 30 = 75 秒，再加一点余量。
+
+ # 为什么必须取上界
+
+ 取短了就会撒谎：真机 2026-09-08 实测，断开 14 秒后重连**成功恢复**，通话好端端地继续。
+ 在那之前宣布「通话已结束」是把一通还能救回来的电话杀掉，而且服务端还认为我们在房里，
+ 房间会挂着一个幽灵成员。**宁可让用户多看几十秒「正在重连」，也不能提前下结论。**
+ */
+export function giveUpDelayMs(pingIntervalSec) {
+    return (SERVER_DEATH_PINGS * pingIntervalSec + RESUME_WINDOW_SEC + GIVE_UP_GRACE_SEC) * 1000;
+}
+/**
+ * 「服务端已经彻底放弃这条会话」的倒计时（协议 §1.4）。
+ *
+ * # 为什么需要它
+ *
+ * 客户端本地放弃的唯一入口原本是「重连上了但 `resumed=false`」——**它要求先连回来**。
+ * 网络一直不回来的话那一刻永远不会到，界面就永远停在「正在重连」，
+ * 而且**连挂断都点不动**（挂断只产出一帧发不出去的 `call.hangup`，
+ * 本地状态按 §4.2 铁律 1 一动不动）。真机 2026-09-08 的 iOS 端就是这一幕。
+ *
+ * # 从 Connection 里拆出来
+ *
+ * 和 `Reconnector` 同一个理由：体量红线（CONVENTIONS §2），
+ * 也让「什么时候该放弃」这条规则有独立的测试面。
+ */
+export class ResumeDeadline {
+    onUnrecoverable;
+    timer = null;
+    pingIntervalSec = 15;
+    constructor(onUnrecoverable) {
+        this.onUnrecoverable = onUnrecoverable;
+    }
+    /**
+     * 握手成功：撤掉倒计时，并记下服务端给的心跳周期（上界要拿它推算）。
+     *
+     * **不管 `resumed` 是真是假都要撤** —— 服务端已经给出裁决，
+     * `resumed=false` 那条自有 `handleHelloOk` 去收场，不该再由倒计时补一刀。
+     */
+    connected(pingIntervalSec) {
+        this.cancel();
+        this.pingIntervalSec = pingIntervalSec;
+    }
+    /**
+     * 起倒计时。
+     *
+     * **只在第一次断开时起**：每一次重连失败都会走到调用点，每次都重排的话
+     * 截止时刻就一直往后挪、永远不会到——而那正是它要治的病。
+     * 起点是第一次断开的那一刻，与服务端算的是同一笔账。
+     */
+    arm() {
+        if (this.timer !== null)
+            return;
+        const delayMs = giveUpDelayMs(this.pingIntervalSec);
+        logger.info('恢复窗口倒计时已起', { delayMs });
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            logger.warn('断开已超过恢复窗口，会话不可恢复', {});
+            this.onUnrecoverable();
+        }, delayMs);
+    }
+    /** 撤销。连上了、或宿主 logout 了都要调。幂等。 */
+    cancel() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+    /** armed 供测试与诊断观察。 */
+    get armed() {
+        return this.timer !== null;
+    }
+}
+//# sourceMappingURL=resumeDeadline.js.map

package/dist/signaling/resumeDeadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumeDeadline.js","sourceRoot":"","sources":["../../src/signaling/resumeDeadline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtC,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,sCAAsC;AACtC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,kCAAkC;AAClC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAEnC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAAC,eAAuB;IACnD,OAAO,CAAC,kBAAkB,GAAG,eAAe,GAAG,iBAAiB,GAAG,iBAAiB,CAAC,GAAG,IAAI,CAAC;AAC/F,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IAII;IAHrB,KAAK,GAAyC,IAAI,CAAC;IACnD,eAAe,GAAG,EAAE,CAAC;IAE7B,YAA6B,eAA2B;QAA3B,oBAAe,GAAf,eAAe,CAAY;IAAG,CAAC;IAE5D;;;;;OAKG;IACH,SAAS,CAAC,eAAuB;QAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED;;;;;;OAMG;IACH,GAAG;QACD,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO;QAChC,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;YACpC,IAAI,CAAC,eAAe,EAAE,CAAC;QACzB,CAAC,EAAE,OAAO,CAAC,CAAC;IACd,CAAC;IAED,iCAAiC;IACjC,MAAM;QACJ,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,sBAAsB;IACtB,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/dist/signaling/tokenExpiry.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 接入票到期前的主动换票定时器。
+ *
+ * # 为什么需要它
+ *
+ * 服务端只在 `sys.hello` 握手时验一次票，之后永不复查。所以票过期**不会**断开已建立的
+ * 连接——真正出问题的时刻是**过期之后的第一次重连**：那一次握手撞上 `4401`，
+ * 按退避档重试三次，然后 `kickedOut`，用户被踢回登录页。
+ *
+ * 而这条路径是**被动**的：用户先经历一次掉线加三轮重试，宿主才知道要换票。
+ * 有了 `sys.hello.ok` 下发的 `token_expires_at_ms`，我们可以在到期**前**提醒宿主，
+ * 让它静默换票，用户全程无感。
+ *
+ * 见 im-rtc-server/docs/design/TOKEN_LIFECYCLE_DESIGN.md §6-①②。
+ *
+ * # 为什么单独一个模块
+ *
+ * 它是纯逻辑（时刻计算 + 一个定时器），可以脱离 WebSocket 直接单测；
+ * 而 connection.ts 已经贴着 400 行的体量红线（CONVENTIONS §2）。
+ */
+/** TimerHandle 是宿主环境的定时器句柄。Node 与浏览器的类型不同，这里不关心具体是什么。 */
+export type TimerHandle = ReturnType<typeof setTimeout>;
+/**
+ * DEFAULT_LEAD_MS 是提前量：到期前多久提醒宿主换票。
+ *
+ * 60 秒的依据是「够宿主打一次自家后台的换票接口，且不至于早到让宿主觉得莫名其妙」。
+ * 比这个再短的话，一次慢请求就跨过了到期时刻。
+ */
+export declare const DEFAULT_LEAD_MS = 60000;
+/**
+ * MAX_TIMER_DELAY_MS 是 `setTimeout` 延时的 32 位上限（2^31-1 ≈ 24.8 天）。
+ *
+ * 超过它的值不会「等很久」，而是**立刻触发**——长有效期的票会因此每次握手都误报一次。
+ * 见 {@link TokenExpiryTimer.armStep}。
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** TokenExpiryOptions 是构造参数。带 Fn 的都是为了测试可注入。 */
+export interface TokenExpiryOptions {
+    /** 到期前多久触发。默认 {@link DEFAULT_LEAD_MS}。 */
+    leadMs?: number;
+    /** 触发时调它。**同一张票只会触发一次**。 */
+    onWillExpire: (info: {
+        expiresAtMs: number;
+    }) => void;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => TimerHandle;
+    clearTimer?: (handle: TimerHandle) => void;
+}
+/**
+ * TokenExpiryTimer 盯着当前这张票的到期时刻，在到期前触发一次提醒。
+ *
+ * 生命周期：每次握手成功 `arm(hello.tokenExpiresAtMs)`；宿主换票后
+ * `arm(newExpiresAtMs)` 重新武装；连接关闭 `disarm()`。
+ */
+export declare class TokenExpiryTimer {
+    private handle;
+    private readonly leadMs;
+    private readonly onWillExpire;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    constructor(options: TokenExpiryOptions);
+    /**
+     * arm 按新的到期时刻重新武装。
+     *
+     * - `expiresAtMs <= 0` = 服务端说「未知」（协议 §1.2）→ **解除武装，不报错**。
+     *   这条路径退化成打这个补丁之前的被动行为，是刻意的降级而不是故障。
+     * - 已经进入提前量窗口（含已过期）→ **立刻触发一次**，而不是静默跳过。
+     *   票只剩 10 秒时更需要提醒宿主，不是更不需要。
+     */
+    arm(expiresAtMs: number): void;
+    /**
+     * armStep 排一段定时；**超过 32 位上限就先睡满一段再续排**。
+     *
+     * `setTimeout` 的延时是 32 位有符号整数：传超过 2^31-1 ms（约 24.8 天）的值，
+     * 浏览器与 Node 都会**溢出成立刻触发**。一枚有效期 30 天的票算出来的延时正好越界，
+     * 于是每次握手成功都马上抛一条 `tokenWillExpire`——宿主老老实实去后台换一次票，
+     * 下次重连再来一遍，而真正该在到期前 60 秒响的那一次**反而没有了**。
+     *
+     * 分段续排比钳到上限对：钳完就在第 24.8 天误报，而分段是「睡满一段，醒来重算」，
+     * 剩多久算多久。（iOS 的 Int64 毫秒、Android 的 Long 都没有这个坎，只有 JS 有。）
+     */
+    private armStep;
+    /** disarm 解除武装。重复调用安全。 */
+    disarm(): void;
+    /** isArmed 供测试与自检用。 */
+    get isArmed(): boolean;
+}
+//# sourceMappingURL=tokenExpiry.d.ts.map

package/dist/signaling/tokenExpiry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenExpiry.d.ts","sourceRoot":"","sources":["../../src/signaling/tokenExpiry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAEhD,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,YAAY,EAAE,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACtD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAC;IACvD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CAC5C;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0C;IACvE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IACvE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;gBAE/C,OAAO,EAAE,kBAAkB;IAQvC;;;;;;;OAOG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAM9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO;IAef,0BAA0B;IAC1B,MAAM,IAAI,IAAI;IAMd,uBAAuB;IACvB,IAAI,OAAO,IAAI,OAAO,CAErB;CACF"}

package/dist/signaling/tokenExpiry.js

@@ -0,0 +1,106 @@
+/**
+ * 接入票到期前的主动换票定时器。
+ *
+ * # 为什么需要它
+ *
+ * 服务端只在 `sys.hello` 握手时验一次票，之后永不复查。所以票过期**不会**断开已建立的
+ * 连接——真正出问题的时刻是**过期之后的第一次重连**：那一次握手撞上 `4401`，
+ * 按退避档重试三次，然后 `kickedOut`，用户被踢回登录页。
+ *
+ * 而这条路径是**被动**的：用户先经历一次掉线加三轮重试，宿主才知道要换票。
+ * 有了 `sys.hello.ok` 下发的 `token_expires_at_ms`，我们可以在到期**前**提醒宿主，
+ * 让它静默换票，用户全程无感。
+ *
+ * 见 im-rtc-server/docs/design/TOKEN_LIFECYCLE_DESIGN.md §6-①②。
+ *
+ * # 为什么单独一个模块
+ *
+ * 它是纯逻辑（时刻计算 + 一个定时器），可以脱离 WebSocket 直接单测；
+ * 而 connection.ts 已经贴着 400 行的体量红线（CONVENTIONS §2）。
+ */
+/**
+ * DEFAULT_LEAD_MS 是提前量：到期前多久提醒宿主换票。
+ *
+ * 60 秒的依据是「够宿主打一次自家后台的换票接口，且不至于早到让宿主觉得莫名其妙」。
+ * 比这个再短的话，一次慢请求就跨过了到期时刻。
+ */
+export const DEFAULT_LEAD_MS = 60_000;
+/**
+ * MAX_TIMER_DELAY_MS 是 `setTimeout` 延时的 32 位上限（2^31-1 ≈ 24.8 天）。
+ *
+ * 超过它的值不会「等很久」，而是**立刻触发**——长有效期的票会因此每次握手都误报一次。
+ * 见 {@link TokenExpiryTimer.armStep}。
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * TokenExpiryTimer 盯着当前这张票的到期时刻，在到期前触发一次提醒。
+ *
+ * 生命周期：每次握手成功 `arm(hello.tokenExpiresAtMs)`；宿主换票后
+ * `arm(newExpiresAtMs)` 重新武装；连接关闭 `disarm()`。
+ */
+export class TokenExpiryTimer {
+    handle = null;
+    leadMs;
+    onWillExpire;
+    now;
+    setTimer;
+    clearTimer;
+    constructor(options) {
+        this.leadMs = options.leadMs ?? DEFAULT_LEAD_MS;
+        this.onWillExpire = options.onWillExpire;
+        this.now = options.now ?? (() => Date.now());
+        this.setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    }
+    /**
+     * arm 按新的到期时刻重新武装。
+     *
+     * - `expiresAtMs <= 0` = 服务端说「未知」（协议 §1.2）→ **解除武装，不报错**。
+     *   这条路径退化成打这个补丁之前的被动行为，是刻意的降级而不是故障。
+     * - 已经进入提前量窗口（含已过期）→ **立刻触发一次**，而不是静默跳过。
+     *   票只剩 10 秒时更需要提醒宿主，不是更不需要。
+     */
+    arm(expiresAtMs) {
+        this.disarm();
+        if (expiresAtMs <= 0)
+            return;
+        this.armStep(expiresAtMs);
+    }
+    /**
+     * armStep 排一段定时；**超过 32 位上限就先睡满一段再续排**。
+     *
+     * `setTimeout` 的延时是 32 位有符号整数：传超过 2^31-1 ms（约 24.8 天）的值，
+     * 浏览器与 Node 都会**溢出成立刻触发**。一枚有效期 30 天的票算出来的延时正好越界，
+     * 于是每次握手成功都马上抛一条 `tokenWillExpire`——宿主老老实实去后台换一次票，
+     * 下次重连再来一遍，而真正该在到期前 60 秒响的那一次**反而没有了**。
+     *
+     * 分段续排比钳到上限对：钳完就在第 24.8 天误报，而分段是「睡满一段，醒来重算」，
+     * 剩多久算多久。（iOS 的 Int64 毫秒、Android 的 Long 都没有这个坎，只有 JS 有。）
+     */
+    armStep(expiresAtMs) {
+        const remaining = expiresAtMs - this.leadMs - this.now();
+        const delay = Math.min(Math.max(0, remaining), MAX_TIMER_DELAY_MS);
+        // 用 setTimer(…, 0) 而不是同步调用：arm 是在握手成功的路径上调的，
+        // 同步回调会让宿主的 updateToken 重入到还没走完的连接流程里。
+        this.handle = this.setTimer(() => {
+            this.handle = null;
+            if (remaining > MAX_TIMER_DELAY_MS) {
+                this.armStep(expiresAtMs);
+                return;
+            }
+            this.onWillExpire({ expiresAtMs });
+        }, delay);
+    }
+    /** disarm 解除武装。重复调用安全。 */
+    disarm() {
+        if (this.handle === null)
+            return;
+        this.clearTimer(this.handle);
+        this.handle = null;
+    }
+    /** isArmed 供测试与自检用。 */
+    get isArmed() {
+        return this.handle !== null;
+    }
+}
+//# sourceMappingURL=tokenExpiry.js.map

package/dist/signaling/tokenExpiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenExpiry.js","sourceRoot":"","sources":["../../src/signaling/tokenExpiry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAahD;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,GAAuB,IAAI,CAAC;IACzB,MAAM,CAAS;IACf,YAAY,CAA0C;IACtD,GAAG,CAAe;IAClB,QAAQ,CAA8C;IACtD,UAAU,CAAgC;IAE3D,YAAY,OAA2B;QACrC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC;QAChD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;QACzC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAW,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACrD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAe,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAClF,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,CAAC,CAAC,MAAM,EAAQ,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAAC,WAAmB;QACrB,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO;QAC7B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;OAUG;IACK,OAAO,CAAC,WAAmB;QACjC,MAAM,SAAS,GAAG,WAAW,GAAG,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,kBAAkB,CAAC,CAAC;QACnE,6CAA6C;QAC7C,uCAAuC;QACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;YAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,SAAS,GAAG,kBAAkB,EAAE,CAAC;gBACnC,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;gBAC1B,OAAO;YACT,CAAC;YACD,IAAI,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QACrC,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAED,0BAA0B;IAC1B,MAAM;QACJ,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO;QACjC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,uBAAuB;IACvB,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;IAC9B,CAAC;CACF"}

package/dist/signaling/webSocket.d.ts

@@ -0,0 +1,59 @@
+/**
+ * WebSocket 的最小接口。
+ *
+ * engine **必须能在无 DOM 的环境构造**（CONVENTIONS §1）——一致性向量与时序测试
+ * 都跑在 Node 里。所以这里只声明用得到的那几个成员，测试注入假实现，
+ * 浏览器里注入原生 WebSocket。
+ */
+/** WebSocketLike 是 engine 用到的 WebSocket 子集。 */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    readyState: number;
+    onopen: (() => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+}
+/** WebSocketFactory 按 URL 造一条连接。 */
+export type WebSocketFactory = (url: string) => WebSocketLike;
+/** WS_OPEN 是 WebSocket.OPEN 的值，避免在无 DOM 环境引用全局常量。 */
+export declare const WS_OPEN = 1;
+/** CloseCode 是协议约定的 WS 关闭码（RTC_PROTOCOL.md §1.5）。 */
+export declare const CloseCode: {
+    /** 正常关闭。**我们自己 logout 时发的就是它**；别人发过来的不算数，见 shouldReconnect。 */
+    readonly normal: 1000;
+    /** 服务端下线/重启。立即重连。 */
+    readonly goingAway: 1001;
+    /** 信封非法/帧超长/协议版本不支持。**不重连**，属实现 bug。 */
+    readonly badProtocol: 4400;
+    /** 未鉴权/鉴权超时/token 无效。换新 token 后重连。 */
+    readonly unauthorized: 4401;
+    /** 被踢（同 uid 同 device_id 在别处登录）。**不重连**。 */
+    readonly kickedOut: 4403;
+    /** 频率超限。退避加倍后重连。 */
+    readonly rateLimited: 4429;
+};
+/**
+ * shouldReconnect 按关闭码判断要不要重连。
+ *
+ * 4400 与 4403 **绝不重连**：前者是我们自己的实现 bug，重连只会再撞一次；
+ * 后者是被踢，重连等于跟另一台设备打架。
+ *
+ * **1000 不在这张表里**——「是不是我们自己要走的」看的是意图，不是关闭码。
+ * `close()` 会先把 state 置成 `closed`，`connection.ts` 那句
+ * `this.state !== 'closed'` 已经把 logout 挡住了；再按码挡一次，挡掉的只剩
+ * **别人发过来的 1000**：浏览器掐掉后台标签页的连接、代理/系统休眠断链，
+ * 用的都是这个码。服务端从不主动发 1000（重启走 1001 goingAway），
+ * 所以这里收到的 1000 一定不是「对面让我别回来了」。
+ * 症状是一个后台标签页显示「连接已断开（1000），不会自动回」，必须手动刷新。
+ */
+export declare function shouldReconnect(code: number): boolean;
+/** browserWebSocketFactory 是浏览器环境的默认工厂。 */
+export declare const browserWebSocketFactory: WebSocketFactory;
+//# sourceMappingURL=webSocket.d.ts.map

package/dist/signaling/webSocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSocket.d.ts","sourceRoot":"","sources":["../../src/signaling/webSocket.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,oCAAoC;AACpC,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;AAE9D,qDAAqD;AACrD,eAAO,MAAM,OAAO,IAAI,CAAC;AAEzB,qDAAqD;AACrD,eAAO,MAAM,SAAS;IACpB,+DAA+D;;IAE/D,qBAAqB;;IAErB,wCAAwC;;IAExC,sCAAsC;;IAEtC,2CAA2C;;IAE3C,oBAAoB;;CAEZ,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,2CAA2C;AAC3C,eAAO,MAAM,uBAAuB,EAAE,gBAMrC,CAAC"}

package/dist/signaling/webSocket.js

@@ -0,0 +1,50 @@
+/**
+ * WebSocket 的最小接口。
+ *
+ * engine **必须能在无 DOM 的环境构造**（CONVENTIONS §1）——一致性向量与时序测试
+ * 都跑在 Node 里。所以这里只声明用得到的那几个成员，测试注入假实现，
+ * 浏览器里注入原生 WebSocket。
+ */
+/** WS_OPEN 是 WebSocket.OPEN 的值，避免在无 DOM 环境引用全局常量。 */
+export const WS_OPEN = 1;
+/** CloseCode 是协议约定的 WS 关闭码（RTC_PROTOCOL.md §1.5）。 */
+export const CloseCode = {
+    /** 正常关闭。**我们自己 logout 时发的就是它**；别人发过来的不算数，见 shouldReconnect。 */
+    normal: 1000,
+    /** 服务端下线/重启。立即重连。 */
+    goingAway: 1001,
+    /** 信封非法/帧超长/协议版本不支持。**不重连**，属实现 bug。 */
+    badProtocol: 4400,
+    /** 未鉴权/鉴权超时/token 无效。换新 token 后重连。 */
+    unauthorized: 4401,
+    /** 被踢（同 uid 同 device_id 在别处登录）。**不重连**。 */
+    kickedOut: 4403,
+    /** 频率超限。退避加倍后重连。 */
+    rateLimited: 4429,
+};
+/**
+ * shouldReconnect 按关闭码判断要不要重连。
+ *
+ * 4400 与 4403 **绝不重连**：前者是我们自己的实现 bug，重连只会再撞一次；
+ * 后者是被踢，重连等于跟另一台设备打架。
+ *
+ * **1000 不在这张表里**——「是不是我们自己要走的」看的是意图，不是关闭码。
+ * `close()` 会先把 state 置成 `closed`，`connection.ts` 那句
+ * `this.state !== 'closed'` 已经把 logout 挡住了；再按码挡一次，挡掉的只剩
+ * **别人发过来的 1000**：浏览器掐掉后台标签页的连接、代理/系统休眠断链，
+ * 用的都是这个码。服务端从不主动发 1000（重启走 1001 goingAway），
+ * 所以这里收到的 1000 一定不是「对面让我别回来了」。
+ * 症状是一个后台标签页显示「连接已断开（1000），不会自动回」，必须手动刷新。
+ */
+export function shouldReconnect(code) {
+    return code !== CloseCode.badProtocol && code !== CloseCode.kickedOut;
+}
+/** browserWebSocketFactory 是浏览器环境的默认工厂。 */
+export const browserWebSocketFactory = (url) => {
+    const Ctor = globalThis.WebSocket;
+    if (Ctor === undefined) {
+        throw new Error('当前环境没有 WebSocket；请通过 webSocketFactory 注入实现');
+    }
+    return new Ctor(url);
+};
+//# sourceMappingURL=webSocket.js.map

package/dist/signaling/webSocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSocket.js","sourceRoot":"","sources":["../../src/signaling/webSocket.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,qDAAqD;AACrD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AAEzB,qDAAqD;AACrD,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,+DAA+D;IAC/D,MAAM,EAAE,IAAI;IACZ,qBAAqB;IACrB,SAAS,EAAE,IAAI;IACf,wCAAwC;IACxC,WAAW,EAAE,IAAI;IACjB,sCAAsC;IACtC,YAAY,EAAE,IAAI;IAClB,2CAA2C;IAC3C,SAAS,EAAE,IAAI;IACf,oBAAoB;IACpB,WAAW,EAAE,IAAI;CACT,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,KAAK,SAAS,CAAC,WAAW,IAAI,IAAI,KAAK,SAAS,CAAC,SAAS,CAAC;AACxE,CAAC;AAED,2CAA2C;AAC3C,MAAM,CAAC,MAAM,uBAAuB,GAAqB,CAAC,GAAG,EAAE,EAAE;IAC/D,MAAM,IAAI,GAAI,UAAiE,CAAC,SAAS,CAAC;IAC1F,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC"}

package/dist/state/callMachine.d.ts

@@ -0,0 +1,56 @@
+import type { MediaType } from '../signaling/enums.js';
+import type { EmittedEvent, MachineInput, MachineOutput, OutgoingFrame } from './types.js';
+/**
+ * 通话状态机：RTC_PROTOCOL.md §5.1 的 TS 实现。
+ *
+ * 一致性向量：`im-rtc-server/docs/conformance/call_fsm.json`，四端跑同一份。
+ *
+ * # 三条容易写错的地方
+ *
+ * 1. **没有 `ended` 状态**——`ended` 是事件不是状态。草图 §09 里那个「停 1.5s」的
+ *    方框是 uikit 的展示状态，由 uikit 自己持有（不变量 I5）。
+ * 2. **便利事件只在 1v1 抛**（`onCallCancelled/Rejected/Busy/NoAnswer`）。群通话里
+ *    某人拒接只抛 `onUserReject`——否则会违反「便利事件后必定跟 onCallEnd」（I7）。
+ * 3. **状态只由信令帧与宿主调用驱动，禁止由定时器改状态**（I4）。
+ *    本地振铃倒计时只改 UI，超时由服务端裁决。
+ */
+/** CallState 是通话状态。**没有 ended**，见文件头。 */
+export type CallState = 'idle' | 'inviting' | 'ringing' | 'accepting' | 'connecting' | 'connected';
+/** CallRole 是本端在这通电话里的角色。 */
+export type CallRole = 'caller' | 'callee' | '';
+/** CallContext 是状态机持有的全部数据。 */
+export interface CallContext {
+    readonly state: CallState;
+    readonly callId: string;
+    readonly roomId: string;
+    readonly roomToken: string;
+    readonly mediaType: MediaType;
+    readonly isGroup: boolean;
+    readonly role: CallRole;
+    /** 通话时长的起点，来自服务端。**客户端不自己算时长**（I8）。 */
+    readonly connectedAtMs: number;
+    /**
+     * 拨出中**还没拿到 call_id** 就按了取消：先记下，`call.invite.ok` 一到就补发 `call.cancel`（见 callRecv.ts）。
+     *
+     * 不这样的话那一帧带着空 call_id 上线路，服务端回 1401，宿主平白多收一条 error
+     * （2026-09-15 10:09 demo-react 真机）。与 iOS `IMCallContext.cancelPending` 同形。
+     */
+    readonly cancelPending: boolean;
+    /**
+     * 本通电话记下的群号 / user_data——主叫来自 `call()` 的选项，被叫来自 `call.incoming`。
+     *
+     * **只当 `call.connected` 的兜底用**（HOST_INTEGRATION_DESIGN §3.3）：`onCallBegin` 优先取
+     * `call.connected` 里的值，为空才回落到这里，兼容尚未升级的旧服务端。
+     */
+    readonly chatGroupId: string;
+    readonly userData: string;
+}
+/** initialCallContext 是 idle 态的初值。 */
+export declare const initialCallContext: CallContext;
+/** out 构造一次状态转移的产物。callRecv.ts 也用它。 */
+export declare function out(state: CallContext, send?: OutgoingFrame[], emit?: EmittedEvent[]): MachineOutput<CallContext>;
+/** reduceCall 是通话状态机的唯一入口。 */
+export declare function reduceCall(ctx: CallContext, input: MachineInput): MachineOutput<CallContext>;
+/** synthesizeNetworkEnd 是不变量 I8 的那个**唯一例外**。 */
+export declare function synthesizeNetworkEnd(ctx: CallContext, nowMs: number): MachineOutput<CallContext>;
+//# sourceMappingURL=callMachine.d.ts.map

package/dist/state/callMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callMachine.d.ts","sourceRoot":"","sources":["../../src/state/callMachine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAEvD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAI3F;;;;;;;;;;;;;GAaG;AAEH,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;AAEnG,6BAA6B;AAC7B,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,EAAE,CAAC;AAEhD,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,sCAAsC;AACtC,eAAO,MAAM,kBAAkB,EAAE,WAYhC,CAAC;AAGF,uCAAuC;AACvC,wBAAgB,GAAG,CACjB,KAAK,EAAE,WAAW,EAClB,IAAI,GAAE,aAAa,EAAO,EAC1B,IAAI,GAAE,YAAY,EAAO,GACxB,aAAa,CAAC,WAAW,CAAC,CAE5B;AAED,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,aAAa,CAAC,WAAW,CAAC,CAS5F;AA+ID,gDAAgD;AAChD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAehG"}

package/dist/state/callMachine.js

@@ -0,0 +1,176 @@
+import { ErrorCode, errorName } from '../errors.js';
+import { CallEndReason } from '../reasons.js';
+import { FrameType } from '../signaling/registry.js';
+import { reduceRecv } from './callRecv.js';
+import { bool, num, str, strArray } from './types.js';
+/** initialCallContext 是 idle 态的初值。 */
+export const initialCallContext = {
+    state: 'idle',
+    callId: '',
+    roomId: '',
+    roomToken: '',
+    mediaType: 'audio',
+    isGroup: false,
+    role: '',
+    connectedAtMs: 0,
+    cancelPending: false,
+    chatGroupId: '',
+    userData: '',
+};
+/** out 构造一次状态转移的产物。callRecv.ts 也用它。 */
+export function out(state, send = [], emit = []) {
+    return { state, send, emit };
+}
+/** reduceCall 是通话状态机的唯一入口。 */
+export function reduceCall(ctx, input) {
+    switch (input.kind) {
+        case 'act':
+            return reduceAct(ctx, input.op, input.args ?? {});
+        case 'recv':
+            return reduceRecv(ctx, input.type, input.data);
+        case 'internal':
+            return reduceInternal(ctx, input.name);
+    }
+}
+function reduceInternal(ctx, name) {
+    // 媒体就绪：room.join.ok 到手 + sub PC 的 ICE 连通（§5.1）。
+    if (name === 'media_ready' && ctx.state === 'connecting') {
+        return out({ ...ctx, state: 'connected' });
+    }
+    /*
+      **`call.invite` 被服务端拒了要回 idle**，与 `join_failed` 同一个道理。
+  
+      不退的话通话机永远停在 `inviting`：界面上是「正在呼叫…」转个不停，
+      而那通电话服务端根本没建；随后每一次挂断都发向一个不存在的 call，
+      换回 `1401 call_not_found`，**永远退不出去**。
+      （实测：群呼把主叫自己也放进了 callee_ids，服务端回 1004，
+      然后连点五次挂断全是 1401。）
+  
+      抛 `onCallEnd` 而不是只清状态：它是所有结束分支的唯一出口（设计 §7.5），
+      界面只认这一个信号来收场子。reason 用 `error`——这通电话从未建立，
+      hangup/cancel/reject 哪个都不是实情。
+    */
+    if (name === 'call_failed' && ctx.state !== 'idle') {
+        return out(initialCallContext, [], [{
+                cb: 'onCallEnd',
+                args: {
+                    call_id: ctx.callId,
+                    reason: CallEndReason.error,
+                    duration_sec: 0,
+                    ended_by: '',
+                },
+            }]);
+    }
+    return out(ctx);
+}
+function reduceAct(ctx, op, args) {
+    switch (op) {
+        case 'call':
+            return startCall(ctx, args);
+        case 'accept':
+            return acceptCall(ctx);
+        case 'reject':
+            // reject 只发帧，状态由随后的 call.ended 推进——服务端才是裁决方。
+            return ctx.state === 'ringing'
+                ? out(ctx, [{ type: FrameType.callReject, data: { call_id: ctx.callId } }])
+                : invalidState(ctx);
+        case 'cancel':
+            if (ctx.state !== 'inviting')
+                return invalidState(ctx);
+            // 还没拿到 call_id（invite.ok 在路上）：这一帧发出去只会换回 1401。先挂起，invite.ok 一到就补发（callRecv.ts）。
+            if (ctx.callId === '')
+                return out({ ...ctx, cancelPending: true });
+            return out(ctx, [{ type: FrameType.callCancel, data: { call_id: ctx.callId } }]);
+        case 'hangup':
+            return ctx.state === 'connected' || ctx.state === 'connecting'
+                ? out(ctx, [{ type: FrameType.callHangup, data: { call_id: ctx.callId } }])
+                : invalidState(ctx);
+        case 'invite_more':
+            return inviteMore(ctx, args);
+        case 'join_call':
+            return joinOngoingCall(ctx, args);
+        default:
+            return invalidState(ctx);
+    }
+}
+function startCall(ctx, args) {
+    if (ctx.state !== 'idle')
+        return invalidState(ctx);
+    const calleeIds = strArray(args, 'callee_ids');
+    const mediaType = str(args, 'media_type') === 'video' ? 'video' : 'audio';
+    const isGroup = bool(args, 'is_group');
+    const chatGroupId = str(args, 'chat_group_id');
+    const userData = str(args, 'user_data');
+    /*
+      **省略 = 协议默认值**（newFrameData 的规矩，见 registry.ts）：只在宿主真的给了值时才
+      把键放进去，交给 frameSender → encodeFields 那一层去填协议默认值。显式写空串/0 会把
+      「没传」和「传了空/0」混为一谈——`timeout_sec` 尤其致命：写 0 会被 §2.6 的钳制夹到
+      下限 5s，而不是协议默认的 30s。
+    */
+    const data = { callee_ids: calleeIds, media_type: mediaType, is_group: isGroup };
+    if (chatGroupId !== '')
+        data['chat_group_id'] = chatGroupId;
+    if (userData !== '')
+        data['user_data'] = userData;
+    if (Object.hasOwn(args, 'timeout_sec'))
+        data['timeout_sec'] = num(args, 'timeout_sec');
+    return out({ ...ctx, state: 'inviting', role: 'caller', mediaType, isGroup, chatGroupId, userData }, [{ type: FrameType.callInvite, data }]);
+}
+function acceptCall(ctx) {
+    // 第二次 accept 必须**本地**拦下，不能发上去让服务端回 1405（不变量 R1 的同款理由）。
+    if (ctx.state !== 'ringing')
+        return invalidState(ctx);
+    return out({ ...ctx, state: 'accepting' }, [
+        { type: FrameType.callAccept, data: { call_id: ctx.callId } },
+    ]);
+}
+function inviteMore(ctx, args) {
+    if (ctx.state !== 'connected' && ctx.state !== 'connecting')
+        return invalidState(ctx);
+    return out(ctx, [
+        {
+            type: FrameType.callInviteMore,
+            data: { call_id: ctx.callId, callee_ids: strArray(args, 'callee_ids') },
+        },
+    ]);
+}
+/**
+ * joinOngoingCall 是「群成员看到『进行中』主动加入」（§4.1）。
+ *
+ * **「怎么知道有通话在进行中」不在本协议里**——那是宿主拿 webhook `call.started`
+ * 自己发广播的事。engine 只负责把 call_id 送上去。
+ */
+function joinOngoingCall(ctx, args) {
+    if (ctx.state !== 'idle')
+        return invalidState(ctx);
+    const callId = str(args, 'call_id');
+    return out({ ...ctx, state: 'accepting', role: 'callee', callId, isGroup: true }, [
+        { type: FrameType.callJoin, data: { call_id: callId } },
+    ]);
+}
+function invalidState(ctx) {
+    return out(ctx, [], [
+        {
+            cb: 'onError',
+            args: { code: ErrorCode.invalidState, name: errorName(ErrorCode.invalidState) },
+        },
+    ]);
+}
+/** synthesizeNetworkEnd 是不变量 I8 的那个**唯一例外**。 */
+export function synthesizeNetworkEnd(ctx, nowMs) {
+    if (ctx.state === 'idle')
+        return out(ctx);
+    const durationSec = ctx.connectedAtMs > 0 ? Math.max(0, Math.floor((nowMs - ctx.connectedAtMs) / 1000)) : 0;
+    return out({ ...initialCallContext }, [], [
+        {
+            cb: 'onCallEnd',
+            args: {
+                call_id: ctx.callId,
+                reason: CallEndReason.network,
+                duration_sec: durationSec,
+                ended_by: '',
+            },
+        },
+    ]);
+}
+//# sourceMappingURL=callMachine.js.map