lunibee 0.3.1 → 0.3.3

package/dist/rest/limiter.d.ts

@@ -1,4 +1,30 @@
-import type { RateLimitStore } from "./store.js";
+import { type RateLimitStore } from "./store.js";
+import { type RESTTelemetry } from "./telemetry.js";
+/** Default for `maxBackoff`: ten minutes. */
+export declare const DEFAULT_MAX_BACKOFF_MS = 600000;
+/** What {@link RateLimiter.acquire} obtained. */
+export interface Grant {
+    /** A unit was reserved atomically (false for a store without `reserve`). */
+    reserved: boolean;
+    /** The bucket's limit is known, so further requests need not wait for this one's response. */
+    known: boolean;
+    /** The window the unit came from (store clock), when the store reports it. */
+    resetAt?: number;
+}
+/** Context for {@link RateLimiter.applyResponse} beyond the response itself. */
+export interface ApplyResponseOptions {
+    /** Bucket-key prefix of the request's identity (see `requestIdentity`). */
+    identity?: string;
+    /** Global-limit scope the request counts against, if any. */
+    global?: string;
+    /** The decoded error body, for `retry_after` and `global` on a 429. */
+    body?: {
+        retry_after?: number;
+        global?: boolean;
+    };
+    /** The grant the request was sent under. */
+    grant?: Grant;
+}
 /**
  * Owns Discord's rate-limit state: when a request may go out, and what a
  * response says about the bucket it landed in.
@@ -10,33 +36,72 @@ export declare class RateLimiter {
     #private;
     /**
      * @param store Rate-limit state store.
-     * @param options `concurrent`: set when several requests per bucket can be
-     *   in flight, so a late response cannot raise `remaining` within its window.
+     * @param options `maxBackoff`: the most, in ms, that a rate-limit header can
+     *   make later requests wait (default 10 minutes). `probeMs`: how long a
+     *   request discovering an unknown bucket holds it (default 16 s; keep it
+     *   above the transport timeout). `globalLimit`: most requests per second
+     *   per global scope, enforced before Discord answers 429 (default none;
+     *   `REST` passes 50). `telemetry`: event sink. `concurrent` is
+     *   accepted for compatibility: responses are always merged so a late one
+     *   cannot raise `remaining`.
      */
     constructor(store: RateLimitStore, options?: {
         concurrent?: boolean;
+        maxBackoff?: number;
+        probeMs?: number;
+        globalLimit?: number;
+        telemetry?: RESTTelemetry;
     });
+    /** The ceiling on a wait a server header can cause, in ms. */
+    get maxBackoff(): number;
     /** The backing store, shared across processes when a distributed store is used. */
     get store(): RateLimitStore;
-    /** Resolves the bucket key a request should be gated on. */
-    resolveBucketKey(route: string, major: string): Promise<string>;
     /** Whether the backing store can reserve allowance atomically. */
     get reserves(): boolean;
+    /**
+     * Resolves the bucket key a request should be gated on. With an
+     * `identity`, the key is prefixed by it, so two bots never share a bucket.
+     */
+    resolveBucketKey(route: string, major: string, identity?: string): Promise<string>;
     /**
      * Waits until both the route bucket and the global limit permit sending.
      *
      * When the store supports it, allowance is *reserved* rather than merely
      * observed. Reading `remaining` and deciding to send is a race across
      * workers: three processes all read `remaining: 1` and all send. A
-     * reservation hands the unit to exactly one of them.
+     * reservation hands the unit to exactly one of them. A request is never
+     * sent without its reservation: a store that keeps refusing without a
+     * wait, or that fails, ends the request with a `"coordination"` error.
+     * @throws {RESTError} `"aborted"` on cancellation, `"coordination"` on a
+     *   broken store, `"rateLimited"` when waiting would exceed `maxBackoff`.
+     */
+    acquire(bucketKey: string, signal: AbortSignal | undefined, path: string, options?: {
+        global?: string;
+    }): Promise<Grant>;
+    /**
+     * Extends the global limit (of `scope`), never shortening a longer one
+     * already recorded. Atomic when the store has `extendGlobalReset`.
+     */
+    noteGlobalReset(resetAt: number, scope?: string): Promise<void>;
+    /**
+     * How long a 429 asks to wait, in ms: the body's `retry_after`, else the
+     * `Retry-After` header, else `X-RateLimit-Reset-After`, else one second.
+     * Negative or non-numeric values are ignored, not read as zero.
      */
-    acquire(bucketKey: string, signal: AbortSignal | undefined, path: string): Promise<void>;
-    /** Extends the global limit, never shortening a longer one already recorded. */
-    noteGlobalReset(resetAt: number): Promise<void>;
+    retryAfterMs(response: Response, body?: {
+        retry_after?: number;
+    }): number;
     /**
      * Records a response's rate-limit headers and returns the bucket key the
      * request actually belongs to: Discord may reveal a server bucket hash that
      * differs from the route-derived key used before the first response.
      */
-    applyResponse(response: Response, bucketKey: string, route: string, major: string): Promise<string>;
+    applyResponse(response: Response, bucketKey: string, route: string, major: string, options?: ApplyResponseOptions): Promise<string>;
+    /**
+     * Gives back what a grant held when the request did not get a response:
+     * a probe placeholder is always cleared; the unit itself is returned only
+     * with `notSent` (the request certainly never left), because a request
+     * that may have reached Discord may also have spent it.
+     */
+    releaseGrant(bucketKey: string, grant: Grant, notSent: boolean): Promise<void>;
 }

package/dist/rest/redis.d.ts

@@ -1,4 +1,25 @@
-import { type RateLimitStore, type BucketState, type Reservation } from "./store.js";
+import { type BucketState, type BucketUpdate, type RateLimitStore, type Reservation, type ReserveOptions } from "./store.js";
+import { type CoordinationMode, type RESTTelemetry } from "./telemetry.js";
+/**
+ * Atomically checks the global limit and consumes one unit of a bucket.
+ * A port of `reserveState` in store.ts.
+ *
+ * `KEYS[1]` bucket · `KEYS[2]` global reset · `KEYS[3]` global request count
+ * (both optional) · `ARGV` probe ms, poll ms, linger ms, global limit, window ms.
+ * Returns `{1, resetAt, known}` or `{0, waitMs, reason}`.
+ */
+export declare const RESERVE_SCRIPT = "\nlocal function now_ms()\n  local t = redis.call('TIME')\n  return tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nend\nlocal function load(key)\n  local raw = redis.call('GET', key)\n  if not raw then return nil end\n  local ok, s = pcall(cjson.decode, raw)\n  if ok and type(s) == 'table' and type(s.resetAt) == 'number'\n    and type(s.remaining) == 'number' then return s end\n  return nil\nend\nlocal function save(key, s, now, linger)\n  local ttl = math.max(1, math.ceil(s.resetAt - now)) + linger\n  redis.call('SET', key, cjson.encode(s), 'PX', ttl)\nend\n\nlocal now = now_ms()\nlocal glimit, gwindow = tonumber(ARGV[4]) or 0, tonumber(ARGV[5]) or 1000\nif #KEYS > 1 then\n  local g = tonumber(redis.call('GET', KEYS[2]) or '0') or 0\n  if g > now then return {0, math.ceil(g - now), 'global'} end\nend\nif #KEYS < 3 then glimit = 0 end\n-- A sliding log of send times: at most glimit in any gwindow span.\nif glimit > 0 then\n  redis.call('ZREMRANGEBYSCORE', KEYS[3], '-inf', now - gwindow)\n  if redis.call('ZCARD', KEYS[3]) >= glimit then\n    local oldest = redis.call('ZRANGE', KEYS[3], 0, 0, 'WITHSCORES')\n    return {0, math.max(1, tonumber(oldest[2]) + gwindow - now + 1), 'global'}\n  end\nend\nlocal function count()\n  if glimit > 0 then\n    local seq = redis.call('ZCARD', KEYS[3])\n    redis.call('ZADD', KEYS[3], now, now .. ':' .. seq)\n    redis.call('PEXPIRE', KEYS[3], gwindow + 1000)\n  end\nend\nlocal probe, poll, linger = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])\nlocal s = load(KEYS[1])\nif s and s.resetAt > now then\n  if s.remaining > 0 then\n    s.remaining = s.remaining - 1\n    save(KEYS[1], s, now, linger)\n    count()\n    return {1, s.resetAt, 1}\n  end\n  local wait = s.resetAt - now\n  if s.provisional then wait = math.min(wait, poll) end\n  local reason = 'bucket'\n  if s.probe then reason = 'probe' end\n  return {0, math.ceil(wait), reason}\nend\nlocal resetAt = now + probe\nif s and type(s.limit) == 'number' and s.limit > 0 then\n  save(KEYS[1], {remaining = s.limit - 1, resetAt = resetAt, limit = s.limit, provisional = true}, now, linger)\n  count()\n  return {1, resetAt, 1}\nend\nsave(KEYS[1], {remaining = 0, resetAt = resetAt, provisional = true, probe = true}, now, 0)\ncount()\nreturn {1, resetAt, 0}\n";
+/**
+ * Atomically merges a response into a bucket. A port of `reconcileState`.
+ *
+ * `KEYS[1]` bucket · `ARGV` remaining, reset-after ms, limit, window, retry ms
+ * (each '' when absent), linger ms.
+ */
+export declare const RECONCILE_SCRIPT = "\nlocal function now_ms()\n  local t = redis.call('TIME')\n  return tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nend\nlocal function load(key)\n  local raw = redis.call('GET', key)\n  if not raw then return nil end\n  local ok, s = pcall(cjson.decode, raw)\n  if ok and type(s) == 'table' and type(s.resetAt) == 'number'\n    and type(s.remaining) == 'number' then return s end\n  return nil\nend\nlocal function save(key, s, now, linger)\n  local ttl = math.max(1, math.ceil(s.resetAt - now)) + linger\n  redis.call('SET', key, cjson.encode(s), 'PX', ttl)\nend\n\nlocal now = now_ms()\nlocal rem, after, limit = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])\nlocal win, retry, linger = tonumber(ARGV[4]), tonumber(ARGV[5]), tonumber(ARGV[6])\nlocal tol = 50\nlocal incoming = nil\nif after then incoming = math.ceil(now + after) end\nlocal s = load(KEYS[1])\nlocal n\nif s and s.resetAt > now and not s.probe then\n  n = s\n  local stale = win and n.window and win < n.window - tol\n  if not stale then\n    if rem then n.remaining = math.min(n.remaining, rem) end\n    if incoming then\n      local newer = win and n.window and win > n.window + tol\n      if n.provisional or newer then n.resetAt = incoming\n      else n.resetAt = math.max(n.resetAt, incoming) end\n      n.provisional = nil\n    end\n    if win then n.window = math.max(n.window or 0, win) end\n  end\nelse\n  if not rem and not retry then\n    if s and s.probe then redis.call('DEL', KEYS[1]) end\n    return 0\n  end\n  n = {remaining = rem or 0, resetAt = incoming or now}\n  if s and type(s.limit) == 'number' then n.limit = s.limit end\n  if win then n.window = win end\nend\nif limit and limit > 0 then n.limit = limit end\nif retry then\n  n.remaining = 0\n  n.resetAt = math.max(n.resetAt, math.ceil(now + retry))\n  n.provisional = nil\nend\nsave(KEYS[1], n, now, linger)\nreturn 1\n";
+/** Extends a global limit, never shortening it. `KEYS[1]` global · `ARGV[1]` wait ms. */
+export declare const EXTEND_GLOBAL_SCRIPT = "\nlocal function now_ms()\n  local t = redis.call('TIME')\n  return tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nend\nlocal function load(key)\n  local raw = redis.call('GET', key)\n  if not raw then return nil end\n  local ok, s = pcall(cjson.decode, raw)\n  if ok and type(s) == 'table' and type(s.resetAt) == 'number'\n    and type(s.remaining) == 'number' then return s end\n  return nil\nend\nlocal function save(key, s, now, linger)\n  local ttl = math.max(1, math.ceil(s.resetAt - now)) + linger\n  redis.call('SET', key, cjson.encode(s), 'PX', ttl)\nend\n\nlocal now = now_ms()\nlocal target = math.ceil(now + tonumber(ARGV[1]))\nlocal cur = tonumber(redis.call('GET', KEYS[1]) or '0') or 0\nif target > cur then\n  redis.call('SET', KEYS[1], tostring(target), 'PX', math.max(1, target - now))\n  return target - now\nend\nreturn math.max(0, cur - now)\n";
+/** Clears a probe or refunds a unit. `KEYS[1]` bucket · `ARGV` resetAt, refund (1/0). */
+export declare const RELEASE_SCRIPT = "\nlocal function now_ms()\n  local t = redis.call('TIME')\n  return tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nend\nlocal function load(key)\n  local raw = redis.call('GET', key)\n  if not raw then return nil end\n  local ok, s = pcall(cjson.decode, raw)\n  if ok and type(s) == 'table' and type(s.resetAt) == 'number'\n    and type(s.remaining) == 'number' then return s end\n  return nil\nend\nlocal function save(key, s, now, linger)\n  local ttl = math.max(1, math.ceil(s.resetAt - now)) + linger\n  redis.call('SET', key, cjson.encode(s), 'PX', ttl)\nend\n\nlocal s = load(KEYS[1])\nif not s or s.resetAt ~= tonumber(ARGV[1]) then return 0 end\nif s.probe then\n  redis.call('DEL', KEYS[1])\n  return 1\nend\nif ARGV[2] == '1' then\n  local cap = s.remaining + 1\n  if type(s.limit) == 'number' then cap = math.min(cap, s.limit) end\n  s.remaining = cap\n  redis.call('SET', KEYS[1], cjson.encode(s), 'KEEPTTL')\n  return 1\nend\nreturn 0\n";
 /**
  * A Redis client interface that matches the subset of ioredis
  * methods needed for the RedisRateLimitStore.
@@ -10,45 +31,105 @@ export interface MinimalRedisClient {
     del(...keys: string[]): Promise<number>;
     /**
      * Optional Lua evaluation (ioredis/node-redis compatible). When present,
-     * {@link RedisRateLimitStore.reserve} becomes available and the limiter
-     * reserves allowance atomically instead of racing on observed state.
+     * the store reserves, reconciles and extends limits atomically; without
+     * it the store is observational and workers can race on the last unit.
      */
     eval?(script: string, numKeys: number, ...args: Array<string | number>): Promise<unknown>;
 }
+/**
+ * Adapts Bun's built-in `Bun.RedisClient` (or anything with
+ * `send(command, args)`) to {@link MinimalRedisClient}, with `eval`.
+ *
+ * ```ts
+ * const store = new RedisRateLimitStore({
+ *     client: fromBunRedis(new Bun.RedisClient(process.env.REDIS_URL)),
+ * });
+ * ```
+ */
+export declare function fromBunRedis(client: {
+    send(command: string, args: string[]): Promise<unknown>;
+}): MinimalRedisClient;
+/**
+ * What the store does when Redis cannot be reached.
+ *
+ * - `degraded-local` (default): limit from this process's last known state,
+ *   report the mode change, and return to Redis when it answers again. Several
+ *   processes limiting alone can together exceed a limit.
+ * - `fail-closed`: refuse to send. Requests fail with a `RESTError` of kind
+ *   `"coordination"` until Redis answers.
+ */
+export type RedisFailurePolicy = "degraded-local" | "fail-closed";
+/** Options for `RedisRateLimitStore`. */
 export interface RedisRateLimitStoreOptions {
-    /** The Redis client instance (e.g. ioredis). */
+    /** The Redis client instance (e.g. ioredis, or `fromBunRedis(...)`). */
     client: MinimalRedisClient;
-    /** Prefix to prepend to all Redis keys. Defaults to 'lunibee:rest:' */
+    /**
+     * Prefix of every key. Defaults to `lunibee:rest:`; keys are then
+     * versioned (`lunibee:rest:v1:…`). On Redis Cluster, put a hash tag in it
+     * (`{lunibee}:rest:`) so one script's keys share a slot.
+     */
     prefix?: string;
-    /** Called whenever a Redis operation fails before local fallback behavior is used. */
+    /** Called whenever a Redis operation fails. */
     onError?: (operation: string, error: unknown) => void;
+    /** What to do while Redis is unreachable. Default `"degraded-local"`. */
+    failurePolicy?: RedisFailurePolicy;
+    /** Longest one Redis command may take before it counts as failed, in ms. Default 2000. */
+    commandTimeout?: number;
+    /** Throw at construction when the client has no `eval` (no atomic reservations). Default false. */
+    requireAtomic?: boolean;
+    /** Receives `store` latency and `mode` events. */
+    telemetry?: RESTTelemetry;
+}
+/** The store's health, for diagnostics endpoints. */
+export interface RedisStoreDiagnostics {
+    mode: CoordinationMode;
+    failurePolicy: RedisFailurePolicy;
+    atomic: boolean;
+    failures: number;
+    lastFailureAt?: number;
+    lastError?: string;
 }
 /**
- * Redis-backed implementation of RateLimitStore for distributed rate limit synchronization.
- * Allows multiple shards or workers to share Discord API rate limits seamlessly.
+ * Redis-backed implementation of RateLimitStore for distributed rate limit
+ * synchronization: workers sharing one Redis share every limit, reserve
+ * allowance atomically, and merge responses atomically.
  */
 export declare class RedisRateLimitStore implements RateLimitStore {
     #private;
     constructor(options: RedisRateLimitStoreOptions);
     /** The most recent Redis error, if any. */
     get lastError(): unknown;
-    /** Whether no Redis operation has failed since construction or the last successful health check. */
+    /** Whether no Redis operation has failed since construction or the last successful one. */
     isHealthy(): boolean;
-    getBucketHash(route: string): Promise<string | undefined>;
-    setBucketHash(route: string, hash: string): Promise<void>;
-    getBucket(key: string): Promise<BucketState | undefined>;
-    updateBucket(key: string, state: BucketState): Promise<void>;
+    /** How limits are being enforced right now. */
+    get mode(): CoordinationMode;
     /** Whether the backing client supports atomic reservations. */
     get supportsReservation(): boolean;
+    /** The store's current health. */
+    diagnostics(): RedisStoreDiagnostics;
     /**
-     * Atomically consumes one unit of a bucket's allowance across the fleet.
-     *
-     * Assigned in the constructor only when the client exposes `eval`, so a
-     * client that cannot reserve atomically does not advertise that it can.
-     * A Redis failure falls back to the local mirror rather than blocking:
-     * refusing every request during an outage would stall the bot.
+     * Checks that the client can run the store's scripts (some managed Redis
+     * services disable `EVAL`). Call it at startup to fail fast.
+     * @throws {TypeError} If the client has no `eval`.
+     * @throws {RESTError} Of kind `"coordination"`, if the script cannot run.
      */
-    reserve?: (key: string) => Promise<Reservation>;
-    getGlobalReset(): Promise<number>;
-    setGlobalReset(resetAt: number): Promise<void>;
+    verify(): Promise<void>;
+    getBucketHash(route: string): Promise<string | undefined>;
+    setBucketHash(route: string, hash: string): Promise<void>;
+    getBucket(key: string): Promise<BucketState | undefined>;
+    updateBucket(key: string, state: BucketState): Promise<void>;
+    /** Atomically checks the global limit and consumes one unit of the bucket. */
+    reserve?: (key: string, options?: ReserveOptions) => Promise<Reservation>;
+    /** Atomically merges a response into the bucket. */
+    reconcile?: (key: string, update: BucketUpdate) => Promise<void>;
+    /** Atomically extends a global limit, never shortening it. */
+    extendGlobalReset?: (scope: string, waitMs: number) => Promise<void>;
+    /** Clears a probe placeholder or refunds an unsent request's unit. */
+    release?: (key: string, grant: {
+        resetAt?: number;
+    }, refund: boolean) => Promise<void>;
+    /** Whether {@link reserve} checks the global limit itself. */
+    readonly reservesGlobal?: boolean;
+    getGlobalReset(scope?: string): Promise<number>;
+    setGlobalReset(resetAt: number, scope?: string): Promise<void>;
 }

package/dist/rest/scheduler.d.ts

@@ -1,3 +1,10 @@
+/** Limits for {@link RequestScheduler}. */
+export interface SchedulerOptions {
+    /** Most requests waiting for a slot across all buckets. Default unlimited. */
+    maxQueued?: number;
+    /** Most requests waiting for a slot on one bucket. Default unlimited. */
+    maxQueuedPerBucket?: number;
+}
 /**
  * Serialises work per rate-limit bucket.
  *
@@ -5,13 +12,18 @@
  * limit state its predecessor's response wrote. The queue slot is released on
  * every exit path — including an abort raised while still waiting — because a
  * slot that is never released wedges its bucket for the process lifetime.
+ * Buckets queue independently: a slow bucket never holds up another.
  */
 export declare class RequestScheduler {
     #private;
     /** Maximum times a request may be moved to a different bucket queue. */
     static readonly MAX_REMAPS = 2;
+    /** Creates an empty scheduler. @param options Queue limits. */
+    constructor(options?: SchedulerOptions);
     /** Number of bucket keys currently holding a queue slot. */
     get size(): number;
+    /** Number of requests waiting for a slot. */
+    get queued(): number;
     /**
      * Runs `task` under the bucket key that `resolveKey` reports *at the moment
      * the slot is acquired*, not at enqueue time.
@@ -37,6 +49,7 @@ export declare class RequestScheduler {
      * @param path Request path, used for cancellation error context.
      * @param task Work to run while holding the slot, given an idempotent
      *   callback that frees the slot before the task settles.
+     * @throws {RESTError} Of kind `"overloaded"` when a queue limit is reached.
      */
     run<T>(key: string, signal: AbortSignal | undefined, path: string, task: (release: () => void) => Promise<T>): Promise<T>;
 }

package/dist/rest/store.d.ts

@@ -1,20 +1,81 @@
+/**
+ * A rate-limit bucket as stored: units `remaining` in the window and when it
+ * resets (`resetAt`, ms since the epoch, in the store's clock).
+ */
 export interface BucketState {
     remaining: number;
     resetAt: number;
+    /** The bucket's limit per window, once a response has told us. */
+    limit?: number;
+    /** `X-RateLimit-Reset` of the window this state describes, in epoch ms. */
+    window?: number;
+    /**
+     * `resetAt` is an estimate, not a server value: the window was opened by a
+     * reservation after the last one elapsed. A server reset replaces it.
+     */
+    provisional?: boolean;
+    /**
+     * Placeholder for a bucket nobody knows yet: one request (the probe) is
+     * on its way to discover the limit, and everyone else waits for it.
+     */
+    probe?: boolean;
 }
 /**
  * Outcome of an atomic reservation.
  *
  * `granted` means one unit of the bucket's allowance now belongs to the caller
  * and to nobody else — the distinction that a read-then-write cannot make when
- * several workers share a store.
+ * several workers share a store. `known` says whether the bucket's limit is
+ * known (so more requests may follow concurrently) or this request is the
+ * probe that discovers it; `resetAt` identifies the window the unit came from.
+ * A refusal says how long to wait and why.
  */
 export type Reservation = {
     granted: true;
+    known?: boolean;
+    resetAt?: number;
 } | {
     granted: false;
     retryAfterMs: number;
+    reason?: "bucket" | "global" | "probe";
 };
+/** Options for {@link RateLimitStore.reserve}. */
+export interface ReserveOptions {
+    /** Global-limit scope to check in the same atomic step, if any. */
+    global?: string;
+    /** How long a probe may hold an unknown bucket before others may try (ms). */
+    probeMs?: number;
+    /**
+     * Most requests per second the `global` scope may send, counted in the
+     * same atomic step (Discord's global limit, 50 for most bots). Omitted or
+     * 0: only a recorded global 429 is enforced.
+     */
+    globalLimit?: number;
+}
+/**
+ * Span of the proactive global limit's sliding log (ms): at most the limit is
+ * sent in any span this long. A second plus a margin, so latency jitter
+ * cannot squeeze more than the limit into one second as Discord counts it.
+ */
+export declare const GLOBAL_WINDOW_MS = 1050;
+/**
+ * Takes one slot from a sliding log of send times, or says how long until
+ * one frees. `log` holds the send times still inside the window, oldest first.
+ */
+export declare function takeGlobalSlot(log: number[], now: number, limit: number, window?: number): number;
+/** What a response said about a bucket, for {@link RateLimitStore.reconcile}. */
+export interface BucketUpdate {
+    /** `X-RateLimit-Remaining`. */
+    remaining?: number;
+    /** `X-RateLimit-Reset-After`, in ms from now. */
+    resetAfterMs?: number;
+    /** `X-RateLimit-Limit`. */
+    limit?: number;
+    /** `X-RateLimit-Reset`, epoch ms: identifies the window. */
+    window?: number;
+    /** A bucket 429's wait, in ms: the bucket is spent until then. */
+    retryAfterMs?: number;
+}
 /** Interface for distributed or local rate limit synchronization. */
 export interface RateLimitStore {
     /** Gets the server bucket hash for a normalized route. */
@@ -23,21 +84,47 @@ export interface RateLimitStore {
     setBucketHash(route: string, hash: string): Promise<void> | void;
     /** Gets the current state for a bucket key. */
     getBucket(key: string): Promise<BucketState | undefined> | BucketState | undefined;
-    /** Updates the state for a bucket key. */
+    /** Replaces the state for a bucket key. */
     updateBucket(key: string, state: BucketState): Promise<void> | void;
-    /** Gets the global reset timestamp. */
-    getGlobalReset(): Promise<number> | number;
-    /** Sets the global reset timestamp. */
-    setGlobalReset(resetAt: number): Promise<void> | void;
+    /** Gets the global reset timestamp (of `scope`, when the store keeps several). */
+    getGlobalReset(scope?: string): Promise<number> | number;
+    /** Sets the global reset timestamp (of `scope`, when the store keeps several). */
+    setGlobalReset(resetAt: number, scope?: string): Promise<void> | void;
     /**
      * Atomically consumes one unit of a bucket's allowance.
      *
      * Optional: a store that cannot do this atomically must omit it, and the
      * limiter falls back to waiting on observed state. Implementations must
-     * grant when the bucket is unknown or its window has elapsed — an unknown
-     * bucket is discovered by sending, and refusing would deadlock the route.
+     * never refuse forever: an unknown bucket is discovered by sending, so
+     * one caller (the probe) must be granted.
      */
-    reserve?(key: string): Promise<Reservation> | Reservation;
+    reserve?(key: string, options?: ReserveOptions): Promise<Reservation> | Reservation;
+    /**
+     * Whether {@link reserve} also checks `options.global` atomically. When
+     * it does not, the limiter reads the global reset itself first.
+     */
+    readonly reservesGlobal?: boolean;
+    /**
+     * Atomically merges what a response said into a bucket, so a late or
+     * out-of-order response cannot hand back allowance already reserved.
+     * Optional: without it the limiter reads, merges and writes.
+     */
+    reconcile?(key: string, update: BucketUpdate): Promise<void> | void;
+    /**
+     * Atomically extends a global limit to at least `waitMs` from now, never
+     * shortening a longer one. Optional: without it the limiter reads and
+     * writes, which a concurrent writer can shorten.
+     */
+    extendGlobalReset?(scope: string, waitMs: number): Promise<void> | void;
+    /**
+     * Gives back what a granted reservation held, when that is certain to be
+     * safe: a probe placeholder is cleared (so the next request may probe),
+     * and with `refund` — the request was never sent — the unit is returned
+     * to the window it came from, if that window is still current.
+     */
+    release?(key: string, grant: {
+        resetAt?: number;
+    }, refund: boolean): Promise<void> | void;
     /**
      * Evicts expired bucket entries. Optional: stores with native key
      * expiry (e.g. Redis) can omit it. `maxAge` (ms) additionally drops
@@ -46,9 +133,38 @@ export interface RateLimitStore {
      */
     prune?(maxAge?: number): Promise<void> | void;
 }
+/** Longest a refused waiter sleeps on a placeholder before asking again (ms). */
+export declare const PROBE_POLL_MS = 50;
+/** Default time a probe may hold an unknown bucket (ms). */
+export declare const DEFAULT_PROBE_MS = 16000;
+/** How long a bucket's limit is remembered after its window resets (ms). */
+export declare const BUCKET_LINGER_MS = 60000;
+/**
+ * The reservation decision, shared by every built-in store (the Redis store
+ * runs a Lua port of it). Returns the new state to write, if any.
+ */
+export declare function reserveState(state: BucketState | undefined, now: number, probeMs: number): {
+    reservation: Reservation;
+    next?: BucketState;
+};
+/**
+ * The merge of a response into a bucket, shared by every built-in store.
+ *
+ * Within a window `remaining` only ever goes down: the stored value already
+ * counts reservations still in flight, the header counts what the server
+ * has seen, and the lower of the two is the one that cannot over-send. A
+ * response from an older window than the one stored is ignored. An estimated
+ * reset is replaced by the server's.
+ *
+ * Returns the state to write, `null` to delete, or `undefined` for no change.
+ */
+export declare function reconcileState(state: BucketState | undefined, update: BucketUpdate, now: number): BucketState | null | undefined;
 /** Local memory implementation of RateLimitStore. */
 export declare class MemoryRateLimitStore implements RateLimitStore {
     #private;
+    readonly reservesGlobal = true;
+    /** Creates an empty instance. */
+    constructor();
     getBucketHash(route: string): string | undefined;
     setBucketHash(route: string, hash: string): void;
     getBucket(key: string): BucketState | undefined;
@@ -58,10 +174,17 @@ export declare class MemoryRateLimitStore implements RateLimitStore {
      * Single-process reservation is trivially atomic: JavaScript will not
      * interleave this method with another caller's copy of it.
      */
-    reserve(key: string): Reservation;
+    reserve(key: string, options?: ReserveOptions): Reservation;
+    reconcile(key: string, update: BucketUpdate): void;
+    release(key: string, grant: {
+        resetAt?: number;
+    }, refund: boolean): void;
     updateBucket(key: string, state: BucketState): void;
     /** Removes buckets whose reset is in the past (or older than `maxAge` ms). */
     prune(maxAge?: number): void;
-    getGlobalReset(): number;
-    setGlobalReset(resetAt: number): void;
+    getGlobalReset(scope?: string): number;
+    setGlobalReset(resetAt: number, scope?: string): void;
+    extendGlobalReset(scope: string, waitMs: number): void;
+    /** Number of buckets held (for diagnostics and leak checks). */
+    get size(): number;
 }

package/dist/rest/telemetry.d.ts

@@ -0,0 +1,151 @@
+/**
+ * What the REST pipeline reports while it works. Every field is bounded and
+ * free of secrets: routes are normalized (ids become `:id`, tokens `:token`,
+ * reaction emoji `:emoji`), and no token, fingerprint or body is included.
+ */
+export type RESTTelemetryEvent = 
+/** One HTTP attempt got a response. */
+{
+    type: "response";
+    method: string;
+    route: string;
+    status: number;
+    durationMs: number;
+}
+/** A request settled (after every attempt), successfully or not. */
+ | {
+    type: "request";
+    method: string;
+    route: string;
+    status: number;
+    attempts: number;
+    durationMs: number;
+    ok: boolean;
+}
+/** Discord answered 429. */
+ | {
+    type: "rateLimited";
+    route: string;
+    scope: "user" | "global" | "shared" | "unknown";
+    retryAfterMs: number;
+}
+/** A request waited for a limit before it could be sent. */
+ | {
+    type: "wait";
+    reason: "bucket" | "global" | "probe";
+    durationMs: number;
+}
+/** A reservation was asked of the store. */
+ | {
+    type: "reservation";
+    granted: boolean;
+    known: boolean;
+    latencyMs: number;
+}
+/** A request is being sent again. */
+ | {
+    type: "retry";
+    route: string;
+    reason: "rateLimited" | "server" | "network";
+    attempt: number;
+}
+/** A request was cancelled. */
+ | {
+    type: "cancelled";
+    stage: "queued" | "waiting" | "transport" | "retry";
+}
+/** A request was refused because a queue was full. */
+ | {
+    type: "overloaded";
+}
+/** Discord answered 401 on a bot route: later requests with the token are refused. */
+ | {
+    type: "tokenRejected";
+}
+/** A transport attempt failed without a response. */
+ | {
+    type: "networkError";
+    timedOut: boolean;
+}
+/** A route learned its bucket hash, or the hash changed. */
+ | {
+    type: "bucket";
+    change: "discovered" | "remapped";
+    route: string;
+}
+/** One store command (Redis), with its latency. */
+ | {
+    type: "store";
+    operation: string;
+    latencyMs: number;
+    ok: boolean;
+}
+/** The store's coordination mode changed. */
+ | {
+    type: "mode";
+    mode: CoordinationMode;
+    previous: CoordinationMode;
+}
+/** Queue depth and in-flight requests, after a change. */
+ | {
+    type: "queue";
+    queued: number;
+    inFlight: number;
+};
+/**
+ * How a store enforces limits right now.
+ *
+ * - `distributed`: shared state with atomic reservations.
+ * - `observational`: shared state without atomic reservations (a client with
+ *   no `eval`): workers can race on the last unit.
+ * - `degraded-local`: shared state is unreachable and this process is
+ *   limiting alone, from its last known state.
+ * - `unavailable`: shared state is unreachable and requests fail
+ *   (`failurePolicy: "fail-closed"`).
+ * - `local`: a process-local store.
+ */
+export type CoordinationMode = "distributed" | "observational" | "degraded-local" | "unavailable" | "local";
+/** Receives telemetry events. Must be fast and must not throw. */
+export interface RESTTelemetry {
+    emit(event: RESTTelemetryEvent): void;
+}
+/** Calls a sink without letting it break the request path. */
+export declare function emitTelemetry(sink: RESTTelemetry | undefined, event: RESTTelemetryEvent): void;
+/** A snapshot of {@link RESTMetrics}. */
+export interface RESTMetricsSnapshot {
+    /** `name{label="v",…}` → count. */
+    counters: Record<string, number>;
+    /** `name` → last value. */
+    gauges: Record<string, number>;
+    /** `name{…}` → latency distribution in ms. */
+    histograms: Record<string, {
+        count: number;
+        sum: number;
+        buckets: Record<string, number>;
+    }>;
+}
+/**
+ * An in-memory metrics aggregator for {@link RESTTelemetry}: counters,
+ * gauges and latency histograms, with a hard cap on distinct label sets so
+ * an unexpected route shape cannot grow it without bound.
+ *
+ * ```ts
+ * const metrics = new RESTMetrics();
+ * const rest = new REST({ token, telemetry: metrics });
+ * // later: metrics.snapshot(), or metrics.toPrometheus() for a /metrics endpoint
+ * ```
+ */
+export declare class RESTMetrics implements RESTTelemetry {
+    #private;
+    /** @param options `maxRoutes`: distinct route labels kept before the rest become `other` (default 500). */
+    constructor(options?: {
+        maxRoutes?: number;
+    });
+    emit(event: RESTTelemetryEvent): void;
+    /** The current values. */
+    snapshot(): RESTMetricsSnapshot;
+    /** Clears every value. */
+    reset(): void;
+    /** The values in the Prometheus text exposition format. */
+    toPrometheus(prefix?: string): string;
+}