@agentunion/fastaun 0.2.18 → 0.2.19

package/dist/client.js

@@ -344,6 +344,8 @@ export class AUNClient {
     _peerPrekeysCache = new Map();
     _prekeyReplenishInflight = new Set();
     _prekeyReplenished = new Set();
+    // 当前活跃 prekey：只有这个 prekey 被消费时才触发 replenish 上传
+    _activePrekeyId = '';
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     _seqTracker = new SeqTracker();
     _seqTrackerContext = null;
@@ -375,6 +377,8 @@ export class AUNClient {
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    /** 缓存最近一次 gateway.disconnect 信息（含服务端附带的 detail），用于后续 connection.state 透传 */
+    _lastDisconnectInfo = null;
     _logger;
     _clientLog;
     constructor(config, debug = false) {
@@ -744,12 +748,29 @@ export class AUNClient {
                 const gid = (p.group_id ?? '');
                 if (gid) {
                     const ns = `group:${gid}`;
-                    if (rawMessages.length > 0) {
-                        this._seqTracker.onPullResult(ns, rawMessages);
+                    // 区分解密成功 / 失败：失败的 payload 仍是 e2ee.group_encrypted。
+                    const decryptedOnly = [];
+                    let failedCount = 0;
+                    const decryptedMessages = Array.isArray(r.messages) ? r.messages : [];
+                    for (const m of decryptedMessages) {
+                        if (!isJsonObject(m))
+                            continue;
+                        const payload = isJsonObject(m.payload) ? m.payload : {};
+                        const ptype = payload.type;
+                        if (ptype === 'e2ee.group_encrypted') {
+                            failedCount++;
+                            this._enqueuePendingDecrypt(gid, m);
+                        }
+                        else {
+                            decryptedOnly.push(m);
+                        }
+                    }
+                    if (decryptedOnly.length > 0) {
+                        // 仅用解密成功的消息推进 contig；失败的等 retry 解密成功才推进。
+                        this._seqTracker.onPullResult(ns, decryptedOnly);
                     }
                     // ⚠️ 逻辑边界 L4：group retention floor 通道 = cursor.current_seq
                     // 群路径目前无独立 earliest_available_seq 字段；若未来引入 group retention，需新增字段并同步更新此处。
-                    // 与 S2 [1,seq-1] 历史 gap 配合使用，force_contiguous_seq 是跳过空洞的唯一手段。
                     const cursor = isJsonObject(r.cursor) ? r.cursor : null;
                     if (cursor) {
                         const serverAck = Number(cursor.current_seq ?? 0);
@@ -762,9 +783,9 @@ export class AUNClient {
                         }
                     }
                     this._saveSeqTrackerState();
-                    // auto-ack contiguous_seq
+                    // auto-ack：仅当没有解密失败时才 ack。失败时让服务端 cursor 留在原位等 retry。
                     const contig = this._seqTracker.getContiguousSeq(ns);
-                    const shouldAck = rawMessages.length > 0 || (cursor !== null && Number(cursor.current_seq ?? 0) > 0);
+                    const shouldAck = failedCount === 0 && (decryptedOnly.length > 0 || (cursor !== null && Number(cursor.current_seq ?? 0) > 0));
                     if (contig > 0 && shouldAck) {
                         this._transport.call('group.ack_messages', {
                             group_id: gid,
@@ -773,6 +794,10 @@ export class AUNClient {
                             slot_id: this._slotId,
                         }).catch((e) => { this._clientLog.debug(`group.pull auto-ack failed: group=${gid} ${formatCaughtError(e)}`); });
                     }
+                    // 有解密失败时调度 recovery 兜底定时
+                    if (failedCount > 0) {
+                        this._scheduleRecoveryTimeout(gid);
+                    }
                 }
             }
             if (method === 'group.thought.get' && isJsonObject(result)) {
@@ -935,8 +960,10 @@ export class AUNClient {
                 const did = String(pk.device_id ?? '').trim();
                 return did && did !== PREKEY_FALLBACK_DEVICE_ID;
             });
-            const canUseMultiDevice = routablePrekeys.length > 0
-                && (routablePrekeys.length > 1 || selfSyncCopies.length > 0);
+            // 只要有 routable prekey 就走 multi_device 路径（即使只有 1 个 recipient device + 0 self copies）。
+            // 这确保服务端为每个已注册设备存储副本，离线设备重连后能 pull 到。
+            // single 路径仅在完全没有 routable prekey 时使用（legacy 兼容）。
+            const canUseMultiDevice = routablePrekeys.length > 0;
             if (!canUseMultiDevice) {
                 return await this._sendEncryptedSingle({
                     toAid,
@@ -1726,6 +1753,22 @@ export class AUNClient {
         }
         // 拦截 P2P 传输的群组密钥分发/请求/响应消息
         if (await this._tryHandleGroupKeyMessage(msg)) {
+            // group_key 控制消息也要推进 seq tracker + auto-ack，
+            // 否则 fillP2pGap 会因为 contig 卡在此 seq 之前而重复拉取同样的历史消息。
+            const seq = msg.seq;
+            if (seq !== undefined && seq !== null && this._aid) {
+                const ns = `p2p:${this._aid}`;
+                this._seqTracker.onMessageSeq(ns, seq);
+                this._saveSeqTrackerState();
+                const contig = this._seqTracker.getContiguousSeq(ns);
+                if (contig > 0) {
+                    this._transport.call('message.ack', {
+                        seq: contig,
+                        device_id: this._deviceId,
+                        slot_id: this._slotId,
+                    }).catch(() => { });
+                }
+            }
             return;
         }
         // P2P 空洞检测
@@ -1812,8 +1855,12 @@ export class AUNClient {
         }
         const decrypted = await this._decryptGroupMessage(msg);
         this._clientLog.debug(`group message decrypt done: group=${groupId}, from=${String(msg.from ?? '')}, seq=${String(seq ?? '')}, e2ee=${String(!!decrypted.e2ee)}`);
-        // 只有带 payload 的真实消息，在同步解密/恢复尝试结束后才推进游标。
-        if (groupId && seq !== undefined && seq !== null) {
+        // 解密失败时**不推进 seq tracker / 不 auto-ack**：让服务端 cursor 留在原位，
+        // 等密钥恢复后 retry 解密成功才推进 + ack；recovery 真的失败时由
+        // _retryPendingDecryptMsgs(forceAdvanceOnFail=true) 兜底强制推进。
+        const payloadForCheck = isJsonObject(msg.payload) ? msg.payload : null;
+        const isDecryptFail = payloadForCheck?.type === 'e2ee.group_encrypted' && !decrypted.e2ee;
+        if (!isDecryptFail && groupId && seq !== undefined && seq !== null) {
             const ns = `group:${groupId}`;
             const needPull = this._seqTracker.onMessageSeq(ns, seq);
             if (needPull) {
@@ -1832,10 +1879,12 @@ export class AUNClient {
             this._saveSeqTrackerState();
         }
         // R3: 解密失败 → 不 publish 密文给应用层，入 pending 队列 + 发 undecryptable 事件
-        const payloadForCheck = isJsonObject(msg.payload) ? msg.payload : null;
-        if (payloadForCheck?.type === 'e2ee.group_encrypted' && !decrypted.e2ee) {
-            if (groupId)
+        if (isDecryptFail) {
+            if (groupId) {
                 this._enqueuePendingDecrypt(groupId, msg);
+                // 触发 recovery 兜底定时（30s 后如果仍未解开，强制推进）
+                this._scheduleRecoveryTimeout(groupId);
+            }
             await this._publishAppEvent('group.message_undecryptable', {
                 message_id: msg.message_id,
                 group_id: groupId,
@@ -2787,11 +2836,31 @@ export class AUNClient {
         }
         let result;
         if (actualPayload.type === 'e2ee.group_key_distribution') {
+            // 快速跳过已过期的历史 epoch 分发：本地已有更高 epoch 时不发任何 RPC，
+            // 避免 fillP2pGap 拉到大量历史群密钥消息时触发 epoch 编排风暴。
+            const distGroupId = String(actualPayload.group_id ?? '');
+            const distEpoch = Number(actualPayload.epoch ?? 0);
+            if (distGroupId && distEpoch > 0) {
+                const localEpoch = this._groupE2ee.currentEpoch(distGroupId) ?? 0;
+                if (localEpoch >= distEpoch) {
+                    this._clientLog.debug(`skip stale group_key_distribution: group=${distGroupId} msg_epoch=${distEpoch} local_epoch=${localEpoch}`);
+                    return true;
+                }
+            }
             if (!await this._verifyActiveGroupRotationDistribution(actualPayload)) {
                 return true;
             }
         }
         else if (actualPayload.type === 'e2ee.group_key_response') {
+            const respGroupId = String(actualPayload.group_id ?? '');
+            const respEpoch = Number(actualPayload.epoch ?? 0);
+            if (respGroupId && respEpoch > 0) {
+                const localEpoch = this._groupE2ee.currentEpoch(respGroupId) ?? 0;
+                if (localEpoch >= respEpoch) {
+                    this._clientLog.debug(`skip stale group_key_response: group=${respGroupId} msg_epoch=${respEpoch} local_epoch=${localEpoch}`);
+                    return true;
+                }
+            }
             if (!await this._verifyGroupKeyResponseEpoch(actualPayload)) {
                 return true;
             }
@@ -3057,6 +3126,8 @@ export class AUNClient {
     async _uploadPrekey() {
         const prekeyMaterial = this._e2ee.generatePrekey();
         const result = await this._transport.call('message.e2ee.put_prekey', prekeyMaterial);
+        // 上传成功后记录为活跃 prekey
+        this._activePrekeyId = String(prekeyMaterial.prekey_id ?? '');
         return isJsonObject(result) ? { ...result } : { ok: true };
     }
     /**
@@ -3223,23 +3294,47 @@ export class AUNClient {
         queue.push(msg);
         this._pendingDecryptMsgs.set(ns, queue.slice(-PENDING_DECRYPT_LIMIT));
     }
-    async _retryPendingDecryptMsgs(groupId) {
+    async _retryPendingDecryptMsgs(groupId, forceAdvanceOnFail = false) {
         const ns = `group:${groupId}`;
         const queue = this._pendingDecryptMsgs.get(ns);
         if (!queue || queue.length === 0)
             return;
         this._pendingDecryptMsgs.set(ns, []);
         const stillPending = [];
+        let forceAdvancedAny = false;
         for (const msg of queue) {
             try {
                 const decrypted = await this._decryptGroupMessage(msg);
                 const payload = isJsonObject(msg.payload) ? msg.payload : null;
                 if (payload?.type === 'e2ee.group_encrypted' && !decrypted.e2ee) {
-                    stillPending.push(msg);
+                    if (forceAdvanceOnFail) {
+                        // recovery 真的失败：强制推进 seq tracker + 发 undecryptable + ack
+                        this._clientLog.info(`group recovery give up: group=${groupId} seq=${String(msg.seq ?? '')} → force advance + publish undecryptable`);
+                        const seq = msg.seq;
+                        if (seq !== undefined && seq !== null) {
+                            this._seqTracker.onMessageSeq(ns, seq);
+                            this._saveSeqTrackerState();
+                            forceAdvancedAny = true;
+                        }
+                        await this._publishAppEvent('group.message_undecryptable', {
+                            message_id: msg.message_id,
+                            group_id: groupId,
+                            from: msg.from,
+                            seq,
+                            timestamp: msg.timestamp,
+                            _decrypt_error: 'epoch recovery failed',
+                        });
+                    }
+                    else {
+                        stillPending.push(msg);
+                    }
                     continue;
                 }
                 const seq = msg.seq;
                 if (seq !== undefined && seq !== null) {
+                    // 推进 seq tracker（之前 push/pull 失败时没推进）
+                    this._seqTracker.onMessageSeq(ns, seq);
+                    this._saveSeqTrackerState();
                     await this._publishOrderedMessage('group.message_created', ns, seq, decrypted);
                 }
                 else {
@@ -3250,6 +3345,18 @@ export class AUNClient {
                 stillPending.push(msg);
             }
         }
+        // 强制推进有变更时，按 contig auto-ack
+        if (forceAdvancedAny) {
+            const contig = this._seqTracker.getContiguousSeq(ns);
+            if (contig > 0) {
+                this._transport.call('group.ack_messages', {
+                    group_id: groupId,
+                    msg_seq: contig,
+                    device_id: this._deviceId,
+                    slot_id: this._slotId,
+                }).catch((e) => { this._clientLog.debug(`group recovery force-advance ack failed: group=${groupId} ${formatCaughtError(e)}`); });
+            }
+        }
         const queuedDuringRetry = this._pendingDecryptMsgs.get(ns) ?? [];
         const mergedPending = [...stillPending, ...queuedDuringRetry].slice(-PENDING_DECRYPT_LIMIT);
         if (mergedPending.length)
@@ -3257,6 +3364,28 @@ export class AUNClient {
         else
             this._pendingDecryptMsgs.delete(ns);
     }
+    /**
+     * recovery 兜底定时：N 秒后如果 pending queue 仍有未解开消息，强制推进 cursor。
+     * 同一 group 短时间内只调度一次。
+     */
+    _recoveryTimeoutScheduled = new Map();
+    _scheduleRecoveryTimeout(groupId, timeoutMs = 30000) {
+        if (!groupId)
+            return;
+        const now = Date.now();
+        const last = this._recoveryTimeoutScheduled.get(groupId) ?? 0;
+        if (last && (last + timeoutMs) > now)
+            return;
+        this._recoveryTimeoutScheduled.set(groupId, now);
+        setTimeout(() => {
+            const ns = `group:${groupId}`;
+            const queue = this._pendingDecryptMsgs.get(ns);
+            if (!queue || queue.length === 0)
+                return;
+            this._clientLog.info(`group recovery timeout: group=${groupId} → force advance`);
+            this._retryPendingDecryptMsgs(groupId, true).catch((exc) => this._clientLog.warn(`group ${groupId} recovery timeout retry failed: ${formatCaughtError(exc)}`));
+        }, timeoutMs).unref?.();
+    }
     _scheduleRetryPendingDecryptMsgs(groupId) {
         if (!groupId || !this._pendingDecryptMsgs.has(`group:${groupId}`))
             return;
@@ -3963,6 +4092,11 @@ export class AUNClient {
         const groupId = String(payload.group_id ?? '').trim();
         if (!groupId)
             return false;
+        // 历史群（不在当前 session 活跃列表）：跳过 RPC 验证，只做本地 handle_incoming
+        if (!this._groupSynced.has(groupId)) {
+            this._clientLog.debug(`skip RPC verify for inactive group: group=${groupId} rotation=${rotationId}`);
+            return true;
+        }
         const epoch = Number(payload.epoch ?? 0);
         if (!Number.isFinite(epoch) || epoch <= 0)
             return false;
@@ -4796,6 +4930,9 @@ export class AUNClient {
         this._gatewayUrl = gatewayUrl;
         this._slotId = String(params.slot_id ?? '');
         this._connectDeliveryMode = { ...(params.delivery_mode ?? this._connectDeliveryMode) };
+        const extraInfo = (params.extra_info && typeof params.extra_info === 'object' && !Array.isArray(params.extra_info))
+            ? params.extra_info
+            : undefined;
         const prevState = this._state;
         this._auth.setInstanceContext({ deviceId: this._deviceId, slotId: this._slotId });
         this._state = 'connecting';
@@ -4814,6 +4951,9 @@ export class AUNClient {
                     deviceId: this._deviceId,
                     slotId: this._slotId,
                     deliveryMode: this._connectDeliveryMode,
+                    connectionKind: String(params.connection_kind ?? 'long'),
+                    shortTtlMs: Number(params.short_ttl_ms ?? 0),
+                    extraInfo,
                 });
                 if (isJsonObject(authContext)) {
                     const auth = authContext;
@@ -4834,6 +4974,9 @@ export class AUNClient {
                     deviceId: this._deviceId,
                     slotId: this._slotId,
                     deliveryMode: this._connectDeliveryMode,
+                    connectionKind: String(params.connection_kind ?? 'long'),
+                    shortTtlMs: Number(params.short_ttl_ms ?? 0),
+                    extraInfo,
                 });
                 this._syncIdentityAfterConnect(String(params.access_token));
             }
@@ -4854,6 +4997,11 @@ export class AUNClient {
             catch (exc) {
                 this._clientLog.warn(`prekey upload failed: ${formatCaughtError(exc)}`);
             }
+            // connect/reconnect 成功后自动触发一次 P2P message.pull，补齐离线期间积压
+            // 群消息按惰性触发，不在此处主动 pull
+            void this._fillP2pGap().catch((exc) => {
+                this._clientLog.warn(`schedule post-connect P2P gap fill failed: ${formatCaughtError(exc)}`);
+            });
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms gateway=${gatewayUrl}, aid=${this._aid ?? ''}`);
         }
         catch (err) {
@@ -4940,16 +5088,29 @@ export class AUNClient {
         if ('timeouts' in request && request.timeouts != null && !isJsonObject(request.timeouts)) {
             throw new ValidationError('timeouts must be a dict');
         }
+        // 长短连接参数校验
+        const connectionKind = String(request.connection_kind ?? 'long');
+        if (connectionKind !== 'long' && connectionKind !== 'short') {
+            throw new ValidationError(`connection_kind must be "long" or "short", got "${connectionKind}"`);
+        }
+        request.connection_kind = connectionKind;
+        const shortTtlMs = Number(request.short_ttl_ms ?? 0);
+        if (!Number.isFinite(shortTtlMs) || shortTtlMs < 0 || Math.floor(shortTtlMs) !== shortTtlMs) {
+            throw new ValidationError('short_ttl_ms must be a non-negative integer');
+        }
+        request.short_ttl_ms = connectionKind === 'short' ? shortTtlMs : 0;
         return request;
     }
     /** 从参数构建会话选项 */
     _buildSessionOptions(params) {
+        const connectionKind = String(params.connection_kind ?? 'long');
         const options = {
-            auto_reconnect: DEFAULT_SESSION_OPTIONS.auto_reconnect,
+            auto_reconnect: connectionKind === 'short' ? false : DEFAULT_SESSION_OPTIONS.auto_reconnect,
             heartbeat_interval: DEFAULT_SESSION_OPTIONS.heartbeat_interval,
             token_refresh_before: DEFAULT_SESSION_OPTIONS.token_refresh_before,
             retry: { ...DEFAULT_SESSION_OPTIONS.retry },
             timeouts: { ...DEFAULT_SESSION_OPTIONS.timeouts },
+            connection_kind: connectionKind,
         };
         if ('auto_reconnect' in params)
             options.auto_reconnect = Boolean(params.auto_reconnect);
@@ -4968,6 +5129,9 @@ export class AUNClient {
     // ── 内部：后台任务 ────────────────────────────────────────
     /** 启动所有后台任务 */
     _startBackgroundTasks() {
+        // 短连接生命周期短，禁用心跳与 token 刷新（不接收推送、不需要长期会话维护）
+        if (this._sessionOptions.connection_kind === 'short')
+            return;
         this._startHeartbeatTask();
         this._startTokenRefreshTask();
         this._startGroupEpochTasks();
@@ -5191,23 +5355,18 @@ export class AUNClient {
         const prekeyId = this._extractConsumedPrekeyId(message);
         if (!prekeyId || this._state !== 'connected')
             return;
-        if (this._prekeyReplenished.has(prekeyId))
+        // 只有活跃 prekey 被消费时才触发上传。历史 prekey 被消费不触发，避免上传风暴。
+        if (!this._activePrekeyId || prekeyId !== this._activePrekeyId)
             return;
-        // 同一时刻只允许一个 put_prekey inflight
-        if (this._prekeyReplenishInflight.size > 0)
-            return;
-        this._prekeyReplenishInflight.add(prekeyId);
+        // 清空活跃标记，防止重复触发（新上传完成后会设新的 active）
+        this._activePrekeyId = '';
         void (async () => {
             try {
                 await this._uploadPrekey();
-                this._prekeyReplenished.add(prekeyId);
             }
             catch (exc) {
                 this._clientLog.warn(`replenish current prekey after consuming ${prekeyId} failed: ${formatCaughtError(exc)}`);
             }
-            finally {
-                this._prekeyReplenishInflight.delete(prekeyId);
-            }
         })();
     }
     /** 启动群组 epoch 相关后台任务 */
@@ -5291,13 +5450,34 @@ export class AUNClient {
     }
     // ── 内部：断线重连 ────────────────────────────────────────
     /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
-    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011]);
-    /** 处理服务端主动断开通知 event/gateway.disconnect */
-    _onGatewayDisconnect(data) {
-        const code = data?.code;
-        const reason = data?.reason ?? '';
-        this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}`);
+    static _NO_RECONNECT_CODES = new Set([4001, 4003, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015]);
+    /** 处理服务端主动断开通知 event/gateway.disconnect。
+     *
+     * 服务端可能附带结构化 detail 字段（如配额超限时含 aid/device_id/slot_id/quota_kind/evicted_by）。
+     * 透传到应用层可订阅事件 'gateway.disconnect'，方便业务定位被踢原因。
+     */
+    async _onGatewayDisconnect(data) {
+        const payload = (data && typeof data === 'object') ? data : {};
+        const code = payload.code;
+        const reason = payload.reason ?? '';
+        const detail = (payload.detail && typeof payload.detail === 'object' && !Array.isArray(payload.detail))
+            ? payload.detail
+            : {};
+        this._clientLog.warn(`server initiated disconnect: code=${code}, reason=${reason}, detail=${JSON.stringify(detail)}`);
         this._serverKicked = true;
+        // 缓存最近一次 disconnect 信息，让后续 connection.state(terminal_failed) 也能带 detail
+        this._lastDisconnectInfo = { code, reason, detail };
+        // 透传给应用层订阅者
+        try {
+            await this._dispatcher.publish('gateway.disconnect', {
+                code,
+                reason,
+                detail,
+            });
+        }
+        catch (exc) {
+            this._clientLog.debug(`publish gateway.disconnect failed: ${exc instanceof Error ? exc.message : String(exc)}`);
+        }
     }
     /** 传输层断线回调 */
     async _handleTransportDisconnect(error, closeCode) {
@@ -5319,9 +5499,18 @@ export class AUNClient {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppressing auto-reconnect: ${reason}`);
-            await this._dispatcher.publish('connection.state', {
+            const disconnectInfo = this._lastDisconnectInfo ?? {};
+            const eventPayload = {
                 state: this._state, error, reason,
-            });
+            };
+            // 把服务端附带的结构化 detail（如配额超限信息）也带给应用层
+            if (disconnectInfo.detail && Object.keys(disconnectInfo.detail).length > 0) {
+                eventPayload.detail = disconnectInfo.detail;
+            }
+            if (disconnectInfo.code !== undefined && disconnectInfo.code !== null) {
+                eventPayload.code = disconnectInfo.code;
+            }
+            await this._dispatcher.publish('connection.state', eventPayload);
             return;
         }
         // 1000 = 正常关闭, 1006 = 网络异常断开（无 close frame），其他 code = 服务端主动关闭