im-rtc-call-engine 1.0.0

package/dist/signaling/connection.js

@@ -0,0 +1,365 @@
+import { ErrorCode, RtcError, rtcErrorFromWire } from '../errors.js';
+import { logger, redact } from '../logger.js';
+import { SDK_VERSION } from '../version.js';
+import { decodeEnvelope, encodeEnvelope, okType } from './envelope.js';
+import { decodeFields, encodeFields } from './fieldSpec.js';
+import { HELLO_FIELDS, HELLO_OK_FIELDS } from './frames.sys.js';
+import { TokenExpiryTimer } from './tokenExpiry.js';
+import { handshakeGiveUpReason } from './handshakeGiveUp.js';
+import { Heartbeat } from './heartbeat.js';
+import { PendingRequests } from './pendingRequests.js';
+import { Reconnector } from './reconnector.js';
+import { ResumeDeadline } from './resumeDeadline.js';
+import { FrameType, lookupFrame } from './registry.js';
+import { CloseCode, WS_OPEN, browserWebSocketFactory, shouldReconnect } from './webSocket.js';
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+/** 宿主不传 sdk 时 `sys.hello` 带的标识。版本号取 SDK_VERSION，别在这里另写一份。 */
+const DEFAULT_SDK = `web/${SDK_VERSION}`;
+/**
+ * MAX_AUTH_FAILURES 是连续几次 4401 之后彻底放弃（协议 §1.5 关闭码表）。
+ *
+ * **一定要有这个上限**：4401 说的是「这枚 token 不好使」，而重连**带的是同一枚
+ * token**——没有上限就是拿同一把坏钥匙永远敲同一扇门。实测里服务端重启换了签名密钥，
+ * 一个没关的标签页重试到第 19 次还在敲，日志里全是 `token_invalid`，
+ * 把真正的问题淹掉了。上限到了就抛 `onKickedOut` 把宿主赶回登录页去换新 token。
+ */
+const MAX_AUTH_FAILURES = 3;
+/** Connection 是一条信令连接。断线会自动重连，除非关闭码明说不该重连。 */
+export class Connection {
+    options;
+    ws = null;
+    state = 'idle';
+    sessionId = '';
+    seq = 0;
+    pending;
+    heartbeat;
+    reconnector;
+    token;
+    /** 连续鉴权失败次数。握手一成功就清零——只有**连续**失败才说明票是死的。 */
+    authFailures = 0;
+    tokenExpiry;
+    /** 「服务端已经彻底放弃这条会话」的倒计时。见 `ResumeDeadline`。 */
+    resumeDeadline;
+    constructor(options) {
+        this.token = options.token;
+        this.heartbeat = new Heartbeat({
+            sendPing: () => this.sendPing(),
+            onDead: () => this.ws?.close(CloseCode.goingAway, 'heartbeat timeout'),
+        });
+        this.pending = new PendingRequests(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+        this.tokenExpiry = new TokenExpiryTimer({
+            ...(options.tokenExpiryLeadMs === undefined ? {} : { leadMs: options.tokenExpiryLeadMs }),
+            onWillExpire: (info) => this.options.events?.onTokenWillExpire?.(info),
+        });
+        this.resumeDeadline = new ResumeDeadline(() => {
+            this.sessionId = ''; // 服务端已经丢掉它，再拿去要 resume 只会白跑一趟
+            this.options.events?.onSessionUnrecoverable?.();
+        });
+        this.reconnector = new Reconnector(async () => {
+            await this.connect();
+        }, (err) => this.emitError(err), options.random ?? Math.random);
+        this.options = {
+            url: options.url,
+            token: options.token,
+            deviceId: options.deviceId,
+            sdk: options.sdk ?? DEFAULT_SDK,
+            events: options.events ?? {},
+            webSocketFactory: options.webSocketFactory ?? browserWebSocketFactory,
+            requestTimeoutMs: options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+            random: options.random ?? Math.random,
+        };
+    }
+    /** currentState 返回连接状态。 */
+    get currentState() {
+        return this.state;
+    }
+    /** currentSessionId 返回会话 id；重连时会带上它请求恢复。 */
+    get currentSessionId() {
+        return this.sessionId;
+    }
+    /**
+     * updateToken 换一枚新的接入票（旧票过期时用）。下次连接生效。
+     *
+     * **顺带把鉴权失败计数清零**：换票就是「这次不一样了」的唯一信号，
+     * 不清的话已经用光重试次数的连接换了新票也再没有机会试。
+     */
+    updateToken(token, expiresAtMs) {
+        this.token = token;
+        this.authFailures = 0;
+        // 宿主刚从自家后台拿到票，必然知道它的 expires_in。传了就按新票重新武装；
+        // 不传就让旧定时器继续跑到下一次握手——那时 sys.hello.ok 会给出权威值。
+        if (expiresAtMs !== undefined)
+            this.tokenExpiry.arm(expiresAtMs);
+    }
+    /** connect 建立连接并完成握手。已连上时直接返回。 */
+    async connect() {
+        if (this.state === 'connected' && this.ws !== null) {
+            throw new RtcError(ErrorCode.invalidState, { cause: new Error('已经连上了') });
+        }
+        this.state = this.sessionId === '' ? 'connecting' : 'reconnecting';
+        const socket = this.options.webSocketFactory(this.options.url);
+        this.ws = socket;
+        await new Promise((resolve, reject) => {
+            socket.onopen = () => resolve();
+            socket.onerror = () => reject(new RtcError(ErrorCode.networkUnreachable, { cause: new Error('WebSocket 打开失败') }));
+            socket.onclose = (event) => this.handleClose(event);
+        });
+        socket.onmessage = (event) => this.handleMessage(event.data);
+        const hello = await this.handshake();
+        this.state = 'connected';
+        this.authFailures = 0;
+        this.reconnector.succeeded();
+        this.resumeDeadline.connected(hello.pingIntervalSec);
+        this.heartbeat.start(hello.pingIntervalSec);
+        this.tokenExpiry.arm(hello.tokenExpiresAtMs);
+        this.options.events?.onConnected?.(hello);
+        return hello;
+    }
+    /** close 主动关闭，**不会**触发重连。 */
+    close() {
+        this.state = 'closed';
+        this.heartbeat.stop();
+        this.reconnector.stop();
+        // **只有 logout 撤这条倒计时**：鉴权连续失败那条路要让它走完（见 ResumeDeadline）。
+        this.resumeDeadline.cancel();
+        this.tokenExpiry.disarm();
+        this.pending.rejectAll(new RtcError(ErrorCode.invalidState, { cause: new Error('连接已关闭') }));
+        this.ws?.close(CloseCode.normal, 'client logout');
+        this.ws = null;
+    }
+    /**
+     * request 发一个请求并等它的应答。
+     *
+     * 返回的 data 是**已按帧声明解码**的对象；未注册的应答类型返回原始 data。
+     */
+    async request(type, fields, value) {
+        if (this.state !== 'connected') {
+            throw new RtcError(ErrorCode.invalidState, {
+                forType: type,
+                cause: new Error(`连接不可用（当前 ${this.state}）`),
+            });
+        }
+        return this.dispatchRequest(type, fields, value);
+    }
+    /**
+     * dispatchRequest 不检查连接状态。
+     *
+     * 独立出来是因为 **sys.hello 本身就要在 connecting 状态下发出去**——
+     * 让握手走公开的 request() 会被状态检查挡住（踩过一次：所有时序测试都挂在
+     * 「一帧都没发出去」）。
+     */
+    async dispatchRequest(type, fields, value) {
+        const socket = this.ws;
+        if (socket === null) {
+            throw new RtcError(ErrorCode.invalidState, {
+                forType: type,
+                cause: new Error('还没有连接'),
+            });
+        }
+        const reqId = this.nextReqId();
+        const raw = encodeEnvelope(type, reqId, encodeFields(fields, value));
+        const waiting = this.pending.track(reqId, type);
+        try {
+            socket.send(raw);
+        }
+        catch (cause) {
+            this.pending.abandon(reqId);
+            throw new RtcError(ErrorCode.networkUnreachable, { forType: type, cause });
+        }
+        return waiting;
+    }
+    /** send 发一帧但不等应答（服务端主动事件的回应，如 sub 的 answer）。 */
+    sendFrame(type, reqId, fields, value) {
+        const socket = this.ws;
+        if (socket === null || socket.readyState !== WS_OPEN)
+            return;
+        socket.send(encodeEnvelope(type, reqId, encodeFields(fields, value)));
+    }
+    /**
+     * fire 发一个请求但**不等应答**：应答照常按 req_id 配对后丢掉，不会漏进事件流。
+     *
+     * 只给 `CallEngine.forceEnd()` 用：结束帧不许排在帧循环与在途请求后面
+     * （2026-09-13 iOS 那次挂断一帧没发出去，卡的正是那一段）。
+     * 帧在这次调用里就同步写进 socket（`dispatchRequest` 在第一个 await 之前就 send 了）。
+     * 未连接时只记一条日志——握手之前发业务帧会被服务端当成协议错误。
+     */
+    fire(type, fields, value) {
+        if (this.state !== 'connected') {
+            logger.warn('帧没发出去：连接不可用', { type, state: this.state });
+            return;
+        }
+        void this.dispatchRequest(type, fields, value).catch((err) => {
+            logger.info('不等应答的请求失败了', {
+                type,
+                code: err instanceof RtcError ? err.code : 'unknown',
+            });
+        });
+    }
+    nextReqId() {
+        this.seq += 1;
+        return `w-${this.seq}`;
+    }
+    async handshake() {
+        const hello = decodeFields(HELLO_FIELDS, {});
+        hello.token = this.token;
+        hello.deviceId = this.options.deviceId;
+        hello.sessionId = this.sessionId;
+        hello.sdk = this.options.sdk ?? DEFAULT_SDK;
+        logger.debug('发送 sys.hello', {
+            deviceId: hello.deviceId,
+            sessionId: hello.sessionId,
+            // 凭据只打前 6 位 + 长度（CONVENTIONS §6）。
+            token: redact(hello.token),
+        });
+        let reply;
+        try {
+            reply = await this.dispatchRequest(FrameType.hello, HELLO_FIELDS, hello);
+        }
+        catch (err) {
+            this.abortIfHandshakeRejected(err);
+            throw err;
+        }
+        const { envelope, data } = reply;
+        if (envelope.type !== okType(FrameType.hello)) {
+            throw new RtcError(ErrorCode.notAuthenticated, {
+                cause: new Error(`握手应答是 ${envelope.type}`),
+            });
+        }
+        // data 已经是线路形状（见 decodeData 的注释），直接解成 camelCase 给调用方。
+        const ok = decodeFields(HELLO_OK_FIELDS, data);
+        this.sessionId = ok.sessionId;
+        return ok;
+    }
+    /**
+     * 握手被拒且重试不可能变好时，一次就放弃，按 {@link handshakeGiveUpReason} 的分类抛给宿主。
+     *
+     * **握手应答类型不对那条不走这里**——那是对端的实现 bug，处置另说，
+     * 不该借这条路悄悄改掉。
+     */
+    abortIfHandshakeRejected(err) {
+        const reason = handshakeGiveUpReason(err);
+        if (reason === null)
+            return;
+        const rtc = err;
+        logger.error('握手被拒，不再重连', { code: rtc.code, name: rtc.name_, reason });
+        // stop() 是闩不是取消：connect() 被拒那条是微任务，排在 close 事件之后，
+        // 只取消定时器的话它会把重连又排回来（见 Reconnector.stop 的注释）。
+        this.reconnector.stop();
+        this.state = 'closed';
+        this.options.events?.onKickedOut?.({ reason });
+    }
+    handleMessage(raw) {
+        if (typeof raw !== 'string')
+            return;
+        // 收到**任何**帧都算对端活着，不只是 pong（§1.3）。
+        this.heartbeat.noteFrameReceived();
+        let envelope;
+        try {
+            envelope = decodeEnvelope(raw);
+        }
+        catch (err) {
+            // 解不开的帧是对端的实现 bug。抛给宿主并断开——继续读只会读到更多垃圾。
+            this.emitError(err);
+            this.ws?.close(CloseCode.badProtocol, 'undecodable frame');
+            return;
+        }
+        if (envelope.reqId !== '' && this.pending.settle(envelope, (e) => this.decodeData(e)))
+            return;
+        this.dispatchEvent(envelope);
+    }
+    dispatchEvent(envelope) {
+        if (envelope.type === FrameType.error) {
+            const error = rtcErrorFromWire(envelope.data);
+            if (error.code === ErrorCode.kickedOut)
+                this.options.events?.onKickedOut?.({ reason: 'takenOver' });
+            this.options.events?.onError?.(error);
+            return;
+        }
+        if (lookupFrame(envelope.type) === undefined) {
+            // §2.3：客户端收到未知 type **必须静默忽略**——服务端可能比我们新。
+            logger.debug('忽略未知帧', { type: envelope.type });
+            return;
+        }
+        this.options.events?.onEvent?.(envelope.type, this.decodeData(envelope), envelope);
+    }
+    /**
+     * decodeData 返回**线路形状**（snake_case）的规范化 data。
+     *
+     * 「解出来再编回去」看着多余，其实是在做三件事：填默认值、枚举兜底、数值钳制。
+     * 保持 snake_case 是因为**状态机吃的是线路形状**——它跑的一致性向量就是线路形状，
+     * 换成 camelCase 会让状态机与向量之间多一层翻译，而那层翻译没人测。
+     *
+     * # 解不动就按原始 data 放行，**绝不往上抛**
+     *
+     * 这里原先是裸的 `decodeFields`。字段类型对不上（服务端把 int 位置发成了字符串）时它抛
+     * `bad_params`，而调用点在 `PendingRequests.settle` 里——那时 waiter **已经被摘掉、
+     * 超时也已经清掉**，`resolve` 却还没执行：那个 `request()` 的 promise 从此永远不落定。
+     * 症状是 `room.join.ok` 明明回来了，房间机却永远停在 `joining`，之后每次 publish 被
+     * R1 拒成 2005，而宿主一条错误都收不到（异常从 `onmessage` 里冲出去成了未捕获错误）。
+     * iOS（`(try? decodedData()) ?? envelope.data`）与 Android（catch 后回退 `envelope.data`）
+     * 本来就是这么做的，本端是四端里唯一漏掉兜底的。
+     *
+     * 回退之后字段读取一律走 `Wire.*` 那套「读不出来就取零值」的取数器，状态机不会崩；
+     * 真正的原因进日志 + 一条 error 事件，不塞进应答里让业务分不清。
+     */
+    decodeData(envelope) {
+        const fields = lookupFrame(envelope.type);
+        if (fields === undefined)
+            return { ...envelope.data };
+        try {
+            return encodeFields(fields, decodeFields(fields, envelope.data));
+        }
+        catch (err) {
+            logger.warn('帧解码失败，按原始 data 放行', { type: envelope.type, cause: String(err) });
+            this.emitError(err);
+            return { ...envelope.data };
+        }
+    }
+    handleClose(event) {
+        this.heartbeat.stop();
+        this.ws = null;
+        this.pending.rejectAll(new RtcError(ErrorCode.networkUnreachable, { cause: new Error('连接已断开') }));
+        if (event.code === CloseCode.kickedOut)
+            this.options.events?.onKickedOut?.({ reason: 'takenOver' });
+        /*
+          4401 要计数。重连**带的是同一枚 token**，所以「换新 token 后重连」这条规则
+          只有配上一个上限才成立——否则一枚废票能自己重试到天荒地老。
+          连续 3 次之后按协议 §1.5 抛 onKickedOut，让宿主回登录页重新取票。
+        */
+        let exhausted = false;
+        if (event.code === CloseCode.unauthorized) {
+            this.authFailures += 1;
+            exhausted = this.authFailures >= MAX_AUTH_FAILURES;
+            if (exhausted) {
+                logger.info('鉴权连续失败，停止重连', { failures: this.authFailures });
+                this.reconnector.stop();
+                this.options.events?.onKickedOut?.({ reason: 'authExpired' });
+            }
+        }
+        const willReconnect = !exhausted && this.state !== 'closed' && shouldReconnect(event.code);
+        this.options.events?.onDisconnected?.({
+            code: event.code,
+            reason: event.reason,
+            willReconnect,
+        });
+        if (!willReconnect) {
+            this.state = 'closed';
+            return;
+        }
+        this.state = 'reconnecting';
+        this.resumeDeadline.arm();
+        this.reconnector.schedule();
+    }
+    /** sendPing 发一个心跳帧。连接不可用时静默跳过——心跳失败自有判死逻辑接手。 */
+    sendPing() {
+        const socket = this.ws;
+        if (socket !== null && socket.readyState === WS_OPEN) {
+            socket.send(encodeEnvelope(FrameType.ping, this.nextReqId(), {}));
+        }
+    }
+    emitError(err) {
+        const error = err instanceof RtcError ? err : new RtcError(ErrorCode.internal, { cause: err });
+        this.options.events?.onError?.(error);
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/signaling/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/signaling/connection.ts"],"names":[],"mappings":"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"}

package/dist/signaling/connectionFactory.d.ts

@@ -0,0 +1,55 @@
+import type { RtcError } from '../errors.js';
+import type { HelloOk, KickedOutReason } from './connection.js';
+import { Connection } from './connection.js';
+import type { WebSocketFactory } from './webSocket.js';
+/**
+ * 按 engine 需要的形状装配一条 `Connection`。
+ *
+ * 单拎出来是因为它有一处**只有类型系统会提醒、但很容易写错**的地方：
+ * `exactOptionalPropertyTypes` 下，可选字段不能显式传 `undefined`，
+ * 只能整个不写——于是 `webSocketFactory` 必须用展开语法条件性地加进去。
+ * 那三行放在门面里既碍眼又容易在下次改动时被"顺手简化"掉。
+ */
+export interface EngineConnectionHandlers {
+    /**
+     * 握手完成——**每一次**，包括自动重连那些。
+     *
+     * 一开始这一条整个漏了：门面只在 `login()` 里手工把 hello.ok 喂给状态机，
+     * 而重连是连接层自己发起的，它那次握手的结果谁都没接。后果不是「少一个事件」
+     * 而是**重连之后状态机根本不知道自己重连了**：`resumed=false` 时房间与通话
+     * 不归零（服务端那边早就没了）、`resumed=true` 时攒下的意图不重放，
+     * 宿主也永远收不到第二次 `connected`——界面卡在「重连中」不动。
+     */
+    onConnected: (hello: HelloOk) => void;
+    onEvent: (type: string, data: Record<string, unknown>) => void;
+    onDisconnected: (info: {
+        code: number;
+        willReconnect: boolean;
+    }) => void;
+    onKickedOut: (info: {
+        reason: KickedOutReason;
+    }) => void;
+    /**
+     * 断得太久，服务端那一侧的会话已经不可能再恢复（§1.4）。
+     *
+     * 与「重连上了但 `resumed=false`」是同一件事，只是**不必等重连成功**——
+     * 网络一直不回来的话那一刻永远不会到，界面就永远停在「正在重连」、
+     * 连挂断都点不动（真机 2026-09-08 的 iOS 端）。
+     */
+    onSessionUnrecoverable: () => void;
+    /** 票快到期，宿主该换票。 */
+    onTokenWillExpire: (info: {
+        expiresAtMs: number;
+    }) => void;
+    onError: (error: RtcError) => void;
+}
+/** EngineConnectionConfig 是装配一条连接需要的最小信息。 */
+export interface EngineConnectionConfig {
+    url: string;
+    token: string;
+    deviceId: string;
+    webSocketFactory?: WebSocketFactory;
+}
+/** createConnection 造一条已挂好回调、尚未连接的 Connection。 */
+export declare function createConnection(config: EngineConnectionConfig, handlers: EngineConnectionHandlers): Connection;
+//# sourceMappingURL=connectionFactory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connectionFactory.d.ts","sourceRoot":"","sources":["../../src/signaling/connectionFactory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAqB,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACtC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC/D,cAAc,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IACzE,WAAW,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,eAAe,CAAA;KAAE,KAAK,IAAI,CAAC;IACzD;;;;;;OAMG;IACH,sBAAsB,EAAE,MAAM,IAAI,CAAC;IACnC,kBAAkB;IAClB,iBAAiB,EAAE,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC3D,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CACpC;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,wBAAwB,GACjC,UAAU,CAyBZ"}

package/dist/signaling/connectionFactory.js

@@ -0,0 +1,29 @@
+import { checkDeviceId } from '../protocolId.js';
+import { Connection } from './connection.js';
+/** createConnection 造一条已挂好回调、尚未连接的 Connection。 */
+export function createConnection(config, handlers) {
+    // **在开 socket 之前拦**：不拦的话服务端回 1004，而它那句「device_id 只允许
+    // [A-Za-z0-9_-]」到不了宿主手里——宿主看到的只有一个 bad_params，
+    // 界面上就是「登录失败」四个字。安卓真机上为此查了一轮（见 deviceId.ts）。
+    checkDeviceId(config.deviceId);
+    const options = {
+        url: config.url,
+        token: config.token,
+        deviceId: config.deviceId,
+        // exactOptionalPropertyTypes：没有工厂时**不能传 undefined**，只能不写这个键。
+        ...(config.webSocketFactory === undefined
+            ? {}
+            : { webSocketFactory: config.webSocketFactory }),
+        events: {
+            onConnected: (hello) => handlers.onConnected(hello),
+            onSessionUnrecoverable: () => handlers.onSessionUnrecoverable(),
+            onEvent: (type, data) => handlers.onEvent(type, data),
+            onDisconnected: (info) => handlers.onDisconnected({ code: info.code, willReconnect: info.willReconnect }),
+            onKickedOut: (info) => handlers.onKickedOut(info),
+            onTokenWillExpire: (info) => handlers.onTokenWillExpire(info),
+            onError: (error) => handlers.onError(error),
+        },
+    };
+    return new Connection(options);
+}
+//# sourceMappingURL=connectionFactory.js.map

package/dist/signaling/connectionFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionFactory.js","sourceRoot":"","sources":["../../src/signaling/connectionFactory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA8C7C,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAC9B,MAA8B,EAC9B,QAAkC;IAElC,qDAAqD;IACrD,+CAA+C;IAC/C,6CAA6C;IAC7C,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC/B,MAAM,OAAO,GAAsB;QACjC,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,6DAA6D;QAC7D,GAAG,CAAC,MAAM,CAAC,gBAAgB,KAAK,SAAS;YACvC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAClD,MAAM,EAAE;YACN,WAAW,EAAE,CAAC,KAAK,EAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC;YACzD,sBAAsB,EAAE,GAAS,EAAE,CAAC,QAAQ,CAAC,sBAAsB,EAAE;YACrE,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAQ,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC;YAC3D,cAAc,EAAE,CAAC,IAAI,EAAQ,EAAE,CAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;YACjF,WAAW,EAAE,CAAC,IAAI,EAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC;YACvD,iBAAiB,EAAE,CAAC,IAAI,EAAQ,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC;YACnE,OAAO,EAAE,CAAC,KAAK,EAAQ,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC;SAClD;KACF,CAAC;IACF,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC"}

package/dist/signaling/connectionTypes.d.ts

@@ -0,0 +1,94 @@
+import type { Envelope } from './envelope.js';
+import type { RtcError } from '../errors.js';
+import type { WebSocketFactory } from './webSocket.js';
+/**
+ * 连接层的公开类型。
+ *
+ * 从 connection.ts 抽出来（CONVENTIONS §2 的 400 行红线）——那边留实现，这边留契约。
+ * 公开 API 不变：connection.ts 仍然把它们原样 re-export。
+ */
+/** ConnectionState 是连接状态。 */
+export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'closed';
+/** HelloOk 是握手成功后的服务端信息。 */
+export interface HelloOk {
+    uid: string;
+    deviceId: string;
+    sessionId: string;
+    resumed: boolean;
+    pingIntervalSec: number;
+    /** 本次握手用的那张票的到期时刻（Unix 毫秒）。**0 = 未知**。 */
+    tokenExpiresAtMs: number;
+    limits: {
+        maxFrameBytes: number;
+        maxCallees: number;
+        maxRoomParticipants: number;
+        maxUserDataBytes: number;
+        ringTimeoutSecDefault: number;
+    };
+}
+/**
+ * KickedOutReason 是被踢的原因。
+ *
+ * **不合并成一个「被踢」**：三种情况宿主的处置完全不同——一个该回登录页，
+ * 一个该悄悄换票重来，一个该去改配置。合并的结果是宿主只能都当登录失效处理，
+ * 把可以静默恢复的场景也变成了「请重新登录」，把该改配置的场景变成了让用户干瞪眼。
+ */
+export type KickedOutReason = 'takenOver' | 'authExpired' | 'configRejected';
+/** ConnectionEvents 是连接层对外的回调。 */
+export interface ConnectionEvents {
+    /** 握手完成。resumed=true 表示恢复了旧会话，房间成员关系还在。 */
+    onConnected?: (hello: HelloOk) => void;
+    /** 连接断开。willReconnect=false 时不会再自动回来。 */
+    onDisconnected?: (info: {
+        code: number;
+        reason: string;
+        willReconnect: boolean;
+    }) => void;
+    /**
+     * 被踢，**不会自动重连**。
+     *
+     * reason 决定宿主该做什么，三者处置完全不同：
+     * - `takenOver` —— 同账号同设备号在别处登录，或宿主主动吊销（都是 4403/1104，
+     *   客户端无从区分）。**回登录页**，换票也没用。
+     * - `authExpired` —— 票不被接受且连续三次都没换上（4401 用尽）。
+     *   宿主应重新取一枚票再 `login`。
+     * - `configRejected` —— 服务端拒绝了这次接入的**参数**（握手应答里 retryable=false
+     *   的错误码：device_id 不合规、协议版本不受支持、应用被停用……）。
+     *   **去改配置**——换票和重试都救不了。具体哪里不对看 `login()` 抛出的 RtcError；
+     *   如果是重连期间被拒，那条码走 onError。
+     */
+    onKickedOut?: (info: {
+        reason: KickedOutReason;
+    }) => void;
+    /**
+     * 断得太久了，**服务端那一侧的会话已经不可能再恢复**（§1.4 的恢复窗口过了）。
+     *
+     * 与「重连上了但 `resumed=false`」是同一件事，只是**不必等重连成功**——
+     * 网络一直不回来的话那一刻永远不会到。少了它，界面就永远停在「正在重连」、
+     * 连挂断都点不动（真机 2026-09-08 的 iOS 端）。
+     */
+    onSessionUnrecoverable?: () => void;
+    /** 票快到期了，宿主该去取新票并 updateToken。见 tokenExpiry.ts。 */
+    onTokenWillExpire?: (info: {
+        expiresAtMs: number;
+    }) => void;
+    /** 收到服务端主动推送的事件（req_id 为空的帧）。 */
+    onEvent?: (type: string, data: Record<string, unknown>, envelope: Envelope) => void;
+    /** 内部错误。 */
+    onError?: (error: RtcError) => void;
+}
+/** ConnectionOptions 是构造参数。带 Fn 后缀的都是为了测试可注入。 */
+export interface ConnectionOptions {
+    url: string;
+    token: string;
+    deviceId: string;
+    sdk?: string;
+    events?: ConnectionEvents;
+    webSocketFactory?: WebSocketFactory;
+    /** 请求超时。协议建议 10 秒（§2.2）。 */
+    requestTimeoutMs?: number;
+    random?: () => number;
+    /** 票到期前多久提醒宿主换票。默认 60s，见 tokenExpiry.ts。 */
+    tokenExpiryLeadMs?: number;
+}
+//# sourceMappingURL=connectionTypes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connectionTypes.d.ts","sourceRoot":"","sources":["../../src/signaling/connectionTypes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;;GAKG;AAEH,6BAA6B;AAC7B,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,4BAA4B;AAC5B,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,gBAAgB,EAAE,MAAM,CAAC;QACzB,qBAAqB,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAE7E,kCAAkC;AAClC,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,yCAAyC;IACzC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1F;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,eAAe,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1D;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,MAAM,IAAI,CAAC;IACpC,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC5D,iCAAiC;IACjC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpF,YAAY;IACZ,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;CACrC;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,4BAA4B;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/signaling/connectionTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=connectionTypes.js.map

package/dist/signaling/connectionTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connectionTypes.js","sourceRoot":"","sources":["../../src/signaling/connectionTypes.ts"],"names":[],"mappings":""}

package/dist/signaling/discipline.d.ts

@@ -0,0 +1,6 @@
+/**
+ * checkDiscipline 检查一个已解析的 data 是否满足编码硬规则。
+ * 违规抛 RtcError（bad_envelope 或 bad_params）。
+ */
+export declare function checkDiscipline(data: unknown): void;
+//# sourceMappingURL=discipline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discipline.d.ts","sourceRoot":"","sources":["../../src/signaling/discipline.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAEnD"}