@imbingox/acex 0.4.0-beta.16 → 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

@@ -15,6 +15,7 @@ import {
   buildAcexErrorDetails,
   type VenueErrorReason,
 } from "../errors.ts";
+import type { AsyncEventBusOverflowInfo } from "../internal/async-event-bus.ts";
 import { AsyncEventBus } from "../internal/async-event-bus.ts";
 import { matchesHealthFilter } from "../internal/filters.ts";
 import { ReactiveRateLimiter } from "../internal/rate-limiter.ts";
@@ -26,6 +27,7 @@ import type {
   AccountManager,
   AcexClient,
   AcexInternalError,
+  BufferedEventStreamOptions,
   CancelAllOrdersInput,
   CancelOrderInput,
   ClientEventStreams,
@@ -75,14 +77,30 @@ class ClientEventStreamsImpl implements ClientEventStreams {
   constructor(
     private readonly healthBus: AsyncEventBus<HealthEvent>,
     private readonly errorBus: AsyncEventBus<AcexInternalError>,
+    private readonly onHealthOverflow: (
+      info: AsyncEventBusOverflowInfo,
+    ) => void,
   ) {}
 
-  errors(): AsyncIterable<AcexInternalError> {
-    return this.errorBus.stream();
+  errors(
+    options?: BufferedEventStreamOptions,
+  ): AsyncIterable<AcexInternalError> {
+    return this.errorBus.stream(() => true, {
+      maxBuffer: options?.maxBuffer,
+    });
   }
 
-  health(filter?: HealthEventFilter): AsyncIterable<HealthEvent> {
-    return this.healthBus.stream((event) => matchesHealthFilter(event, filter));
+  health(
+    filter?: HealthEventFilter,
+    options?: BufferedEventStreamOptions,
+  ): AsyncIterable<HealthEvent> {
+    return this.healthBus.stream(
+      (event) => matchesHealthFilter(event, filter),
+      {
+        maxBuffer: options?.maxBuffer,
+        onOverflow: this.onHealthOverflow,
+      },
+    );
   }
 }
 
@@ -109,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 = [
@@ -149,7 +171,11 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     this.market = this.marketManager;
     this.account = this.accountManager;
     this.order = this.orderManager;
-    this.events = new ClientEventStreamsImpl(this.healthBus, this.errorBus);
+    this.events = new ClientEventStreamsImpl(
+      this.healthBus,
+      this.errorBus,
+      this.createOverflowHandler("client.health"),
+    );
   }
 
   // --- AcexClient public API ---
@@ -421,6 +447,21 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     this.healthBus.publish(event);
   }
 
+  private createOverflowHandler(
+    stream: string,
+  ): (info: AsyncEventBusOverflowInfo) => void {
+    return ({ maxBuffer }) => {
+      const error = new AcexError(
+        "EVENT_BUFFER_OVERFLOW",
+        `Event stream buffer overflow: ${stream}`,
+      );
+      this.publishRuntimeError("runtime", error, {
+        stream,
+        maxBuffer,
+      });
+    };
+  }
+
   // --- Private ---
 
   private setClientStatus(status: ClientStatus): void {

package/src/errors.ts

@@ -7,6 +7,7 @@ export type AcexErrorCode =
   | "ACCOUNT_NOT_FOUND"
   | "CLIENT_NOT_STARTED"
   | "CREDENTIALS_MISSING"
+  | "EVENT_BUFFER_OVERFLOW"
   | "VENUE_NOT_SUPPORTED"
   | "MARKET_CATALOG_LOAD_FAILED"
   | "MARKET_SERVER_TIME_FETCH_FAILED"

package/src/internal/async-event-bus.ts

@@ -1,10 +1,25 @@
 type EventPredicate<T> = (event: T) => boolean;
 
+export type AsyncEventBusStreamMode = "buffer" | "conflate";
+
+export interface AsyncEventBusOverflowInfo {
+  maxBuffer: number;
+}
+
+export interface AsyncEventBusStreamOptions<T> {
+  mode?: AsyncEventBusStreamMode;
+  maxBuffer?: number;
+  conflateKey?: (event: T) => string;
+  onOverflow?: (info: AsyncEventBusOverflowInfo) => void;
+}
+
 interface BusListener<T> {
   close(): void;
   dispatch(event: T): void;
 }
 
+const DEFAULT_MAX_BUFFER = 10_000;
+
 function doneResult<T>(): IteratorResult<T> {
   return { done: true, value: undefined as T };
 }
@@ -20,11 +35,67 @@ export class AsyncEventBus<T> {
 
   stream<U extends T = T>(
     filter: ((event: T) => event is U) | EventPredicate<T> = () => true,
+    options: AsyncEventBusStreamOptions<U> = {},
   ): AsyncIterable<U> {
     let closed = false;
-    const queue: U[] = [];
+    const mode = options.mode ?? "buffer";
+    const maxBuffer = options.maxBuffer ?? DEFAULT_MAX_BUFFER;
+    const bufferQueue: U[] = [];
+    const conflateQueue =
+      mode === "conflate" ? new Map<string, U>() : undefined;
+    let overflowNotified = false;
     let pendingResolve: ((result: IteratorResult<U>) => void) | undefined;
 
+    if (mode === "conflate" && !options.conflateKey) {
+      throw new Error("AsyncEventBus conflate mode requires conflateKey");
+    }
+
+    const resetOverflowIfDrained = () => {
+      if (bufferQueue.length === 0) {
+        overflowNotified = false;
+      }
+    };
+
+    const enqueue = (event: U) => {
+      if (conflateQueue) {
+        const key = options.conflateKey?.(event);
+        if (key === undefined) {
+          throw new Error("AsyncEventBus conflate mode requires conflateKey");
+        }
+        conflateQueue.set(key, event);
+        return;
+      }
+
+      bufferQueue.push(event);
+
+      if (bufferQueue.length <= maxBuffer) {
+        return;
+      }
+
+      bufferQueue.shift();
+      if (!overflowNotified) {
+        overflowNotified = true;
+        options.onOverflow?.({ maxBuffer });
+      }
+    };
+
+    const dequeue = (): U | undefined => {
+      if (conflateQueue) {
+        const first = conflateQueue.entries().next();
+        if (first.done) {
+          return undefined;
+        }
+
+        const [key, event] = first.value;
+        conflateQueue.delete(key);
+        return event;
+      }
+
+      const event = bufferQueue.shift();
+      resetOverflowIfDrained();
+      return event;
+    };
+
     const close = () => {
       if (closed) {
         return;
@@ -55,7 +126,7 @@ export class AsyncEventBus<T> {
           return;
         }
 
-        queue.push(typedEvent);
+        enqueue(typedEvent);
       },
     };
 
@@ -70,11 +141,12 @@ export class AsyncEventBus<T> {
           return doneResult<U>();
         }
 
-        const queued = queue.shift();
+        const queued = dequeue();
         if (queued !== undefined) {
           return { done: false, value: queued };
         }
 
+        resetOverflowIfDrained();
         return await new Promise<IteratorResult<U>>((resolve) => {
           pendingResolve = resolve;
         });

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;
+}