@agentunion/fastaun-browser 0.2.18 → 0.2.19

package/dist/client.js

@@ -343,6 +343,8 @@ export class AUNClient {
     _certCache = new Map();
     _prekeyReplenishInflight = new Set();
     _prekeyReplenished = new Set();
+    // 当前活跃 prekey：只有这个 prekey 被消费时才触发 replenish 上传
+    _activePrekeyId = '';
     _peerPrekeysCache = new Map();
     // 后台任务 handle（浏览器 setInterval/setTimeout）
     _heartbeatTimer = null;
@@ -378,6 +380,11 @@ export class AUNClient {
     _reconnectActive = false;
     _reconnectAbort = null;
     _serverKicked = false;
+    /**
+     * 缓存最近一次服务端 gateway.disconnect 信息（含 code/reason/detail），
+     * 让后续 connection.state(terminal_failed) 也能携带 detail（如配额超限信息）。
+     */
+    _lastDisconnectInfo = null;
     // Logger（per-client 单例 + 各模块子 logger）
     _logger;
     _clientLog;
@@ -492,8 +499,8 @@ export class AUNClient {
             });
         }
         // 服务端主动断开通知：记录日志并标记不重连
-        this._dispatcher.subscribe('_raw.gateway.disconnect', (data) => {
-            this._onGatewayDisconnect(data);
+        this._dispatcher.subscribe('_raw.gateway.disconnect', async (data) => {
+            await this._onGatewayDisconnect(data);
         });
     }
     // ── 属性 ──────────────────────────────────────────
@@ -788,7 +795,6 @@ export class AUNClient {
         if (method === 'group.pull' && isJsonObject(result)) {
             const r = result;
             const messages = r.messages;
-            // 先保存原始消息（解密前），用于喂 SeqTracker（与 P2P message.pull 路径对齐）
             const rawMessages = (Array.isArray(messages) ? messages : []).filter(isJsonObject);
             if (rawMessages.length) {
                 r.messages = await this._decryptGroupMessages(rawMessages);
@@ -796,13 +802,28 @@ export class AUNClient {
             const gid = (p.group_id ?? '');
             if (gid) {
                 const ns = `group:${gid}`;
-                // ⚠️ 使用原始消息（rawMessages）喂 SeqTracker，与 P2P message.pull 路径一致
-                if (rawMessages.length) {
-                    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) {
+                    // 仅用解密成功的消息推进 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);
@@ -815,9 +836,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,
@@ -826,6 +847,10 @@ export class AUNClient {
                         slot_id: this._slotId,
                     }).catch((e) => { this._clientLog.warn('group.pull auto-ack failed: group=' + gid, e); });
                 }
+                // 有解密失败时调度 recovery 兜底定时
+                if (failedCount > 0) {
+                    this._scheduleRecoveryTimeout(gid);
+                }
             }
         }
         if (method === 'group.thought.get' && isJsonObject(result)) {
@@ -920,6 +945,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 空洞检测
@@ -1004,8 +1045,12 @@ export class AUNClient {
                 return;
             }
             const decrypted = await this._decryptGroupMessage(msg);
-            // 只有带 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) {
@@ -1023,10 +1068,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 ?? null,
                     group_id: groupId,
@@ -1882,8 +1929,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, payload, messageId, timestamp,
@@ -2731,23 +2780,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 真的失败：强制推进 + 发 undecryptable
+                        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 {
@@ -2758,6 +2831,17 @@ export class AUNClient {
                 stillPending.push(msg);
             }
         }
+        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.warn('group recovery force-advance ack failed: group=' + groupId, e); });
+            }
+        }
         const queuedDuringRetry = this._pendingDecryptMsgs.get(ns) ?? [];
         const mergedPending = [...stillPending, ...queuedDuringRetry].slice(-PENDING_DECRYPT_LIMIT);
         if (mergedPending.length)
@@ -2765,6 +2849,25 @@ export class AUNClient {
         else
             this._pendingDecryptMsgs.delete(ns);
     }
+    // recovery 兜底定时去重：每个 group 在 30s 内最多调度一次"超时强制推进"任务
+    _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._safeAsync(this._retryPendingDecryptMsgs(groupId, true));
+        }, timeoutMs);
+    }
     _scheduleRetryPendingDecryptMsgs(groupId) {
         if (!groupId || !this._pendingDecryptMsgs.has(`group:${groupId}`))
             return;
@@ -3395,11 +3498,31 @@ export class AUNClient {
         let result = null;
         try {
             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 = await 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 = await 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;
                 }
@@ -3681,6 +3804,8 @@ export class AUNClient {
     async _uploadPrekey() {
         const prekeyMaterial = await 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 };
     }
     /** 确保发送方证书在本地可用且未过期 */
@@ -3895,6 +4020,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;
@@ -4679,6 +4809,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: params.extra_info,
                     });
                     if (isJsonObject(authContext)) {
                         const auth = authContext;
@@ -4697,6 +4830,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: params.extra_info,
                     });
                     await this._syncIdentityAfterConnect(String(params.access_token));
                 }
@@ -4728,6 +4864,9 @@ export class AUNClient {
             catch (exc) {
                 this._clientLog.warn(`prekey upload failed:${String(exc)}`);
             }
+            // connect/reconnect 成功后自动触发一次 P2P message.pull，补齐离线期间积压
+            // 群消息按惰性触发，不在此处主动 pull
+            this._safeAsync(this._fillP2pGap());
             this._clientLog.debug(`_connectOnce exit: elapsed=${Date.now() - tStart}ms aid=${this._aid ?? '-'}`);
         }
         catch (err) {
@@ -4813,15 +4952,42 @@ export class AUNClient {
         if (request.timeouts !== undefined && !isJsonObject(request.timeouts)) {
             throw new ValidationError('timeouts must be an object');
         }
+        // 长短连接选项：默认 long，向后兼容
+        const kindRaw = request.connection_kind;
+        if (kindRaw == null) {
+            request.connection_kind = 'long';
+        }
+        else {
+            request.connection_kind = String(kindRaw).trim().toLowerCase();
+        }
+        if (request.connection_kind !== 'long' && request.connection_kind !== 'short') {
+            throw new ValidationError("connection_kind must be 'long' or 'short'");
+        }
+        try {
+            request.short_ttl_ms = Math.max(0, Math.floor(Number(request.short_ttl_ms) || 0));
+        }
+        catch {
+            throw new ValidationError('short_ttl_ms must be a non-negative integer');
+        }
+        if (request.connection_kind !== 'short') {
+            request.short_ttl_ms = 0;
+        }
         return request;
     }
     _buildSessionOptions(params) {
+        const connectionKind = String(params.connection_kind ?? 'long');
+        // 短连接默认禁用 auto_reconnect：短连接生命周期短，自动重连无意义
+        const defaultAutoReconnect = connectionKind === 'short'
+            ? false
+            : DEFAULT_SESSION_OPTIONS.auto_reconnect;
         const options = {
-            auto_reconnect: DEFAULT_SESSION_OPTIONS.auto_reconnect,
+            auto_reconnect: defaultAutoReconnect,
             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,
+            short_ttl_ms: Number(params.short_ttl_ms ?? 0),
         };
         if ('auto_reconnect' in params) {
             options.auto_reconnect = Boolean(params.auto_reconnect);
@@ -4842,6 +5008,10 @@ export class AUNClient {
     }
     // ── 内部：后台任务 ────────────────────────────────
     _startBackgroundTasks() {
+        // 短连接生命周期短，禁用心跳与 token 刷新（不接收推送、不需要长期会话维护）
+        if (this._sessionOptions?.connection_kind === 'short') {
+            return;
+        }
         this._startHeartbeat();
         this._startTokenRefresh();
         this._startPrekeyRefresh();
@@ -5107,22 +5277,17 @@ 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 = '';
         this._safeAsync((async () => {
             try {
                 await this._uploadPrekey();
-                this._prekeyReplenished.add(prekeyId);
             }
             catch (exc) {
-                this._clientLog.warn(`consume prekey ${prekeyId} then replenish current prekey failed: ${String(exc)}`);
-            }
-            finally {
-                this._prekeyReplenishInflight.delete(prekeyId);
+                this._clientLog.warn(`replenish current prekey after consuming ${prekeyId} failed: ${String(exc)}`);
             }
         })());
     }
@@ -5191,13 +5356,28 @@ 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 obj = (data && typeof data === 'object') ? data : {};
+        const code = obj.code;
+        const reason = obj.reason ?? '';
+        const detail = (obj.detail && typeof obj.detail === 'object') ? obj.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?.message ?? exc}`);
+        }
     }
     async _handleTransportDisconnect(error, closeCode) {
         if (this._closing || this._state === 'closed')
@@ -5218,9 +5398,19 @@ export class AUNClient {
             this._state = 'terminal_failed';
             const reason = this._serverKicked ? 'server kicked' : `close code ${closeCode}`;
             this._clientLog.warn(`suppress auto-reconnect: ${reason}`);
-            await this._dispatcher.publish('connection.state', {
+            const disconnectInfo = this._lastDisconnectInfo ?? {};
+            const eventPayload = {
                 state: this._state, error, reason,
-            });
+            };
+            // 把服务端附带的结构化 detail（如配额超限信息）也带给应用层
+            const detail = disconnectInfo.detail;
+            if (detail && typeof detail === 'object' && Object.keys(detail).length > 0) {
+                eventPayload.detail = 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 = 服务端主动关闭