lunibee 0.3.0 → 0.3.1

package/dist/sharding/cluster.d.ts

@@ -1,4 +1,7 @@
 import { type ChildProcess } from "node:child_process";
+import { type ShardReply } from "./bus.js";
+import type { ClusterManagerHealth, ClusterState, WorkerReport } from "./health.js";
+import { type HostStatus, type RemoteOptions } from "./remote.js";
 import { type SupervisorOptions } from "./supervisor.js";
 /** Configuration for managing multiple shard clusters. */
 export interface ClusterManagerOptions {
@@ -6,10 +9,81 @@ export interface ClusterManagerOptions {
     token: string;
     /** Path to the worker script to execute for each cluster. */
     script: string;
-    /** Number of shards. Use "auto" to request Discord's recommended count. */
+    /** Total number of shards. Use "auto" to request Discord's recommended count. */
     shardCount?: number | "auto";
-    /** Number of clusters to spawn. Defaults to the number of logical CPUs. */
+    /**
+     * With `shardCount: "auto"`, size the deployment by guilds instead of
+     * Discord's recommendation: `ceil(guilds / guildsPerShard)` shards, at
+     * least one. 1 to 2500 (Discord's limit); Discord recommends about 1000.
+     * Guilds are assigned to shards by their ID, so this sets the average,
+     * not an exact split.
+     */
+    guildsPerShard?: number;
+    /** The bot's guild count for `guildsPerShard`, instead of asking Discord for it. */
+    guildCount?: number;
+    /**
+     * The shards this deployment runs, out of `shardCount`. Use it to split one
+     * bot across hosts: each host runs a `ClusterManager` with its own range.
+     * Defaults to every shard.
+     */
+    shardIds?: number[];
+    /** Number of clusters to spawn. Defaults to the number of logical CPUs. Not combinable with `shardsPerCluster`. */
     clusterCount?: number;
+    /** Shards per cluster; the cluster count follows. Not combinable with `clusterCount`. */
+    shardsPerCluster?: number;
+    /**
+     * Discord's `max_concurrency` for IDENTIFY pacing. Fetched from `/gateway/bot`
+     * when `shardCount` is "auto" (this value may only lower it); otherwise defaults to 1.
+     */
+    maxConcurrency?: number;
+    /** Ask `/gateway/bot` for `max_concurrency` and the session budget even with a fixed `shardCount`. */
+    fetchLimits?: boolean;
+    /** IDENTIFY coordination across clusters. On by default. */
+    identify?: {
+        /** Set `false` to let every cluster pace its own IDENTIFYs. */
+        coordinate?: boolean;
+        /** Milliseconds between IDENTIFYs on one key. Default 5000. */
+        interval?: number;
+        /** A slot a worker never releases is released after this many ms. Default 60,000. */
+        holdTimeout?: number;
+    };
+    /** Milliseconds between forking two clusters, to spread the CPU cost of starting. Default 500. IDENTIFY pacing does not depend on it. */
+    spawnInterval?: number;
+    /**
+     * A cluster that has not reported ready this many ms after it was forked is
+     * killed and restarted like a crash. Off by default, because a worker that
+     * never reports ready (no `ShardManager`, no `ClusterWorker`) would be killed.
+     */
+    startTimeout?: number;
+    /** Make `spawn()` wait until every cluster reported ready. Default false. */
+    waitForReady?: boolean;
+    /**
+     * When a cluster crashes more often than `supervisor.maxRestarts` allows,
+     * move its shards to the healthiest ready cluster instead of leaving them
+     * offline. Default false.
+     */
+    reassignOnGiveUp?: boolean;
+    /**
+     * Largest shard-bus message, request payload or worker reply the manager
+     * handles, in UTF-8 bytes (a string as it is, anything else as its JSON text). Bigger ones from a worker are
+     * dropped before they are relayed (an `error` event says so; a request
+     * waiting for the answer times out as usual), and bigger ones passed to
+     * `request()`, `broadcast()` or `requestCluster()` throw a `RangeError`.
+     * Default 8 MiB, the same limit as the host link.
+     */
+    maxMessageBytes?: number;
+    /** Default timeout for `request()`, `requestCluster()` and `broadcast()`. Default 5000. */
+    requestTimeout?: number;
+    /** Most requests waiting for answers at once. Default 10,000. */
+    maxPendingRequests?: number;
+    /**
+     * Accept hosts on other machines. The coordinator listens for
+     * `ClusterHost` agents, places clusters on them and supervises those
+     * workers like local ones. See {@link RemoteOptions}.
+     */
+    remote?: RemoteOptions;
+    /** Starts a worker process. Defaults to `child_process.fork()`; replace it for tests or custom launchers. */
+    fork?: (script: string, env: Record<string, string | undefined>) => ChildProcess;
     /** Interval in milliseconds to automatically check for recommended shard count and re-scale if needed. */
     autoScaleInterval?: number;
     /** Optional handler invoked when a background auto-scale check fails. Receives the thrown error. */
@@ -37,35 +111,170 @@ export interface ClusterManagerOptions {
     /** Called whenever a cluster process exits, before any restart. */
     onClusterExit?(cluster: ClusterInfo, code: number | null, signal: NodeJS.Signals | null): void;
 }
-/** Information about a running cluster. */
+/** Information about a cluster. The object is live: it is updated as the cluster changes. */
 export interface ClusterInfo {
     /** Cluster identifier. */
     id: number;
-    /** The child process running the cluster. */
+    /** The current child process (the last one while a restart is pending). For a cluster on another host this is a proxy; `pid` is the pid on that host. */
     process: ChildProcess;
+    /** Where it runs: `"local"` or a host ID. */
+    host: string;
     /** The shard IDs managed by this cluster. */
     shards: number[];
+    /** Where the cluster is in its life. */
+    state: ClusterState;
+    /** How many times it was restarted after a crash. */
+    restarts: number;
+    /** When the current process was forked (epoch ms). */
+    startedAt: number;
+    /** When the current process reported ready. */
+    readyAt?: number;
+    /** When any process of this cluster last reported ready. */
+    lastReadyAt?: number;
+    /** The worker's last health report. */
+    report?: WorkerReport;
+}
+/** What `ClusterManager` emits. */
+export interface ClusterManagerEvents {
+    /** A cluster process was forked. */
+    clusterSpawn: [cluster: ClusterInfo];
+    /** A cluster's shards all finished their handshake. */
+    clusterReady: [cluster: ClusterInfo];
+    /** Every cluster is ready. Emitted again after a recovery. */
+    ready: [];
+    /** A cluster process exited. `expected` is true for a deliberate shutdown. */
+    clusterExit: [
+        cluster: ClusterInfo,
+        code: number | null,
+        signal: NodeJS.Signals | null,
+        expected: boolean
+    ];
+    /** A restart was scheduled after a crash. */
+    clusterRestart: [
+        cluster: ClusterInfo,
+        info: {
+            delay: number;
+            attempt: number;
+        }
+    ];
+    /** A cluster keeps crashing: three or more restarts are pending or recent. */
+    clusterUnstable: [
+        cluster: ClusterInfo,
+        info: {
+            attempt: number;
+            delay: number;
+        }
+    ];
+    /** A cluster did not report ready within `startTimeout` and was killed. */
+    clusterStartTimeout: [cluster: ClusterInfo];
+    /** A cluster crashed too often and will not be restarted. */
+    clusterGiveUp: [cluster: ClusterInfo];
+    /** A failed cluster's shards were moved to another cluster. */
+    shardsReassigned: [info: {
+        shardIds: number[];
+        from: number;
+        to: number;
+    }];
+    /** A host joined the deployment. */
+    hostJoin: [hostId: string];
+    /** A host left or was lost. Its clusters are treated as crashed. */
+    hostLeave: [hostId: string, reason: string];
+    /** An IDENTIFY is waiting for the session-start budget to reset. */
+    identifyWait: [info: {
+        shardId: number;
+        waitMs: number;
+    }];
+    /** Something went wrong that did not stop the deployment (a bad frame, a failed recovery). */
+    error: [error: Error];
+}
+/** Options for a request to a shard or cluster. */
+export interface RequestOptions {
+    /** Milliseconds to wait. Defaults to `requestTimeout`. */
+    timeoutMs?: number;
+    /** Cancels the wait. */
+    signal?: AbortSignal;
+}
+/** What a broadcast collected. It never rejects for a slow or failed shard. */
+export interface BroadcastResult<R = unknown> {
+    /** One reply per answering shard: its result, or the error its handler threw. */
+    replies: ShardReply<R>[];
+    /** Shards that did not answer: down, restarting, or too slow. */
+    missing: number[];
 }
 /**
- * Manages multiple clusters of shards, distributing shards across child processes.
+ * Orchestrates cluster processes: forks one worker per cluster, gives each a
+ * fixed set of shards, restarts crashed clusters with backoff, hands out
+ * IDENTIFY slots across all of them, routes shard-bus messages to the cluster
+ * that owns the target shard, and answers requests, broadcasts and health
+ * queries for the whole deployment.
  *
- * **Runtime requirement:** clustering relies on Node.js `child_process.fork()`
- * and IPC. `fork()` is not fully supported under Bun, so run the cluster
- * manager under the Node.js runtime; `spawn()` will fail on a runtime whose
- * `fork()` is unavailable.
+ * Ownership: the `ClusterManager` decides which cluster owns which shard and
+ * keeps processes alive; the `ShardManager` inside each worker runs those
+ * shards' Gateways. A shard is never owned by two clusters at once.
+ *
+ * Works under Node.js and Bun (`child_process.fork()` with IPC).
  */
 export declare class ClusterManager {
     #private;
-    /** Active clusters indexed by cluster ID. */
+    /** Live clusters (starting or ready) indexed by cluster ID. A crashed cluster leaves this map until it is restarted. */
     readonly clusters: Map<number, ClusterInfo>;
-    /** Total number of shards across all clusters. */
+    /** Total number of shards in the deployment. */
     shardCount: number;
-    /** Creates a cluster manager. @param options Clustering configuration. @throws {TypeError} If token or script is missing. */
+    /** Creates a cluster manager. @param options Clustering configuration. @throws {TypeError} If token or script is missing. @throws {RangeError} If a numeric option is invalid. */
     constructor(options: ClusterManagerOptions);
+    /** Listens for a deployment event. @returns This manager. */
+    on<E extends keyof ClusterManagerEvents>(event: E, listener: (...args: ClusterManagerEvents[E]) => void): this;
+    /** Stops listening for a deployment event. @returns This manager. */
+    off<E extends keyof ClusterManagerEvents>(event: E, listener: (...args: ClusterManagerEvents[E]) => void): this;
     /** Retrieves Discord's recommended shard count. @returns Recommended shard count. @throws {Error} If discovery fails or returns invalid data. */
     fetchRecommendedShardCount(): Promise<number>;
-    /** Spawns all clusters. @returns A promise fulfilled after clusters have launched. */
+    /** The cluster that owns a shard, or `undefined` when the shard is not part of this deployment. */
+    clusterForShard(shardId: number): ClusterInfo | undefined;
+    /** Which cluster owns each shard. A copy: change ownership through recovery, not by writing to it. */
+    assignments(): ReadonlyMap<number, number>;
+    /**
+     * Spawns all clusters. Calling it again while clusters run, or while the
+     * first call is still starting them, returns the same promise.
+     * @throws {Error} If called from a cluster worker (a worker must not start the fleet again).
+     */
     spawn(): Promise<void>;
+    /** The port hosts connect to, once the listener is open (useful with `remote.port: 0`). */
+    get remotePort(): number | undefined;
+    /** The hosts of this deployment: connected or not, and the clusters on each. Empty without `remote`. */
+    hosts(): HostStatus[];
+    /**
+     * Sends a request to one shard and resolves with its handler's result.
+     * @throws {RangeError} If the shard is not part of this deployment.
+     * @throws {Error} If its cluster is down, the handler failed, or no answer arrives in time.
+     */
+    request<R = unknown, T = unknown>(shardId: number, type: string, data: T, options?: RequestOptions): Promise<R>;
+    /**
+     * Asks every shard of every live cluster and collects the answers. Shards
+     * whose cluster is down, or that do not answer in time, are listed in
+     * `missing`; it does not reject for them.
+     */
+    broadcast<R = unknown, T = unknown>(type: string, data: T, options?: RequestOptions): Promise<BroadcastResult<R>>;
+    /**
+     * Sends a request to a cluster's worker (see `ClusterWorker.onRequest()`).
+     * @throws {Error} If the cluster is unknown or down, the handler failed, or no answer arrives in time.
+     */
+    requestCluster<R = unknown, T = unknown>(clusterId: number, type: string, data: T, options?: RequestOptions): Promise<R>;
+    /** Resolves when every cluster is ready. @throws {Error} On timeout, or if the manager stops first. */
+    ready(timeoutMs?: number): Promise<void>;
+    /**
+     * The last known health of every cluster and shard. Reads what the
+     * workers last reported; nothing is sent. Use {@link refreshHealth} for fresh numbers.
+     */
+    health(): ClusterManagerHealth;
+    /**
+     * Asks every live cluster for a fresh report, then returns {@link health}.
+     * A cluster that does not answer in time keeps its last report; it is not
+     * treated as failed (only its process exiting does that).
+     */
+    refreshHealth(options?: {
+        metrics?: boolean;
+        timeoutMs?: number;
+    }): Promise<ClusterManagerHealth>;
     /** Checks if the recommended shard count has changed and respawns if so. */
     checkAutoScale(): Promise<void>;
     /** Gracefully shuts the existing clusters down and respawns them with the new shard count. @param newShardCount The new total shard count. */
@@ -73,7 +282,8 @@ export declare class ClusterManager {
     /**
      * Gracefully stops all active clusters: sends SIGTERM, awaits each child's
      * clean exit, and force-kills (SIGKILL) only children that outlast the
-     * shutdown timeout. Clears the auto-scale timer and cluster map.
+     * shutdown timeout. Safe to call twice or concurrently; cancels restarts,
+     * timers and pending requests.
      * @param timeoutMs Grace period per child before force-kill. Defaults to the configured `shutdownTimeout` (5000 ms).
      */
     shutdownAll(timeoutMs?: number): Promise<void>;

package/dist/sharding/context.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What a cluster worker knows about itself. `ClusterManager` sets it through
+ * environment variables; {@link readClusterContext} reads it back.
+ */
+export interface ClusterContext {
+    /** This cluster's ID. */
+    clusterId: number;
+    /** How many clusters the deployment started. */
+    clusterCount: number;
+    /** Total shards in the deployment (what Discord calls `num_shards`). */
+    shardCount: number;
+    /** Shards this cluster owns. */
+    shardIds: number[];
+    /** Whether the parent hands out IDENTIFY slots for this cluster. */
+    coordinatedIdentify: boolean;
+}
+/** Set to `1` in every process `ClusterManager` forks, so a worker can tell it is one. */
+export declare const WORKER_MARKER = "LUNIBEE_CLUSTER_WORKER";
+/** Whether this process was forked by a `ClusterManager`. */
+export declare function isClusterWorker(env?: Record<string, string | undefined>): boolean;
+/** Checks that shard IDs are unique integers in `[0, total)`. @throws {RangeError} Otherwise. */
+export declare function validateShardIds(shardIds: readonly number[], total: number): void;
+/**
+ * Splits shard IDs across clusters round-robin: the i-th ID goes to cluster
+ * `i % clusterCount`. The same input always gives the same output.
+ * @returns One list per cluster (some may be empty when there are more clusters than shards).
+ * @throws {RangeError} If `clusterCount` is not a positive integer.
+ */
+export declare function allocateShards(shardIds: readonly number[], clusterCount: number): number[][];
+/**
+ * Proves an allocation covers `expected` exactly once.
+ * @throws {Error} Naming the missing, duplicate or unexpected shard IDs.
+ */
+export declare function assertCompleteAllocation(chunks: readonly (readonly number[])[], expected: readonly number[]): void;
+/**
+ * Reads the worker contract from the environment: `CLUSTER_ID`, `CLUSTER_COUNT`,
+ * `SHARD_COUNT`, `SHARD_LIST` (comma separated) and `LUNIBEE_IDENTIFY`.
+ * @returns The context, or `null` when this process is not a cluster worker.
+ * @throws {RangeError} If the variables are present but malformed.
+ */
+export declare function readClusterContext(env?: Record<string, string | undefined>): ClusterContext | null;

package/dist/sharding/gateway-bot.d.ts

@@ -16,3 +16,23 @@ export interface GatewayBotInfo {
  * @throws {Error} If the request fails or the answer is not usable.
  */
 export declare function fetchGatewayBot(token: string): Promise<GatewayBotInfo>;
+/** Discord's hard limit: a shard may serve at most this many guilds. */
+export declare const MAX_GUILDS_PER_SHARD = 2500;
+/** Checks a `guildsPerShard` option. @throws {RangeError} Unless it is an integer from 1 to 2500. */
+export declare function assertGuildsPerShard(value: number): void;
+/** How many shards keep each at or under `guildsPerShard` guilds (at least one). */
+export declare function shardsForGuilds(guilds: number, guildsPerShard: number): number;
+/**
+ * Asks Discord how many guilds the bot is in (`approximate_guild_count` of the application).
+ * @throws {Error} If the request fails or the answer is not usable.
+ */
+export declare function fetchGuildCount(token: string): Promise<number>;
+/**
+ * The shard count to use for `"auto"`: Discord's recommendation, or, with
+ * `guildsPerShard`, enough shards for the bot's guild count (`guildCount`, or
+ * what Discord reports).
+ */
+export declare function resolveShardCount(token: string, info: GatewayBotInfo, options: {
+    guildsPerShard?: number;
+    guildCount?: number;
+}): Promise<number>;

package/dist/sharding/health.d.ts

@@ -0,0 +1,94 @@
+import type { Gateway } from "@lunibee/ws";
+/** Where a shard is in its life, apart from the state of its Gateway socket. */
+export type ShardStatus = 
+/** Created, never connected. */
+"idle"
+/** Connecting or waiting for its IDENTIFY slot. */
+ | "connecting"
+/** Handshake finished; events are flowing. */
+ | "ready"
+/** The socket closed; the Gateway may be reconnecting by itself. */
+ | "disconnected"
+/** The Gateway reported repeated reconnects and is backing off. */
+ | "unstable"
+/** Closed with `destroy()`. */
+ | "destroyed";
+/** Health snapshot for one shard. */
+export interface ShardHealth {
+    id: number;
+    /** Gateway connection state. */
+    state: Gateway["state"];
+    /** Last heartbeat round-trip in ms, or -1 before the first ACK. */
+    ping: number;
+    /** Shard lifecycle, separate from the Gateway `state`. */
+    status: ShardStatus;
+    /** When the shard last became ready (epoch ms), if it ever did. */
+    readyAt?: number;
+    /** When the socket last closed (epoch ms), if it ever did. */
+    disconnectedAt?: number;
+}
+/** Process numbers a worker adds to a health report. Opt-in: they cost a syscall each. */
+export interface WorkerMetrics {
+    /** Resident set size in bytes. */
+    rssBytes: number;
+    /** V8 heap in use in bytes. */
+    heapUsedBytes: number;
+    /** CPU time used by this process, in microseconds. */
+    cpuUserMicros: number;
+    cpuSystemMicros: number;
+}
+/** What a cluster worker reports about itself. */
+export interface WorkerReport {
+    shards: ShardHealth[];
+    metrics?: WorkerMetrics;
+    /** When the worker built the report (epoch ms). */
+    reportedAt: number;
+}
+/** Lifecycle of a cluster process. */
+export type ClusterState = 
+/** Forked; has not said it is ready. */
+"starting"
+/** Every shard in the cluster finished its handshake. */
+ | "ready"
+/** Exited unexpectedly; a restart is scheduled. */
+ | "restarting"
+/** A deliberate shutdown is in progress. */
+ | "stopping"
+/** Stopped on purpose. */
+ | "stopped"
+/** Crashed too often and will not be restarted. */
+ | "failed";
+/** Health of one cluster. */
+export interface ClusterHealth {
+    id: number;
+    state: ClusterState;
+    pid?: number;
+    /** Where it runs: `"local"` or the ID of a host. */
+    host: string;
+    /** Shards this cluster owns right now. */
+    shardIds: number[];
+    /** Milliseconds since this process was forked; 0 when it is not running. */
+    uptimeMs: number;
+    /** How many times it has been restarted after a crash. */
+    restarts: number;
+    startedAt?: number;
+    /** When the current process reported ready. */
+    readyAt?: number;
+    /** When any process of this cluster last reported ready. */
+    lastReadyAt?: number;
+    /** Per-shard health from the worker's last report. Empty until it reports. */
+    shards: ShardHealth[];
+    /** Present when requested with `health({ metrics: true })` and the worker answered. */
+    metrics?: WorkerMetrics;
+    /** When `shards` and `metrics` were reported (epoch ms). */
+    reportedAt?: number;
+}
+/** Health of the whole deployment. */
+export interface ClusterManagerHealth {
+    state: "idle" | "starting" | "ready" | "degraded" | "stopping" | "stopped";
+    totalShards: number;
+    clusters: ClusterHealth[];
+    readyClusters: number;
+    /** Shards with no ready owner right now. */
+    missingShards: number[];
+}

package/dist/sharding/host.d.ts

@@ -0,0 +1,70 @@
+import type { ChildProcess } from "node:child_process";
+/** Options for a {@link ClusterHost}. */
+export interface ClusterHostOptions {
+    /** The coordinator's address: `wss://host:port`. `ws://` is accepted for this machine, or anywhere with `allowInsecure`. */
+    url: string;
+    /** Connect with `ws://` to a coordinator on another machine, over a network you fully trust. Default false. */
+    allowInsecure?: boolean;
+    /** The coordinator's shared secret. */
+    secret: string;
+    /** This host's ID: letters, digits, `.`, `_`, `-`. Must be unique in the deployment. */
+    id: string;
+    /**
+     * The worker script this host runs for every cluster. A coordinator cannot
+     * choose it: remote workers run only what the host owner configured.
+     */
+    script: string;
+    /** Starts a worker process. Defaults to `child_process.fork()`. */
+    fork?: (script: string, env: Record<string, string | undefined>) => ChildProcess;
+    /** First delay before reconnecting, in ms. Default 1000. */
+    reconnectDelay?: number;
+    /** Longest delay between reconnect attempts, in ms. Default 30,000. */
+    maxReconnectDelay?: number;
+}
+/** What a {@link ClusterHost} emits. */
+export interface ClusterHostEvents {
+    /** The coordinator accepted this host. */
+    connected: [];
+    /** The connection ended. Every worker was killed first. */
+    disconnected: [info: {
+        code: number;
+        reason: string;
+    }];
+    /** A worker started for a cluster. */
+    clusterSpawn: [cluster: number];
+    /** A worker exited. */
+    clusterExit: [cluster: number, code: number | null, signal: string | null];
+    /** A refused frame, a failed start or a rejected connection. */
+    error: [error: Error];
+}
+/**
+ * The agent that makes a machine part of a deployment. It connects to the
+ * coordinator, starts the worker script for the clusters the coordinator
+ * places here, and relays their IPC frames both ways. The coordinator's
+ * `ClusterManager` supervises those workers exactly like local ones.
+ *
+ * Fencing: when the connection closes, or the coordinator stays silent for a
+ * whole lease, the host kills every worker at once. The coordinator waits
+ * longer than that before it restarts the clusters elsewhere, so a shard is
+ * never owned in two places.
+ */
+export declare class ClusterHost {
+    #private;
+    constructor(options: ClusterHostOptions);
+    /** Whether the coordinator has accepted this host and the link is open. */
+    get connected(): boolean;
+    /** Cluster IDs running on this host. */
+    clusters(): number[];
+    /** Listens for a host event. @returns This host. */
+    on<E extends keyof ClusterHostEvents>(event: E, listener: (...args: ClusterHostEvents[E]) => void): this;
+    /** Stops listening for a host event. @returns This host. */
+    off<E extends keyof ClusterHostEvents>(event: E, listener: (...args: ClusterHostEvents[E]) => void): this;
+    /**
+     * Connects and resolves once the coordinator accepts this host. After
+     * that, a lost connection is retried with backoff until {@link close}.
+     * @throws {Error} If the first attempt is refused (bad secret, unknown or duplicate ID).
+     */
+    connect(): Promise<void>;
+    /** Kills every worker, closes the connection and stops reconnecting. */
+    close(): Promise<void>;
+}

package/dist/sharding/identify.d.ts

@@ -0,0 +1,62 @@
+/** Discord allows one IDENTIFY per rate-limit key every five seconds. */
+export declare const IDENTIFY_INTERVAL = 5000;
+/** What `/gateway/bot` says about the session budget. */
+export interface IdentifyBudget {
+    total: number;
+    remaining: number;
+    /** Milliseconds until `remaining` resets, counted from construction. */
+    resetAfter: number;
+}
+/** Options for an {@link IdentifyCoordinator}. */
+export interface IdentifyCoordinatorOptions {
+    /** Discord's `max_concurrency`: shards with the same `id % maxConcurrency` share a key. Default 1. */
+    maxConcurrency?: number;
+    /** Milliseconds between two IDENTIFYs on one key. Default 5000. */
+    interval?: number;
+    /** The session-start budget, when known. Without it the coordinator paces but never blocks. */
+    budget?: IdentifyBudget;
+    /** A granted slot that is not released within this many ms is released for the holder. Default 60,000. */
+    holdTimeout?: number;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+    /** Timer, injectable for tests. Must return a handle `cancel` understands. */
+    schedule?: (callback: () => void, ms: number) => unknown;
+    cancel?: (handle: unknown) => void;
+    /** Called when a request has to wait for the budget to reset. */
+    onBudgetWait?: (info: {
+        shardId: number;
+        waitMs: number;
+    }) => void;
+}
+/**
+ * Hands out IDENTIFY slots for a whole deployment. Every cluster asks the
+ * parent, so the limit holds across processes: one IDENTIFY per rate-limit key
+ * per interval, and no more IDENTIFYs than `session_start_limit.remaining`.
+ * It only does arithmetic on timestamps and holds one timer, so it can be
+ * tested with a fake clock.
+ */
+export declare class IdentifyCoordinator {
+    #private;
+    readonly maxConcurrency: number;
+    constructor(options?: IdentifyCoordinatorOptions);
+    /** Slots left in the session budget, or `undefined` when it is unknown. */
+    get remaining(): number | undefined;
+    /** Requests waiting for a slot. */
+    get waiting(): number;
+    /** Slots granted and not yet released. */
+    get holding(): number;
+    /**
+     * Waits for the shard's turn. Resolves when the shard may IDENTIFY now;
+     * call {@link release} once it has. Rejects if `owner` is dropped or the
+     * coordinator closes first.
+     */
+    acquire(owner: number, shardId: number): Promise<void>;
+    /** The shard has sent its IDENTIFY: its key rests for one interval. Ignored unless `owner` holds the slot. */
+    release(owner: number, shardId: number): void;
+    /** A cluster is gone: forget its waiting requests and free the slots it held. */
+    drop(owner: number, reason?: string): void;
+    /** Rejects every waiter and stops the timer. */
+    close(): void;
+    /** Grants every slot that is due and arms one timer for the next. Called internally and by tests after moving the clock. */
+    pump(): void;
+}