@imbingox/acex 0.4.0-beta.17 → 0.4.0-beta.18

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @imbingox/acex
 
+## 0.4.0-beta.18
+
+### Minor Changes
+
+- 3edefc1: Extend the public rate limiter SPI with optional topology plans, bucket reserve headroom, request priority, opaque reservations, and bucket-level snapshots. The default limiter now supports Binance REST topology registration, fixed-window bucket budget admission, cancel-priority reserve for Binance PAPI request weight, usage-header reconciliation, request-not-sent refunds, jittered bucket-level 429 fallback, and bucket-level 429/418 blocking while remaining backward compatible with existing custom `RateLimiter` implementations.
+
 ## 0.4.0-beta.17
 
 ### Minor Changes

package/docs/api.md

@@ -253,7 +253,7 @@ const client = createClient({
 });
 ```
 
-`clock` 只用于 outbound request / signing timestamp，不驱动 WebSocket freshness 的 received-at 时钟。需要自定义 REST 限流行为时可传 `rateLimiter`，否则使用默认 reactive limiter。Binance `riskPollIntervalMs` 默认 5s，用于风险和 mark-to-market 仓位刷新；`privateReconcileIntervalMs` 默认 60s，用于账户余额、仓位和订单状态 REST 对账，显式传 `0` 可关闭 private reconcile，但不关闭 risk polling。`sandbox`、`logger`、`logLevel` 目前是预留位。
+`clock` 只用于 outbound request / signing timestamp，不驱动 WebSocket freshness 的 received-at 时钟。需要自定义 REST 限流行为时可传 `rateLimiter`，否则使用默认 bucket-aware budget limiter：它会注册 Binance REST topology，在 `beforeRequest` 中按固定窗口和 `rateLimit.utilizationTarget`（默认 0.9）主动预扣预算，接近上限时 sleep 到下一窗口；Binance PAPI request-weight 桶为 `priority:"cancel"` 保留 headroom，撤单请求仍计入真实 weight 但可使用保留区；响应后的 Binance usage header 会回填校正 bucket 用量，429/418 block 也会落到对应 bucket，缺少 `Retry-After` 的 429 会冷却到窗口结束并带小 jitter。Binance `riskPollIntervalMs` 默认 5s，用于风险和 mark-to-market 仓位刷新；`privateReconcileIntervalMs` 默认 60s，用于账户余额、仓位和订单状态 REST 对账，显式传 `0` 可关闭 private reconcile，但不关闭 risk polling。`sandbox`、`logger`、`logLevel` 目前是预留位。
 
 ### 4.2 `start()` / `stop()`
 
@@ -599,6 +599,9 @@ interface CreateClientOptions {
   sandbox?: boolean;
   clock?: { now(): number };
   rateLimiter?: RateLimiter;
+  rateLimit?: {
+    utilizationTarget?: number;
+  };
   logger?: Logger;
   logLevel?: "debug" | "info" | "warn" | "error";
   market?: {
@@ -641,14 +644,77 @@ interface RateLimitUsage {
   orderCount?: Record<string, number>;
 }
 
+type RateLimitPriority = "normal" | "cancel" | "risk" | (string & {});
+type RateLimitBucketKind = "request_weight" | "orders" | (string & {});
+type RateLimitScopeDimension = "venue" | "account" | "endpoint";
+
+interface RateLimitBucketReserve {
+  priority: RateLimitPriority;
+  units: number;
+}
+
+interface RateLimitBucketDescriptor {
+  id: string;
+  kind: RateLimitBucketKind;
+  limit: number;
+  intervalMs: number;
+  scope: readonly RateLimitScopeDimension[];
+  utilizationTarget?: number;
+  reserve?: RateLimitBucketReserve;
+}
+
+interface RateLimitCost {
+  bucketId: string;
+  cost: number;
+}
+
+interface RateLimitPlan {
+  id: string;
+  costs: readonly RateLimitCost[];
+  priority?: RateLimitPriority;
+}
+
+interface RateLimitTopology {
+  id: string;
+  buckets: readonly RateLimitBucketDescriptor[];
+  plans: readonly RateLimitPlan[];
+}
+
+interface RateLimitReservation {
+  readonly __opaqueRateLimitReservation?: never;
+}
+
+interface RateLimitTopologyRegistry {
+  registerRateLimitTopology(topology: RateLimitTopology): void;
+}
+
+interface RateLimitBucketSnapshot {
+  bucketId: string;
+  kind: RateLimitBucketKind;
+  limit: number;
+  intervalMs: number;
+  utilizationTarget?: number;
+  reserve?: RateLimitBucketReserve;
+  used?: number;
+  windowStartMs?: number;
+  windowEndMs?: number;
+  blockedUntil?: number;
+  retryAfterMs?: number;
+  state: "ok" | "rate_limited" | "banned";
+  updatedAt?: number;
+}
+
 interface RateLimitRequestContext {
   scope: RateLimitScope;
+  planId?: string;
+  priority?: RateLimitPriority;
 }
 
 interface RateLimitResponseContext {
   status: number;
   headers?: Headers;
   usage?: RateLimitUsage;
+  reservation?: RateLimitReservation;
 }
 
 interface RateLimitTransportErrorContext {
@@ -656,6 +722,8 @@ interface RateLimitTransportErrorContext {
   headers?: Headers;
   retryAfterMs?: number;
   usage?: RateLimitUsage;
+  reservation?: RateLimitReservation;
+  requestNotSent?: boolean;
 }
 
 interface RateLimitSnapshot {
@@ -665,10 +733,13 @@ interface RateLimitSnapshot {
   retryAfterMs?: number;
   state: "ok" | "rate_limited" | "banned";
   updatedAt?: number;
+  buckets?: RateLimitBucketSnapshot[];
 }
 
 interface RateLimiter {
-  beforeRequest(ctx: RateLimitRequestContext): Promise<void> | void;
+  beforeRequest(
+    ctx: RateLimitRequestContext,
+  ): Promise<RateLimitReservation | void> | RateLimitReservation | void;
   afterResponse(
     ctx: RateLimitRequestContext,
     response: RateLimitResponseContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.4.0-beta.17",
+  "version": "0.4.0-beta.18",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",

package/src/adapters/binance/adapter.ts

@@ -17,6 +17,7 @@ import {
   type BinanceMarketDefinition,
   loadBinanceMarkets,
 } from "./market-catalog.ts";
+import { registerBinanceRateLimitTopology } from "./rate-limit-topology.ts";
 import { fetchBinanceServerTime } from "./server-time.ts";
 import {
   type BinanceStreamDescriptor,
@@ -61,7 +62,9 @@ export class BinanceMarketAdapter implements MarketAdapter {
     private readonly options: {
       readonly rateLimiter?: RateLimiter;
     } = {},
-  ) {}
+  ) {
+    registerBinanceRateLimitTopology(this.options.rateLimiter);
+  }
 
   async loadMarkets(): Promise<MarketDefinition[]> {
     const markets = await loadBinanceMarkets(fetch, {

package/src/adapters/binance/market-catalog.ts

@@ -11,8 +11,12 @@ import type {
   RateLimitScope,
 } from "../../types/index.ts";
 import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
+import { getBinanceCatalogRateLimitPlanId } from "./rate-limit-topology.ts";
 
-type FetchLike = typeof fetch;
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
 
 export type BinanceMarketFamily = "spot" | "usdm" | "coinm";
 
@@ -240,8 +244,13 @@ async function requestCatalogJson<T>(
     venue: "binance",
     endpointKey,
   };
+  const requestContext = {
+    scope,
+    planId: getBinanceCatalogRateLimitPlanId(endpointKey),
+  };
 
-  await rateLimiter?.beforeRequest({ scope });
+  const reservation =
+    (await rateLimiter?.beforeRequest(requestContext)) ?? undefined;
 
   try {
     const response = await httpRequest<T>({
@@ -252,32 +261,28 @@ async function requestCatalogJson<T>(
       jsonParseMode: "response",
       retryPolicy: {
         idempotent: true,
-        maxAttempts: 3,
+        maxAttempts: 1,
       },
       messages: BINANCE_CATALOG_HTTP_MESSAGES,
     });
 
-    await rateLimiter?.afterResponse(
-      { scope },
-      {
-        status: response.status,
-        headers: response.headers,
-        usage: parseBinanceRateLimitUsage(response.headers),
-      },
-    );
+    await rateLimiter?.afterResponse(requestContext, {
+      status: response.status,
+      headers: response.headers,
+      usage: parseBinanceRateLimitUsage(response.headers),
+      reservation,
+    });
 
     return response.body;
   } catch (error) {
     if (isTransportError(error)) {
-      await rateLimiter?.onTransportError(
-        { scope },
-        {
-          status: error.status,
-          headers: error.headers,
-          retryAfterMs: error.retryAfterMs,
-          usage: parseBinanceRateLimitUsage(error.headers),
-        },
-      );
+      await rateLimiter?.onTransportError(requestContext, {
+        status: error.status,
+        headers: error.headers,
+        retryAfterMs: error.retryAfterMs,
+        usage: parseBinanceRateLimitUsage(error.headers),
+        reservation,
+      });
     }
 
     throw error;

package/src/adapters/binance/private-adapter.ts

@@ -11,6 +11,7 @@ import type {
   AccountCredentials,
   PositionSide,
   RateLimiter,
+  RateLimitPriority,
   RateLimitScope,
   TimeProvider,
   VenueAccountCapabilities,
@@ -35,10 +36,17 @@ import type {
 } from "../types.ts";
 import { normalizeBinanceErrorCode } from "./error-codes.ts";
 import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
+import {
+  getBinancePapiRateLimitPlanId,
+  registerBinanceRateLimitTopology,
+} from "./rate-limit-topology.ts";
 
 type TimerHandle = ReturnType<typeof setInterval>;
 type SignedRequestMethod = "GET" | "POST" | "DELETE";
-type FetchLike = typeof fetch;
+type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
 
 interface BinancePapiBalance {
   asset?: string;
@@ -172,18 +180,14 @@ const BINANCE_PAPI_WS_BASE_URL = "wss://fstream.binance.com/pm/ws";
 const DEFAULT_RECV_WINDOW = 5_000;
 const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
 const USDM_QUOTE_ASSETS = ["FDUSD", "USDC", "BUSD", "USDT"];
-const SAFE_READ_RETRY_POLICY: HttpRetryPolicy = {
+const SINGLE_ATTEMPT_IDEMPOTENT_POLICY: HttpRetryPolicy = {
   idempotent: true,
-  maxAttempts: 3,
+  maxAttempts: 1,
 };
 const NO_RETRY_POLICY: HttpRetryPolicy = {
   idempotent: false,
   maxAttempts: 1,
 };
-const LISTEN_KEY_KEEPALIVE_RETRY_POLICY: HttpRetryPolicy = {
-  idempotent: true,
-  maxAttempts: 3,
-};
 function getBinancePapiHttpMessages(timeoutMs: number): HttpClientMessages {
   return {
     http: ({ status, statusText, url, rawBody }) =>
@@ -674,7 +678,9 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       readonly signingClock?: TimeProvider;
       readonly rateLimiter?: RateLimiter;
     } = {},
-  ) {}
+  ) {
+    registerBinanceRateLimitTopology(this.options.rateLimiter);
+  }
 
   normalizeVenueErrorCode(code: string) {
     return normalizeBinanceErrorCode(code);
@@ -692,7 +698,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         credentials,
         accountOptions,
         undefined,
-        SAFE_READ_RETRY_POLICY,
+        SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       ),
       this.signedRequest<BinancePapiAccount>(
         "GET",
@@ -700,7 +706,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         credentials,
         accountOptions,
         undefined,
-        SAFE_READ_RETRY_POLICY,
+        SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       ),
       this.signedRequest<BinancePapiUmPosition[]>(
         "GET",
@@ -708,7 +714,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         credentials,
         accountOptions,
         undefined,
-        SAFE_READ_RETRY_POLICY,
+        SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       ),
     ]);
 
@@ -734,7 +740,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         credentials,
         accountOptions,
         undefined,
-        SAFE_READ_RETRY_POLICY,
+        SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       ),
       this.signedRequest<BinancePapiUmPosition[]>(
         "GET",
@@ -742,7 +748,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         credentials,
         accountOptions,
         undefined,
-        SAFE_READ_RETRY_POLICY,
+        SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       ),
     ]);
 
@@ -768,7 +774,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       credentials,
       accountOptions,
       undefined,
-      SAFE_READ_RETRY_POLICY,
+      SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
     );
 
     return {
@@ -797,7 +803,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
           orderId: request.orderId,
           origClientOrderId: request.clientOrderId,
         },
-        SAFE_READ_RETRY_POLICY,
+        SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       );
 
       return mapOpenOrder(response, receivedAt);
@@ -870,6 +876,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         origClientOrderId: request.clientOrderId,
       },
       NO_RETRY_POLICY,
+      "cancel",
     );
 
     const mapped = mapOpenOrder(response, receivedAt);
@@ -896,7 +903,8 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       {
         symbol,
       },
-      SAFE_READ_RETRY_POLICY,
+      SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
+      "cancel",
     );
 
     // Venue responds {code,msg}; returned updates are synthesized from the
@@ -911,6 +919,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         symbol,
       },
       NO_RETRY_POLICY,
+      "cancel",
     );
 
     if (response.code !== undefined && `${response.code}` !== "200") {
@@ -1216,10 +1225,18 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
     accountOptions?: Record<string, unknown>,
     queryParams?: Record<string, string | undefined>,
     retryPolicy?: HttpRetryPolicy,
+    priority?: RateLimitPriority,
   ): Promise<T> {
     const { apiKey, secret } = requirePrivateCredentials(credentials);
     const scope = this.rateLimitScope(method, path, accountOptions);
-    await this.options.rateLimiter?.beforeRequest({ scope });
+    const requestContext = {
+      scope,
+      planId: getBinancePapiRateLimitPlanId(method, path, queryParams),
+      priority,
+    };
+    const reservation =
+      (await this.options.rateLimiter?.beforeRequest(requestContext)) ??
+      undefined;
 
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(queryParams ?? {})) {
@@ -1258,27 +1275,23 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         messages: getBinancePapiHttpMessages(timeoutMs),
       });
 
-      await this.options.rateLimiter?.afterResponse(
-        { scope },
-        {
-          status: response.status,
-          headers: response.headers,
-          usage: parseBinanceRateLimitUsage(response.headers),
-        },
-      );
+      await this.options.rateLimiter?.afterResponse(requestContext, {
+        status: response.status,
+        headers: response.headers,
+        usage: parseBinanceRateLimitUsage(response.headers),
+        reservation,
+      });
 
       return response.body;
     } catch (error) {
       if (isTransportError(error)) {
-        await this.options.rateLimiter?.onTransportError(
-          { scope },
-          {
-            status: error.status,
-            headers: error.headers,
-            retryAfterMs: error.retryAfterMs,
-            usage: parseBinanceRateLimitUsage(error.headers),
-          },
-        );
+        await this.options.rateLimiter?.onTransportError(requestContext, {
+          status: error.status,
+          headers: error.headers,
+          retryAfterMs: error.retryAfterMs,
+          usage: parseBinanceRateLimitUsage(error.headers),
+          reservation,
+        });
       }
 
       throw error;
@@ -1312,7 +1325,7 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "PUT",
       credentials,
       listenKey,
-      LISTEN_KEY_KEEPALIVE_RETRY_POLICY,
+      SINGLE_ATTEMPT_IDEMPOTENT_POLICY,
       accountOptions,
     );
   }
@@ -1344,7 +1357,13 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
       "/papi/v1/listenKey",
       accountOptions,
     );
-    await this.options.rateLimiter?.beforeRequest({ scope });
+    const requestContext = {
+      scope,
+      planId: getBinancePapiRateLimitPlanId(method, "/papi/v1/listenKey"),
+    };
+    const reservation =
+      (await this.options.rateLimiter?.beforeRequest(requestContext)) ??
+      undefined;
 
     const params = new URLSearchParams();
     if (listenKey) {
@@ -1371,27 +1390,23 @@ export class BinancePrivateAdapter implements PrivateUserDataAdapter {
         messages: getBinancePapiHttpMessages(timeoutMs),
       });
 
-      await this.options.rateLimiter?.afterResponse(
-        { scope },
-        {
-          status: response.status,
-          headers: response.headers,
-          usage: parseBinanceRateLimitUsage(response.headers),
-        },
-      );
+      await this.options.rateLimiter?.afterResponse(requestContext, {
+        status: response.status,
+        headers: response.headers,
+        usage: parseBinanceRateLimitUsage(response.headers),
+        reservation,
+      });
 
       return response.body;
     } catch (error) {
       if (isTransportError(error)) {
-        await this.options.rateLimiter?.onTransportError(
-          { scope },
-          {
-            status: error.status,
-            headers: error.headers,
-            retryAfterMs: error.retryAfterMs,
-            usage: parseBinanceRateLimitUsage(error.headers),
-          },
-        );
+        await this.options.rateLimiter?.onTransportError(requestContext, {
+          status: error.status,
+          headers: error.headers,
+          retryAfterMs: error.retryAfterMs,
+          usage: parseBinanceRateLimitUsage(error.headers),
+          reservation,
+        });
       }
 
       throw error;