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

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

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

@@ -0,0 +1,48 @@
+import type {
+  RateLimitBucketDescriptor,
+  RateLimitUsage,
+} from "../../types/index.ts";
+
+export function cloneUsage(usage: RateLimitUsage): RateLimitUsage {
+  return {
+    weight: usage.weight ? { ...usage.weight } : undefined,
+    orderCount: usage.orderCount ? { ...usage.orderCount } : undefined,
+  };
+}
+
+export function usageForBucket(
+  usage: RateLimitUsage,
+  bucket: RateLimitBucketDescriptor,
+): number | undefined {
+  const intervalKey = intervalKeyFromMs(bucket.intervalMs);
+  if (!intervalKey) {
+    return undefined;
+  }
+
+  if (bucket.kind === "request_weight") {
+    return usage.weight?.[intervalKey];
+  }
+
+  if (bucket.kind === "orders") {
+    return usage.orderCount?.[intervalKey];
+  }
+
+  return undefined;
+}
+
+function intervalKeyFromMs(intervalMs: number): string | undefined {
+  const units: Array<readonly [suffix: string, ms: number]> = [
+    ["d", 86_400_000],
+    ["h", 3_600_000],
+    ["m", 60_000],
+    ["s", 1_000],
+  ];
+
+  for (const [suffix, ms] of units) {
+    if (intervalMs >= ms && intervalMs % ms === 0) {
+      return `${intervalMs / ms}${suffix}`;
+    }
+  }
+
+  return undefined;
+}