@aztec-labs/p2p 6.0.0-nightly.20260829

package/src/services/reqresp/rate-limiter/rate_limiter.ts

@@ -0,0 +1,240 @@
+/**
+ * @attribution Rate limiter approach implemented in the lodestar ethereum 2 client.
+ * Rationale is that if it was good enough for them, then it should be good enough for us.
+ * https://github.com/ChainSafe/lodestar
+ */
+import { PeerErrorSeverity } from '@aztec-labs/stdlib/p2p';
+import type { PeerId } from '@libp2p/interface';
+
+import type { PeerScoring } from '../../peer-manager/peer_scoring.js';
+import type { ProtocolRateLimitQuota, ReqRespSubProtocol, ReqRespSubProtocolRateLimits } from '../interface.js';
+import { DEFAULT_RATE_LIMITS } from './rate_limits.js';
+
+// Check for disconnected peers every 10 minutes
+const CHECK_DISCONNECTED_PEERS_INTERVAL_MS = 10 * 60 * 1000;
+
+/**
+ * GCRARateLimiter: A Generic Cell Rate Algorithm (GCRA) based rate limiter.
+ *
+ * How it works:
+ * 1. The rate limiter allows a certain number of operations (quotaCount) within a specified
+ *    time interval (quotaTimeMs).
+ * 2. It uses a "virtual scheduling time" (VST) to determine when the next operation should be allowed.
+ * 3. When an operation is requested, the limiter checks if enough time has passed since the last
+ *    allowed operation.
+ * 4. If sufficient time has passed, the operation is allowed, and the VST is updated.
+ * 5. If not enough time has passed, the operation is denied.
+ *
+ * The limiter also allows for short bursts of activity, as long as the overall rate doesn't exceed
+ * the specified quota over time.
+ *
+ * Usage example:
+ * ```
+ * const limiter = new GCRARateLimiter(100, 60000); // 100 operations per minute
+ * ```
+ */
+export class GCRARateLimiter {
+  // Virtual scheduling time: i.e. the time at which we should allow the next request
+  private vst: number;
+  // The interval at which we emit a new token
+  private readonly emissionInterval: number;
+  // The interval over which we limit the number of requests
+  private readonly limitInterval: number;
+
+  /**
+   * @param quotaCount - The number of requests to allow over the limit interval
+   * @param quotaTimeMs - The time interval over which the quotaCount applies
+   */
+  constructor(quotaCount: number, quotaTimeMs: number) {
+    this.emissionInterval = quotaTimeMs / quotaCount;
+    this.limitInterval = quotaTimeMs;
+    this.vst = Date.now();
+  }
+
+  allow(): boolean {
+    const now = Date.now();
+
+    const newVst = Math.max(this.vst, now) + this.emissionInterval;
+    if (newVst - now <= this.limitInterval) {
+      this.vst = newVst;
+      return true;
+    }
+
+    return false;
+  }
+}
+
+interface PeerRateLimiter {
+  // The rate limiter for this peer
+  limiter: GCRARateLimiter;
+  // The last time the peer was accessed - used to determine if the peer is still connected
+  lastAccess: number;
+}
+
+export enum RateLimitStatus {
+  DeniedGlobal,
+  DeniedPeer,
+  Allowed, // Note: allowed last to prevent enum evaluating to 0 for success
+}
+
+export function prettyPrintRateLimitStatus(status: RateLimitStatus) {
+  switch (status) {
+    case RateLimitStatus.DeniedGlobal:
+      return 'DeniedGlobal';
+    case RateLimitStatus.DeniedPeer:
+      return 'DeniedPeer';
+    case RateLimitStatus.Allowed:
+      return 'Allowed';
+  }
+}
+
+/**
+ * SubProtocolRateLimiter: A rate limiter for managing request rates on a per-peer and global basis for a specific subprotocol.
+ *
+ * This class provides a two-tier rate limiting system:
+ * 1. A global rate limit for all requests across all peers for this subprotocol.
+ * 2. Individual rate limits for each peer.
+ *
+ * How it works:
+ * - When a request comes in, it first checks against the peer's individual rate limit.
+ * - If the peer limit allows, it then checks against the global rate limit.
+ * - The request is only allowed if both the peer-specific and global limits allow it.
+ * - Checking peer limit first ensures a rate-limited peer cannot exhaust the global quota.
+ * - It automatically creates and manages rate limiters for new peers as they make requests.
+ * - It periodically cleans up rate limiters for inactive peers to conserve memory.
+ *
+ * Note: Remember to call `start()` to begin the cleanup process and `stop()` when shutting down to clear the cleanup interval.
+ */
+export class SubProtocolRateLimiter {
+  private peerLimiters: Map<string, PeerRateLimiter> = new Map();
+  private globalLimiter: GCRARateLimiter;
+  private readonly peerQuotaCount: number;
+  private readonly peerQuotaTimeMs: number;
+
+  constructor(peerQuotaCount: number, peerQuotaTimeMs: number, globalQuotaCount: number, globalQuotaTimeMs: number) {
+    this.peerLimiters = new Map();
+    this.globalLimiter = new GCRARateLimiter(globalQuotaCount, globalQuotaTimeMs);
+    this.peerQuotaCount = peerQuotaCount;
+    this.peerQuotaTimeMs = peerQuotaTimeMs;
+  }
+
+  allow(peerId: PeerId): RateLimitStatus {
+    const peerIdStr = peerId.toString();
+    let peerLimiter: PeerRateLimiter | undefined = this.peerLimiters.get(peerIdStr);
+    if (!peerLimiter) {
+      // Create a limiter for this peer
+      peerLimiter = {
+        limiter: new GCRARateLimiter(this.peerQuotaCount, this.peerQuotaTimeMs),
+        lastAccess: Date.now(),
+      };
+      this.peerLimiters.set(peerIdStr, peerLimiter);
+    } else {
+      peerLimiter.lastAccess = Date.now();
+    }
+
+    // Check peer limit first: a rate-limited peer must not consume global quota,
+    // otherwise one spamming peer can starve all others by exhausting the global bucket.
+    if (!peerLimiter.limiter.allow()) {
+      return RateLimitStatus.DeniedPeer;
+    }
+
+    if (!this.globalLimiter.allow()) {
+      return RateLimitStatus.DeniedGlobal;
+    }
+
+    return RateLimitStatus.Allowed;
+  }
+
+  cleanupInactivePeers() {
+    const now = Date.now();
+    this.peerLimiters.forEach((peerLimiter, peerId) => {
+      if (now - peerLimiter.lastAccess > CHECK_DISCONNECTED_PEERS_INTERVAL_MS) {
+        this.peerLimiters.delete(peerId);
+      }
+    });
+  }
+}
+
+/**
+ * RequestResponseRateLimiter.
+ *
+ * A rate limiter that is protocol aware, then peer aware.
+ * SubProtocols can have their own global / peer level rate limits.
+ *
+ * How it works:
+ * - Initializes with a set of rate limit configurations for different subprotocols.
+ * - Creates a separate SubProtocolRateLimiter for each configured subprotocol.
+ * - When a request comes in, it routes the rate limiting decision to the appropriate subprotocol limiter.
+ * - Peers who exceed their peer rate limits will be penalised by the peer manager.
+ *
+ * Usage:
+ * ```
+ * const peerManager = new PeerManager(...);
+ * const rateLimits = {
+ *   subprotocol1: { peerLimit: { quotaCount: 10, quotaTimeMs: 1000 }, globalLimit: { quotaCount: 100, quotaTimeMs: 1000 } },
+ *   subprotocol2: { peerLimit: { quotaCount: 5, quotaTimeMs: 1000 }, globalLimit: { quotaCount: 50, quotaTimeMs: 1000 } }
+ * };
+ * const limiter = new RequestResponseRateLimiter(peerManager, rateLimits);
+ *
+ * Note: Ensure to call `stop()` when shutting down to properly clean up all subprotocol limiters.
+ */
+export class RequestResponseRateLimiter {
+  private subProtocolRateLimiters: Map<ReqRespSubProtocol, SubProtocolRateLimiter>;
+  private rateLimits: ReqRespSubProtocolRateLimits;
+
+  private cleanupInterval: NodeJS.Timeout | undefined = undefined;
+
+  constructor(
+    private peerScoring: PeerScoring,
+    rateLimits: Partial<ReqRespSubProtocolRateLimits> = {},
+  ) {
+    this.subProtocolRateLimiters = new Map();
+
+    this.rateLimits = { ...DEFAULT_RATE_LIMITS, ...rateLimits };
+    for (const [subProtocol, protocolLimits] of Object.entries(this.rateLimits)) {
+      this.subProtocolRateLimiters.set(
+        subProtocol as ReqRespSubProtocol,
+        new SubProtocolRateLimiter(
+          protocolLimits.peerLimit.quotaCount,
+          protocolLimits.peerLimit.quotaTimeMs,
+          protocolLimits.globalLimit.quotaCount,
+          protocolLimits.globalLimit.quotaTimeMs,
+        ),
+      );
+    }
+  }
+
+  start() {
+    this.cleanupInterval = setInterval(() => {
+      this.cleanupInactivePeers();
+    }, CHECK_DISCONNECTED_PEERS_INTERVAL_MS);
+  }
+
+  allow(subProtocol: ReqRespSubProtocol, peerId: PeerId): RateLimitStatus {
+    const limiter = this.subProtocolRateLimiters.get(subProtocol);
+    if (!limiter) {
+      return RateLimitStatus.Allowed;
+    }
+    const rateLimitStatus = limiter.allow(peerId);
+
+    if (rateLimitStatus === RateLimitStatus.DeniedPeer) {
+      this.peerScoring.penalizePeer(peerId, PeerErrorSeverity.HighToleranceError);
+    }
+    return rateLimitStatus;
+  }
+
+  cleanupInactivePeers() {
+    this.subProtocolRateLimiters.forEach(limiter => limiter.cleanupInactivePeers());
+  }
+
+  /**
+   * Make sure to call destroy on each of the sub protocol rate limiters when cleaning up
+   */
+  stop() {
+    clearInterval(this.cleanupInterval);
+  }
+
+  getRateLimits(protocol: ReqRespSubProtocol): ProtocolRateLimitQuota {
+    return this.rateLimits[protocol];
+  }
+}

package/src/services/reqresp/rate-limiter/rate_limits.ts

@@ -0,0 +1,65 @@
+import { ReqRespSubProtocol, type ReqRespSubProtocolRateLimits } from '../interface.js';
+
+// TODO(md): these defaults need to be tuned
+export const DEFAULT_RATE_LIMITS: ReqRespSubProtocolRateLimits = {
+  [ReqRespSubProtocol.PING]: {
+    peerLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 5,
+    },
+    globalLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 50,
+    },
+  },
+  [ReqRespSubProtocol.STATUS]: {
+    peerLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 5,
+    },
+    globalLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 50,
+    },
+  },
+  [ReqRespSubProtocol.AUTH]: {
+    peerLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 5,
+    },
+    globalLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 10,
+    },
+  },
+  [ReqRespSubProtocol.TX]: {
+    peerLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 10,
+    },
+    globalLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 200,
+    },
+  },
+  [ReqRespSubProtocol.GOODBYE]: {
+    peerLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 5,
+    },
+    globalLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 50,
+    },
+  },
+  [ReqRespSubProtocol.BLOCK_TXS]: {
+    peerLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 10,
+    },
+    globalLimit: {
+      quotaTimeMs: 1000,
+      quotaCount: 200,
+    },
+  },
+};