@w3lib/solana-batch-call 0.5.0 → 0.7.0

package/dist/rpc.js

@@ -1,3 +1,4 @@
+import { mapPool, sleep } from './util.js';
 /** 节点返回的 JSON-RPC 错误 */
 export class RpcError extends Error {
     code;
@@ -46,7 +47,7 @@ const RATE_LIMITED = /rate.?limit|too many requests/i;
 /** 服务端临时故障的报错（如 -32000 server is busy、-32603 + 503 overloaded） */
 const TRANSIENT = /\bbusy\b|overload|temporar(il)?y|unavailable|try again|timed? ?out|timeout/i;
 /** 节点限制单次 getMultipleAccounts 的账户数（如 “Too many accounts requested”）：缩小每次的账户数后重试，不是节点故障 */
-const TOO_MANY_ACCOUNTS = /too many accounts/i;
+const TOO_MANY_ACCOUNTS = /too many accounts|maximum of \d+ accounts/i;
 /**
  * publicnode 对单次超过 10 个账户的 getMultipleAccounts 返回 HTTP 403 +“Request blocked”（2026-10，而且要等 3 秒多才返回）：
  * 账户数超过 BLOCKED_LIMIT 时直接按它拆分（逐次减半要多等好几轮），还被拒绝再减半；
@@ -55,17 +56,44 @@ const TOO_MANY_ACCOUNTS = /too many accounts/i;
 const REQUEST_BLOCKED = /request blocked/i;
 const BLOCKED_LIMIT = 10;
 const BLOCKED_FLOOR = 8;
-/** 从报错里学到的节点限制，按节点地址共享（同一个节点的多个客户端不用各自再试一遍） */
-const learnedLimits = new Map();
-function learnedFor(url) {
-    let entry = learnedLimits.get(url);
+/** 按节点地址记的表（健康状态、学到的限制、在途请求数）的条目上限，超出时淘汰最早加入的 */
+const MAX_TRACKED_URLS = 1000;
+/** 按节点地址取条目，没有时创建；表的条目数有上限（淘汰最早加入的） */
+function trackedEntry(map, url, create) {
+    let entry = map.get(url);
     if (!entry) {
-        entry = { methods: new Map() };
-        learnedLimits.set(url, entry);
+        entry = create();
+        map.set(url, entry);
+        if (map.size > MAX_TRACKED_URLS) {
+            map.delete(map.keys().next().value);
+        }
     }
     return entry;
 }
-/** 测试用：清空学到的节点限制 */
+/**
+ * 已知节点的限制（2026-10 实测），首次请求就按它拆分，不必先撞一次报错：
+ * publicnode 单次 getMultipleAccounts 最多 10 个账户、一个批量里最多 1 个 getMultipleAccounts，
+ * 超过账户数要等 3 秒多才返回 403
+ */
+function presetLimits(url) {
+    let host = '';
+    try {
+        host = new URL(url).hostname;
+    }
+    catch {
+        // 地址不合法：没有预置限制
+    }
+    if (/^solana[\w-]*\.publicnode\.com$/i.test(host)) {
+        return { methods: new Map([['getMultipleAccounts', 1]]), maxAccounts: BLOCKED_LIMIT };
+    }
+    return { methods: new Map() };
+}
+/** 从报错里学到的节点限制（含预置的已知限制），按节点地址共享（同一个节点的多个客户端不用各自再试一遍） */
+const learnedLimits = new Map();
+function learnedFor(url) {
+    return trackedEntry(learnedLimits, url, () => presetLimits(url));
+}
+/** 测试用：清空学到的节点限制（预置的已知限制在下次创建连接时重新带上） */
 export function resetLearnedLimits() {
     learnedLimits.clear();
 }
@@ -122,14 +150,126 @@ export function isNodeFault(err) {
 let nextId = 1;
 /** 批量请求被拒绝、可以降级为逐条请求的 HTTP 状态 */
 const BATCH_REJECTED_STATUS = new Set([400, 404, 405, 415, 422]);
-/** 节点不支持批量时，多久后重新尝试批量 */
+/** 节点不支持批量 / 限制批量大小时，多久后重新尝试（批量、原来的批量大小） */
 const BATCH_RETRY_AFTER = 10 * 60 * 1000;
+/** 有副作用、不能去重的方法 */
+const WRITE_METHOD = /^(send|requestAirdrop)/;
+/** 429 时 Retry-After 超过这个时间（毫秒）就不等了，直接报错（交给上层换节点） */
+const MAX_RETRY_AFTER = 10_000;
 function isBatchLimitError(message) {
     return !!message && /batch/i.test(message) && /more than \d+|too (large|many|big)|not (allowed|supported)|exceed/i.test(message);
 }
+/**
+ * 429 后的等待时间：有 Retry-After（秒数或 HTTP 日期）时按它，超过 MAX_RETRY_AFTER 时返回 null（不等，直接报错）；
+ * 否则指数退避（500ms 起）加 ±25% 随机抖动，避免同时被限频的请求又同时重试
+ */
+export function retryDelay(attempt, retryAfter) {
+    const header = retryAfter?.trim();
+    if (header) {
+        const seconds = Number(header);
+        const ms = Number.isFinite(seconds) ? seconds * 1000 : Date.parse(header) - Date.now();
+        if (Number.isFinite(ms)) {
+            return ms > MAX_RETRY_AFTER ? null : Math.max(0, ms);
+        }
+    }
+    return Math.round(500 * 2 ** attempt * (0.75 + Math.random() * 0.5));
+}
+/** 合并多个 AbortSignal（AbortSignal.any 不可用的旧环境手动合并） */
+function anySignal(signals) {
+    if (signals.length === 1) {
+        return signals[0];
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any(signals);
+    }
+    const controller = new AbortController();
+    for (const signal of signals) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true, signal: controller.signal });
+    }
+    return controller.signal;
+}
+const slotsByUrl = new Map();
+/** 拿一个并发名额（先来先得）；signal 取消时不再等 */
+function acquireSlot(slots, limit, signal) {
+    if (signal.aborted) {
+        return Promise.reject(signal.reason);
+    }
+    if (slots.active < limit && !slots.waiting.length) {
+        slots.active++;
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const entry = {
+            limit,
+            start: () => {
+                signal.removeEventListener('abort', onAbort);
+                resolve();
+            },
+        };
+        const onAbort = () => {
+            const i = slots.waiting.indexOf(entry);
+            if (i !== -1) {
+                slots.waiting.splice(i, 1);
+                drainSlots(slots);
+            }
+            reject(signal.reason);
+        };
+        slots.waiting.push(entry);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function releaseSlot(slots) {
+    slots.active--;
+    drainSlots(slots);
+}
+function drainSlots(slots) {
+    for (let head = slots.waiting[0]; head && slots.active < head.limit; head = slots.waiting[0]) {
+        slots.waiting.shift();
+        slots.active++;
+        head.start();
+    }
+}
+/** 调用方是否都已取消（没有调用方传 signal 时不会） */
+function abandoned(item) {
+    return item.waiters.every((w) => w.signal?.aborted);
+}
+/** 还需要结果：没有结果、也没被所有调用方放弃 */
+function live(item) {
+    return !item.done && !abandoned(item);
+}
+/** 去重后的结果按调用方各给一份：第一个调用方拿原对象，其余的拿副本（调用方修改结果不会影响别人） */
+function copyResult(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    return typeof structuredClone === 'function' ? structuredClone(value) : JSON.parse(JSON.stringify(value));
+}
+function resolveItem(item, value) {
+    if (item.done)
+        return;
+    item.done = true;
+    item.waiters.forEach((waiter, i) => {
+        waiter.cleanup?.();
+        waiter.resolve(i === 0 ? value : copyResult(value));
+    });
+}
+function rejectItem(item, reason) {
+    if (item.done)
+        return;
+    item.done = true;
+    for (const waiter of item.waiters) {
+        waiter.cleanup?.();
+        waiter.reject(reason);
+    }
+}
 /**
  * 基于 fetch 的 JSON-RPC 传输：同一收集窗口内的调用合并成一个 JSON-RPC 批量请求。
  * 节点不支持批量（返回非数组）或限制批量大小（如 drpc 免费档最多 3 条）时自动降级。
+ * 同一节点地址同时在途的 HTTP 请求数有上限（maxConcurrency，默认 4）；request 的 signal 会传到 fetch
  */
 export class HttpRpc {
     url;
@@ -141,13 +281,19 @@ export class HttpRpc {
     #retries;
     #fetch;
     #maxBatchSize;
-    /** 从报错里学到的限制（按节点地址共享）：单个方法在一个批量里的数量（如 publicnode：getMultipleAccounts 最多 1 个）、单次的账户数 */
+    #maxConcurrency;
+    #dedupe;
+    /** 节点限制批量大小（413、“more than N”）时临时调小的批量大小，到期恢复 maxBatchSize */
+    #batchLimit = null;
+    /** 从报错里学到的限制（按节点地址共享，含预置的已知限制）：单个方法在一个批量里的数量（如 publicnode：getMultipleAccounts 最多 1 个）、单次的账户数 */
     #learned;
     /** options.batch：调用方是否允许批量 */
     #batchOption;
     /** 节点明确表示不支持批量时，在这之前逐条请求（之后重新尝试批量） */
     #batchDisabledUntil = 0;
     #queue = [];
+    /** 队列里可去重的调用（key → 调用），flush 时清空 */
+    #queuedByKey = new Map();
     #timer = null;
     constructor(url, options = {}) {
         this.url = url;
@@ -160,18 +306,23 @@ export class HttpRpc {
         this.#batchWait = options.batchWait ?? 0;
         this.#retries = Math.max(0, options.retries ?? 2);
         this.#fetch = options.fetch ?? ((...args) => fetch(...args));
+        const concurrency = options.maxConcurrency ?? 4;
+        this.#maxConcurrency = concurrency > 0 ? concurrency : Number.POSITIVE_INFINITY;
+        this.#dedupe = options.dedupe ?? true;
     }
-    request(method, params = []) {
+    request(method, params = [], options) {
+        const signal = options?.signal;
         if (method === 'getMultipleAccounts' && Array.isArray(params[0])) {
-            return this.#getMultipleAccounts(params);
+            return this.#getMultipleAccounts(params, signal);
         }
-        return this.#enqueue(method, params);
+        return this.#enqueue(method, params, signal);
     }
     /**
      * getMultipleAccounts：节点限制单次账户数时（“Too many accounts requested”），减半后分多次请求、合并结果，
-     * 并记下上限，之后直接按上限拆分。合并后 context.slot 取最小值
+     * 并记下上限，之后直接按上限拆分。合并后 context.slot 取最小值。
+     * 拆分后的子请求用并发池发出：一个失败后不再发后面的（节点多半在限频或拒绝），取消后也不再发
      */
-    async #getMultipleAccounts(params) {
+    async #getMultipleAccounts(params, signal) {
         const [addresses, ...rest] = params;
         const max = this.#learned.maxAccounts;
         if (max !== undefined && addresses.length > max) {
@@ -179,7 +330,10 @@ export class HttpRpc {
             for (let i = 0; i < addresses.length; i += max) {
                 parts.push(addresses.slice(i, i + max));
             }
-            const results = (await Promise.all(parts.map((part) => this.#getMultipleAccounts([part, ...rest]))));
+            // 同时排队的子请求数：够把所有并发名额用满即可（每个 HTTP 请求能带几个 getMultipleAccounts × 并发上限）
+            const perPost = this.#batch ? (this.#learned.methods.get('getMultipleAccounts') ?? this.#batchSize) : 1;
+            const limit = Number.isFinite(this.#maxConcurrency) ? this.#maxConcurrency * perPost : parts.length;
+            const results = (await mapPool(parts, limit, (part) => this.#getMultipleAccounts([part, ...rest], signal)));
             const slots = results.map((r) => r?.context?.slot).filter((slot) => typeof slot === 'number');
             return {
                 ...results[0],
@@ -188,15 +342,17 @@ export class HttpRpc {
             };
         }
         try {
-            return await this.#enqueue('getMultipleAccounts', params);
+            return await this.#enqueue('getMultipleAccounts', params, signal);
         }
         catch (err) {
             const tooMany = err instanceof RpcError && TOO_MANY_ACCOUNTS.test(err.message) && addresses.length > 1;
             const blocked = err instanceof RpcError && REQUEST_BLOCKED.test(err.message) && addresses.length > BLOCKED_FLOOR;
             if (tooMany || blocked) {
-                const next = blocked && addresses.length > BLOCKED_LIMIT ? BLOCKED_LIMIT : Math.floor(addresses.length / 2);
+                // publicnode（2026-10）：“A maximum of 10 accounts is allowed”，报错里直接给出上限
+                const stated = Number(/maximum of (\d+) accounts/i.exec(err.message)?.[1]);
+                const next = stated >= 1 ? stated : blocked && addresses.length > BLOCKED_LIMIT ? BLOCKED_LIMIT : Math.floor(addresses.length / 2);
                 this.#learned.maxAccounts = Math.max(1, Math.min(this.#learned.maxAccounts ?? Number.POSITIVE_INFINITY, next));
-                return this.#getMultipleAccounts(params);
+                return this.#getMultipleAccounts(params, signal);
             }
             throw err;
         }
@@ -205,10 +361,50 @@ export class HttpRpc {
     get #batch() {
         return this.#batchOption && Date.now() >= this.#batchDisabledUntil;
     }
-    #enqueue(method, params) {
+    /** 当前的批量大小：节点限制过批量大小时，冷却期内用调小后的值，到期恢复 */
+    get #batchSize() {
+        const limit = this.#batchLimit;
+        if (limit && Date.now() < limit.until) {
+            return limit.size;
+        }
+        this.#batchLimit = null;
+        return this.#maxBatchSize;
+    }
+    /** 节点限制批量大小：10 分钟内按 size 分批，之后恢复（偶发的 413 不会永久缩小批量） */
+    #limitBatchSize(size) {
+        this.#batchLimit = { size: Math.max(1, Math.min(size, this.#batchSize)), until: Date.now() + BATCH_RETRY_AFTER };
+    }
+    #enqueue(method, params, signal) {
+        if (signal?.aborted) {
+            return Promise.reject(signal.reason);
+        }
         return new Promise((resolve, reject) => {
-            this.#queue.push({ method, params, resolve: resolve, reject });
-            if (!this.#batch || this.#queue.length >= this.#maxBatchSize) {
+            const waiter = { resolve: resolve, reject, signal };
+            let key;
+            if (this.#dedupe && !WRITE_METHOD.test(method)) {
+                try {
+                    key = `${method}\u0000${JSON.stringify(params)}`;
+                }
+                catch {
+                    key = undefined; // 参数不能序列化（如 bigint）：不去重，发送时照常报错
+                }
+            }
+            const existing = key === undefined ? undefined : this.#queuedByKey.get(key);
+            const item = existing ?? { method, params, key, waiters: [], done: false, posts: new Set() };
+            item.waiters.push(waiter);
+            if (signal) {
+                const onAbort = () => this.#abortWaiter(item, waiter);
+                signal.addEventListener('abort', onAbort, { once: true });
+                waiter.cleanup = () => signal.removeEventListener('abort', onAbort);
+            }
+            if (existing) {
+                return; // 同一批里相同的调用：共用一个结果
+            }
+            this.#queue.push(item);
+            if (key !== undefined) {
+                this.#queuedByKey.set(key, item);
+            }
+            if (!this.#batch || this.#queue.length >= this.#batchSize) {
                 this.#flush();
             }
             else if (!this.#timer) {
@@ -216,6 +412,31 @@ export class HttpRpc {
             }
         });
     }
+    /**
+     * 调用方取消：立即 reject 这个调用方；同一调用的其他调用方都取消时，还在排队的移出队列，
+     * 已发出的 HTTP 请求在所有成员都被取消后中止
+     */
+    #abortWaiter(item, waiter) {
+        waiter.cleanup?.();
+        waiter.reject(waiter.signal?.reason);
+        if (item.done || !abandoned(item)) {
+            return;
+        }
+        const index = this.#queue.indexOf(item);
+        if (index !== -1) {
+            this.#queue.splice(index, 1);
+            if (item.key !== undefined && this.#queuedByKey.get(item.key) === item) {
+                this.#queuedByKey.delete(item.key);
+            }
+            item.done = true;
+            return;
+        }
+        for (const post of item.posts) {
+            if (post.items.every(abandoned)) {
+                post.controller.abort(waiter.signal?.reason);
+            }
+        }
+    }
     #flush() {
         if (this.#timer) {
             clearTimeout(this.#timer);
@@ -223,19 +444,21 @@ export class HttpRpc {
         }
         const queue = this.#queue;
         this.#queue = [];
+        this.#queuedByKey = new Map();
         for (const chunk of this.#split(queue)) {
             void this.#dispatch(chunk);
         }
     }
-    /** 按 maxBatchSize 和各方法的数量限制分批（保持顺序；不受限的方法照常合并） */
+    /** 按批量大小和各方法的数量限制分批（保持顺序；不受限的方法照常合并） */
     #split(items) {
         const chunks = [];
+        const batchSize = this.#batchSize;
         let current = [];
         let counts = new Map();
         for (const item of items) {
             const limit = this.#learned.methods.get(item.method);
             const count = counts.get(item.method) ?? 0;
-            if (current.length >= this.#maxBatchSize || (limit !== undefined && count >= limit)) {
+            if (current.length >= batchSize || (limit !== undefined && count >= limit)) {
                 chunks.push(current);
                 current = [];
                 counts = new Map();
@@ -260,24 +483,32 @@ export class HttpRpc {
             return false;
         }
         this.#learned.methods.set(method, limit);
-        await Promise.all(this.#split(items).map((chunk) => this.#dispatch(chunk)));
+        await this.#redispatch(items);
         return true;
     }
     /** retriedServerError：这一批已经因 5xx + JSON-RPC 错误重试过一次 */
-    async #dispatch(items, retriedServerError = false) {
+    async #dispatch(chunk, retriedServerError = false) {
+        // 已被所有调用方取消的不再发
+        const items = chunk.filter(live);
+        if (!items.length) {
+            return;
+        }
         if (items.length === 1 || !this.#batch) {
             await Promise.all(items.map((item) => this.#single(item)));
             return;
         }
         const ids = items.map(() => nextId++);
-        let body;
+        let posted;
         try {
-            body = await this.#post(items.map((item, i) => ({ jsonrpc: '2.0', id: ids[i], method: item.method, params: item.params })));
+            posted = await this.#post(items.map((item, i) => ({ jsonrpc: '2.0', id: ids[i], method: item.method, params: item.params })), items);
         }
         catch (err) {
+            if (items.every((item) => !live(item))) {
+                return; // 调用方都取消了（各自已经 reject）
+            }
             if (err instanceof HttpError && err.status === 413 && items.length > 1) {
-                // 请求体太大：批量减半后重发
-                this.#maxBatchSize = Math.max(1, Math.floor(items.length / 2));
+                // 请求体太大：批量减半后重发（一段时间后恢复原来的批量大小）
+                this.#limitBatchSize(Math.floor(items.length / 2));
                 await this.#redispatch(items);
                 return;
             }
@@ -296,19 +527,25 @@ export class HttpRpc {
                     await this.#dispatch(items, true);
                     return;
                 }
-                const [first, ...rest] = items;
+                // 试探用还需要结果的第一条（期间被取消的不再发）
+                const remaining = items.filter(live);
+                if (!remaining.length) {
+                    return;
+                }
+                const [first, ...rest] = remaining;
                 if (await this.#single(first)) {
                     this.#disableBatch();
                     await Promise.all(rest.map((item) => this.#single(item)));
                 }
                 else {
-                    rest.forEach((item) => item.reject(err));
+                    rest.forEach((item) => rejectItem(item, err));
                 }
                 return;
             }
-            items.forEach((item) => item.reject(err));
+            items.forEach((item) => rejectItem(item, err));
             return;
         }
+        const { body } = posted;
         if (!Array.isArray(body)) {
             const error = body?.error;
             // 单个方法在批量里的数量超限（整批被拒）：按限制重新分批，不当成节点问题
@@ -318,7 +555,7 @@ export class HttpRpc {
             const rpcError = new RpcError(error?.message ?? 'Invalid JSON-RPC batch response', error?.code, error?.data);
             // 限频 / 鉴权等节点问题：原样报错，不降级（降级成逐条请求只会让限频更严重）
             if (rpcError.nodeFault) {
-                items.forEach((item) => item.reject(rpcError));
+                items.forEach((item) => rejectItem(item, rpcError));
                 return;
             }
             // 整批被拒（不是账户数超限）：节点多半不支持批量（各家错误码不同：-32600 / -32601 / -32700 …），
@@ -338,11 +575,11 @@ export class HttpRpc {
         }
         const limited = body.find((res) => isBatchLimitError(res.error?.message));
         if (limited) {
-            // 如 “Batch of more than 3 requests are not allowed”：按限制缩小批量后重发；
+            // 如 “Batch of more than 3 requests are not allowed”：按限制缩小批量后重发（一段时间后恢复）；
             // 限制不小于当前批量（节点的上限判断有偏差）或解析不出数字时，降级为逐条请求，避免无限重发
             const max = Number(/more than (\d+)/i.exec(limited.error?.message ?? '')?.[1]);
             if (Number.isFinite(max) && max > 1 && max < items.length) {
-                this.#maxBatchSize = max;
+                this.#limitBatchSize(max);
                 await this.#redispatch(items);
             }
             else {
@@ -365,23 +602,31 @@ export class HttpRpc {
             }
         });
         if (limitedItems.length) {
-            await new Promise((r) => setTimeout(r, 500));
+            const wait = retryDelay(0, posted.retryAfter);
+            if (wait === null) {
+                limitedItems.forEach((item) => settle(item, byId.get(ids[items.indexOf(item)])));
+                return;
+            }
+            await sleep(wait);
             await Promise.all(limitedItems.map((item) => this.#single(item, 0)));
         }
     }
-    /** 按当前的 maxBatchSize 重新分批发送（每批都比原来小，不会无限循环） */
+    /** 按当前的批量大小重新分批发送（每批都比原来小，不会无限循环） */
     async #redispatch(items) {
-        await Promise.all(this.#split(items).map((chunk) => this.#dispatch(chunk)));
+        await Promise.all(this.#split(items.filter(live)).map((chunk) => this.#dispatch(chunk)));
     }
     /** 逐条发送一个调用；返回是否拿到了结果（没有出错） */
     async #single(item, retries = this.#retries) {
+        if (!live(item)) {
+            return false;
+        }
         try {
-            const body = (await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params }, retries));
+            const { body } = await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params }, [item], retries);
             settle(item, body);
             return !body?.error;
         }
         catch (err) {
-            item.reject(err);
+            rejectItem(item, err);
             return false;
         }
     }
@@ -389,62 +634,109 @@ export class HttpRpc {
     #disableBatch() {
         this.#batchDisabledUntil = Date.now() + BATCH_RETRY_AFTER;
     }
-    async #post(payload, retries = this.#retries) {
-        for (let attempt = 0;; attempt++) {
-            let response;
-            try {
-                response = await this.#fetch(this.url, {
-                    method: 'POST',
-                    headers: this.#headers,
-                    body: JSON.stringify(payload),
-                    signal: this.#timeout > 0 && Number.isFinite(this.#timeout) ? AbortSignal.timeout(this.#timeout) : undefined,
-                });
-            }
-            catch (err) {
-                // AbortSignal.timeout 触发时是 TimeoutError（DOMException）
-                const timeout = err?.name === 'TimeoutError';
-                throw new HttpError(`Request to ${this.#safeUrl} failed: ${err?.message ?? err}`, undefined, timeout);
-            }
-            if (response.status === 429 && attempt < retries) {
-                await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
-                continue;
-            }
-            let text;
-            try {
-                text = await response.text();
-            }
-            catch (err) {
-                // 读响应体时超时或连接中断：同样包装成 HttpError（原生 DOMException / TypeError 不会被当成可恢复的节点问题）
-                const timeout = err?.name === 'TimeoutError';
-                throw new HttpError(`Reading response from ${this.#safeUrl} failed: ${err?.message ?? err}`, response.status, timeout);
-            }
-            let body;
-            try {
-                body = parseJson(text);
-            }
-            catch {
-                throw new HttpError(`Invalid JSON from ${this.#safeUrl} (HTTP ${response.status})`, response.status);
-            }
-            // 非 2xx 但返回了 JSON-RPC 结构（如 403 Access forbidden、drpc 的 500 + 批量错误数组）：交给上层解析
-            if (!response.ok && !Array.isArray(body) && !body?.error) {
-                throw new HttpError(`HTTP ${response.status} from ${this.#safeUrl}`, response.status);
-            }
-            // 5xx + 单个 JSON-RPC 错误：
-            // - 繁忙、过载等明确的临时故障：按 HTTP 错误处理，直接换节点（不重试、不逐条，不给过载的节点加量）
-            // - -32603 internal error：含义不明确，标记 rpcError，由 #dispatch 判断是临时故障还是节点用 5xx 拒绝批量
-            // 其他错误（方法数量超限、账户数超限、参数错误、minContextSlot、限频等）照常交给上层按类型处理
-            const bodyError = response.status >= 500 && !Array.isArray(body) ? body?.error : undefined;
-            const kind = bodyError ? classifyRpcError(bodyError.code, bodyError.message ?? '') : undefined;
-            if (kind === 'transient' || kind === 'internal') {
-                const message = bodyError?.message;
-                throw new HttpError(`HTTP ${response.status} from ${this.#safeUrl}${message ? `: ${message}` : ''}`, response.status, false, kind === 'internal');
-            }
-            // 有的节点限频时返回 HTTP 200 + JSON-RPC 错误码 429：同样退避重试
-            if (attempt < retries && isRateLimited(body)) {
-                await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
-                continue;
+    /**
+     * 发一次 HTTP 请求（含 429 退避重试）。items 是这次请求的成员：都被调用方取消时中止 fetch / 退避等待，抛出取消的 reason。
+     * 同一节点地址同时在途的请求数受 maxConcurrency 限制：排队最多等 timeout 毫秒（超时抛 HttpError timeout，交给上层换节点），发出后重新计时
+     */
+    async #post(payload, items, retries = this.#retries) {
+        const post = { items, controller: new AbortController() };
+        const cancel = post.controller.signal;
+        items.forEach((item) => item.posts.add(post));
+        const slots = trackedEntry(slotsByUrl, this.url, () => ({ active: 0, waiting: [] }));
+        try {
+            for (let attempt = 0;; attempt++) {
+                const limited = this.#timeout > 0 && Number.isFinite(this.#timeout);
+                // 排队等名额也受 timeout 限制：同一地址的其他连接把名额占住不放（如 timeout: 0 的请求挂住）时不会无限等下去
+                const queueTimeout = limited ? AbortSignal.timeout(this.#timeout) : null;
+                try {
+                    await acquireSlot(slots, this.#maxConcurrency, queueTimeout ? anySignal([cancel, queueTimeout]) : cancel);
+                }
+                catch (err) {
+                    if (cancel.aborted) {
+                        throw cancel.reason;
+                    }
+                    throw new HttpError(`Request to ${this.#safeUrl} timed out waiting for a free connection slot (maxConcurrency ${this.#maxConcurrency})`, undefined, true);
+                }
+                let response;
+                let text = '';
+                /** 429 后要等多久再重试；null 表示不重试 */
+                let wait = null;
+                try {
+                    const signal = limited ? anySignal([cancel, AbortSignal.timeout(this.#timeout)]) : cancel;
+                    try {
+                        response = await this.#fetch(this.url, { method: 'POST', headers: this.#headers, body: JSON.stringify(payload), signal });
+                    }
+                    catch (err) {
+                        if (cancel.aborted) {
+                            throw cancel.reason;
+                        }
+                        // AbortSignal.timeout 触发时是 TimeoutError（DOMException）
+                        const timeout = err?.name === 'TimeoutError';
+                        throw new HttpError(`Request to ${this.#safeUrl} failed: ${err?.message ?? err}`, undefined, timeout);
+                    }
+                    if (response.status === 429 && attempt < retries) {
+                        wait = retryDelay(attempt, response.headers?.get?.('retry-after'));
+                    }
+                    if (wait !== null) {
+                        void response.body?.cancel().catch(() => { });
+                    }
+                    else {
+                        try {
+                            text = await response.text();
+                        }
+                        catch (err) {
+                            if (cancel.aborted) {
+                                throw cancel.reason;
+                            }
+                            // 读响应体时超时或连接中断：同样包装成 HttpError（原生 DOMException / TypeError 不会被当成可恢复的节点问题）
+                            const timeout = err?.name === 'TimeoutError';
+                            throw new HttpError(`Reading response from ${this.#safeUrl} failed: ${err?.message ?? err}`, response.status, timeout);
+                        }
+                    }
+                }
+                finally {
+                    releaseSlot(slots);
+                }
+                if (wait !== null) {
+                    // 退避期间不占并发名额
+                    await sleep(wait, cancel);
+                    continue;
+                }
+                let body;
+                try {
+                    body = parseJson(text);
+                }
+                catch {
+                    throw new HttpError(`Invalid JSON from ${this.#safeUrl} (HTTP ${response.status})`, response.status);
+                }
+                // 非 2xx 但返回了 JSON-RPC 结构（如 403 Access forbidden、drpc 的 500 + 批量错误数组）：交给上层解析
+                if (!response.ok && !Array.isArray(body) && !body?.error) {
+                    throw new HttpError(`HTTP ${response.status} from ${this.#safeUrl}`, response.status);
+                }
+                // 5xx + 单个 JSON-RPC 错误：
+                // - 繁忙、过载等明确的临时故障：按 HTTP 错误处理，直接换节点（不重试、不逐条，不给过载的节点加量）
+                // - -32603 internal error：含义不明确，标记 rpcError，由 #dispatch 判断是临时故障还是节点用 5xx 拒绝批量
+                // 其他错误（方法数量超限、账户数超限、参数错误、minContextSlot、限频等）照常交给上层按类型处理
+                const bodyError = response.status >= 500 && !Array.isArray(body) ? body?.error : undefined;
+                const kind = bodyError ? classifyRpcError(bodyError.code, bodyError.message ?? '') : undefined;
+                if (kind === 'transient' || kind === 'internal') {
+                    const message = bodyError?.message;
+                    throw new HttpError(`HTTP ${response.status} from ${this.#safeUrl}${message ? `: ${message}` : ''}`, response.status, false, kind === 'internal');
+                }
+                const retryAfter = response.headers?.get?.('retry-after') ?? null;
+                // 有的节点限频时返回 HTTP 200 + JSON-RPC 错误码 429：同样退避重试
+                if (attempt < retries && isRateLimited(body)) {
+                    const wait = retryDelay(attempt, retryAfter);
+                    if (wait !== null) {
+                        await sleep(wait, cancel);
+                        continue;
+                    }
+                }
+                return { body, retryAfter };
             }
-            return body;
+        }
+        finally {
+            items.forEach((item) => item.posts.delete(post));
         }
     }
 }
@@ -486,13 +778,13 @@ function isRateLimited(body) {
 }
 function settle(item, response) {
     if (!response) {
-        item.reject(new HttpError('Missing response in JSON-RPC batch'));
+        rejectItem(item, new HttpError('Missing response in JSON-RPC batch'));
     }
     else if (response.error) {
-        item.reject(new RpcError(response.error.message ?? 'JSON-RPC error', response.error.code, response.error.data));
+        rejectItem(item, new RpcError(response.error.message ?? 'JSON-RPC error', response.error.code, response.error.data));
     }
     else {
-        item.resolve(response.result);
+        resolveItem(item, response.result);
     }
 }
 const requestListeners = new Set();
@@ -549,7 +841,6 @@ function unwrap(node) {
 // 节点健康状态按节点共享（模块级）：客户端重建后，刚出过错的节点仍排在后面。URL 节点按完整 URL，其他按对象
 const healthByUrl = new Map();
 let healthByObject = new WeakMap();
-const MAX_TRACKED_URLS = 1000;
 /** 连续超时这么多次才冷却（单次超时多半只是这次请求慢） */
 const TIMEOUTS_BEFORE_COOLDOWN = 3;
 /** 健康状态的 key：HttpRpc 按完整 URL（不同连接对象共享），其他节点按对象（去掉校验层） */
@@ -560,15 +851,7 @@ function healthKeyOf(node) {
 /** 每次用时按 key 从全局表里取：表淘汰条目后，各实例仍取到同一个对象 */
 function healthOf(key) {
     if (typeof key === 'string') {
-        let health = healthByUrl.get(key);
-        if (!health) {
-            health = { failedAt: 0, timeouts: 0 };
-            healthByUrl.set(key, health);
-            if (healthByUrl.size > MAX_TRACKED_URLS) {
-                healthByUrl.delete(healthByUrl.keys().next().value);
-            }
-        }
-        return health;
+        return trackedEntry(healthByUrl, key, () => ({ failedAt: 0, timeouts: 0 }));
     }
     let health = healthByObject.get(key);
     if (!health) {
@@ -606,17 +889,23 @@ export class FallbackRpc {
         this.#labels = nodes.map(nodeLabel);
         this.#healthKeys = nodes.map(healthKeyOf);
     }
-    async request(method, params) {
+    async request(method, params, options) {
+        const signal = options?.signal;
         const errors = [];
         const order = this.#order();
         for (let attempt = 0; attempt < order.length; attempt++) {
+            // 已取消：不再发、不再换节点
+            if (signal?.aborted) {
+                throw signal.reason;
+            }
             const index = order[attempt];
             const node = this.nodes[index];
             const label = this.#labels[index];
             const health = healthOf(this.#healthKeys[index]);
             const started = Date.now();
             try {
-                const result = await node.request(method, params);
+                // 没有 signal 时按两个参数调用（自定义传输不受影响）
+                const result = await (signal ? node.request(method, params, { signal }) : node.request(method, params));
                 health.failedAt = 0;
                 health.timeouts = 0;
                 emit({ node: label, method, ms: Date.now() - started, ok: true, attempt });
@@ -624,6 +913,10 @@ export class FallbackRpc {
             }
             catch (err) {
                 emit({ node: label, method, ms: Date.now() - started, ok: false, error: err, attempt });
+                // 调用方取消导致的失败：不算节点故障，也不换节点
+                if (signal?.aborted) {
+                    throw signal.reason;
+                }
                 if (!isNodeFault(err)) {
                     throw err;
                 }