lunibee 0.3.0 → 0.3.2

package/dist/rest/index.js

@@ -2,7 +2,7 @@
 // packages/rest/package.json
 var package_default = {
   name: "@lunibee/rest",
-  version: "0.3.0",
+  version: "0.3.2",
   type: "module",
   module: "./src/index.ts",
   types: "./src/index.ts",
@@ -15,38 +15,179 @@ var package_default = {
 };
 
 // packages/rest/src/store.ts
+var GLOBAL_WINDOW_MS = 1050;
+function takeGlobalSlot(log, now, limit, window = GLOBAL_WINDOW_MS) {
+  while (log.length > 0 && log[0] <= now - window)
+    log.shift();
+  if (log.length >= limit)
+    return Math.max(1, log[0] + window - now + 1);
+  log.push(now);
+  return 0;
+}
+var PROBE_POLL_MS = 50;
+var DEFAULT_PROBE_MS = 16000;
+var BUCKET_LINGER_MS = 60000;
+var WINDOW_TOLERANCE_MS = 50;
+function reserveState(state, now, probeMs) {
+  if (state && state.resetAt > now) {
+    if (state.remaining > 0)
+      return {
+        reservation: {
+          granted: true,
+          known: true,
+          resetAt: state.resetAt
+        },
+        next: { ...state, remaining: state.remaining - 1 }
+      };
+    const wait = state.resetAt - now;
+    return {
+      reservation: {
+        granted: false,
+        retryAfterMs: state.provisional ? Math.min(wait, PROBE_POLL_MS) : wait,
+        reason: state.probe ? "probe" : "bucket"
+      }
+    };
+  }
+  const resetAt = now + probeMs;
+  if (state?.limit !== undefined && state.limit > 0)
+    return {
+      reservation: { granted: true, known: true, resetAt },
+      next: {
+        remaining: state.limit - 1,
+        resetAt,
+        limit: state.limit,
+        provisional: true
+      }
+    };
+  return {
+    reservation: { granted: true, known: false, resetAt },
+    next: { remaining: 0, resetAt, provisional: true, probe: true }
+  };
+}
+function reconcileState(state, update, now) {
+  const incoming = update.resetAfterMs === undefined ? undefined : Math.ceil(now + update.resetAfterMs);
+  const active = !!state && state.resetAt > now && !state.probe;
+  let next;
+  if (active) {
+    next = { ...state };
+    const stale = update.window !== undefined && next.window !== undefined && update.window < next.window - WINDOW_TOLERANCE_MS;
+    if (!stale) {
+      if (update.remaining !== undefined)
+        next.remaining = Math.min(next.remaining, update.remaining);
+      if (incoming !== undefined) {
+        const newer = update.window !== undefined && next.window !== undefined && update.window > next.window + WINDOW_TOLERANCE_MS;
+        next.resetAt = next.provisional || newer ? incoming : Math.max(next.resetAt, incoming);
+        delete next.provisional;
+      }
+      if (update.window !== undefined)
+        next.window = Math.max(next.window ?? 0, update.window);
+    }
+  } else {
+    if (update.remaining === undefined && update.retryAfterMs === undefined) {
+      return state?.probe ? null : undefined;
+    }
+    next = {
+      remaining: update.remaining ?? 0,
+      resetAt: incoming ?? now
+    };
+    if (state?.limit !== undefined)
+      next.limit = state.limit;
+    if (update.window !== undefined)
+      next.window = update.window;
+  }
+  if (update.limit !== undefined && update.limit > 0)
+    next.limit = update.limit;
+  if (update.retryAfterMs !== undefined) {
+    next.remaining = 0;
+    next.resetAt = Math.max(next.resetAt, Math.ceil(now + update.retryAfterMs));
+    delete next.provisional;
+  }
+  return next;
+}
+
 class MemoryRateLimitStore {
   #buckets = new Map;
   #routeBuckets = new Map;
-  #globalResetAt = 0;
+  #globals = new Map;
+  #globalLogs = new Map;
   static #PRUNE_INTERVAL = 60000;
   #lastPruneAt = 0;
+  static #MAX_ENTRIES = 1e4;
+  reservesGlobal = true;
+  constructor() {}
+  static #evict(map) {
+    while (map.size > MemoryRateLimitStore.#MAX_ENTRIES)
+      map.delete(map.keys().next().value);
+  }
   getBucketHash(route) {
     return this.#routeBuckets.get(route);
   }
   setBucketHash(route, hash) {
+    this.#routeBuckets.delete(route);
     this.#routeBuckets.set(route, hash);
+    MemoryRateLimitStore.#evict(this.#routeBuckets);
   }
   getBucket(key) {
     return this.#buckets.get(key);
   }
-  reserve(key) {
-    const state = this.#buckets.get(key);
+  reserve(key, options = {}) {
     const now = Date.now();
-    if (!state || state.resetAt <= now)
-      return { granted: true };
-    if (state.remaining > 0) {
-      state.remaining -= 1;
-      return { granted: true };
+    if (options.global !== undefined) {
+      const globalWait = this.getGlobalReset(options.global) - now;
+      if (globalWait > 0)
+        return {
+          granted: false,
+          retryAfterMs: globalWait,
+          reason: "global"
+        };
     }
-    return { granted: false, retryAfterMs: state.resetAt - now };
+    const limit = options.global === undefined ? 0 : options.globalLimit ?? 0;
+    let log;
+    if (limit > 0) {
+      log = this.#globalLogs.get(options.global);
+      if (!log) {
+        this.#globalLogs.set(options.global, log = []);
+        MemoryRateLimitStore.#evict(this.#globalLogs);
+      }
+      const wait = takeGlobalSlot(log, now, limit);
+      if (wait > 0)
+        return { granted: false, retryAfterMs: wait, reason: "global" };
+      log.pop();
+    }
+    const { reservation, next } = reserveState(this.#buckets.get(key), now, options.probeMs ?? DEFAULT_PROBE_MS);
+    if (log && reservation.granted)
+      log.push(now);
+    if (next)
+      this.#write(key, next);
+    return reservation;
+  }
+  reconcile(key, update) {
+    const next = reconcileState(this.#buckets.get(key), update, Date.now());
+    if (next === null)
+      this.#buckets.delete(key);
+    else if (next)
+      this.#write(key, next);
+  }
+  release(key, grant, refund) {
+    const state = this.#buckets.get(key);
+    if (!state || state.resetAt !== grant.resetAt)
+      return;
+    if (state.probe)
+      this.#buckets.delete(key);
+    else if (refund)
+      state.remaining = Math.min(state.remaining + 1, state.limit ?? Number.POSITIVE_INFINITY);
   }
   updateBucket(key, state) {
+    this.#write(key, state);
+  }
+  #write(key, state) {
+    this.#buckets.delete(key);
     this.#buckets.set(key, state);
+    MemoryRateLimitStore.#evict(this.#buckets);
     const now = Date.now();
     if (now - this.#lastPruneAt >= MemoryRateLimitStore.#PRUNE_INTERVAL) {
       this.#lastPruneAt = now;
-      this.prune();
+      this.prune(BUCKET_LINGER_MS);
     }
   }
   prune(maxAge = 0) {
@@ -55,12 +196,27 @@ class MemoryRateLimitStore {
       if (state.resetAt <= cutoff)
         this.#buckets.delete(key);
     }
+    for (const [scope, resetAt] of this.#globals)
+      if (resetAt <= Date.now())
+        this.#globals.delete(scope);
+    for (const [scope, log] of this.#globalLogs)
+      if ((log.at(-1) ?? 0) <= Date.now() - GLOBAL_WINDOW_MS)
+        this.#globalLogs.delete(scope);
+  }
+  getGlobalReset(scope = "") {
+    return this.#globals.get(scope) ?? 0;
   }
-  getGlobalReset() {
-    return this.#globalResetAt;
+  setGlobalReset(resetAt, scope = "") {
+    this.#globals.set(scope, resetAt);
+    MemoryRateLimitStore.#evict(this.#globals);
   }
-  setGlobalReset(resetAt) {
-    this.#globalResetAt = resetAt;
+  extendGlobalReset(scope, waitMs) {
+    const resetAt = Date.now() + Math.max(0, waitMs);
+    if (resetAt > this.getGlobalReset(scope))
+      this.setGlobalReset(resetAt, scope);
+  }
+  get size() {
+    return this.#buckets.size;
   }
 }
 
@@ -85,6 +241,24 @@ function kindFromStatus(status) {
 function redactPath(path) {
   return path.replace(/^(\/webhooks\/[^/?]+\/)[^/?]+/i, "$1:token").replace(/^(\/interactions\/[^/?]+\/)[^/?]+/i, "$1:token");
 }
+var TOKEN_IN_TEXT = /(\/(?:webhooks|interactions)\/[^/\s?"'`]+\/)[^/\s?"'`]+/gi;
+function redactText(text) {
+  return text.replace(TOKEN_IN_TEXT, "$1:token");
+}
+function sanitizeCause(error) {
+  if (!(error instanceof Error))
+    return;
+  const copy = new Error(redactText(error.message));
+  copy.name = error.name;
+  if (error.stack)
+    copy.stack = redactText(error.stack);
+  for (const key of ["code", "errno", "syscall"]) {
+    const value = error[key];
+    if (typeof value === "string" || typeof value === "number")
+      copy[key] = value;
+  }
+  return copy;
+}
 var HINTS = {
   50001: "The bot cannot see this resource: check that it is in the guild and has View Channel there.",
   50013: "The bot lacks a permission for this action, or the target role or member is at or above the bot's highest role."
@@ -110,24 +284,31 @@ class RESTError extends Error {
     this.path = options.path === undefined ? undefined : redactPath(options.path);
   }
   get retryable() {
-    return this.kind === "rateLimited" || this.kind === "server" || this.kind === "network" || this.kind === "timeout";
+    return this.kind === "rateLimited" || this.kind === "server" || this.kind === "network" || this.kind === "timeout" || this.kind === "coordination" || this.kind === "overloaded";
   }
 }
 function abortError(path, reason) {
   return new RESTError(reason instanceof Error ? reason.message : "Discord REST request was aborted", 0, undefined, undefined, { path, cause: reason, kind: "aborted" });
 }
+var MAX_TIMER_MS = 2147483647;
 async function sleep(delay, signal, path) {
   if (delay <= 0)
     return;
+  delay = Math.min(delay, MAX_TIMER_MS);
   await new Promise((resolve, reject) => {
-    const timer = setTimeout(resolve, delay);
-    const abort = () => {
+    const finish = (error) => {
       clearTimeout(timer);
-      reject(abortError(path, signal?.reason));
+      signal?.removeEventListener("abort", onAbort);
+      if (error)
+        reject(error);
+      else
+        resolve();
     };
+    const onAbort = () => finish(abortError(path, signal?.reason));
+    const timer = setTimeout(finish, delay);
     if (signal?.aborted)
-      return abort();
-    signal?.addEventListener("abort", abort, { once: true });
+      return onAbort();
+    signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
 async function abortable(promise, signal, path) {
@@ -135,10 +316,17 @@ async function abortable(promise, signal, path) {
     return promise;
   if (signal.aborted)
     throw abortError(path, signal.reason);
-  return Promise.race([
-    promise,
-    new Promise((_, reject) => signal.addEventListener("abort", () => reject(abortError(path, signal.reason)), { once: true }))
-  ]);
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(path, signal.reason));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, (error) => {
+      signal.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+  });
 }
 
 // packages/rest/src/route.ts
@@ -146,7 +334,7 @@ import { createHash } from "crypto";
 function normalizeRoutePath(path) {
   const queryIndex = path.indexOf("?");
   const routePath = queryIndex === -1 ? path : path.slice(0, queryIndex);
-  return redactPath(routePath).replace(/\/\d+(?=\/|$)/g, "/:id");
+  return redactPath(routePath).replace(/\/\d+(?=\/|$)/g, "/:id").replace(/\/reactions\/[^/]+/i, "/reactions/:emoji");
 }
 function majorParameter(path) {
   const match = /^\/(channels|guilds|webhooks)\/(\d+)(?:\/([^/?]+))?/i.exec(path);
@@ -185,9 +373,22 @@ function serializeQuery(query) {
 class RequestScheduler {
   static MAX_REMAPS = 2;
   #queues = new Map;
+  #waiting = new Map;
+  #queued = 0;
+  #maxQueued;
+  #maxQueuedPerBucket;
+  constructor(options = {}) {
+    this.#maxQueued = options.maxQueued ?? Number.POSITIVE_INFINITY;
+    this.#maxQueuedPerBucket = options.maxQueuedPerBucket ?? Number.POSITIVE_INFINITY;
+    if (!(this.#maxQueued >= 0) || !(this.#maxQueuedPerBucket >= 0))
+      throw new RangeError("Queue limits must be non-negative numbers.");
+  }
   get size() {
     return this.#queues.size;
   }
+  get queued() {
+    return this.#queued;
+  }
   async runResolved(resolveKey, signal, path, task) {
     let key = await resolveKey();
     for (let hop = 0;hop < RequestScheduler.MAX_REMAPS; hop++) {
@@ -204,7 +405,10 @@ class RequestScheduler {
     return this.run(key, signal, path, (release) => task(key, release));
   }
   async run(key, signal, path, task) {
-    const previous = this.#queues.get(key) ?? Promise.resolve();
+    const previous = this.#queues.get(key);
+    const waiting = this.#waiting.get(key) ?? 0;
+    if (previous && (this.#queued >= this.#maxQueued || waiting >= this.#maxQueuedPerBucket))
+      throw new RESTError("The REST request queue is full; request not sent.", 0, undefined, undefined, { path, kind: "overloaded" });
     let open;
     const gate = new Promise((resolve) => {
       open = resolve;
@@ -220,7 +424,21 @@ class RequestScheduler {
         this.#queues.delete(key);
     };
     try {
-      await abortable(previous, signal, path);
+      if (previous) {
+        this.#queued++;
+        this.#waiting.set(key, waiting + 1);
+        try {
+          await abortable(previous, signal, path);
+        } finally {
+          this.#queued--;
+          const left = (this.#waiting.get(key) ?? 1) - 1;
+          if (left > 0)
+            this.#waiting.set(key, left);
+          else
+            this.#waiting.delete(key);
+        }
+      } else
+        await abortable(Promise.resolve(), signal, path);
       return await task(release);
     } finally {
       release();
@@ -228,90 +446,520 @@ class RequestScheduler {
   }
 }
 
+// packages/rest/src/headers.ts
+function headerNumber(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null || raw.trim() === "")
+    return;
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+var BUCKET_HASH = /^[A-Za-z0-9:_\-.]{1,64}$/;
+var MAX_COUNT = 1e5;
+function count(value) {
+  return value === undefined || value > MAX_COUNT ? undefined : Math.floor(value);
+}
+function parseRateLimitHeaders(headers) {
+  const remaining = headerNumber(headers, "X-RateLimit-Remaining");
+  const limit = headerNumber(headers, "X-RateLimit-Limit");
+  const resetAfter = headerNumber(headers, "X-RateLimit-Reset-After");
+  const reset = headerNumber(headers, "X-RateLimit-Reset");
+  const retryAfter = headerNumber(headers, "Retry-After");
+  const bucket = headers.get("X-RateLimit-Bucket")?.trim();
+  const scope = headers.get("X-RateLimit-Scope")?.trim().toLowerCase();
+  return {
+    limit: count(limit),
+    remaining: count(remaining),
+    resetAfterMs: resetAfter === undefined ? undefined : resetAfter * 1000,
+    resetAtMs: reset === undefined ? undefined : reset * 1000,
+    bucket: bucket && BUCKET_HASH.test(bucket) ? bucket : undefined,
+    scope: scope === "user" || scope === "global" || scope === "shared" ? scope : undefined,
+    global: headers.get("X-RateLimit-Global")?.trim().toLowerCase() === "true",
+    retryAfterMs: retryAfter === undefined ? undefined : retryAfter * 1000
+  };
+}
+
+// packages/rest/src/telemetry.ts
+function emitTelemetry(sink, event) {
+  if (!sink)
+    return;
+  try {
+    sink.emit(event);
+  } catch {}
+}
+var LATENCY_BOUNDS = [
+  1,
+  5,
+  10,
+  25,
+  50,
+  100,
+  250,
+  500,
+  1000,
+  2500,
+  5000,
+  1e4,
+  30000,
+  60000
+];
+
+class RESTMetrics {
+  #counters = new Map;
+  #gauges = new Map;
+  #histograms = new Map;
+  #routes = new Set;
+  #maxRoutes;
+  constructor(options = {}) {
+    this.#maxRoutes = options.maxRoutes ?? 500;
+  }
+  #route(route) {
+    if (this.#routes.has(route))
+      return route;
+    if (this.#routes.size >= this.#maxRoutes)
+      return "other";
+    this.#routes.add(route);
+    return route;
+  }
+  #inc(name, labels = {}, by = 1) {
+    const key = metricKey(name, labels);
+    this.#counters.set(key, (this.#counters.get(key) ?? 0) + by);
+  }
+  #observe(name, value, labels = {}) {
+    const key = metricKey(name, labels);
+    let h = this.#histograms.get(key);
+    if (!h) {
+      h = {
+        counts: new Array(LATENCY_BOUNDS.length + 1).fill(0),
+        sum: 0,
+        count: 0
+      };
+      this.#histograms.set(key, h);
+    }
+    let i = LATENCY_BOUNDS.findIndex((bound) => value <= bound);
+    if (i === -1)
+      i = LATENCY_BOUNDS.length;
+    h.counts[i]++;
+    h.sum += value;
+    h.count++;
+  }
+  emit(event) {
+    switch (event.type) {
+      case "response":
+        this.#inc("responses_total", {
+          method: event.method,
+          route: this.#route(event.route),
+          status: String(event.status)
+        });
+        this.#observe("response_latency_ms", event.durationMs, {
+          method: event.method
+        });
+        break;
+      case "request":
+        this.#inc("requests_total", {
+          method: event.method,
+          outcome: event.ok ? "ok" : "error"
+        });
+        this.#observe("request_latency_ms", event.durationMs, {
+          method: event.method
+        });
+        break;
+      case "rateLimited":
+        this.#inc("rate_limited_total", {
+          scope: event.scope,
+          route: this.#route(event.route)
+        });
+        break;
+      case "wait":
+        this.#inc("waits_total", { reason: event.reason });
+        this.#observe("wait_ms", event.durationMs, {
+          reason: event.reason
+        });
+        break;
+      case "reservation":
+        this.#inc("reservations_total", {
+          outcome: event.granted ? "granted" : "refused"
+        });
+        this.#observe("reservation_latency_ms", event.latencyMs);
+        break;
+      case "retry":
+        this.#inc("retries_total", { reason: event.reason });
+        break;
+      case "cancelled":
+        this.#inc("cancellations_total", { stage: event.stage });
+        break;
+      case "overloaded":
+        this.#inc("overloaded_total");
+        break;
+      case "tokenRejected":
+        this.#inc("token_rejected_total");
+        break;
+      case "networkError":
+        this.#inc("network_errors_total", {
+          timeout: String(event.timedOut)
+        });
+        break;
+      case "bucket":
+        this.#inc("bucket_changes_total", { change: event.change });
+        break;
+      case "store":
+        this.#inc("store_commands_total", {
+          operation: event.operation,
+          ok: String(event.ok)
+        });
+        this.#observe("store_latency_ms", event.latencyMs, {
+          operation: event.operation
+        });
+        break;
+      case "mode":
+        this.#inc("mode_changes_total", { mode: event.mode });
+        this.#gauges.set("degraded", event.mode === "degraded-local" || event.mode === "unavailable" ? 1 : 0);
+        break;
+      case "queue":
+        this.#gauges.set("queued", event.queued);
+        this.#gauges.set("in_flight", event.inFlight);
+        break;
+    }
+  }
+  snapshot() {
+    const histograms = {};
+    for (const [key, h] of this.#histograms) {
+      const buckets = {};
+      let running = 0;
+      LATENCY_BOUNDS.forEach((bound, i) => {
+        running += h.counts[i];
+        buckets[String(bound)] = running;
+      });
+      buckets["+Inf"] = h.count;
+      histograms[key] = { count: h.count, sum: h.sum, buckets };
+    }
+    return {
+      counters: Object.fromEntries(this.#counters),
+      gauges: Object.fromEntries(this.#gauges),
+      histograms
+    };
+  }
+  reset() {
+    this.#counters.clear();
+    this.#gauges.clear();
+    this.#histograms.clear();
+    this.#routes.clear();
+  }
+  toPrometheus(prefix = "lunibee_rest") {
+    const lines = [];
+    const typed = new Set;
+    const type = (name, kind) => {
+      if (typed.has(name))
+        return;
+      typed.add(name);
+      lines.push(`# TYPE ${name} ${kind}`);
+    };
+    for (const [key, value] of this.#counters) {
+      const name = `${prefix}_${key.split("{")[0]}`;
+      type(name, "counter");
+      lines.push(`${prefix}_${key} ${value}`);
+    }
+    for (const [key, value] of this.#gauges) {
+      type(`${prefix}_${key}`, "gauge");
+      lines.push(`${prefix}_${key} ${value}`);
+    }
+    for (const [key, h] of this.#histograms) {
+      const [base, rawLabels = ""] = key.split("{");
+      const labels = rawLabels.replace(/\}$/, "");
+      const name = `${prefix}_${base}`;
+      type(name, "histogram");
+      const join = (extra) => `{${[labels, extra].filter(Boolean).join(",")}}`;
+      let running = 0;
+      LATENCY_BOUNDS.forEach((bound, i) => {
+        running += h.counts[i];
+        lines.push(`${name}_bucket${join(`le="${bound}"`)} ${running}`);
+      });
+      lines.push(`${name}_bucket${join('le="+Inf"')} ${h.count}`);
+      lines.push(`${name}_sum${labels ? `{${labels}}` : ""} ${h.sum}`);
+      lines.push(`${name}_count${labels ? `{${labels}}` : ""} ${h.count}`);
+    }
+    return `${lines.join(`
+`)}
+`;
+  }
+}
+function metricKey(name, labels) {
+  const entries = Object.entries(labels);
+  if (entries.length === 0)
+    return name;
+  return `${name}{${entries.map(([k, v]) => `${k}="${v.replace(/["\\\n]/g, "_")}"`).join(",")}}`;
+}
+
 // packages/rest/src/limiter.ts
+var DEFAULT_MAX_BACKOFF_MS = 600000;
+var MAX_IDLE_REFUSALS = 16;
+var MAX_CACHED_ROUTES = 1e4;
+
 class RateLimiter {
   #store;
-  #concurrent;
+  #maxBackoff;
+  #telemetry;
+  #probeMs;
+  #routes = new Map;
+  #globalLimit;
+  #localGlobal = new Map;
   constructor(store, options = {}) {
     this.#store = store;
-    this.#concurrent = options.concurrent ?? false;
+    this.#maxBackoff = options.maxBackoff ?? DEFAULT_MAX_BACKOFF_MS;
+    if (!(this.#maxBackoff >= 0))
+      throw new RangeError("maxBackoff must be a non-negative number.");
+    this.#probeMs = options.probeMs ?? DEFAULT_PROBE_MS;
+    if (!(this.#probeMs > 0))
+      throw new RangeError("probeMs must be a positive number.");
+    this.#telemetry = options.telemetry;
+    this.#globalLimit = options.globalLimit ?? 0;
+    if (!(this.#globalLimit >= 0) || !Number.isFinite(this.#globalLimit))
+      throw new RangeError("globalLimit must be a non-negative number.");
+  }
+  get maxBackoff() {
+    return this.#maxBackoff;
+  }
+  #capWait(ms) {
+    return Math.min(Math.max(0, ms), this.#maxBackoff);
   }
   get store() {
     return this.#store;
   }
-  async resolveBucketKey(route, major) {
-    return scopeBucket(await this.#store.getBucketHash(route) ?? route, major);
-  }
   get reserves() {
     return typeof this.#store.reserve === "function";
   }
-  async acquire(bucketKey, signal, path) {
-    await this.#waitGlobal(signal, path);
-    if (!this.#store.reserve) {
-      const bucket = await this.#store.getBucket(bucketKey);
+  #cacheRoute(route, hash) {
+    this.#routes.delete(route);
+    this.#routes.set(route, hash);
+    if (this.#routes.size > MAX_CACHED_ROUTES)
+      this.#routes.delete(this.#routes.keys().next().value);
+  }
+  async resolveBucketKey(route, major, identity) {
+    let hash = this.#routes.get(`${route}\x00${major}`) ?? this.#routes.get(route);
+    if (hash === undefined) {
+      hash = await this.#store.getBucketHash(route);
+      if (hash !== undefined)
+        this.#cacheRoute(route, hash);
+    }
+    const key = scopeBucket(hash ?? route, major);
+    return identity === undefined ? key : `${identity}/${key}`;
+  }
+  async#call(path, operation, call) {
+    try {
+      return await call();
+    } catch (error) {
+      if (error instanceof RESTError)
+        throw error;
+      throw new RESTError(`The rate-limit store failed (${operation}); request not sent.`, 0, undefined, undefined, { path, kind: "coordination", cause: sanitizeCause(error) });
+    }
+  }
+  async acquire(bucketKey, signal, path, options = {}) {
+    const store = this.#store;
+    const global = "global" in options ? options.global : "";
+    if (!store.reserve) {
+      await this.#waitGlobal(global ?? "", signal, path);
+      if (global !== undefined)
+        await this.#localGlobalSlot(global, signal, path);
+      const bucket = await this.#call(path, "getBucket", () => store.getBucket(bucketKey));
       if (bucket) {
         const delay = bucket.resetAt - Date.now();
         if (bucket.remaining <= 0 && delay > 0)
-          await sleep(delay, signal, path);
+          await this.#wait("bucket", delay, signal, path);
       }
+      return {
+        reserved: false,
+        known: !!bucket && bucket.resetAt > Date.now()
+      };
+    }
+    const started = performance.now();
+    let idle = 0;
+    for (;; ) {
+      if (global !== undefined && !store.reservesGlobal) {
+        await this.#waitGlobal(global, signal, path);
+        await this.#localGlobalSlot(global, signal, path);
+      }
+      const asked = performance.now();
+      const reservation = await this.#call(path, "reserve", () => store.reserve(bucketKey, {
+        global,
+        probeMs: this.#probeMs,
+        globalLimit: this.#globalLimit || undefined
+      }));
+      if (!reservation || typeof reservation !== "object" || typeof reservation.granted !== "boolean")
+        throw new RESTError("The rate-limit store returned an invalid reservation; request not sent.", 0, undefined, undefined, { path, kind: "coordination" });
+      if (reservation.granted) {
+        let known = reservation.known;
+        if (known === undefined) {
+          const bucket = await this.#call(path, "getBucket", () => store.getBucket(bucketKey));
+          known = !!bucket && bucket.resetAt > Date.now();
+        }
+        emitTelemetry(this.#telemetry, {
+          type: "reservation",
+          granted: true,
+          known,
+          latencyMs: performance.now() - asked
+        });
+        return { reserved: true, known, resetAt: reservation.resetAt };
+      }
+      emitTelemetry(this.#telemetry, {
+        type: "reservation",
+        granted: false,
+        known: true,
+        latencyMs: performance.now() - asked
+      });
+      let wait = Number(reservation.retryAfterMs);
+      if (!(wait > 0)) {
+        if (++idle > MAX_IDLE_REFUSALS)
+          throw new RESTError("The rate-limit store keeps refusing without a wait; request not sent.", 0, undefined, undefined, { path, kind: "coordination" });
+        wait = Math.min(100, 2 ** idle);
+      } else
+        idle = 0;
+      if (performance.now() - started + wait > 2 * this.#maxBackoff)
+        throw new RESTError(`Waited for the rate limit longer than twice maxBackoff (${Math.ceil(this.#maxBackoff / 1000)}s); request not sent.`, 429, undefined, undefined, { path });
+      await this.#wait(reservation.reason ?? "bucket", wait, signal, path);
+    }
+  }
+  async#wait(reason, delay, signal, path) {
+    const ms = Math.min(delay, this.#maxBackoff);
+    await sleep(ms, signal, path);
+    emitTelemetry(this.#telemetry, {
+      type: "wait",
+      reason,
+      durationMs: ms
+    });
+  }
+  async#localGlobalSlot(scope, signal, path) {
+    if (!this.#globalLimit)
       return;
+    let log = this.#localGlobal.get(scope);
+    if (!log) {
+      this.#localGlobal.set(scope, log = []);
+      if (this.#localGlobal.size > MAX_CACHED_ROUTES)
+        this.#localGlobal.delete(this.#localGlobal.keys().next().value);
     }
-    for (let attempt = 0;attempt < 8; attempt++) {
-      const reservation = await this.#store.reserve(bucketKey);
-      if (reservation.granted)
+    for (;; ) {
+      const wait = takeGlobalSlot(log, Date.now(), this.#globalLimit);
+      if (wait === 0)
         return;
-      await sleep(Math.max(1, reservation.retryAfterMs), signal, path);
-      await this.#waitGlobal(signal, path);
+      await this.#wait("global", wait, signal, path);
     }
   }
-  async#waitGlobal(signal, path) {
-    const globalDelay = await this.#store.getGlobalReset() - Date.now();
+  async#waitGlobal(scope, signal, path) {
+    const globalDelay = await this.#call(path, "getGlobalReset", () => this.#store.getGlobalReset(scope)) - Date.now();
     if (globalDelay > 0)
-      await sleep(globalDelay, signal, path);
+      await this.#wait("global", globalDelay, signal, path);
   }
-  async noteGlobalReset(resetAt) {
-    const current = await this.#store.getGlobalReset();
-    await this.#store.setGlobalReset(Math.max(current, resetAt));
-  }
-  async applyResponse(response, bucketKey, route, major) {
+  async noteGlobalReset(resetAt, scope = "") {
+    const waitMs = this.#capWait(resetAt - Date.now());
+    if (this.#store.extendGlobalReset) {
+      await this.#store.extendGlobalReset(scope, waitMs);
+      return;
+    }
+    const current = await this.#store.getGlobalReset(scope);
+    const target = Date.now() + waitMs;
+    if (target > current)
+      await this.#store.setGlobalReset(target, scope);
+  }
+  retryAfterMs(response, body = {}) {
+    const fromBody = body.retry_after;
+    if (typeof fromBody === "number" && Number.isFinite(fromBody) && fromBody >= 0)
+      return fromBody * 1000;
+    const headers = parseRateLimitHeaders(response.headers);
+    return headers.retryAfterMs ?? headers.resetAfterMs ?? 1000;
+  }
+  async applyResponse(response, bucketKey, route, major, options = {}) {
+    const headers = parseRateLimitHeaders(response.headers);
     let currentKey = bucketKey;
-    const serverBucket = response.headers.get("X-RateLimit-Bucket");
-    if (serverBucket) {
-      await this.#store.setBucketHash(route, serverBucket);
-      currentKey = scopeBucket(serverBucket, major);
-    }
-    const stored = await this.#store.getBucket(currentKey);
-    const bucket = stored ? { ...stored } : { remaining: 1, resetAt: 0 };
-    const windowActive = this.#concurrent && !!stored && stored.resetAt > Date.now();
-    const remaining = Number(response.headers.get("X-RateLimit-Remaining"));
-    const resetAfter = Number(response.headers.get("X-RateLimit-Reset-After"));
-    const reset = Number(response.headers.get("X-RateLimit-Reset"));
-    if (Number.isFinite(remaining))
-      bucket.remaining = Math.max(0, remaining);
-    if (Number.isFinite(resetAfter))
-      bucket.resetAt = Date.now() + Math.max(0, resetAfter) * 1000;
-    else if (Number.isFinite(reset))
-      bucket.resetAt = reset * 1000;
-    if (windowActive && stored) {
-      bucket.remaining = Math.min(bucket.remaining, stored.remaining);
-      bucket.resetAt = Math.max(bucket.resetAt, stored.resetAt);
-    }
-    if (response.status === 429) {
-      const retryAfter = Number(response.headers.get("Retry-After"));
-      if (Number.isFinite(retryAfter))
-        bucket.resetAt = Math.max(bucket.resetAt, Date.now() + retryAfter * 1000);
-    }
-    await this.#store.updateBucket(currentKey, bucket);
-    if (response.headers.get("X-RateLimit-Global") === "true") {
-      const retryAfter = Number(response.headers.get("Retry-After"));
-      if (Number.isFinite(retryAfter))
-        await this.noteGlobalReset(Date.now() + retryAfter * 1000);
+    if (headers.bucket) {
+      const previous = this.#routes.get(route);
+      this.#cacheRoute(`${route}\x00${major}`, headers.bucket);
+      if (previous !== headers.bucket) {
+        await this.#store.setBucketHash(route, headers.bucket);
+        this.#cacheRoute(route, headers.bucket);
+        emitTelemetry(this.#telemetry, {
+          type: "bucket",
+          change: previous === undefined ? "discovered" : "remapped",
+          route
+        });
+      }
+      const key = scopeBucket(headers.bucket, major);
+      currentKey = options.identity === undefined ? key : `${options.identity}/${key}`;
     }
+    const limited = response.status === 429;
+    const retryAfterMs = limited ? this.#capWait(this.retryAfterMs(response, options.body)) : undefined;
+    const global = limited && (options.body?.global === true || headers.global || headers.scope === "global");
+    const onGlobal = global && options.global !== undefined;
+    let resetAfterMs = headers.resetAfterMs;
+    if (resetAfterMs === undefined && headers.resetAtMs !== undefined)
+      resetAfterMs = Math.max(0, headers.resetAtMs - Date.now());
+    const update = {
+      remaining: headers.remaining,
+      resetAfterMs: resetAfterMs === undefined ? undefined : this.#capWait(resetAfterMs),
+      limit: headers.limit,
+      window: headers.resetAtMs !== undefined && Math.abs(headers.resetAtMs - Date.now()) <= this.#maxBackoff ? headers.resetAtMs : undefined,
+      retryAfterMs: limited && !onGlobal ? retryAfterMs : undefined
+    };
+    if (this.#store.reconcile)
+      await this.#store.reconcile(currentKey, update);
+    else {
+      const next = reconcileState(await this.#store.getBucket(currentKey), update, Date.now());
+      if (next === null)
+        await this.#store.updateBucket(currentKey, {
+          remaining: 0,
+          resetAt: 0
+        });
+      else if (next)
+        await this.#store.updateBucket(currentKey, next);
+    }
+    if (currentKey !== bucketKey && options.grant?.reserved && this.#store.release)
+      await this.#store.release(bucketKey, options.grant, false);
+    if (onGlobal)
+      await this.noteGlobalReset(Date.now() + retryAfterMs, options.global);
     return currentKey;
   }
+  async releaseGrant(bucketKey, grant, notSent) {
+    if (!grant.reserved || !this.#store.release)
+      return;
+    try {
+      await this.#store.release(bucketKey, grant, notSent);
+    } catch {}
+  }
+}
+
+// packages/rest/src/identity.ts
+import { createHash as createHash2 } from "crypto";
+function tokenFingerprint(token) {
+  return createHash2("sha256").update(token).digest("hex").slice(0, 16);
+}
+function requestIdentity(path, fingerprint) {
+  if (/^\/interactions\//i.test(path))
+    return { bucket: "shared" };
+  if (/^\/webhooks\/[^/?]+\/[^/?]+/i.test(path))
+    return { bucket: "shared", global: fingerprint ?? "anon" };
+  if (!fingerprint)
+    return { bucket: "anon", global: "anon" };
+  return { bucket: fingerprint, global: fingerprint };
 }
 
 // packages/rest/src/transport.ts
+var LOOPBACK = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/i;
+function parseBaseURL(raw, allowInsecure = false) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new TypeError("baseURL must be an absolute http(s) URL.");
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:")
+    throw new TypeError("baseURL must use https.");
+  if (url.username || url.password)
+    throw new TypeError("baseURL must not contain credentials.");
+  if (url.search || url.hash || /[?#]/.test(raw))
+    throw new TypeError("baseURL must not contain a query or fragment.");
+  if (url.protocol === "http:" && !allowInsecure && !LOOPBACK.test(url.hostname))
+    throw new TypeError("baseURL must use https: the bot token would travel in cleartext (allowInsecureBaseURL: true overrides this for a trusted network).");
+  return url.href.replace(/\/$/, "");
+}
+
 class TransportError extends Error {
   timedOut;
   constructor(message, timedOut, cause) {
@@ -326,7 +974,7 @@ class HttpTransport {
   #timeout;
   #fetch;
   constructor(options = {}) {
-    this.#baseURL = (options.baseURL ?? "https://discord.com/api/v10").replace(/\/$/, "");
+    this.#baseURL = parseBaseURL(options.baseURL ?? "https://discord.com/api/v10", options.allowInsecureBaseURL);
     this.#timeout = Math.max(1, options.timeout ?? 15000);
     this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
   }
@@ -348,13 +996,14 @@ class HttpTransport {
         method: request.method,
         headers: request.headers,
         body: request.body,
-        signal: controller.signal
+        signal: controller.signal,
+        redirect: "error"
       });
     } catch (error) {
       if (error instanceof RESTError)
         throw error;
       const timedOut = error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError");
-      throw new TransportError(timedOut ? `Discord REST request timed out after ${this.#timeout}ms` : "Discord REST request failed", timedOut, error);
+      throw new TransportError(timedOut ? `Discord REST request timed out after ${this.#timeout}ms` : "Discord REST request failed", timedOut, sanitizeCause(error));
     } finally {
       clearTimeout(timer);
       request.signal?.removeEventListener("abort", onAbort);
@@ -364,6 +1013,7 @@ class HttpTransport {
 
 // packages/rest/src/decoder.ts
 class ResponseDecoder {
+  constructor() {}
   async read(response) {
     if (response.status === 204)
       return;
@@ -532,36 +1182,185 @@ var RESTErrorCode = {
   CannotReplyWithoutReadHistory: 160002
 };
 // packages/rest/src/redis.ts
-var RESERVE_SCRIPT = `
-local raw = redis.call('GET', KEYS[1])
-if not raw then return {1, 0} end
-local ok, state = pcall(cjson.decode, raw)
-if not ok or type(state) ~= 'table' or type(state.resetAt) ~= 'number' then
-  return {1, 0}
+var LUA_PRELUDE = `
+local function now_ms()
+  local t = redis.call('TIME')
+  return tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+end
+local function load(key)
+  local raw = redis.call('GET', key)
+  if not raw then return nil end
+  local ok, s = pcall(cjson.decode, raw)
+  if ok and type(s) == 'table' and type(s.resetAt) == 'number'
+    and type(s.remaining) == 'number' then return s end
+  return nil
+end
+local function save(key, s, now, linger)
+  local ttl = math.max(1, math.ceil(s.resetAt - now)) + linger
+  redis.call('SET', key, cjson.encode(s), 'PX', ttl)
+end
+`;
+var RESERVE_SCRIPT = `${LUA_PRELUDE}
+local now = now_ms()
+local glimit, gwindow = tonumber(ARGV[4]) or 0, tonumber(ARGV[5]) or 1000
+if #KEYS > 1 then
+  local g = tonumber(redis.call('GET', KEYS[2]) or '0') or 0
+  if g > now then return {0, math.ceil(g - now), 'global'} end
+end
+if #KEYS < 3 then glimit = 0 end
+-- A sliding log of send times: at most glimit in any gwindow span.
+if glimit > 0 then
+  redis.call('ZREMRANGEBYSCORE', KEYS[3], '-inf', now - gwindow)
+  if redis.call('ZCARD', KEYS[3]) >= glimit then
+    local oldest = redis.call('ZRANGE', KEYS[3], 0, 0, 'WITHSCORES')
+    return {0, math.max(1, tonumber(oldest[2]) + gwindow - now + 1), 'global'}
+  end
+end
+local function count()
+  if glimit > 0 then
+    local seq = redis.call('ZCARD', KEYS[3])
+    redis.call('ZADD', KEYS[3], now, now .. ':' .. seq)
+    redis.call('PEXPIRE', KEYS[3], gwindow + 1000)
+  end
 end
-local now = tonumber(ARGV[1])
-local wait = state.resetAt - now
-if wait <= 0 then return {1, 0} end
-if type(state.remaining) == 'number' and state.remaining > 0 then
-  state.remaining = state.remaining - 1
-  redis.call('SET', KEYS[1], cjson.encode(state), 'PX', math.ceil(wait))
-  return {1, 0}
+local probe, poll, linger = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
+local s = load(KEYS[1])
+if s and s.resetAt > now then
+  if s.remaining > 0 then
+    s.remaining = s.remaining - 1
+    save(KEYS[1], s, now, linger)
+    count()
+    return {1, s.resetAt, 1}
+  end
+  local wait = s.resetAt - now
+  if s.provisional then wait = math.min(wait, poll) end
+  local reason = 'bucket'
+  if s.probe then reason = 'probe' end
+  return {0, math.ceil(wait), reason}
 end
-return {0, math.ceil(wait)}
+local resetAt = now + probe
+if s and type(s.limit) == 'number' and s.limit > 0 then
+  save(KEYS[1], {remaining = s.limit - 1, resetAt = resetAt, limit = s.limit, provisional = true}, now, linger)
+  count()
+  return {1, resetAt, 1}
+end
+save(KEYS[1], {remaining = 0, resetAt = resetAt, provisional = true, probe = true}, now, 0)
+count()
+return {1, resetAt, 0}
+`;
+var RECONCILE_SCRIPT = `${LUA_PRELUDE}
+local now = now_ms()
+local rem, after, limit = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
+local win, retry, linger = tonumber(ARGV[4]), tonumber(ARGV[5]), tonumber(ARGV[6])
+local tol = 50
+local incoming = nil
+if after then incoming = math.ceil(now + after) end
+local s = load(KEYS[1])
+local n
+if s and s.resetAt > now and not s.probe then
+  n = s
+  local stale = win and n.window and win < n.window - tol
+  if not stale then
+    if rem then n.remaining = math.min(n.remaining, rem) end
+    if incoming then
+      local newer = win and n.window and win > n.window + tol
+      if n.provisional or newer then n.resetAt = incoming
+      else n.resetAt = math.max(n.resetAt, incoming) end
+      n.provisional = nil
+    end
+    if win then n.window = math.max(n.window or 0, win) end
+  end
+else
+  if not rem and not retry then
+    if s and s.probe then redis.call('DEL', KEYS[1]) end
+    return 0
+  end
+  n = {remaining = rem or 0, resetAt = incoming or now}
+  if s and type(s.limit) == 'number' then n.limit = s.limit end
+  if win then n.window = win end
+end
+if limit and limit > 0 then n.limit = limit end
+if retry then
+  n.remaining = 0
+  n.resetAt = math.max(n.resetAt, math.ceil(now + retry))
+  n.provisional = nil
+end
+save(KEYS[1], n, now, linger)
+return 1
 `;
+var EXTEND_GLOBAL_SCRIPT = `${LUA_PRELUDE}
+local now = now_ms()
+local target = math.ceil(now + tonumber(ARGV[1]))
+local cur = tonumber(redis.call('GET', KEYS[1]) or '0') or 0
+if target > cur then
+  redis.call('SET', KEYS[1], tostring(target), 'PX', math.max(1, target - now))
+  return target - now
+end
+return math.max(0, cur - now)
+`;
+var RELEASE_SCRIPT = `${LUA_PRELUDE}
+local s = load(KEYS[1])
+if not s or s.resetAt ~= tonumber(ARGV[1]) then return 0 end
+if s.probe then
+  redis.call('DEL', KEYS[1])
+  return 1
+end
+if ARGV[2] == '1' then
+  local cap = s.remaining + 1
+  if type(s.limit) == 'number' then cap = math.min(cap, s.limit) end
+  s.remaining = cap
+  redis.call('SET', KEYS[1], cjson.encode(s), 'KEEPTTL')
+  return 1
+end
+return 0
+`;
+var VERIFY_SCRIPT = "return redis.call('TIME')[1]";
+function fromBunRedis(client) {
+  return {
+    get: (key) => client.send("GET", [key]),
+    mget: (keys) => client.send("MGET", keys),
+    set: (key, value, mode, duration) => client.send("SET", mode === undefined ? [key, String(value)] : [key, String(value), mode, String(duration)]),
+    del: (...keys) => client.send("DEL", keys),
+    eval: (script, numKeys, ...args) => client.send("EVAL", [script, String(numKeys), ...args.map(String)])
+  };
+}
+var SCHEMA = "v1";
 
 class RedisRateLimitStore {
   #client;
   #prefix;
   #onErrorCallback;
+  #policy;
+  #timeout;
+  #telemetry;
+  #atomic;
   #local = new MemoryRateLimitStore;
   #lastError;
+  #lastFailureAt;
+  #failures = 0;
+  #mode;
   constructor(options) {
     this.#client = options.client;
-    this.#prefix = options.prefix ?? "lunibee:rest:";
+    this.#prefix = `${options.prefix ?? "lunibee:rest:"}${SCHEMA}:`;
     this.#onErrorCallback = options.onError;
-    if (typeof options.client.eval === "function")
-      this.reserve = (key) => this.#reserve(key);
+    this.#policy = options.failurePolicy ?? "degraded-local";
+    if (this.#policy !== "degraded-local" && this.#policy !== "fail-closed")
+      throw new TypeError('failurePolicy must be "degraded-local" or "fail-closed".');
+    this.#timeout = options.commandTimeout ?? 2000;
+    if (!(this.#timeout > 0))
+      throw new RangeError("commandTimeout must be a positive number.");
+    this.#telemetry = options.telemetry;
+    this.#atomic = typeof options.client.eval === "function";
+    if (options.requireAtomic && !this.#atomic)
+      throw new TypeError("requireAtomic: the Redis client has no eval method, so reservations cannot be atomic.");
+    this.#mode = this.#atomic ? "distributed" : "observational";
+    if (this.#atomic) {
+      this.reserve = (key, opts) => this.#reserve(key, opts);
+      this.reconcile = (key, update) => this.#reconcile(key, update);
+      this.extendGlobalReset = (scope, waitMs) => this.#extendGlobal(scope, waitMs);
+      this.release = (key, grant, refund) => this.#release(key, grant, refund);
+      this.reservesGlobal = true;
+    }
   }
   get lastError() {
     return this.#lastError;
@@ -569,107 +1368,204 @@ class RedisRateLimitStore {
   isHealthy() {
     return this.#lastError === undefined;
   }
-  #onError(operation, error) {
-    this.#lastError = error;
-    console.warn(`[lunibee/rest] Redis rate-limit store ${operation} failed; ` + `falling back to local limiting for this call.`, error);
-    try {
-      this.#onErrorCallback?.(operation, error);
-    } catch {}
+  get mode() {
+    return this.#mode;
   }
-  #markHealthy() {
-    this.#lastError = undefined;
+  get supportsReservation() {
+    return this.#atomic;
   }
-  async getBucketHash(route) {
+  diagnostics() {
+    const error = this.#lastError;
+    return {
+      mode: this.#mode,
+      failurePolicy: this.#policy,
+      atomic: this.#atomic,
+      failures: this.#failures,
+      lastFailureAt: this.#lastFailureAt,
+      lastError: error === undefined ? undefined : String(sanitizeCause(error)?.message ?? error)
+    };
+  }
+  async verify() {
+    if (!this.#atomic)
+      throw new TypeError("The Redis client has no eval method: reservations cannot be atomic.");
     try {
-      const hash = await this.#client.get(`${this.#prefix}route:${route}`);
-      this.#markHealthy();
-      return hash ?? undefined;
+      await this.#withTimeout(this.#client.eval(VERIFY_SCRIPT, 0));
     } catch (error) {
-      this.#onError("getBucketHash", error);
-      return this.#local.getBucketHash(route);
+      throw new RESTError("The Redis rate-limit store cannot run its scripts.", 0, undefined, undefined, { kind: "coordination", cause: sanitizeCause(error) });
     }
   }
-  async setBucketHash(route, hash) {
-    this.#local.setBucketHash(route, hash);
+  #setMode(mode) {
+    if (mode === this.#mode)
+      return;
+    const previous = this.#mode;
+    this.#mode = mode;
+    emitTelemetry(this.#telemetry, { type: "mode", mode, previous });
+    console.warn(mode === "degraded-local" ? "[lunibee/rest] Redis rate-limit store unreachable: limiting locally in this process until it answers." : mode === "unavailable" ? "[lunibee/rest] Redis rate-limit store unreachable: requests fail until it answers (fail-closed)." : "[lunibee/rest] Redis rate-limit store reachable again: limits are shared.");
+  }
+  #withTimeout(promise) {
+    let timer;
+    return Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`Redis command timed out after ${this.#timeout}ms`)), this.#timeout);
+      })
+    ]).finally(() => clearTimeout(timer));
+  }
+  async#run(operation, command, fallback, enforcing) {
+    const started = performance.now();
     try {
-      await this.#client.set(`${this.#prefix}route:${route}`, hash, "EX", 604800);
-      this.#markHealthy();
+      const value = await this.#withTimeout(command());
+      emitTelemetry(this.#telemetry, {
+        type: "store",
+        operation,
+        latencyMs: performance.now() - started,
+        ok: true
+      });
+      this.#lastError = undefined;
+      this.#setMode(this.#atomic ? "distributed" : "observational");
+      return value;
     } catch (error) {
-      this.#onError("setBucketHash", error);
+      emitTelemetry(this.#telemetry, {
+        type: "store",
+        operation,
+        latencyMs: performance.now() - started,
+        ok: false
+      });
+      this.#lastError = error;
+      this.#lastFailureAt = Date.now();
+      this.#failures++;
+      try {
+        this.#onErrorCallback?.(operation, error);
+      } catch {}
+      if (this.#policy === "fail-closed") {
+        this.#setMode("unavailable");
+        if (enforcing)
+          throw new RESTError(`The Redis rate-limit store is unavailable (${operation}); request not sent (failurePolicy: "fail-closed").`, 0, undefined, undefined, { kind: "coordination", cause: sanitizeCause(error) });
+      } else
+        this.#setMode("degraded-local");
+      return fallback();
     }
   }
+  #bucketKey(key) {
+    return `${this.#prefix}bucket:${key}`;
+  }
+  #globalKey(scope) {
+    return `${this.#prefix}global:${scope}`;
+  }
+  async getBucketHash(route) {
+    return this.#run("getBucketHash", async () => await this.#client.get(`${this.#prefix}route:${route}`) ?? undefined, () => this.#local.getBucketHash(route), false);
+  }
+  async setBucketHash(route, hash) {
+    this.#local.setBucketHash(route, hash);
+    await this.#run("setBucketHash", async () => {
+      await this.#client.set(`${this.#prefix}route:${route}`, hash, "EX", 604800);
+    }, () => {
+      return;
+    }, false);
+  }
   async getBucket(key) {
-    try {
-      const data = await this.#client.get(`${this.#prefix}bucket:${key}`);
-      this.#markHealthy();
+    return this.#run("getBucket", async () => {
+      const data = await this.#client.get(this.#bucketKey(key));
       if (!data)
         return;
-      return JSON.parse(data);
-    } catch (error) {
-      this.#onError("getBucket", error);
-      return this.#local.getBucket(key);
-    }
-  }
-  async updateBucket(key, state) {
-    this.#local.updateBucket(key, state);
-    const bucketKey = `${this.#prefix}bucket:${key}`;
-    const ttl = Math.ceil((state.resetAt - Date.now()) / 1000);
-    try {
-      if (ttl <= 0) {
-        await this.#client.del(bucketKey);
-        this.#markHealthy();
+      try {
+        return JSON.parse(data);
+      } catch {
         return;
       }
-      await this.#client.set(bucketKey, JSON.stringify(state), "EX", ttl);
-      this.#markHealthy();
-    } catch (error) {
-      this.#onError("updateBucket", error);
-    }
+    }, () => this.#local.getBucket(key), true);
   }
-  get supportsReservation() {
-    return typeof this.#client.eval === "function";
+  async updateBucket(key, state) {
+    this.#local.updateBucket(key, state);
+    const ttl = Math.ceil(state.resetAt - Date.now());
+    await this.#run("updateBucket", async () => {
+      if (ttl <= 0)
+        await this.#client.del(this.#bucketKey(key));
+      else
+        await this.#client.set(this.#bucketKey(key), JSON.stringify(state), "PX", ttl);
+    }, () => {
+      return;
+    }, false);
   }
   reserve;
-  async#reserve(key) {
-    try {
-      const result = await this.#client.eval(RESERVE_SCRIPT, 1, `${this.#prefix}bucket:${key}`, Date.now());
-      this.#markHealthy();
-      if (!Array.isArray(result))
-        return { granted: true };
-      const [granted, retryAfterMs] = result;
-      return Number(granted) === 1 ? { granted: true } : { granted: false, retryAfterMs: Number(retryAfterMs) || 0 };
-    } catch (error) {
-      this.#onError("reserve", error);
-      return this.#local.reserve(key);
+  reconcile;
+  extendGlobalReset;
+  release;
+  reservesGlobal;
+  async#reserve(key, options = {}) {
+    const keys = [this.#bucketKey(key)];
+    if (options.global !== undefined) {
+      keys.push(this.#globalKey(options.global));
+      if (options.globalLimit)
+        keys.push(`${this.#prefix}global-log:${options.global}`);
     }
+    return this.#run("reserve", async () => {
+      const result = await this.#client.eval(RESERVE_SCRIPT, keys.length, ...keys, options.probeMs ?? DEFAULT_PROBE_MS, PROBE_POLL_MS, BUCKET_LINGER_MS, options.globalLimit ?? 0, GLOBAL_WINDOW_MS);
+      return parseReservation(result);
+    }, () => this.#local.reserve(key, options), true);
+  }
+  async#reconcile(key, update) {
+    this.#local.reconcile(key, update);
+    const arg = (value) => value === undefined ? "" : String(value);
+    await this.#run("reconcile", async () => {
+      await this.#client.eval(RECONCILE_SCRIPT, 1, this.#bucketKey(key), arg(update.remaining), arg(update.resetAfterMs), arg(update.limit), arg(update.window), arg(update.retryAfterMs), BUCKET_LINGER_MS);
+    }, () => {
+      return;
+    }, false);
   }
-  async getGlobalReset() {
-    try {
-      const resetAt = await this.#client.get(`${this.#prefix}global`);
-      this.#markHealthy();
-      return resetAt ? Number(resetAt) : 0;
-    } catch (error) {
-      this.#onError("getGlobalReset", error);
-      return this.#local.getGlobalReset();
-    }
+  async#extendGlobal(scope, waitMs) {
+    this.#local.extendGlobalReset(scope, waitMs);
+    await this.#run("extendGlobalReset", async () => {
+      await this.#client.eval(EXTEND_GLOBAL_SCRIPT, 1, this.#globalKey(scope), Math.max(0, Math.ceil(waitMs)));
+    }, () => {
+      return;
+    }, false);
   }
-  async setGlobalReset(resetAt) {
-    this.#local.setGlobalReset(resetAt);
-    const globalKey = `${this.#prefix}global`;
-    const ttl = Math.ceil((resetAt - Date.now()) / 1000);
-    try {
-      if (ttl <= 0) {
-        await this.#client.del(globalKey);
-        this.#markHealthy();
-        return;
-      }
-      await this.#client.set(globalKey, String(resetAt), "EX", ttl);
-      this.#markHealthy();
-    } catch (error) {
-      this.#onError("setGlobalReset", error);
-    }
+  async#release(key, grant, refund) {
+    this.#local.release(key, grant, refund);
+    if (grant.resetAt === undefined)
+      return;
+    await this.#run("release", async () => {
+      await this.#client.eval(RELEASE_SCRIPT, 1, this.#bucketKey(key), grant.resetAt, refund ? "1" : "0");
+    }, () => {
+      return;
+    }, false);
+  }
+  async getGlobalReset(scope = "") {
+    return this.#run("getGlobalReset", async () => {
+      const resetAt = await this.#client.get(this.#globalKey(scope));
+      return resetAt ? Number(resetAt) || 0 : 0;
+    }, () => this.#local.getGlobalReset(scope), true);
+  }
+  async setGlobalReset(resetAt, scope = "") {
+    this.#local.setGlobalReset(resetAt, scope);
+    const ttl = Math.ceil(resetAt - Date.now());
+    await this.#run("setGlobalReset", async () => {
+      if (ttl <= 0)
+        await this.#client.del(this.#globalKey(scope));
+      else
+        await this.#client.set(this.#globalKey(scope), String(resetAt), "PX", ttl);
+    }, () => {
+      return;
+    }, false);
   }
 }
+function parseReservation(result) {
+  if (!Array.isArray(result) || result.length < 3)
+    throw new Error("Unexpected reply from the reservation script.");
+  const [granted, value, flag] = result;
+  const n = Number(value);
+  if (!Number.isFinite(n))
+    throw new Error("Unexpected reply from the reservation script.");
+  if (Number(granted) === 1)
+    return { granted: true, known: Number(flag) === 1, resetAt: n };
+  const reason = String(flag);
+  return {
+    granted: false,
+    retryAfterMs: Math.max(0, n),
+    reason: reason === "global" || reason === "probe" ? reason : "bucket"
+  };
+}
 // packages/rest/src/webhook.ts
 class WebhookClient {
   id;
@@ -690,29 +1586,49 @@ class WebhookClient {
     }
     this.#rest = new REST(restOptions);
   }
-  async send(options) {
+  #prepare(options, base = {}) {
     const payload = typeof options === "string" ? { content: options } : options;
-    const { thread_id, files, ...body } = payload;
-    const params = new URLSearchParams({ wait: "true" });
+    const {
+      thread_id: threadWire,
+      threadId,
+      avatarURL,
+      allowedMentions,
+      files,
+      ...body
+    } = payload;
+    const thread_id = threadWire ?? threadId;
+    if (avatarURL !== undefined && body.avatar_url === undefined)
+      body.avatar_url = avatarURL;
+    if (allowedMentions !== undefined && body.allowed_mentions === undefined)
+      body.allowed_mentions = allowedMentions;
+    const params = new URLSearchParams(base);
     if (thread_id)
       params.set("thread_id", String(thread_id));
-    const query = `?${params}`;
-    const formattedEmbeds = body.embeds?.map((e) => ("toJSON" in e) ? e.toJSON() : e);
-    const formattedComponents = body.components?.map((c) => ("toJSON" in c) ? c.toJSON() : c);
+    const json = { ...body };
+    if (body.embeds)
+      json.embeds = body.embeds.map((e) => ("toJSON" in e) ? e.toJSON() : e);
+    if (body.components)
+      json.components = body.components.map((c) => ("toJSON" in c) ? c.toJSON() : c);
+    const text = params.toString();
+    return { query: text ? `?${text}` : "", json, files };
+  }
+  async send(options) {
+    const { query, json, files } = this.#prepare(options, { wait: "true" });
     const path = `${Routes.webhook(this.id, this.token)}${query}`;
-    const json = {
-      ...body,
-      embeds: formattedEmbeds,
-      components: formattedComponents
-    };
     return files?.length ? this.#rest.postWithFiles(path, json, files) : this.#rest.post(path, json);
   }
+  async fetchMessage(messageId, options = {}) {
+    const query = options.threadId ? `?${new URLSearchParams({ thread_id: options.threadId })}` : "";
+    return this.#rest.get(`${Routes.webhookMessage(this.id, this.token, messageId)}${query}`);
+  }
   async editMessage(messageId, options) {
-    const payload = typeof options === "string" ? { content: options } : options;
-    return this.#rest.patch(Routes.webhookMessage(this.id, this.token, messageId), payload);
+    const { query, json, files } = this.#prepare(options);
+    const path = `${Routes.webhookMessage(this.id, this.token, messageId)}${query}`;
+    return files?.length ? this.#rest.patchWithFiles(path, json, files) : this.#rest.patch(path, json);
   }
-  async deleteMessage(messageId) {
-    await this.#rest.delete(Routes.webhookMessage(this.id, this.token, messageId));
+  async deleteMessage(messageId, options = {}) {
+    const query = options.threadId ? `?${new URLSearchParams({ thread_id: options.threadId })}` : "";
+    await this.#rest.delete(`${Routes.webhookMessage(this.id, this.token, messageId)}${query}`);
   }
 }
 
@@ -721,7 +1637,9 @@ var LIBRARY_VERSION = package_default.version;
 var LIBRARY_URL = "https://github.com/Ekretos/lunibee";
 var USER_AGENT = `DiscordBot (${LIBRARY_URL}, ${LIBRARY_VERSION})`;
 function assertSafePath(path) {
-  const end = path.search(/[?#]/);
+  if (/[\u0000-\u0020\u007f#]/.test(path))
+    throw new TypeError("REST paths must not contain control characters, spaces or '#'.");
+  const end = path.indexOf("?");
   const pathname = end === -1 ? path : path.slice(0, end);
   if (pathname.includes("\\"))
     throw new TypeError("REST paths must not contain backslashes.");
@@ -732,7 +1650,11 @@ function assertSafePath(path) {
     } catch {
       throw new TypeError("REST path has malformed percent-encoding.");
     }
-    if (decoded === "." || decoded === "..")
+    const bare = decoded.replace(/[\u0000-\u0020\u007f]/g, "");
+    if (bare === "." || bare === ".." || /[\\/]/.test(decoded) && decoded.split(/[\\/]/).some((s) => {
+      const part = s.replace(/[\u0000-\u0020\u007f]/g, "");
+      return part === "." || part === "..";
+    }))
       throw new TypeError("REST paths must not contain '.' or '..' segments.");
   }
 }
@@ -743,7 +1665,8 @@ var REQUEST_DATA_KEYS = new Set([
   "headers",
   "reason",
   "auth",
-  "signal"
+  "signal",
+  "maxQueueWait"
 ]);
 function isRequestData(value) {
   if (value === null || typeof value !== "object")
@@ -779,27 +1702,66 @@ function createRetryPolicy(maxRetries = 2) {
   };
 }
 
+class QueueWaitExceeded extends Error {
+  ms;
+  constructor(ms) {
+    super("maxQueueWait exceeded");
+    this.ms = ms;
+  }
+}
+function checkWait(ms) {
+  if (ms === undefined)
+    return;
+  if (!(ms >= 0) || !Number.isFinite(ms))
+    throw new RangeError("maxQueueWait must be a non-negative number.");
+  return ms;
+}
+
 class REST {
   #retryPolicy;
   #token;
+  #fingerprint;
+  #telemetry;
+  #closing = new AbortController;
+  #inFlight = 0;
+  #idle;
+  #rejected;
+  #stopOnInvalidToken;
+  #maxQueueWait;
+  #invalid = new Array(10).fill(0);
+  #invalidMinute = 0;
+  #drained;
   #limiter;
-  #scheduler = new RequestScheduler;
+  #scheduler;
   #transport;
   #decoder = new ResponseDecoder;
   #hooks = {};
   #concurrentBuckets;
   constructor(options = {}) {
     this.#token = options.token;
+    this.#fingerprint = options.token ? tokenFingerprint(options.token) : undefined;
+    this.#telemetry = options.telemetry;
+    this.#scheduler = new RequestScheduler({
+      maxQueued: options.maxQueued,
+      maxQueuedPerBucket: options.maxQueuedPerBucket
+    });
     this.#retryPolicy = options.retryPolicy ?? createRetryPolicy(options.retries ?? 2);
     this.#transport = options.transport ?? new HttpTransport({
       baseURL: options.baseURL,
+      allowInsecureBaseURL: options.allowInsecureBaseURL,
       timeout: options.timeout
     });
     const store = options.store ?? new MemoryRateLimitStore;
     this.#concurrentBuckets = (options.concurrentBuckets ?? true) && typeof store.reserve === "function";
     this.#limiter = new RateLimiter(store, {
-      concurrent: this.#concurrentBuckets
+      concurrent: this.#concurrentBuckets,
+      maxBackoff: options.maxBackoff,
+      probeMs: this.#transport.timeout > 0 ? this.#transport.timeout + 1000 : undefined,
+      telemetry: options.telemetry,
+      globalLimit: options.globalLimit === false ? undefined : options.globalLimit ?? 50
     });
+    this.#stopOnInvalidToken = options.stopOnInvalidToken ?? true;
+    this.#maxQueueWait = checkWait(options.maxQueueWait);
     if (options.hooks)
       this.#hooks = options.hooks;
   }
@@ -814,9 +1776,64 @@ class REST {
     if (!token.trim())
       throw new TypeError("A Discord bot token is required.");
     this.#token = token;
+    this.#fingerprint = tokenFingerprint(token);
+    this.#rejected = undefined;
   }
-  async request(method, path, body, options = {}) {
-    if (!method.toUpperCase())
+  diagnostics() {
+    const store = this.#limiter.store;
+    return {
+      mode: store.mode ?? (store instanceof MemoryRateLimitStore ? "local" : "distributed"),
+      queued: this.#scheduler.queued,
+      inFlight: this.#inFlight,
+      buckets: this.#scheduler.size,
+      closed: this.#closing.signal.aborted,
+      invalidRequests: this.#invalidCount(0),
+      tokenRejected: this.#rejected !== undefined && this.#rejected === this.#fingerprint
+    };
+  }
+  async close() {
+    if (!this.#closing.signal.aborted)
+      this.#closing.abort(new Error("The REST client was closed."));
+    if (this.#inFlight === 0)
+      return;
+    this.#drained ??= new Promise((resolve) => {
+      this.#idle = resolve;
+    });
+    await this.#drained;
+  }
+  #invalidCount(add) {
+    const minute = Math.floor(Date.now() / 60000);
+    const elapsed = Math.min(10, minute - this.#invalidMinute);
+    for (let i = 1;i <= elapsed; i++)
+      this.#invalid[(this.#invalidMinute + i) % 10] = 0;
+    if (elapsed > 0)
+      this.#invalidMinute = minute;
+    this.#invalid[minute % 10] += add;
+    return this.#invalid.reduce((a, b) => a + b, 0);
+  }
+  #queueChanged() {
+    emitTelemetry(this.#telemetry, {
+      type: "queue",
+      queued: this.#scheduler.queued,
+      inFlight: this.#inFlight
+    });
+  }
+  async request(methodOrOptions, pathArg, bodyArg, optionsArg = {}) {
+    let method;
+    let path;
+    let body = bodyArg;
+    let options = optionsArg;
+    if (typeof methodOrOptions === "object" && methodOrOptions !== null) {
+      const { method: m, path: p, fullRoute, ...rest } = methodOrOptions;
+      method = m;
+      path = p ?? fullRoute ?? "";
+      body = rest.body;
+      options = rest;
+    } else {
+      method = methodOrOptions;
+      path = pathArg;
+    }
+    if (typeof method !== "string" || !method.toUpperCase())
       throw new TypeError("REST method is required.");
     if (!path.startsWith("/"))
       throw new TypeError("REST paths must start with '/'.");
@@ -824,22 +1841,101 @@ class REST {
     const route = createRouteKey(method, path);
     const files = options.files;
     if (files && files.length > 0 && !(body instanceof FormData))
-      body = this.#fileForm(body, files);
+      body = this.#fileForm(body, await Promise.all(files.map(async (file) => ({
+        ...file,
+        data: await file.data
+      }))));
     const query = serializeQuery(options.query);
     const requestPath = query ? `${path}${query}` : path;
-    return this.#scheduler.runResolved(() => this.#limiter.resolveBucketKey(route.route, route.major), options.signal, path, (bucketKey, release) => this.#attempts(route, requestPath, body, options, bucketKey, release));
+    if (this.#closing.signal.aborted)
+      throw abortError(path, this.#closing.signal.reason);
+    const identity = requestIdentity(path, options.auth !== false && this.#token ? this.#fingerprint : undefined);
+    if (identity.bucket === this.#fingerprint && this.#rejected === this.#fingerprint)
+      throw new RESTError("Discord rejected this bot token (401); request not sent. Call setToken() with a valid token.", 401, undefined, undefined, { method: route.method, path, kind: "authentication" });
+    const queueWait = checkWait(options.maxQueueWait) ?? this.#maxQueueWait;
+    let deadline;
+    const sources = [this.#closing.signal];
+    if (options.signal)
+      sources.push(options.signal);
+    if (queueWait !== undefined) {
+      const expired = new AbortController;
+      deadline = setTimeout(() => expired.abort(new QueueWaitExceeded(queueWait)), queueWait);
+      sources.push(expired.signal);
+    }
+    const waitSignal = sources.length === 1 ? sources[0] : AbortSignal.any(sources);
+    const state = { attempts: 0, status: 0 };
+    const started = performance.now();
+    this.#inFlight++;
+    this.#queueChanged();
+    try {
+      return await this.#scheduler.runResolved(() => this.#limiter.resolveBucketKey(route.route, route.major, identity.bucket), waitSignal, path, (bucketKey, release) => {
+        this.#queueChanged();
+        return this.#attempts(route, requestPath, body, options, { identity, waitSignal, state }, bucketKey, release);
+      });
+    } catch (caught) {
+      let error = caught;
+      if (error instanceof RESTError && error.kind === "aborted" && error.cause instanceof QueueWaitExceeded)
+        error = new RESTError(`The request waited longer than maxQueueWait (${error.cause.ms}ms) before it could be sent.`, 0, undefined, undefined, { method: route.method, path, kind: "overloaded" });
+      if (error instanceof RESTError) {
+        if (error.kind === "aborted" && state.attempts === 0)
+          emitTelemetry(this.#telemetry, {
+            type: "cancelled",
+            stage: "queued"
+          });
+        else if (error.kind === "overloaded")
+          emitTelemetry(this.#telemetry, { type: "overloaded" });
+        if (state.status === 0)
+          state.status = error.status;
+      }
+      throw error;
+    } finally {
+      clearTimeout(deadline);
+      emitTelemetry(this.#telemetry, {
+        type: "request",
+        method: route.method,
+        route: route.route,
+        status: state.status,
+        attempts: state.attempts,
+        durationMs: performance.now() - started,
+        ok: state.status >= 200 && state.status < 300
+      });
+      if (--this.#inFlight === 0 && this.#idle) {
+        this.#idle();
+        this.#idle = undefined;
+        this.#drained = undefined;
+      }
+      this.#queueChanged();
+    }
   }
-  async#attempts(route, requestPath, body, options, initialBucketKey, release) {
+  async#attempts(route, requestPath, body, options, context, initialBucketKey, release) {
     const { method, path } = route;
+    const { identity, waitSignal, state } = context;
+    const label = route.route;
     let bucketKey = initialBucketKey;
     for (let attempt = 0;attempt <= this.#retryPolicy.maxRetries; attempt++) {
-      await this.#limiter.acquire(bucketKey, options.signal, path);
-      if (this.#concurrentBuckets) {
-        const bucket = await this.#limiter.store.getBucket(bucketKey);
-        if (bucket && bucket.resetAt > Date.now())
-          release();
+      let grant;
+      try {
+        grant = await this.#limiter.acquire(bucketKey, waitSignal, path, { global: identity.global });
+      } catch (error) {
+        if (error instanceof RESTError && error.kind === "aborted")
+          emitTelemetry(this.#telemetry, {
+            type: "cancelled",
+            stage: "waiting"
+          });
+        throw error;
+      }
+      if (this.#concurrentBuckets && grant.known)
+        release();
+      if (waitSignal.aborted) {
+        await this.#limiter.releaseGrant(bucketKey, grant, true);
+        emitTelemetry(this.#telemetry, {
+          type: "cancelled",
+          stage: "waiting"
+        });
+        throw abortError(path, waitSignal.reason);
       }
       this.#emit(this.#hooks.onRequest, { method, path, attempt });
+      state.attempts = attempt + 1;
       const requestStart = Date.now();
       let response;
       try {
@@ -851,13 +1947,44 @@ class REST {
           signal: options.signal
         });
       } catch (error) {
-        if (error instanceof RESTError)
+        const notSent = error instanceof RESTError && error.kind === "aborted";
+        await this.#limiter.releaseGrant(bucketKey, grant, notSent);
+        if (error instanceof RESTError) {
+          if (error.kind === "aborted")
+            emitTelemetry(this.#telemetry, {
+              type: "cancelled",
+              stage: "transport"
+            });
           throw error;
-        if (options.signal?.aborted)
+        }
+        if (options.signal?.aborted) {
+          emitTelemetry(this.#telemetry, {
+            type: "cancelled",
+            stage: "transport"
+          });
           throw abortError(path, options.signal.reason);
-        const failure = error instanceof TransportError ? error : new TransportError("Discord REST request failed", false, error);
+        }
+        const failure = error instanceof TransportError ? error : new TransportError("Discord REST request failed", false, sanitizeCause(error));
+        emitTelemetry(this.#telemetry, {
+          type: "networkError",
+          timedOut: failure.timedOut
+        });
         if (!failure.timedOut && attempt < this.#retryPolicy.maxRetries && this.#retryPolicy.shouldRetry(method, 0)) {
-          await sleep(this.#retryPolicy.getDelay(attempt), options.signal, path);
+          const delay = this.#retryPolicy.getDelay(attempt);
+          this.#emit(this.#hooks.onRetry, {
+            method,
+            path,
+            attempt,
+            status: 0,
+            delayMs: delay
+          });
+          emitTelemetry(this.#telemetry, {
+            type: "retry",
+            route: label,
+            reason: "network",
+            attempt
+          });
+          await this.#retrySleep(delay, waitSignal, path);
           continue;
         }
         throw new RESTError(failure.message, 0, undefined, undefined, {
@@ -867,30 +1994,60 @@ class REST {
           kind: failure.timedOut ? "timeout" : "network"
         });
       }
+      state.status = response.status;
+      if (response.status === 401 || response.status === 403 || response.status === 429 && response.headers.get("X-RateLimit-Scope") !== "shared")
+        this.#invalidCount(1);
+      if (response.status === 401 && this.#stopOnInvalidToken && identity.bucket === this.#fingerprint) {
+        this.#rejected = this.#fingerprint;
+        emitTelemetry(this.#telemetry, { type: "tokenRejected" });
+      }
+      const durationMs = Date.now() - requestStart;
       this.#emit(this.#hooks.onResponse, {
         method,
         path,
         status: response.status,
-        durationMs: Date.now() - requestStart
+        durationMs
+      });
+      emitTelemetry(this.#telemetry, {
+        type: "response",
+        method,
+        route: label,
+        status: response.status,
+        durationMs
       });
-      bucketKey = await this.#limiter.applyResponse(response, bucketKey, route.route, route.major);
       const payload = await this.#decoder.read(response);
+      const data = response.ok ? {} : this.#decoder.errorData(payload);
+      bucketKey = await this.#limiter.applyResponse(response, bucketKey, route.route, route.major, {
+        identity: identity.bucket,
+        global: identity.global,
+        body: data,
+        grant
+      });
       if (response.ok)
         return response.status === 204 ? undefined : payload;
-      const data = this.#decoder.errorData(payload);
-      const retryAfter = response.status === 429 ? this.#decoder.retryAfter(response, data) : undefined;
-      if (data.global && retryAfter !== undefined)
-        await this.#limiter.noteGlobalReset(Date.now() + retryAfter * 1000);
-      if (response.status === 429)
+      const limited = response.status === 429;
+      const retryAfterMs = limited ? this.#limiter.retryAfterMs(response, data) : undefined;
+      if (limited) {
+        const global = data.global === true || response.headers.get("X-RateLimit-Global") === "true";
+        const scope = response.headers.get("X-RateLimit-Scope")?.toLowerCase();
+        emitTelemetry(this.#telemetry, {
+          type: "rateLimited",
+          route: label,
+          scope: global ? "global" : scope === "user" || scope === "shared" ? scope : "unknown",
+          retryAfterMs
+        });
         this.#emit(this.#hooks.onRateLimit, {
           method,
           path,
-          retryAfterMs: (retryAfter ?? 1) * 1000,
-          global: data.global ?? false,
-          bucket: await this.#limiter.store.getBucketHash(route.route)
+          retryAfterMs,
+          global,
+          bucket: response.headers.get("X-RateLimit-Bucket") ?? await this.#limiter.store.getBucketHash(route.route)
         });
+      }
       if (attempt < this.#retryPolicy.maxRetries && this.#retryPolicy.shouldRetry(method, response.status)) {
-        const delay = this.#retryPolicy.getDelay(attempt, retryAfter);
+        const delay = this.#retryPolicy.getDelay(attempt, limited ? retryAfterMs / 1000 : undefined);
+        if (delay > this.#limiter.maxBackoff)
+          throw new RESTError(`Discord asked to wait ${Math.ceil(delay / 1000)}s before retrying, longer than maxBackoff (${Math.ceil(this.#limiter.maxBackoff / 1000)}s).`, response.status, data.code, payload, { method, path });
         this.#emit(this.#hooks.onRetry, {
           method,
           path,
@@ -898,13 +2055,30 @@ class REST {
           status: response.status,
           delayMs: delay
         });
-        await sleep(delay, options.signal, path);
+        emitTelemetry(this.#telemetry, {
+          type: "retry",
+          route: label,
+          reason: limited ? "rateLimited" : "server",
+          attempt
+        });
+        await this.#retrySleep(limited ? delay - retryAfterMs : delay, waitSignal, path);
         continue;
       }
       throw new RESTError(data.message ?? response.statusText ?? `Discord REST request failed with status ${response.status}`, response.status, data.code, payload, { method, path });
     }
     throw new RESTError("Discord REST request exhausted its retry attempts", 0, undefined, undefined, { method, path });
   }
+  async#retrySleep(delay, signal, path) {
+    try {
+      await sleep(delay, signal, path);
+    } catch (error) {
+      emitTelemetry(this.#telemetry, {
+        type: "cancelled",
+        stage: "retry"
+      });
+      throw error;
+    }
+  }
   #headers(body, options) {
     const isFormData = typeof FormData !== "undefined" && body instanceof FormData;
     const headers = { ...options.headers };
@@ -956,15 +2130,15 @@ class REST {
       const blob = file.data instanceof Blob ? file.data : new Blob([file.data], {
         type: file.contentType ?? "application/octet-stream"
       });
-      form.append(`files[${i}]`, blob, file.name);
+      form.append(`files[${i}]`, blob, file.name.replace(/[\r\n"\\]/g, "_"));
     }
     return form;
   }
   postWithFiles(path, payload, files, options) {
-    return this.request("POST", path, this.#fileForm(payload, files), options);
+    return this.request("POST", path, payload, { ...options, files });
   }
   patchWithFiles(path, payload, files, options) {
-    return this.request("PATCH", path, this.#fileForm(payload, files), options);
+    return this.request("PATCH", path, payload, { ...options, files });
   }
   #emit(hook, ctx) {
     if (!hook)
@@ -976,12 +2150,14 @@ class REST {
   }
 }
 export {
+  DEFAULT_MAX_BACKOFF_MS,
   RESTError as DiscordAPIError,
   HttpTransport,
   MemoryRateLimitStore,
   REST,
   RESTError,
   RESTErrorCode,
+  RESTMetrics,
   RateLimiter,
   RedisRateLimitStore,
   RequestScheduler,
@@ -992,11 +2168,16 @@ export {
   abortError,
   createRetryPolicy,
   createRouteKey,
+  fromBunRedis,
+  headerNumber,
   majorParameter,
   normalizeRoutePath,
+  parseRateLimitHeaders,
   redactPath,
+  requestIdentity,
   scopeBucket,
-  serializeQuery
+  serializeQuery,
+  tokenFingerprint
 };
 
-//# debugId=76878940534439C564756E2164756E21
+//# debugId=8464D7D05D07B1F864756E2164756E21