@imbingox/acex 0.3.1-beta.0 → 0.4.0-beta.10

package/src/internal/rate-limiter.ts

@@ -0,0 +1,181 @@
+import type {
+  RateLimiter,
+  RateLimitRequestContext,
+  RateLimitResponseContext,
+  RateLimitScope,
+  RateLimitSnapshot,
+  RateLimitTransportErrorContext,
+  RateLimitUsage,
+} from "../types/index.ts";
+
+interface ReactiveRateLimiterOptions {
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly defaultRateLimitMs?: number;
+  readonly defaultBanMs?: number;
+}
+
+interface RateLimitState {
+  usage?: RateLimitUsage;
+  blockedUntil?: number;
+  retryAfterMs?: number;
+  state: RateLimitSnapshot["state"];
+  updatedAt?: number;
+}
+
+const DEFAULT_RATE_LIMIT_MS = 0;
+const DEFAULT_BAN_MS = 60_000;
+
+export class ReactiveRateLimiter implements RateLimiter {
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly defaultRateLimitMs: number;
+  private readonly defaultBanMs: number;
+  private readonly states = new Map<string, RateLimitState>();
+
+  constructor(options: ReactiveRateLimiterOptions = {}) {
+    this.now = options.now ?? Date.now;
+    this.sleep = options.sleep ?? defaultSleep;
+    this.defaultRateLimitMs =
+      options.defaultRateLimitMs ?? DEFAULT_RATE_LIMIT_MS;
+    this.defaultBanMs = options.defaultBanMs ?? DEFAULT_BAN_MS;
+  }
+
+  async beforeRequest(ctx: RateLimitRequestContext): Promise<void> {
+    const snapshot = this.getSnapshot(ctx.scope);
+    if (!snapshot?.blockedUntil || snapshot.blockedUntil <= this.now()) {
+      return;
+    }
+
+    await this.sleep(Math.max(0, snapshot.blockedUntil - this.now()));
+  }
+
+  afterResponse(
+    ctx: RateLimitRequestContext,
+    response: RateLimitResponseContext,
+  ): void {
+    if (response.usage) {
+      const existing = this.getState(ctx.scope);
+      const hasActiveBlock =
+        existing?.blockedUntil !== undefined &&
+        existing.blockedUntil > this.now();
+      this.updateState(ctx.scope, {
+        usage: cloneUsage(response.usage),
+        state: hasActiveBlock ? existing.state : "ok",
+      });
+    }
+  }
+
+  onTransportError(
+    ctx: RateLimitRequestContext,
+    error: RateLimitTransportErrorContext,
+  ): void {
+    if (error.usage) {
+      this.updateState(ctx.scope, {
+        usage: cloneUsage(error.usage),
+      });
+    }
+
+    if (error.status !== 429 && error.status !== 418) {
+      return;
+    }
+
+    const now = this.now();
+    const isBan = error.status === 418;
+    const retryAfterMs =
+      error.retryAfterMs ??
+      (isBan ? this.defaultBanMs : this.defaultRateLimitMs);
+    const blockedUntil =
+      retryAfterMs > 0
+        ? now + retryAfterMs
+        : this.getState(ctx.scope)?.blockedUntil;
+
+    this.updateState(ctx.scope, {
+      blockedUntil,
+      retryAfterMs,
+      state: isBan ? "banned" : "rate_limited",
+    });
+  }
+
+  getSnapshot(scope: RateLimitScope): RateLimitSnapshot | undefined {
+    const state = this.getState(scope);
+    if (!state) {
+      return undefined;
+    }
+
+    const now = this.now();
+    const blockedUntil =
+      state.blockedUntil !== undefined && state.blockedUntil > now
+        ? state.blockedUntil
+        : undefined;
+    const runtimeState =
+      blockedUntil === undefined && state.state !== "ok" ? "ok" : state.state;
+
+    return {
+      scope: { ...scope },
+      usage: state.usage ? cloneUsage(state.usage) : undefined,
+      blockedUntil,
+      retryAfterMs: blockedUntil ? state.retryAfterMs : undefined,
+      state: runtimeState,
+      updatedAt: state.updatedAt,
+    };
+  }
+
+  private getState(scope: RateLimitScope): RateLimitState | undefined {
+    return this.states.get(scopeKey(scope));
+  }
+
+  private updateState(
+    scope: RateLimitScope,
+    patch: Partial<RateLimitState>,
+  ): void {
+    const existing = this.getState(scope);
+    const nextBlockedUntil = maxOptional(
+      existing?.blockedUntil,
+      patch.blockedUntil,
+    );
+    const nextState =
+      patch.state ??
+      (nextBlockedUntil !== undefined
+        ? (existing?.state ?? "ok")
+        : existing?.state);
+
+    this.states.set(scopeKey(scope), {
+      usage: patch.usage ?? existing?.usage,
+      blockedUntil: nextBlockedUntil,
+      retryAfterMs: patch.retryAfterMs ?? existing?.retryAfterMs,
+      state: nextState ?? "ok",
+      updatedAt: this.now(),
+    });
+  }
+}
+
+function scopeKey(scope: RateLimitScope): string {
+  return [scope.venue, scope.accountId ?? "", scope.endpointKey].join("\0");
+}
+
+function cloneUsage(usage: RateLimitUsage): RateLimitUsage {
+  return {
+    weight: usage.weight ? { ...usage.weight } : undefined,
+    orderCount: usage.orderCount ? { ...usage.orderCount } : undefined,
+  };
+}
+
+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);
+}
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/internal/watermark.ts

@@ -0,0 +1,83 @@
+export const CROSS_CLOCK_WATERMARK_GRACE_MS = 10_000;
+
+export interface WatermarkedRecord {
+  exchangeTs?: number;
+  receivedAt: number;
+}
+
+export interface WatermarkApplyOptions {
+  requestStartedAt?: number;
+  source?: "command" | "rest" | "stream";
+  graceMs?: number;
+}
+
+export interface SnapshotDeletionGuard {
+  requestStartedAt: number;
+  snapshotExchangeTs?: number;
+}
+
+export function shouldApplyWatermarkedUpdate(
+  current: WatermarkedRecord | undefined,
+  incoming: WatermarkedRecord,
+  options: WatermarkApplyOptions = {},
+): boolean {
+  if (!current) {
+    return true;
+  }
+
+  const graceMs = options.graceMs ?? CROSS_CLOCK_WATERMARK_GRACE_MS;
+  const requestStartedAt = options.requestStartedAt;
+
+  if (
+    options.source === "rest" &&
+    requestStartedAt !== undefined &&
+    current.receivedAt > requestStartedAt &&
+    (current.exchangeTs === undefined || incoming.exchangeTs === undefined)
+  ) {
+    return false;
+  }
+
+  if (current.exchangeTs !== undefined && incoming.exchangeTs !== undefined) {
+    if (incoming.exchangeTs < current.exchangeTs) {
+      return false;
+    }
+    if (incoming.exchangeTs > current.exchangeTs) {
+      return true;
+    }
+
+    return incoming.receivedAt >= current.receivedAt;
+  }
+
+  if (current.exchangeTs !== undefined) {
+    if (incoming.receivedAt < current.exchangeTs + graceMs) {
+      return false;
+    }
+
+    return incoming.receivedAt >= current.receivedAt;
+  }
+
+  if (incoming.exchangeTs !== undefined) {
+    if (incoming.exchangeTs < current.receivedAt - graceMs) {
+      return false;
+    }
+
+    return incoming.receivedAt >= current.receivedAt;
+  }
+
+  return incoming.receivedAt >= current.receivedAt;
+}
+
+export function canDeleteMissingFromSnapshot(
+  current: WatermarkedRecord,
+  guard: SnapshotDeletionGuard,
+): boolean {
+  if (current.receivedAt > guard.requestStartedAt) {
+    return false;
+  }
+
+  return !(
+    current.exchangeTs !== undefined &&
+    guard.snapshotExchangeTs !== undefined &&
+    current.exchangeTs > guard.snapshotExchangeTs
+  );
+}