@erox/rate-limiter 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+# @discord-toolkit/rate-limiter
+
+Handles Discord's rate limits automatically. Wraps your requests, tracks
+the buckets, queues stuff when it needs to, retries on 429s. You don't
+have to think about any of it.
+
+Current with Discord API v10 rate limit behavior as of mid-2026,
+including `X-RateLimit-Scope`, the shared-bucket 429 exemption, and the
+invalid-request ban threshold.
+
+## Why
+
+Discord splits rate limits per-route (via the `X-RateLimit-Bucket`
+header) and also has a global cap on top of that (50 req/sec by
+default). Most people either ignore this until they get hit with 429s
+in production, or they write some half-working delay logic that breaks
+the moment they add a second route. This handles both layers properly.
+
+## Install
+
+```
+npm install @discord-toolkit/rate-limiter
+```
+
+## Quick start
+
+```js
+const { RateLimitManager } = require('@discord-toolkit/rate-limiter');
+
+const limiter = new RateLimitManager();
+
+async function sendMessage(channelId, content) {
+  const routeKey = `POST /channels/${channelId}/messages`;
+
+  return limiter.schedule(routeKey, () =>
+    fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bot ${TOKEN}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ content }),
+    })
+  );
+}
+```
+
+Call `sendMessage` as many times as you want, from wherever — it queues
+and paces itself against whatever Discord tells it in the response
+headers. That's the whole pitch.
+
+---
+
+## Beginner guide: what's actually going on
+
+If you're new to rate limiting on Discord, here's the short version:
+
+1. Every time you hit an endpoint (send a message, edit a role, whatever),
+   Discord's response includes headers telling you how many more requests
+   you can make before you get cut off, and when that count resets.
+2. If you ignore those headers and just fire requests as fast as your
+   code can go, eventually you'll get a `429 Too Many Requests` back.
+   Do that too often and Discord can temporarily ban your bot from the
+   API entirely (a "Cloudflare ban"), which is much worse than a slow bot.
+3. There isn't just one limit — there's a limit *per route* (e.g.
+   sending messages in one channel doesn't affect your ability to edit
+   roles) and a *global* limit across everything combined.
+
+This library reads those headers for you after every request and holds
+back future requests to the same bucket until it's safe, instead of you
+having to write `setTimeout` guesses everywhere.
+
+You don't need to understand buckets deeply to use this — just wrap your
+requests in `limiter.schedule(...)` like the example above and it's handled.
+Read on if you want the details.
+
+---
+
+## API reference
+
+### `new RateLimitManager(options)`
+
+Creates a manager. You'll usually want exactly one of these per bot,
+shared across all your commands/handlers.
+
+| option | default | what it does |
+|---|---|---|
+| `globalLimit` | `50` | requests/sec allowed across every route combined |
+| `maxRetries` | `3` | how many times a 429 gets retried before the call throws |
+| `onRateLimit` | `undefined` | `(info) => void`, called every time a 429 is hit |
+| `onInvalidRequestWarning` | `undefined` | `(count) => void`, called once the invalid-request count crosses `invalidRequestWarningThreshold` in a 10-minute window |
+| `invalidRequestWarningThreshold` | `8000` | how many 401/403/non-shared-429 responses in 10 minutes before `onInvalidRequestWarning` fires (Discord's own cutoff is 10,000) |
+
+```js
+const limiter = new RateLimitManager({
+  globalLimit: 50,
+  maxRetries: 5,
+  onRateLimit: (info) => {
+    console.warn(`rate limited on ${info.routeKey}, retrying in ${info.retryAfterMs}ms`);
+  },
+  onInvalidRequestWarning: (count) => {
+    console.error(`hit ${count} invalid requests in the last 10 minutes - approaching an IP ban`);
+  },
+});
+```
+
+### `onRateLimit` payload
+
+```js
+{
+  routeKey: 'POST /channels/123/messages',
+  global: false,       // whether this was the global limit or a per-route one
+  scope: 'user',       // 'user' | 'shared' | null, from X-RateLimit-Scope
+  retryAfterMs: 1200,
+  attempt: 1,          // which retry attempt this is
+}
+```
+
+`scope: 'shared'` means the 429 came from contention on a resource other
+apps also hit (common on things like reaction endpoints), not from your
+own bot overusing it - these don't count toward the invalid-request
+tracker since they're not really "your" mistake.
+
+### `limiter.schedule(routeKey, requestFn)`
+
+The main method. Queues `requestFn` behind whatever rate limit state
+exists for `routeKey`, waits if needed, runs it, reads the response
+headers, and retries automatically on 429.
+
+- **`routeKey`** — a string identifying the endpoint. Use `METHOD path`
+  with actual IDs, e.g. `"POST /channels/123/messages"`. Different IDs
+  for the same route type should get different keys so they don't block
+  each other unnecessarily (they'll get merged automatically if Discord
+  says they share a bucket anyway).
+- **`requestFn`** — a function `() => Promise<Response>` that actually
+  performs the request. Must return something fetch-shaped: a `Response`
+  object with `.headers.get(name)`, `.json()`, and `.clone()`. If you're
+  using `node-fetch`, undici, or the built-in global `fetch`, you're fine.
+  Axios users: wrap the response so it matches this shape, or use `fetch`
+  instead for the parts that go through the limiter.
+
+Returns whatever `requestFn` resolves to (the `Response`), after any
+needed retries.
+
+Throws if `maxRetries` is exceeded on repeated 429s.
+
+### `limiter.buckets`
+
+A `Map` of bucket id → `Bucket` instance, in case you want to inspect
+state directly (mostly useful for debugging/logging).
+
+### `limiter.global`
+
+The shared `GlobalBucket` instance tracking the overall request cap.
+
+---
+
+## Which action maps to which route key
+
+This library doesn't hardcode Discord's routes for you — you pass the
+route key yourself, since it's transport-agnostic (works with any HTTP
+client). Here's a cheat sheet for common actions so you're not guessing
+the format:
+
+| action | route key example |
+|---|---|
+| send message | `POST /channels/{channel.id}/messages` |
+| edit message | `PATCH /channels/{channel.id}/messages/{message.id}` |
+| delete message | `DELETE /channels/{channel.id}/messages/{message.id}` |
+| add reaction | `PUT /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me` |
+| create channel | `POST /guilds/{guild.id}/channels` |
+| edit channel | `PATCH /channels/{channel.id}` |
+| ban member | `PUT /guilds/{guild.id}/bans/{user.id}` |
+| kick member | `DELETE /guilds/{guild.id}/members/{user.id}` |
+| edit role | `PATCH /guilds/{guild.id}/roles/{role.id}` |
+| respond to interaction | `POST /interactions/{interaction.id}/{interaction.token}/callback` |
+| edit interaction reply | `PATCH /webhooks/{application.id}/{interaction.token}/messages/@original` |
+
+The exact string doesn't have to match Discord's docs word for word —
+what matters is that requests to the *same actual endpoint with the same
+major params* use the *same route key*, so they queue together correctly.
+Discord's own bucket id (returned in headers) gets merged in automatically,
+so even if your key naming is a little off, correctness won't break —
+you just might get slightly less optimal queuing until the real bucket
+id kicks in after the first request.
+
+---
+
+## How retries work
+
+When a request comes back `429`:
+
+1. The response body is read for `retry_after` (seconds) and whether
+   it's a `global` limit or scoped to this bucket.
+2. If global, the shared `GlobalBucket` gets locked for that duration —
+   every route pauses.
+3. If scoped, only that specific bucket gets locked.
+4. The request is automatically re-queued and retried.
+5. If it 429s again more than `maxRetries` times in a row, it throws
+   instead of retrying forever.
+
+You don't need to catch 429s yourself in normal use — just be ready to
+catch the eventual error if `maxRetries` is exceeded (usually means
+something's wrong, like clock drift or way too much concurrent traffic).
+
+---
+
+## Common mistakes
+
+- **Using a new route key with the ID baked in wrong.** `POST /channels/123/messages`
+  and `POST /channels/456/messages` are different buckets — that's correct,
+  don't try to collapse them into one key.
+- **Not sharing one `RateLimitManager` instance.** If you create a new
+  one per command, none of them know about each other's rate limit state.
+  Create one at startup and pass it around (or use a module-level singleton).
+- **Wrapping something that isn't fetch-shaped.** If `requestFn` doesn't
+  return a real `Response`-like object, header reading will throw. Check
+  your HTTP client's return shape first.
+
+## The invalid-request ban (and how this protects you)
+
+Separately from per-route and global rate limits, Discord tracks
+401/403/429 responses per IP over a rolling 10-minute window and
+temporarily bans the IP once that count crosses roughly 10,000. This is
+easy to trip accidentally: a bug that keeps hitting a 403 in a loop, or
+overly aggressive retries, will get you there fast.
+
+This library tracks that count internally (excluding `scope: 'shared'`
+429s, which aren't your bot's fault) and calls `onInvalidRequestWarning`
+once you cross `invalidRequestWarningThreshold` (default 8,000), giving
+you headroom to fix whatever's looping before you actually get banned.
+
+## Notes
+
+- This doesn't make the actual HTTP calls for you — it just paces them.
+  Bring your own client.
+- Works with any Discord API wrapper, or raw `fetch`, since it doesn't
+  care what's inside `requestFn` beyond the response shape.
+
+## Changelog
+
+**0.2.0**
+- Reads `X-RateLimit-Scope` and skips counting `shared`-scoped 429s
+  against the invalid-request tracker.
+- Falls back to the `Retry-After` header when a 429 response has no
+  usable JSON body.
+- Added `onRateLimit` and `onInvalidRequestWarning` hooks.
+- Fixed a deadlock where a retried request could get stuck forever if
+  the retry was scheduled while the same bucket's queue was still
+  awaiting the original attempt.
+
+**0.1.0**
+- Initial release: per-route bucket tracking, global bucket, automatic
+  429 retry.

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@erox/rate-limiter",
+  "version": "0.2.0",
+  "description": "Handles Discord API rate limits so you don't have to think about it",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": ["discord", "rate-limit", "bot"],
+  "author": "Erox (https://www.npmjs.com/~erox_the._exotic)",
+  "homepage": "https://www.npmjs.com/~erox_the._exotic",
+  "license": "MIT"
+}

package/src/bucket.js

@@ -0,0 +1,71 @@
+'use strict';
+
+// Tracks the rate limit state for a single Discord API bucket.
+// Discord groups routes into buckets via the X-RateLimit-Bucket header,
+// so multiple routes can share the same bucket depending on major params.
+
+class Bucket {
+  constructor(id) {
+    this.id = id;
+    this.limit = Infinity;
+    this.remaining = Infinity;
+    this.resetAt = 0; // epoch ms
+    this.scope = null; // 'user' | 'shared' | 'global', from X-RateLimit-Scope
+    this.queue = [];
+    this.processing = false;
+  }
+
+  updateFromHeaders(headers) {
+    const limit = headers.get('x-ratelimit-limit');
+    const remaining = headers.get('x-ratelimit-remaining');
+    const resetAfter = headers.get('x-ratelimit-reset-after');
+
+    if (limit !== null) this.limit = Number(limit);
+    if (remaining !== null) this.remaining = Number(remaining);
+    if (resetAfter !== null) {
+      this.resetAt = Date.now() + Number(resetAfter) * 1000;
+    }
+  }
+
+  get isLimited() {
+    return this.remaining <= 0 && Date.now() < this.resetAt;
+  }
+
+  get waitTime() {
+    return this.isLimited ? this.resetAt - Date.now() : 0;
+  }
+
+  async enqueue(task) {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ task, resolve, reject });
+      this._process();
+    });
+  }
+
+  async _process() {
+    if (this.processing) return;
+    this.processing = true;
+
+    while (this.queue.length) {
+      if (this.isLimited) {
+        await sleep(this.waitTime);
+      }
+
+      const { task, resolve, reject } = this.queue.shift();
+      try {
+        const result = await task();
+        resolve(result);
+      } catch (err) {
+        reject(err);
+      }
+    }
+
+    this.processing = false;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+module.exports = { Bucket };

package/src/globalBucket.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Discord enforces a global cap (default 50 requests/sec per bot) on top
+// of per-route buckets. This tracks that separately since it applies
+// across every route regardless of which bucket a request belongs to.
+
+class GlobalBucket {
+  constructor(limit = 50) {
+    this.limit = limit;
+    this.remaining = limit;
+    this.windowStart = Date.now();
+    this.lockedUntil = 0;
+  }
+
+  _refillIfNeeded() {
+    const now = Date.now();
+    if (now - this.windowStart >= 1000) {
+      this.windowStart = now;
+      this.remaining = this.limit;
+    }
+  }
+
+  get isLocked() {
+    return Date.now() < this.lockedUntil;
+  }
+
+  lock(retryAfterMs) {
+    this.lockedUntil = Date.now() + retryAfterMs;
+  }
+
+  async take() {
+    this._refillIfNeeded();
+
+    if (this.isLocked) {
+      await sleep(this.lockedUntil - Date.now());
+      return this.take();
+    }
+
+    if (this.remaining <= 0) {
+      const waitMs = 1000 - (Date.now() - this.windowStart);
+      await sleep(Math.max(waitMs, 0));
+      return this.take();
+    }
+
+    this.remaining -= 1;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+module.exports = { GlobalBucket };

package/src/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const { RateLimitManager } = require('./queue');
+const { Bucket } = require('./bucket');
+const { GlobalBucket } = require('./globalBucket');
+
+module.exports = {
+  RateLimitManager,
+  Bucket,
+  GlobalBucket,
+};

package/src/queue.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const { Bucket } = require('./bucket');
+const { GlobalBucket } = require('./globalBucket');
+
+// Ties per-route buckets and the global bucket together. This is the
+// piece that actually wraps a request function and decides when it's
+// safe to fire it off.
+
+// Discord temporarily bans IPs that rack up too many invalid responses
+// (401/403/429) within a 10 minute window (currently 10,000). This is
+// tracked separately from per-route/global limits since it's a distinct
+// failure mode that's easy to trip during retries or bad-permission bugs.
+const INVALID_REQUEST_WINDOW_MS = 10 * 60 * 1000;
+
+class RateLimitManager {
+  constructor(opts = {}) {
+    this.buckets = new Map(); // route key -> Bucket
+    this.routeToBucketId = new Map(); // route key -> discord bucket id
+    this.global = new GlobalBucket(opts.globalLimit || 50);
+    this.maxRetries = opts.maxRetries ?? 3;
+
+    this.onRateLimit = opts.onRateLimit; // (info) => void, fired whenever a 429 is hit
+    this.onInvalidRequestWarning = opts.onInvalidRequestWarning; // (count) => void
+
+    this._invalidTimestamps = [];
+    this.invalidRequestWarningThreshold = opts.invalidRequestWarningThreshold ?? 8000;
+  }
+
+  _bucketFor(routeKey) {
+    const bucketId = this.routeToBucketId.get(routeKey) || routeKey;
+    if (!this.buckets.has(bucketId)) {
+      this.buckets.set(bucketId, new Bucket(bucketId));
+    }
+    return this.buckets.get(bucketId);
+  }
+
+  _trackInvalidRequest() {
+    const now = Date.now();
+    this._invalidTimestamps.push(now);
+    this._invalidTimestamps = this._invalidTimestamps.filter(
+      (t) => now - t < INVALID_REQUEST_WINDOW_MS
+    );
+
+    if (
+      this.onInvalidRequestWarning &&
+      this._invalidTimestamps.length === this.invalidRequestWarningThreshold
+    ) {
+      this.onInvalidRequestWarning(this._invalidTimestamps.length);
+    }
+  }
+
+  // routeKey: a string identifying the route + major params, e.g. "POST /channels/123/messages"
+  // requestFn: () => Promise<Response> (fetch-like, must return a Response object)
+  //
+  // Retries are handled with a loop inside the single enqueued task below,
+  // rather than by recursively calling schedule()/enqueue() again. Recursing
+  // back into bucket.enqueue() from within a task that bucket's own queue is
+  // currently awaiting would deadlock - the queue can't advance to the newly
+  // pushed retry because it's still blocked on the task that pushed it.
+  async schedule(routeKey, requestFn) {
+    const bucket = this._bucketFor(routeKey);
+
+    return bucket.enqueue(async () => {
+      let attempt = 0;
+
+      while (true) {
+        await this.global.take();
+
+        const res = await requestFn();
+
+        const discordBucketId = res.headers.get('x-ratelimit-bucket');
+        if (discordBucketId && this.routeToBucketId.get(routeKey) !== discordBucketId) {
+          this.routeToBucketId.set(routeKey, discordBucketId);
+        }
+        bucket.updateFromHeaders(res.headers);
+        bucket.scope = res.headers.get('x-ratelimit-scope') || bucket.scope;
+
+        if (res.status === 401 || res.status === 403) {
+          this._trackInvalidRequest();
+          return res;
+        }
+
+        if (res.status !== 429) {
+          return res;
+        }
+
+        // 429s scoped as "shared" come from contention on a resource shared
+        // with other apps/users, not our own overuse - they don't count
+        // toward the invalid request ban threshold.
+        if (bucket.scope !== 'shared') {
+          this._trackInvalidRequest();
+        }
+
+        if (attempt >= this.maxRetries) {
+          throw new Error(`Rate limited after ${this.maxRetries} retries on ${routeKey}`);
+        }
+
+        const body = await res.clone().json().catch(() => null);
+        const headerRetryAfter = res.headers.get('retry-after');
+        const retryAfterSeconds = body?.retry_after ?? (headerRetryAfter ? Number(headerRetryAfter) : 1);
+        const retryAfterMs = retryAfterSeconds * 1000;
+        const isGlobal = body?.global ?? res.headers.get('x-ratelimit-global') === 'true';
+
+        if (isGlobal) {
+          this.global.lock(retryAfterMs);
+        } else {
+          bucket.remaining = 0;
+          bucket.resetAt = Date.now() + retryAfterMs;
+        }
+
+        attempt += 1;
+
+        if (this.onRateLimit) {
+          this.onRateLimit({
+            routeKey,
+            global: isGlobal,
+            scope: bucket.scope,
+            retryAfterMs,
+            attempt,
+          });
+        }
+
+        // loop and retry - global.take() and the bucket's own reset check
+        // (inside enqueue's caller) will naturally hold this back until
+        // whichever lock we just set has expired
+        if (bucket.isLimited) {
+          await sleep(bucket.waitTime);
+        }
+      }
+    });
+  }
+}
+
+function sleep(ms) {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+module.exports = { RateLimitManager };