@agentunion/fastaun 0.5.32 → 0.5.34

package/dist/transport.d.ts

@@ -11,6 +11,7 @@ import type { EventDispatcher } from './events.js';
 import { type ModuleLogger } from './logger.js';
 import { type JsonObject, type RpcMessage, type RpcParams, type RpcResult } from './types.js';
 import { type ServiceEventVerificationResult } from './org-protocol.js';
+import { RpcBudget } from './client/rpc-budget.js';
 export type RpcBackground = false | true | 'event' | 'pull';
 /** 断线回调，closeCode 为 WebSocket close code（1006 = 网络异常断开，其他 = 服务端主动关闭） */
 export type DisconnectCallback = (error: Error | null, closeCode?: number) => void | Promise<void>;
@@ -26,6 +27,7 @@ export declare function shortRpcViaNetworkActor(url: string, method: string, par
  * WebSocket JSON-RPC 2.0 传输层
  */
 export declare class RPCTransport {
+    readonly rpcBudget: RpcBudget;
     private _logger;
     private _dispatcher;
     private _serviceEventVerifier;
@@ -67,6 +69,10 @@ export declare class RPCTransport {
     private _riskDeliveries;
     private _idCounter;
     private _metaObserver;
+    private _syncControlObserver;
+    private _syncAdmission;
+    private _syncAuxiliary;
+    private readonly _budgetWaiters;
     private _requestAdmission;
     private _requestCheck;
     private _riskControlHandler;
@@ -100,6 +106,8 @@ export declare class RPCTransport {
     };
     constructor(opts: {
         eventDispatcher: EventDispatcher;
+        rpcBudget?: RpcBudget;
+        syncAuxiliary?: boolean;
         timeout?: number;
         onDisconnect?: DisconnectCallback | null;
         verifySsl?: boolean;
@@ -137,6 +145,9 @@ export declare class RPCTransport {
     private _finishRiskDelivery;
     private _receiveRiskControl;
     private _dispatchRiskControl;
+    setSyncControlObserver(observer: ((meta: Record<string, unknown>, method: string, params: JsonObject) => void) | null): void;
+    setSyncAdmission(policy: JsonObject | null): void;
+    private _checkSyncAdmission;
     setProtocolMetaObserver(observer: MetaObserver | null): void;
     setProtocolDisconnectCallback(callback: DisconnectCallback | null): void;
     waitForPending(timeoutMs: number, signal?: AbortSignal): Promise<void>;
@@ -177,6 +188,7 @@ export declare class RPCTransport {
     call(method: string, params?: RpcParams, timeout?: number, trace?: string, background?: RpcBackground): Promise<RpcResult>;
     private _callWithSent;
     private _call;
+    private _callWithAdmission;
     private _callAdmitted;
     private _callLocal;
     /** 发送 JSON-RPC 2.0 Notification，不分配 id，也不等待响应。 */

package/dist/transport.js

@@ -16,6 +16,7 @@ import { isJsonObject } from './types.js';
 import { parseJsonStrict, validateOrgRequestJSON } from './org-protocol.js';
 import { RiskController } from './risk-control.js';
 import { messageClassOf } from './client/control-messages.js';
+import { RpcBudget } from './client/rpc-budget.js';
 const MAX_WS_PAYLOAD_SIZE = 1_000_000;
 const MAX_RPC_INFLIGHT = 16;
 const MAX_BACKGROUND_RPC_INFLIGHT = 8;
@@ -550,6 +551,7 @@ export function shortRpcViaNetworkActor(url, method, params, verifySsl = false)
  * WebSocket JSON-RPC 2.0 传输层
  */
 export class RPCTransport {
+    rpcBudget;
     _logger;
     _dispatcher;
     _serviceEventVerifier = null;
@@ -593,6 +595,10 @@ export class RPCTransport {
     // Gateway 在 RPC envelope 注入 _meta 字段（与 result 同级），由 client 层 observer 接收。
     // observer 抛异常会被吞掉，不影响 RPC result 返回。
     _metaObserver = null;
+    _syncControlObserver = null;
+    _syncAdmission = null;
+    _syncAuxiliary = false;
+    _budgetWaiters = new Set();
     _requestAdmission = null;
     _requestCheck = null;
     _riskControlHandler = null;
@@ -626,11 +632,13 @@ export class RPCTransport {
         };
     }
     get foregroundWaiting() {
-        return this._rpcQueue.length;
+        return this._rpcQueue.length + this.rpcBudget.foregroundWaiting;
     }
     _eventBackpressure(timeout = 30_000) { if (this._worker)
         return this._workerCommand({ type: 'event_backpressure', timeout }); return Promise.resolve(this.foregroundWaiting > 0 || Number(this._ws?.bufferedAmount ?? 0) >= 65536); }
     constructor(opts) {
+        this.rpcBudget = opts.rpcBudget ?? new RpcBudget();
+        this._syncAuxiliary = opts.syncAuxiliary ?? false;
         this._logger = opts.logger ?? _noopLogger;
         this._dispatcher = opts.eventDispatcher;
         this._timeout = opts.timeout ?? 35_000;
@@ -687,6 +695,7 @@ export class RPCTransport {
                     aunTransportWorker: true,
                     timeout: opts.timeout ?? 35_000,
                     verifySsl: opts.verifySsl ?? true,
+                    syncAuxiliary: this._syncAuxiliary,
                 },
             });
             this._worker = worker;
@@ -712,7 +721,7 @@ export class RPCTransport {
                     return;
                 }
                 if (message.type === 'foreground_drained') {
-                    if (this._workerConnected && message.generation === this._workerGeneration)
+                    if (this._workerConnected && message.generation === this._workerGeneration && !this.rpcBudget.foregroundWaiting)
                         this._onForegroundDrained?.();
                     return;
                 }
@@ -818,6 +827,9 @@ export class RPCTransport {
             pending.reject(error);
         }
         this._workerPending.clear();
+        for (const request of this._budgetWaiters)
+            request.cancel?.();
+        this._budgetWaiters.clear();
         void worker.terminate().catch(() => { });
         if (wasConnected) {
             this._dispatcher.enqueueProtocol('connection.error', { error });
@@ -864,6 +876,11 @@ export class RPCTransport {
         }
         if (this._workerGeneration === null || message.generation !== this._workerGeneration)
             return;
+        if (message.event === '_transport.sync_control') {
+            const value = message.payload;
+            this._syncControlObserver?.(value.meta, value.method, value.params ?? {});
+            return;
+        }
         if (message.event === '_transport.rate_limit') {
             const until = Number(message.payload?.until_ms);
             if (Number.isFinite(until))
@@ -1110,6 +1127,23 @@ export class RPCTransport {
                 this._worker.postMessage({ type: 'risk_release', generation: this._workerGeneration ?? undefined });
         });
     }
+    setSyncControlObserver(observer) {
+        this._syncControlObserver = observer;
+    }
+    setSyncAdmission(policy) {
+        this._syncAdmission = policy ? { ...policy } : null;
+        this._worker?.postMessage({ type: 'sync_admission', syncAdmission: this._syncAdmission });
+    }
+    _checkSyncAdmission(guard) {
+        if (!isJsonObject(guard))
+            return;
+        const value = guard;
+        const policy = this._syncAdmission;
+        if (!policy || policy.parent_connection_id !== value.parent_connection_id || policy.version !== value.version
+            || Number(policy.max_history_pull_inflight) <= 0 || Number(policy.max_history_inflight_bytes) <= 0 || Number(policy.history_bytes_per_second) <= 0) {
+            throw new StateError('history sync policy changed before send', { data: { sync_policy_changed: true }, retryable: true });
+        }
+    }
     setProtocolMetaObserver(observer) {
         this._metaObserver = observer;
         this._protocolMetaObserver = true;
@@ -1528,6 +1562,9 @@ export class RPCTransport {
     }
     /** 关闭连接 */
     async close() {
+        for (const request of this._budgetWaiters)
+            request.cancel?.();
+        this._budgetWaiters.clear();
         if (this._worker) {
             const worker = this._worker;
             this._workerConnected = false;
@@ -1673,6 +1710,25 @@ export class RPCTransport {
         return Object.assign(result, { cancel: request.cancel });
     }
     _call(method, params, timeout, trace, background = false, onSent, sentCheckpoint) {
+        const selected = normalizeRpcBackground(background !== false ? background : params?._rpc_background);
+        const kind = selected === true && ['message.peers', 'message.pull', 'message.v2.pull', 'message.ack', 'message.v2.ack', 'group.pull', 'group.v2.pull', 'group.pull_events', 'group.ack_messages', 'group.v2.ack'].includes(method) ? 'pull' : selected;
+        const deadline = Math.min(typeof params?._rpc_deadline === 'number' ? params._rpc_deadline : Infinity, Date.now() + (timeout ?? this._timeout));
+        if (method === 'gateway.risk_ack')
+            return this._callWithAdmission(method, params, Math.max(1, deadline - Date.now()), trace, background, onSent, sentCheckpoint);
+        let started = false;
+        let request;
+        request = this.rpcBudget.run(kind, () => {
+            started = true;
+            this._budgetWaiters.delete(request);
+            return this._callWithAdmission(method, params, Math.max(1, deadline - Date.now()), trace, background, onSent, sentCheckpoint);
+        }, deadline, this._messagePriority(params?.message_class), method);
+        if (!started) {
+            this._budgetWaiters.add(request);
+            void request.then(() => this._budgetWaiters.delete(request), () => this._budgetWaiters.delete(request));
+        }
+        return request;
+    }
+    _callWithAdmission(method, params, timeout, trace, background = false, onSent, sentCheckpoint) {
         if (!this._requestAdmission)
             return this._callAdmitted(method, params, timeout, trace, background, onSent, sentCheckpoint);
         let release;
@@ -1687,6 +1743,7 @@ export class RPCTransport {
         }
     }
     _callAdmitted(method, params, timeout, trace, background = false, onSent, sentCheckpoint) {
+        this._checkSyncAdmission(params?._rpc_sync_guard);
         if (this._worker) {
             const requestContext = trafficLogContext('outbound', params ?? {});
             const requestLog = withLogContext(this._logger, requestContext);
@@ -1726,6 +1783,10 @@ export class RPCTransport {
         const backgroundRpc = selectedBackground === true && ['message.peers', 'message.pull', 'message.v2.pull', 'message.ack', 'message.v2.ack', 'group.pull', 'group.v2.pull', 'group.pull_events', 'group.ack_messages', 'group.v2.ack'].includes(method) ? 'pull' : selectedBackground;
         delete localParams._rpc_background;
         delete localParams._rpc_deadline;
+        const sync = localParams._rpc_sync;
+        delete localParams._rpc_sync;
+        const syncGuard = localParams._rpc_sync_guard;
+        delete localParams._rpc_sync_guard;
         const requestContext = trafficLogContext('outbound', sendParams);
         const requestLog = withLogContext(this._logger, requestContext);
         const responseLog = withLogContext(requestLog, {
@@ -1746,6 +1807,7 @@ export class RPCTransport {
             id: rpcId,
             method,
             params: sendParams,
+            ...(sync && typeof sync === 'object' ? { _meta: { sync } } : {}),
         });
         const payloadSize = new TextEncoder().encode(payload).length;
         if (payloadSize > MAX_WS_PAYLOAD_SIZE) {
@@ -1829,6 +1891,7 @@ export class RPCTransport {
                 priority: this._messagePriority(localParams.message_class),
                 logger: requestLog,
                 onSent,
+                ...(isJsonObject(syncGuard) ? { syncGuard: syncGuard } : {}),
             });
             if (backgroundRpc) {
                 this._rpcQueue.pop();
@@ -1843,6 +1906,7 @@ export class RPCTransport {
                     priority: this._messagePriority(localParams.message_class),
                     logger: requestLog,
                     onSent,
+                    ...(isJsonObject(syncGuard) ? { syncGuard: syncGuard } : {}),
                 });
             }
             this._drainRpcQueue();
@@ -1874,7 +1938,7 @@ export class RPCTransport {
             });
         }
         const normalizedMethod = String(method ?? '').trim();
-        if (!normalizedMethod.startsWith('notification/') && !normalizedMethod.startsWith('event/')) {
+        if (!normalizedMethod.startsWith('notification/') && !normalizedMethod.startsWith('event/') && normalizedMethod !== 'gateway.sync_demand') {
             throw new ValidationError('notify method must start with notification/ or event/');
         }
         if (params !== undefined && params !== null && !isJsonObject(params)) {
@@ -2071,7 +2135,7 @@ export class RPCTransport {
         }
         if (this._rpcQueue.length > 0) {
             this._rpcQueue = this._rpcQueue.filter((entry) => entry.rpcId !== rpcId || (pending !== undefined && entry.pending !== pending));
-            if (this._rpcQueue.length === 0 && !this._closed)
+            if (this.foregroundWaiting === 0 && !this._closed)
                 this._onForegroundDrained?.();
         }
         if (this._backgroundRpcQueue.length > 0) {
@@ -2150,6 +2214,7 @@ export class RPCTransport {
                         return false;
                     }
                     this._requestCheck?.(`rpc:${entry.method}`);
+                    this._checkSyncAdmission(entry.syncGuard);
                     entry.pending.sent = true;
                     return true;
                 }, this._isRiskControlMethod(entry.method) ? 3 : entry.priority).then(() => {
@@ -2178,7 +2243,7 @@ export class RPCTransport {
             if (!this._closed && this._backgroundRpcQueue.length && remaining > 0) {
                 this._rateLimitTimer = setTimeout(() => { this._rateLimitTimer = null; this._drainRpcQueue(); }, Math.min(remaining, 2_147_483_647));
             }
-            if (foregroundDrained)
+            if (foregroundDrained && !this.rpcBudget.foregroundWaiting)
                 this._onForegroundDrained?.();
         }
     }
@@ -2229,6 +2294,9 @@ export class RPCTransport {
             this._stopWebSocketHeartbeat(ws);
             const wasClosed = this._closed;
             this._closed = true;
+            for (const request of this._budgetWaiters)
+                request.cancel?.();
+            this._budgetWaiters.clear();
             for (const wake of this._rateLimitWaiters)
                 wake();
             if (this._rateLimitTimer !== null)
@@ -2272,7 +2340,8 @@ export class RPCTransport {
                 this._dispatcher.enqueueProtocol('connection.error', { error: err });
             }
         });
-        this._startWebSocketHeartbeat(ws);
+        if (!this._syncAuxiliary)
+            this._startWebSocketHeartbeat(ws);
     }
     /** 使用 WebSocket 控制帧检测半开连接，不占用 JSON-RPC 并发额度。 */
     _startWebSocketHeartbeat(ws) {
@@ -2365,6 +2434,17 @@ export class RPCTransport {
     }
     /** 路由消息：RPC 响应 / challenge / 事件 / 通知 */
     _routeMessage(message) {
+        const syncMethod = String(message.method ?? '');
+        const syncMeta = isJsonObject(message._meta) ? message._meta : {};
+        if (syncMeta.sync_policy !== undefined || syncMethod.startsWith('event/gateway.sync_')) {
+            const policy = syncMeta.sync_policy;
+            if (isJsonObject(policy) && this._syncAdmission?.parent_connection_id === policy.parent_connection_id
+                && Number.isSafeInteger(policy.version) && Number(policy.version) > Number(this._syncAdmission?.version))
+                this._syncAdmission = { ...policy };
+            this._syncControlObserver?.(syncMeta, syncMethod, message.params ?? {});
+        }
+        if (syncMethod === 'event/gateway.sync_policy_changed' || syncMethod === 'event/gateway.sync_channel_close')
+            return;
         // 入口 debug: 识别消息类型
         const hasId = 'id' in message;
         const methodStr = String(message.method ?? '');
@@ -2550,6 +2630,7 @@ if (!isMainThread && Boolean(workerData?.aunTransportWorker) && parentPort) {
         eventDispatcher: workerDispatcher,
         timeout: Number(workerData.timeout ?? 35_000),
         verifySsl: Boolean(workerData.verifySsl ?? true),
+        syncAuxiliary: Boolean(workerData.syncAuxiliary),
         // Worker 内只让 close handler 经 workerDispatcher 转发一次，主线程负责执行真实回调。
         onDisconnect: () => { },
     });
@@ -2562,6 +2643,7 @@ if (!isMainThread && Boolean(workerData?.aunTransportWorker) && parentPort) {
     actor._onRpcResponse = () => parentPort.postMessage({
         type: 'rpc_response', generation: bridgeGeneration(),
     });
+    actor.setSyncControlObserver((meta, method, params) => parentPort.postMessage({ type: 'event', generation: actor._connectionGeneration, event: '_transport.sync_control', payload: { meta, method, params } }));
     actor.setProtocolMetaObserver((meta) => workerDispatcher.enqueueProtocol('_transport.observer', {
         kind: 'meta_observer', payload: meta,
     }));
@@ -2596,6 +2678,9 @@ if (!isMainThread && Boolean(workerData?.aunTransportWorker) && parentPort) {
             }
             let result;
             switch (command.type) {
+                case 'sync_admission':
+                    actor.setSyncAdmission(command.syncAdmission ?? null);
+                    return;
                 case 'risk_snapshot': {
                     const state = command.riskState;
                     const target = state.target;