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

package/src/adapters/binance/rate-limit-topology.ts

@@ -0,0 +1,257 @@
+import type {
+  RateLimiter,
+  RateLimitPriority,
+  RateLimitTopology,
+  RateLimitTopologyRegistry,
+} from "../../types/index.ts";
+
+const ONE_MINUTE_MS = 60_000;
+
+const SPOT_REQUEST_WEIGHT_LIMIT_1M = 6_000;
+const FAPI_REQUEST_WEIGHT_LIMIT_1M = 2_400;
+const DAPI_REQUEST_WEIGHT_LIMIT_1M = 6_000;
+const PAPI_REQUEST_WEIGHT_LIMIT_1M = 6_000;
+const PAPI_CANCEL_REQUEST_WEIGHT_RESERVE_1M = 300;
+const PAPI_ORDERS_LIMIT_1M = 1_200;
+
+export const BINANCE_RATE_LIMIT_BUCKETS = {
+  spotRequestWeight1m: "binance:spot:request-weight:1m",
+  fapiRequestWeight1m: "binance:fapi:request-weight:1m",
+  dapiRequestWeight1m: "binance:dapi:request-weight:1m",
+  papiRequestWeight1m: "binance:papi:request-weight:1m",
+  papiOrders1m: "binance:papi:orders:1m",
+} as const;
+
+export const BINANCE_RATE_LIMIT_PLANS = {
+  spotExchangeInfo: "binance:spot:exchange-info",
+  fapiExchangeInfo: "binance:fapi:exchange-info",
+  dapiExchangeInfo: "binance:dapi:exchange-info",
+  fapiServerTime: "binance:fapi:server-time",
+  papiBalance: "binance:papi:balance",
+  papiAccount: "binance:papi:account",
+  papiPositionRisk: "binance:papi:position-risk",
+  papiQueryOrder: "binance:papi:query-order",
+  papiOpenOrdersSymbol: "binance:papi:open-orders:symbol",
+  papiOpenOrdersAll: "binance:papi:open-orders:all",
+  papiNewOrder: "binance:papi:new-order",
+  papiCancelOrder: "binance:papi:cancel-order",
+  papiCancelAllOrders: "binance:papi:cancel-all-orders",
+  papiListenKey: "binance:papi:listen-key",
+} as const;
+
+export const BINANCE_RATE_LIMIT_TOPOLOGY: RateLimitTopology = {
+  id: "binance-rest-rate-limits:v1",
+  buckets: [
+    {
+      id: BINANCE_RATE_LIMIT_BUCKETS.spotRequestWeight1m,
+      kind: "request_weight",
+      limit: SPOT_REQUEST_WEIGHT_LIMIT_1M,
+      intervalMs: ONE_MINUTE_MS,
+      scope: ["venue"],
+    },
+    {
+      id: BINANCE_RATE_LIMIT_BUCKETS.fapiRequestWeight1m,
+      kind: "request_weight",
+      limit: FAPI_REQUEST_WEIGHT_LIMIT_1M,
+      intervalMs: ONE_MINUTE_MS,
+      scope: ["venue"],
+    },
+    {
+      id: BINANCE_RATE_LIMIT_BUCKETS.dapiRequestWeight1m,
+      kind: "request_weight",
+      limit: DAPI_REQUEST_WEIGHT_LIMIT_1M,
+      intervalMs: ONE_MINUTE_MS,
+      scope: ["venue"],
+    },
+    {
+      id: BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      kind: "request_weight",
+      limit: PAPI_REQUEST_WEIGHT_LIMIT_1M,
+      intervalMs: ONE_MINUTE_MS,
+      scope: ["venue"],
+      reserve: {
+        priority: "cancel",
+        units: PAPI_CANCEL_REQUEST_WEIGHT_RESERVE_1M,
+      },
+    },
+    {
+      id: BINANCE_RATE_LIMIT_BUCKETS.papiOrders1m,
+      kind: "orders",
+      limit: PAPI_ORDERS_LIMIT_1M,
+      intervalMs: ONE_MINUTE_MS,
+      scope: ["venue", "account"],
+    },
+  ],
+  plans: [
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.spotExchangeInfo,
+      BINANCE_RATE_LIMIT_BUCKETS.spotRequestWeight1m,
+      20,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.fapiExchangeInfo,
+      BINANCE_RATE_LIMIT_BUCKETS.fapiRequestWeight1m,
+      1,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.dapiExchangeInfo,
+      BINANCE_RATE_LIMIT_BUCKETS.dapiRequestWeight1m,
+      1,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.fapiServerTime,
+      BINANCE_RATE_LIMIT_BUCKETS.fapiRequestWeight1m,
+      1,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiBalance,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      20,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiAccount,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      20,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiPositionRisk,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      5,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiQueryOrder,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      1,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiOpenOrdersSymbol,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      1,
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiOpenOrdersAll,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      40,
+    ),
+    {
+      id: BINANCE_RATE_LIMIT_PLANS.papiNewOrder,
+      costs: [
+        {
+          bucketId: BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+          cost: 0,
+        },
+        {
+          bucketId: BINANCE_RATE_LIMIT_BUCKETS.papiOrders1m,
+          cost: 1,
+        },
+      ],
+    },
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiCancelOrder,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      1,
+      "cancel",
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiCancelAllOrders,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      1,
+      "cancel",
+    ),
+    requestWeightPlan(
+      BINANCE_RATE_LIMIT_PLANS.papiListenKey,
+      BINANCE_RATE_LIMIT_BUCKETS.papiRequestWeight1m,
+      1,
+    ),
+  ],
+};
+
+export function registerBinanceRateLimitTopology(
+  rateLimiter: RateLimiter | undefined,
+): void {
+  const registry = getRateLimitTopologyRegistry(rateLimiter);
+  registry?.registerRateLimitTopology(BINANCE_RATE_LIMIT_TOPOLOGY);
+}
+
+export function getBinanceCatalogRateLimitPlanId(
+  endpointKey: string,
+): string | undefined {
+  switch (endpointKey) {
+    case "GET /api/v3/exchangeInfo":
+      return BINANCE_RATE_LIMIT_PLANS.spotExchangeInfo;
+    case "GET /fapi/v1/exchangeInfo":
+      return BINANCE_RATE_LIMIT_PLANS.fapiExchangeInfo;
+    case "GET /dapi/v1/exchangeInfo":
+      return BINANCE_RATE_LIMIT_PLANS.dapiExchangeInfo;
+    default:
+      return undefined;
+  }
+}
+
+export function getBinanceServerTimeRateLimitPlanId(): string {
+  return BINANCE_RATE_LIMIT_PLANS.fapiServerTime;
+}
+
+export function getBinancePapiRateLimitPlanId(
+  method: string,
+  path: string,
+  queryParams?: Record<string, string | undefined>,
+): string | undefined {
+  switch (`${method} ${path}`) {
+    case "GET /papi/v1/balance":
+      return BINANCE_RATE_LIMIT_PLANS.papiBalance;
+    case "GET /papi/v1/account":
+      return BINANCE_RATE_LIMIT_PLANS.papiAccount;
+    case "GET /papi/v1/um/positionRisk":
+      return BINANCE_RATE_LIMIT_PLANS.papiPositionRisk;
+    case "GET /papi/v1/um/order":
+      return BINANCE_RATE_LIMIT_PLANS.papiQueryOrder;
+    case "GET /papi/v1/um/openOrders":
+      return queryParams?.symbol
+        ? BINANCE_RATE_LIMIT_PLANS.papiOpenOrdersSymbol
+        : BINANCE_RATE_LIMIT_PLANS.papiOpenOrdersAll;
+    case "POST /papi/v1/um/order":
+      return BINANCE_RATE_LIMIT_PLANS.papiNewOrder;
+    case "DELETE /papi/v1/um/order":
+      return BINANCE_RATE_LIMIT_PLANS.papiCancelOrder;
+    case "DELETE /papi/v1/um/allOpenOrders":
+      return BINANCE_RATE_LIMIT_PLANS.papiCancelAllOrders;
+    case "POST /papi/v1/listenKey":
+    case "PUT /papi/v1/listenKey":
+    case "DELETE /papi/v1/listenKey":
+      return BINANCE_RATE_LIMIT_PLANS.papiListenKey;
+    default:
+      return undefined;
+  }
+}
+
+function requestWeightPlan(
+  id: string,
+  bucketId: string,
+  cost: number,
+  priority?: RateLimitPriority,
+): RateLimitTopology["plans"][number] {
+  return {
+    id,
+    costs: [{ bucketId, cost }],
+    priority,
+  };
+}
+
+function getRateLimitTopologyRegistry(
+  rateLimiter: RateLimiter | undefined,
+): RateLimitTopologyRegistry | undefined {
+  if (!rateLimiter) {
+    return undefined;
+  }
+
+  const candidate = rateLimiter as RateLimiter &
+    Partial<RateLimitTopologyRegistry>;
+  return isRateLimitTopologyRegistry(candidate) ? candidate : undefined;
+}
+
+function isRateLimitTopologyRegistry(
+  value: RateLimiter & Partial<RateLimitTopologyRegistry>,
+): value is RateLimiter & RateLimitTopologyRegistry {
+  return typeof value.registerRateLimitTopology === "function";
+}

package/src/adapters/binance/server-time.ts

@@ -9,6 +9,7 @@ import type {
   VenueServerTime,
 } from "../../types/index.ts";
 import { parseBinanceRateLimitUsage } from "./rate-limit.ts";
+import { getBinanceServerTimeRateLimitPlanId } from "./rate-limit-topology.ts";
 
 type FetchLike = (
   input: string | URL | Request,
@@ -43,8 +44,13 @@ export async function fetchBinanceServerTime(
     venue: "binance",
     endpointKey: "GET /fapi/v1/time",
   };
+  const requestContext = {
+    scope,
+    planId: getBinanceServerTimeRateLimitPlanId(),
+  };
 
-  await options.rateLimiter?.beforeRequest({ scope });
+  const reservation =
+    (await options.rateLimiter?.beforeRequest(requestContext)) ?? undefined;
 
   const requestSentAt = now();
   const startMono = monotonicNow();
@@ -65,14 +71,12 @@ export async function fetchBinanceServerTime(
     const responseReceivedAt = now();
     const endMono = monotonicNow();
 
-    await options.rateLimiter?.afterResponse(
-      { scope },
-      {
-        status: response.status,
-        headers: response.headers,
-        usage: parseBinanceRateLimitUsage(response.headers),
-      },
-    );
+    await options.rateLimiter?.afterResponse(requestContext, {
+      status: response.status,
+      headers: response.headers,
+      usage: parseBinanceRateLimitUsage(response.headers),
+      reservation,
+    });
 
     const { serverTime } = response.body;
     if (typeof serverTime !== "number" || !Number.isFinite(serverTime)) {
@@ -90,15 +94,13 @@ export async function fetchBinanceServerTime(
     };
   } catch (error) {
     if (isTransportError(error)) {
-      await options.rateLimiter?.onTransportError(
-        { scope },
-        {
-          status: error.status,
-          headers: error.headers,
-          retryAfterMs: error.retryAfterMs,
-          usage: parseBinanceRateLimitUsage(error.headers),
-        },
-      );
+      await options.rateLimiter?.onTransportError(requestContext, {
+        status: error.status,
+        headers: error.headers,
+        retryAfterMs: error.retryAfterMs,
+        usage: parseBinanceRateLimitUsage(error.headers),
+        reservation,
+      });
     }
 
     throw error;

package/src/client/runtime.ts

@@ -127,7 +127,11 @@ export class AcexClientImpl implements AcexClient, ClientContext {
   constructor(options: CreateClientOptions = {}) {
     activeClients.add(this);
 
-    const rateLimiter = options.rateLimiter ?? new ReactiveRateLimiter();
+    const rateLimiter =
+      options.rateLimiter ??
+      new ReactiveRateLimiter({
+        utilizationTarget: options.rateLimit?.utilizationTarget,
+      });
     const marketAdapter = new BinanceMarketAdapter({ rateLimiter });
     this.marketAdapters = new Map([[marketAdapter.venue, marketAdapter]]);
     const privateAdapters = [

package/src/internal/rate-limiter/snapshot.ts

@@ -0,0 +1,67 @@
+import type {
+  RateLimitBucketSnapshot,
+  RateLimitSnapshot,
+} from "../../types/index.ts";
+import { maxOptional, stateSeverity } from "./state.ts";
+
+export function aggregateBucketSnapshots(
+  base: RateLimitSnapshot,
+  buckets: RateLimitBucketSnapshot[],
+): Pick<
+  RateLimitSnapshot,
+  "blockedUntil" | "retryAfterMs" | "state" | "updatedAt"
+> {
+  let selectedBlock: RateLimitBlockedSnapshot | undefined =
+    blockCandidate(base);
+  let updatedAt = base.updatedAt;
+
+  for (const bucket of buckets) {
+    updatedAt = maxOptional(updatedAt, bucket.updatedAt);
+    selectedBlock = selectLaterBlock(selectedBlock, blockCandidate(bucket));
+  }
+
+  return {
+    blockedUntil: selectedBlock?.blockedUntil,
+    retryAfterMs: selectedBlock?.retryAfterMs,
+    state: selectedBlock?.state ?? base.state,
+    updatedAt,
+  };
+}
+
+interface RateLimitBlockedSnapshot {
+  blockedUntil: number;
+  retryAfterMs?: number;
+  state: RateLimitSnapshot["state"];
+}
+
+function blockCandidate(
+  snapshot: Pick<RateLimitSnapshot, "blockedUntil" | "retryAfterMs" | "state">,
+): RateLimitBlockedSnapshot | undefined {
+  if (snapshot.blockedUntil === undefined) {
+    return undefined;
+  }
+  return {
+    blockedUntil: snapshot.blockedUntil,
+    retryAfterMs: snapshot.retryAfterMs,
+    state: snapshot.state,
+  };
+}
+
+function selectLaterBlock(
+  current: RateLimitBlockedSnapshot | undefined,
+  candidate: RateLimitBlockedSnapshot | undefined,
+): RateLimitBlockedSnapshot | undefined {
+  if (!candidate) {
+    return current;
+  }
+  if (!current || candidate.blockedUntil > current.blockedUntil) {
+    return candidate;
+  }
+  if (
+    candidate.blockedUntil === current.blockedUntil &&
+    stateSeverity(candidate.state) > stateSeverity(current.state)
+  ) {
+    return candidate;
+  }
+  return current;
+}

package/src/internal/rate-limiter/state.ts

@@ -0,0 +1,98 @@
+import type {
+  RateLimitBucketDescriptor,
+  RateLimitScope,
+  RateLimitSnapshot,
+} from "../../types/index.ts";
+
+export function scopeKey(scope: RateLimitScope): string {
+  return [scope.venue, scope.accountId ?? "", scope.endpointKey].join("\0");
+}
+
+export function bucketStateKey(
+  scope: RateLimitScope,
+  bucket: RateLimitBucketDescriptor,
+): string {
+  return [
+    bucket.id,
+    ...bucket.scope.map((dimension) => scopeValue(scope, dimension)),
+  ].join("\0");
+}
+
+function scopeValue(
+  scope: RateLimitScope,
+  dimension: RateLimitBucketDescriptor["scope"][number],
+): string {
+  switch (dimension) {
+    case "venue":
+      return scope.venue;
+    case "account":
+      return scope.accountId ?? "";
+    case "endpoint":
+      return scope.endpointKey;
+  }
+}
+
+export function windowStartMs(now: number, intervalMs: number): number {
+  return Math.floor(now / intervalMs) * intervalMs;
+}
+
+export function windowEndMs(windowStart: number, intervalMs: number): number {
+  return windowStart + intervalMs;
+}
+
+export function maxOptional(
+  left: number | undefined,
+  right: number | undefined,
+): number | undefined {
+  if (left === undefined) {
+    return right;
+  }
+  if (right === undefined) {
+    return left;
+  }
+  return Math.max(left, right);
+}
+
+export function nextRateLimitState(
+  existingState: RateLimitSnapshot["state"] | undefined,
+  patchState: RateLimitSnapshot["state"] | undefined,
+  patchWinsBlock: boolean,
+  blockedUntil: number | undefined,
+): RateLimitSnapshot["state"] | undefined {
+  if (!patchState) {
+    return blockedUntil !== undefined ? (existingState ?? "ok") : existingState;
+  }
+  if (!patchWinsBlock && existingState) {
+    return moreSevereState(existingState, patchState);
+  }
+  return patchState;
+}
+
+export function nextRetryAfterMs<T extends { retryAfterMs?: number }>(
+  existing: T | undefined,
+  patch: Partial<T>,
+  patchWinsBlock: boolean,
+): number | undefined {
+  if (patchWinsBlock) {
+    return patch.retryAfterMs ?? existing?.retryAfterMs;
+  }
+  return existing?.retryAfterMs;
+}
+
+function moreSevereState(
+  left: RateLimitSnapshot["state"],
+  right: RateLimitSnapshot["state"],
+): RateLimitSnapshot["state"] {
+  return stateSeverity(left) >= stateSeverity(right) ? left : right;
+}
+
+export function stateSeverity(state: RateLimitSnapshot["state"]): number {
+  switch (state) {
+    case "banned":
+      return 2;
+    case "rate_limited":
+      return 1;
+    case "ok":
+      return 0;
+  }
+}

package/src/internal/rate-limiter/topology.ts

@@ -0,0 +1,123 @@
+import type {
+  RateLimitBucketDescriptor,
+  RateLimitPlan,
+} from "../../types/index.ts";
+
+export function validateBucketDescriptor(
+  bucket: RateLimitBucketDescriptor,
+): void {
+  if (!bucket.id) {
+    throw new Error("Rate limit bucket descriptor id is required");
+  }
+  if (!Number.isFinite(bucket.limit) || bucket.limit < 0) {
+    throw new Error(`Invalid rate limit bucket limit: ${bucket.id}`);
+  }
+  if (!Number.isFinite(bucket.intervalMs) || bucket.intervalMs <= 0) {
+    throw new Error(`Invalid rate limit bucket interval: ${bucket.id}`);
+  }
+  if (bucket.reserve) {
+    if (!bucket.reserve.priority) {
+      throw new Error(
+        `Invalid rate limit bucket reserve priority: ${bucket.id}`,
+      );
+    }
+    if (
+      !Number.isFinite(bucket.reserve.units) ||
+      bucket.reserve.units < 0 ||
+      bucket.reserve.units > bucket.limit
+    ) {
+      throw new Error(`Invalid rate limit bucket reserve units: ${bucket.id}`);
+    }
+  }
+}
+
+export function validatePlan(
+  plan: RateLimitPlan,
+  buckets: ReadonlyMap<string, RateLimitBucketDescriptor>,
+): void {
+  if (!plan.id) {
+    throw new Error("Rate limit plan id is required");
+  }
+  for (const cost of plan.costs) {
+    if (!buckets.has(cost.bucketId)) {
+      throw new Error(
+        `Rate limit plan ${plan.id} references unknown bucket: ${cost.bucketId}`,
+      );
+    }
+    if (!Number.isFinite(cost.cost) || cost.cost < 0) {
+      throw new Error(`Invalid rate limit cost for plan: ${plan.id}`);
+    }
+  }
+}
+
+export function cloneBucketDescriptor(
+  bucket: RateLimitBucketDescriptor,
+): RateLimitBucketDescriptor {
+  return {
+    ...bucket,
+    reserve: bucket.reserve ? { ...bucket.reserve } : undefined,
+    scope: [...bucket.scope],
+  };
+}
+
+export function clonePlan(plan: RateLimitPlan): RateLimitPlan {
+  return {
+    ...plan,
+    costs: plan.costs.map((cost) => ({ ...cost })),
+  };
+}
+
+export function bucketDescriptorsEqual(
+  left: RateLimitBucketDescriptor,
+  right: RateLimitBucketDescriptor,
+): boolean {
+  return (
+    left.id === right.id &&
+    left.kind === right.kind &&
+    left.limit === right.limit &&
+    left.intervalMs === right.intervalMs &&
+    left.utilizationTarget === right.utilizationTarget &&
+    reservesEqual(left.reserve, right.reserve) &&
+    arraysEqual(left.scope, right.scope)
+  );
+}
+
+export function plansEqual(left: RateLimitPlan, right: RateLimitPlan): boolean {
+  if (
+    left.id !== right.id ||
+    left.priority !== right.priority ||
+    left.costs.length !== right.costs.length
+  ) {
+    return false;
+  }
+
+  return left.costs.every((cost, index) => {
+    const other = right.costs[index];
+    if (!other) {
+      return false;
+    }
+    return cost.bucketId === other.bucketId && cost.cost === other.cost;
+  });
+}
+
+function arraysEqual<T>(left: readonly T[], right: readonly T[]): boolean {
+  return (
+    left.length === right.length &&
+    left.every((value, index) => value === right[index])
+  );
+}
+
+function reservesEqual(
+  left: RateLimitBucketDescriptor["reserve"],
+  right: RateLimitBucketDescriptor["reserve"],
+): boolean {
+  if (!left || !right) {
+    return left === right;
+  }
+
+  return left.priority === right.priority && left.units === right.units;
+}
+
+export function uniqueStrings(values: readonly string[]): string[] {
+  return [...new Set(values)];
+}

package/src/internal/rate-limiter/types.ts

@@ -0,0 +1,49 @@
+import type {
+  RateLimitPriority,
+  RateLimitSnapshot,
+  RateLimitUsage,
+} from "../../types/index.ts";
+
+export interface ReactiveRateLimiterOptions {
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly random?: () => number;
+  readonly defaultRateLimitMs?: number;
+  readonly defaultBanMs?: number;
+  readonly retryJitterMs?: number;
+  readonly utilizationTarget?: number;
+}
+
+export interface EndpointRateLimitState {
+  usage?: RateLimitUsage;
+  blockedUntil?: number;
+  retryAfterMs?: number;
+  banStrikeCount?: number;
+  state: RateLimitSnapshot["state"];
+  updatedAt?: number;
+}
+
+export interface BucketRateLimitState {
+  used?: number;
+  windowStartMs?: number;
+  blockedUntil?: number;
+  retryAfterMs?: number;
+  banStrikeCount?: number;
+  state: RateLimitSnapshot["state"];
+  updatedAt?: number;
+}
+
+export interface RateLimitReservationBucket {
+  bucketId: string;
+  stateKey: string;
+  cost: number;
+  windowStartMs: number;
+}
+
+export interface BudgetRateLimitReservation {
+  readonly __opaqueRateLimitReservation?: never;
+  readonly admittedAt: number;
+  readonly planId: string;
+  readonly priority: RateLimitPriority;
+  readonly buckets: readonly RateLimitReservationBucket[];
+}