@w3lib/solana-batch-call 0.2.0 → 0.2.2

package/src/rpc.ts

@@ -17,28 +17,67 @@ export class RpcError extends Error {
     this.name = 'RpcError'
     this.code = code
     this.data = data
+    const kind = classifyRpcError(code, message)
     this.nodeFault =
       code === 403 ||
-      code === 429 ||
       code === -32005 ||
-      // 节点高度没到 minContextSlot：换节点可能成功
-      code === MIN_CONTEXT_SLOT_NOT_REACHED ||
-      /minimum context slot/i.test(message) ||
-      /forbidden|blocked|personal token|api.?key|rate.?limit|too many|not allowed|unauthori[sz]ed|limit exceeded|disabled|not available|not supported/i.test(message)
+      // 节点高度没到 minContextSlot、限频、服务端临时故障（繁忙、过载、暂不可用、超时）：换节点可能成功；
+      // 临时故障也不应据此关闭批量（降级只会加重负载）
+      kind === 'min-slot' ||
+      kind === 'rate-limited' ||
+      kind === 'transient' ||
+      (/forbidden|blocked|personal token|api.?key|too many|not allowed|unauthori[sz]ed|limit exceeded|disabled|not available|not supported/i.test(message) &&
+        kind !== 'too-many-accounts')
   }
 }
 
+/**
+ * JSON-RPC 错误的分类（RpcError.nodeFault、HTTP 5xx 的处理共用，避免两份清单各自维护）：
+ * - method-limit / too-many-accounts：节点对批量 / 单次账户数的限制，按限制重新分批或缩小
+ * - invalid-params：参数错误（-32602），确定性的
+ * - min-slot / rate-limited / transient：节点落后、限频、服务端临时故障，换节点
+ * - internal：-32603 internal error，含义不明确（可能是临时故障，也可能是节点拒绝批量）
+ */
+type RpcErrorKind = 'method-limit' | 'too-many-accounts' | 'invalid-params' | 'min-slot' | 'rate-limited' | 'transient' | 'internal' | 'other'
+
+function classifyRpcError(code: number | undefined, message: string): RpcErrorKind {
+  if (METHOD_LIMIT.test(message)) return 'method-limit'
+  if (TOO_MANY_ACCOUNTS.test(message)) return 'too-many-accounts'
+  if (code === -32602) return 'invalid-params'
+  if (code === MIN_CONTEXT_SLOT_NOT_REACHED || /minimum context slot/i.test(message)) return 'min-slot'
+  if (code === 429 || RATE_LIMITED.test(message)) return 'rate-limited'
+  if (TRANSIENT.test(message)) return 'transient'
+  if (code === -32603) return 'internal'
+  return 'other'
+}
+
+/** 节点限制单个方法在批量里的数量（如 publicnode：“Maximum number of 'getMultipleAccounts' calls in a batch request is 1”） */
+const METHOD_LIMIT = /maximum number of '([^']+)' calls in a batch request is (\d+)/i
+
+/** 限频的报错 */
+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
+
 /** HTTP 层错误（非 2xx、网络错误、超时） */
 export class HttpError extends Error {
   readonly status: number | undefined
   /** 请求超时（HttpRpcOptions.timeout） */
   readonly timeout: boolean
 
-  constructor(message: string, status?: number, timeout = false) {
+  /** 5xx 的响应体是 JSON-RPC 错误（服务端故障，或节点用 5xx 拒绝批量请求） */
+  readonly rpcError: boolean
+
+  constructor(message: string, status?: number, timeout = false, rpcError = false) {
     super(message)
     this.name = 'HttpError'
     this.status = status
     this.timeout = timeout
+    this.rpcError = rpcError
   }
 }
 
@@ -118,6 +157,9 @@ let nextId = 1
 /** 批量请求被拒绝、可以降级为逐条请求的 HTTP 状态 */
 const BATCH_REJECTED_STATUS = new Set([400, 404, 405, 415, 422])
 
+/** 节点不支持批量时，多久后重新尝试批量 */
+const BATCH_RETRY_AFTER = 10 * 60 * 1000
+
 function isBatchLimitError(message: string | undefined): boolean {
   return !!message && /batch/i.test(message) && /more than \d+|too (large|many|big)|not (allowed|supported)|exceed/i.test(message)
 }
@@ -136,7 +178,14 @@ export class HttpRpc implements RpcTransport {
   readonly #retries: number
   readonly #fetch: typeof fetch
   #maxBatchSize: number
-  #batch: boolean
+  /** 节点对单个方法在一个批量里的数量限制（如 publicnode：getMultipleAccounts 最多 1 个），从报错里学到 */
+  readonly #methodLimits = new Map<string, number>()
+  /** options.batch：调用方是否允许批量 */
+  readonly #batchOption: boolean
+  /** 节点明确表示不支持批量时，在这之前逐条请求（之后重新尝试批量） */
+  #batchDisabledUntil = 0
+  /** 节点限制单次 getMultipleAccounts 的账户数时学到的上限 */
+  #maxAccounts: number | undefined
   #queue: Pending[] = []
   #timer: ReturnType<typeof setTimeout> | null = null
 
@@ -146,13 +195,59 @@ export class HttpRpc implements RpcTransport {
     this.#timeout = options.timeout ?? 10_000
     this.#headers = { 'content-type': 'application/json', ...options.headers }
     this.#maxBatchSize = Math.max(1, options.maxBatchSize ?? 20)
-    this.#batch = options.batch ?? true
+    this.#batchOption = options.batch ?? true
     this.#batchWait = options.batchWait ?? 0
     this.#retries = Math.max(0, options.retries ?? 2)
     this.#fetch = options.fetch ?? ((...args) => fetch(...args))
   }
 
   request<T = unknown>(method: string, params: readonly unknown[] = []): Promise<T> {
+    if (method === 'getMultipleAccounts' && Array.isArray(params[0])) {
+      return this.#getMultipleAccounts(params) as Promise<T>
+    }
+    return this.#enqueue<T>(method, params)
+  }
+
+  /**
+   * getMultipleAccounts：节点限制单次账户数时（“Too many accounts requested”），减半后分多次请求、合并结果，
+   * 并记下上限，之后直接按上限拆分。合并后 context.slot 取最小值
+   */
+  async #getMultipleAccounts(params: readonly unknown[]): Promise<unknown> {
+    const [addresses, ...rest] = params as [unknown[], ...unknown[]]
+    const max = this.#maxAccounts
+    if (max !== undefined && addresses.length > max) {
+      const parts: unknown[][] = []
+      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])))) as Array<{
+        context?: { slot?: number }
+        value?: unknown[]
+      }>
+      const slots = results.map((r) => r?.context?.slot).filter((slot): slot is number => typeof slot === 'number')
+      return {
+        ...results[0],
+        context: { ...results[0]?.context, ...(slots.length ? { slot: Math.min(...slots) } : {}) },
+        value: results.flatMap((r) => r?.value ?? []),
+      }
+    }
+    try {
+      return await this.#enqueue('getMultipleAccounts', params)
+    } catch (err) {
+      if (err instanceof RpcError && TOO_MANY_ACCOUNTS.test(err.message) && addresses.length > 1) {
+        this.#maxAccounts = Math.max(1, Math.min(this.#maxAccounts ?? Number.POSITIVE_INFINITY, Math.floor(addresses.length / 2)))
+        return this.#getMultipleAccounts(params)
+      }
+      throw err
+    }
+  }
+
+  /** 是否合并成批量请求：调用方允许，且不在 “节点不支持批量” 的冷却期内 */
+  get #batch(): boolean {
+    return this.#batchOption && Date.now() >= this.#batchDisabledUntil
+  }
+
+  #enqueue<T>(method: string, params: readonly unknown[]): Promise<T> {
     return new Promise<T>((resolve, reject) => {
       this.#queue.push({ method, params, resolve: resolve as (value: unknown) => void, reject })
       if (!this.#batch || this.#queue.length >= this.#maxBatchSize) {
@@ -170,12 +265,51 @@ export class HttpRpc implements RpcTransport {
     }
     const queue = this.#queue
     this.#queue = []
-    for (let i = 0; i < queue.length; i += this.#maxBatchSize) {
-      void this.#dispatch(queue.slice(i, i + this.#maxBatchSize))
+    for (const chunk of this.#split(queue)) {
+      void this.#dispatch(chunk)
+    }
+  }
+
+  /** 按 maxBatchSize 和各方法的数量限制分批（保持顺序；不受限的方法照常合并） */
+  #split(items: readonly Pending[]): Pending[][] {
+    const chunks: Pending[][] = []
+    let current: Pending[] = []
+    let counts = new Map<string, number>()
+    for (const item of items) {
+      const limit = this.#methodLimits.get(item.method)
+      const count = counts.get(item.method) ?? 0
+      if (current.length >= this.#maxBatchSize || (limit !== undefined && count >= limit)) {
+        chunks.push(current)
+        current = []
+        counts = new Map()
+      }
+      current.push(item)
+      counts.set(item.method, (counts.get(item.method) ?? 0) + 1)
     }
+    if (current.length) {
+      chunks.push(current)
+    }
+    return chunks
   }
 
-  async #dispatch(items: Pending[]): Promise<void> {
+  /**
+   * 报错是 “某方法在批量里的数量超限” 时（如 “Maximum number of 'getMultipleAccounts' calls in a batch request is 1”），
+   * 记下限制并按限制重新分批，返回 true；限制解析不出或这批本来就没超限（避免无限重发）时返回 false
+   */
+  async #retryWithMethodLimit(items: Pending[], message: string | undefined): Promise<boolean> {
+    const match = METHOD_LIMIT.exec(message ?? '')
+    const method = match?.[1]
+    const limit = Number(match?.[2])
+    if (!method || !Number.isFinite(limit) || limit < 1 || items.filter((item) => item.method === method).length <= limit) {
+      return false
+    }
+    this.#methodLimits.set(method, limit)
+    await Promise.all(this.#split(items).map((chunk) => this.#dispatch(chunk)))
+    return true
+  }
+
+  /** retriedServerError：这一批已经因 5xx + JSON-RPC 错误重试过一次 */
+  async #dispatch(items: Pending[], retriedServerError = false): Promise<void> {
     if (items.length === 1 || !this.#batch) {
       await Promise.all(items.map((item) => this.#single(item)))
       return
@@ -198,23 +332,53 @@ export class HttpRpc implements RpcTransport {
         await Promise.all(items.map((item) => this.#single(item)))
         return
       }
+      // 5xx + -32603（含义不明确：临时故障，或节点用 5xx 拒绝批量）：先原样重试一次批量（偶发故障这次就成功了，不降级）；
+      // 仍然失败时只用第一条单独试探——成功说明是批量本身被拒，暂停批量（10 分钟后重试）并逐条发送其余的；
+      // 失败则是临时故障，其余的直接报错（换节点），不给出问题的节点加量
+      if (err instanceof HttpError && err.rpcError && items.length > 1) {
+        if (!retriedServerError) {
+          await this.#dispatch(items, true)
+          return
+        }
+        const [first, ...rest] = items as [Pending, ...Pending[]]
+        if (await this.#single(first)) {
+          this.#disableBatch()
+          await Promise.all(rest.map((item) => this.#single(item)))
+        } else {
+          rest.forEach((item) => item.reject(err))
+        }
+        return
+      }
       items.forEach((item) => item.reject(err))
       return
     }
     if (!Array.isArray(body)) {
       const error = (body as RpcResponse)?.error
+      // 单个方法在批量里的数量超限（整批被拒）：按限制重新分批，不当成节点问题
+      if (await this.#retryWithMethodLimit(items, error?.message)) {
+        return
+      }
       const rpcError = new RpcError(error?.message ?? 'Invalid JSON-RPC batch response', error?.code, error?.data)
       // 限频 / 鉴权等节点问题：原样报错，不降级（降级成逐条请求只会让限频更严重）
       if (rpcError.nodeFault) {
         items.forEach((item) => item.reject(rpcError))
         return
       }
-      // 其他（如 -32600 invalid request）：节点不支持批量，降级为逐条请求
-      this.#disableBatch()
+      // 整批被拒（不是账户数超限）：节点多半不支持批量（各家错误码不同：-32600 / -32601 / -32700 …），
+      // 一段时间内改为逐条请求（10 分钟后重新尝试批量，偶发的错误不会永久关闭）；不关的话每批都要先失败一次再逐条重发。
+      // 账户数超限只把这一批逐条重发（由 HTTP 层按节点缩小单次读取数量）
+      if (!TOO_MANY_ACCOUNTS.test(error?.message ?? '')) {
+        this.#disableBatch()
+      }
       await Promise.all(items.map((item) => this.#single(item)))
       return
     }
     const byId = new Map((body as RpcResponse[]).map((res) => [res.id, res]))
+    // 有的节点把 “方法数量超限” 放在批量结果的某一项里
+    const methodLimited = (body as RpcResponse[]).find((res) => METHOD_LIMIT.test(res.error?.message ?? ''))
+    if (methodLimited && (await this.#retryWithMethodLimit(items, methodLimited.error?.message))) {
+      return
+    }
     const limited = (body as RpcResponse[]).find((res) => isBatchLimitError(res.error?.message))
     if (limited) {
       // 如 “Batch of more than 3 requests are not allowed”：按限制缩小批量后重发；
@@ -229,11 +393,13 @@ export class HttpRpc implements RpcTransport {
       }
       return
     }
-    // 批量里个别调用被限频（JSON-RPC 429）：只把这些调用退避后单独重试
+    // 批量里个别调用被限频（JSON-RPC 429）：只把这些调用退避后单独重试一次（不再叠加 #post 的重试）；
+    // 整批都是 429 时 #post 已经退避重试过整批，不再逐条重试——否则请求数会成倍放大
+    const allLimited = isRateLimited(body)
     const limitedItems: Pending[] = []
     items.forEach((item, i) => {
       const response = byId.get(ids[i])
-      if (response?.error?.code === 429 && this.#retries > 0) {
+      if (response?.error?.code === 429 && this.#retries > 0 && !allLimited) {
         limitedItems.push(item)
       } else {
         settle(item, response)
@@ -241,34 +407,33 @@ export class HttpRpc implements RpcTransport {
     })
     if (limitedItems.length) {
       await new Promise((r) => setTimeout(r, 500))
-      await Promise.all(limitedItems.map((item) => this.#single(item)))
+      await Promise.all(limitedItems.map((item) => this.#single(item, 0)))
     }
   }
 
   /** 按当前的 maxBatchSize 重新分批发送（每批都比原来小，不会无限循环） */
   async #redispatch(items: Pending[]): Promise<void> {
-    const size = this.#maxBatchSize
-    const chunks: Pending[][] = []
-    for (let i = 0; i < items.length; i += size) {
-      chunks.push(items.slice(i, i + size))
-    }
-    await Promise.all(chunks.map((chunk) => this.#dispatch(chunk)))
+    await Promise.all(this.#split(items).map((chunk) => this.#dispatch(chunk)))
   }
 
-  async #single(item: Pending): Promise<void> {
+  /** 逐条发送一个调用；返回是否拿到了结果（没有出错） */
+  async #single(item: Pending, retries = this.#retries): Promise<boolean> {
     try {
-      const body = (await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params })) as RpcResponse
+      const body = (await this.#post({ jsonrpc: '2.0', id: nextId++, method: item.method, params: item.params }, retries)) as RpcResponse
       settle(item, body)
+      return !body?.error
     } catch (err) {
       item.reject(err)
+      return false
     }
   }
 
+  /** 节点明确表示不支持批量：10 分钟内逐条请求，之后重新尝试批量（节点可能只是临时出错或已经升级） */
   #disableBatch(): void {
-    this.#batch = false
+    this.#batchDisabledUntil = Date.now() + BATCH_RETRY_AFTER
   }
 
-  async #post(payload: unknown): Promise<unknown> {
+  async #post(payload: unknown, retries = this.#retries): Promise<unknown> {
     for (let attempt = 0; ; attempt++) {
       let response: Response
       try {
@@ -283,11 +448,18 @@ export class HttpRpc implements RpcTransport {
         const timeout = (err as { name?: unknown } | null)?.name === 'TimeoutError'
         throw new HttpError(`Request to ${this.#safeUrl} failed: ${(err as Error)?.message ?? err}`, undefined, timeout)
       }
-      if (response.status === 429 && attempt < this.#retries) {
+      if (response.status === 429 && attempt < retries) {
         await new Promise((r) => setTimeout(r, 500 * 2 ** attempt))
         continue
       }
-      const text = await response.text()
+      let text: string
+      try {
+        text = await response.text()
+      } catch (err) {
+        // 读响应体时超时或连接中断：同样包装成 HttpError（原生 DOMException / TypeError 不会被当成可恢复的节点问题）
+        const timeout = (err as { name?: unknown } | null)?.name === 'TimeoutError'
+        throw new HttpError(`Reading response from ${this.#safeUrl} failed: ${(err as Error)?.message ?? err}`, response.status, timeout)
+      }
       let body: unknown
       try {
         body = parseJson(text)
@@ -298,8 +470,18 @@ export class HttpRpc implements RpcTransport {
       if (!response.ok && !Array.isArray(body) && !(body as RpcResponse)?.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 as RpcResponse)?.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 < this.#retries && isRateLimited(body)) {
+      if (attempt < retries && isRateLimited(body)) {
         await new Promise((r) => setTimeout(r, 500 * 2 ** attempt))
         continue
       }
@@ -326,7 +508,17 @@ function parseJson(text: string): unknown {
       typeof value === 'number' && !Number.isSafeInteger(value) && Number.isInteger(value) && context?.source ? context.source : value,
     )
   }
-  return JSON.parse(text.replace(/([:[,]\s*)(-?\d{16,})(?=\s*[,}\]])/g, '$1"$2"'))
+  return JSON.parse(quoteBigIntegers(text))
+}
+
+/**
+ * 把 JSON 文本里数值位置上 16 位以上的整数改成字符串（不支持 source text access 的环境用）。
+ * 跳过字符串字面量：错误信息等字符串里的长数字不会被改动
+ */
+export function quoteBigIntegers(text: string): string {
+  return text.replace(/"(?:[^"\\]|\\.)*"|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g, (token) =>
+    token[0] !== '"' && /^-?\d{16,}$/.test(token) ? `"${token}"` : token,
+  )
 }
 
 function safeOrigin(url: string): string {

package/src/shortcuts.ts

@@ -38,11 +38,24 @@ function setBounded<K, V>(map: Map<K, V>, key: K, value: V): void {
   }
 }
 
+// 配置里的函数（如自定义 fetch）按对象编号参与缓存键：同一个函数对象复用同一个客户端（WeakMap 不阻止回收）
+const functionIds = new WeakMap<object, number>()
+let nextFunctionId = 0
+
+/** 配置的缓存键：对象的键按字母排序（写法顺序不同视为同一份配置），函数按对象编号；无法序列化时返回 null（不缓存） */
 function configKey(config: ClientConfig): string | null {
   try {
     return JSON.stringify(config, (_key, value: unknown) => {
       if (typeof value === 'function') {
-        throw new Error('not comparable')
+        let id = functionIds.get(value)
+        if (id === undefined) {
+          id = ++nextFunctionId
+          functionIds.set(value, id)
+        }
+        return `function#${id}`
+      }
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
       }
       return value
     })