lunibee 0.3.0 → 0.3.2

package/dist/sharding/identify.d.ts

@@ -0,0 +1,64 @@
+/** 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;
+    /** Milliseconds between resets after that one. Discord resets the budget every 24 hours (the default). */
+    period?: 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;
+}

package/dist/sharding/index.d.ts

@@ -1,12 +1,23 @@
 import { type GatewayBotInfo } from "./gateway-bot.js";
 import { Gateway } from "@lunibee/ws";
-export { fetchGatewayBot, type GatewayBotInfo } from "./gateway-bot.js";
+import { type ClusterContext } from "./context.js";
+import type { ShardHealth, WorkerReport } from "./health.js";
+import { ClusterWorker, type IdentifyGate } from "./worker.js";
+export { MAX_GUILDS_PER_SHARD, fetchGatewayBot, fetchGuildCount, shardsForGuilds, type GatewayBotInfo, } from "./gateway-bot.js";
 export { ShardBus } from "./bus.js";
 export { BroadcastChannelTransport, IpcTransport, type IpcEndpoint, type ShardBusTransport, } from "./transport.js";
 export { ShardSupervisor, type SupervisorOptions } from "./supervisor.js";
 export type { ShardBusErrorHandler, ShardBusOptions, ShardMessage, ShardMessageHandler, ShardReply, } from "./bus.js";
 export { ClusterManager } from "./cluster.js";
-export type { ClusterManagerOptions, ClusterInfo } from "./cluster.js";
+export type { ClusterManagerOptions, ClusterManagerEvents, ClusterInfo, BroadcastResult, RequestOptions, } from "./cluster.js";
+export { allocateShards, assertCompleteAllocation, isClusterWorker, readClusterContext, validateShardIds, type ClusterContext, } from "./context.js";
+export { ClusterWorker, type IdentifyGate } from "./worker.js";
+export { ClusterHost, type ClusterHostEvents, type ClusterHostOptions, } from "./host.js";
+export type { HostStatus, RemoteOptions } from "./remote.js";
+export { RemoteClose, REMOTE_PROTOCOL_VERSION } from "./remote-protocol.js";
+export { IdentifyCoordinator, IDENTIFY_INTERVAL, type IdentifyBudget, type IdentifyCoordinatorOptions, } from "./identify.js";
+export { RequestTracker } from "./requests.js";
+export type { ClusterHealth, ClusterManagerHealth, ClusterState, ShardHealth, ShardStatus, WorkerMetrics, WorkerReport, } from "./health.js";
 /** Configuration for a sharded Gateway client. */
 export interface ShardManagerOptions {
     /** Bot token. */
@@ -15,6 +26,16 @@ export interface ShardManagerOptions {
     intents: ConstructorParameters<typeof Gateway>[0]["intents"];
     /** Number of shards. Use `"auto"` to request Discord's recommended count. */
     shardCount?: number | "auto";
+    /**
+     * 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;
     /** Gateway reconnect behavior. */
     reconnect?: boolean;
     /**
@@ -35,14 +56,25 @@ export interface ShardManagerOptions {
     autoScaleInterval?: number;
     /** Optional handler invoked when a background auto-scale check fails. Receives the thrown error. */
     onAutoScaleError?: (error: unknown) => void;
-}
-/** 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;
+    /**
+     * The shards this manager runs, out of `shardCount`. Defaults to all of
+     * them, or to the cluster's own list inside a worker forked by
+     * `ClusterManager`. Must be unique integers in `[0, shardCount)`.
+     */
+    shardIds?: number[];
+    /**
+     * The worker contract. Read from the environment inside a worker forked by
+     * `ClusterManager`; pass `false` to ignore it, or a context to override it.
+     */
+    cluster?: ClusterContext | false;
+    /**
+     * Where to get IDENTIFY slots. Inside a coordinated cluster this is the
+     * parent, so the limit holds across all clusters. Pass `false` to pace
+     * locally with `spawnDelay` instead.
+     */
+    identify?: IdentifyGate | false;
+    /** The worker to report to. Defaults to this process's `ClusterWorker` inside a cluster. */
+    worker?: ClusterWorker | false;
 }
 /** What `ShardManager` emits about its shards. */
 export interface ShardManagerEvents {
@@ -57,6 +89,14 @@ export interface ShardManagerEvents {
     shardResume: [shardId: number];
     /** A shard reported an error. */
     shardError: [shardId: number, error: Error];
+    /** Every shard this manager owns is ready. Emitted again after a shard drops and recovers. */
+    ready: [];
+    /**
+     * A shard's `Gateway` was created and has not connected yet: attach dispatch
+     * listeners here so none of its events are missed. Fires again for the new
+     * Gateways after `destroy()` + `connect()` or `reshard()`.
+     */
+    shardCreate: [shardId: number, gateway: Gateway];
     /** A shard reconnected too often too fast and is backing off (see `Gateway` `unstable`). */
     shardUnstable: [
         shardId: number,
@@ -80,8 +120,10 @@ export declare class ShardManager {
     static readonly IDENTIFY_INTERVAL = 5000;
     /** Active Gateway shards indexed by shard identifier. */
     readonly shards: Map<number, Gateway>;
-    /** Number of shards managed by this instance after initialization. */
+    /** Total shards in the deployment once initialized, 0 before and after `destroy()`. */
     get shardCount(): number;
+    /** IDs of the shards this manager owns. */
+    get shardIds(): number[];
     /** Creates a shard manager. @param options Sharding configuration. @throws {TypeError} If token or intents are invalid. @throws {RangeError} If shard count is invalid. */
     constructor(options: ShardManagerOptions);
     /** Retrieves Discord's recommended shard count. @returns Recommended shard count. @throws {Error} If discovery fails or returns invalid data. */
@@ -90,6 +132,12 @@ export declare class ShardManager {
     fetchGatewayInfo(): Promise<GatewayBotInfo>;
     /** Connects all shards sequentially. A destroyed manager is reinitialized before connecting. @returns A promise fulfilled after all shards connect. @throws {Error} If a shard fails to connect. */
     connect(): Promise<void>;
+    /**
+     * Takes over more shards of the same deployment (recovery after another
+     * cluster gave up) and connects them through the same IDENTIFY path.
+     * @throws {RangeError} If an ID is invalid, already owned, or the manager is not initialized.
+     */
+    addShards(shardIds: readonly number[]): Promise<void>;
     /** Checks if the recommended shard count has changed and reconnects if so. */
     checkAutoScale(): Promise<void>;
     /** Forces a reshard to a new shard count, replacing all active shards. @param count New shard count. */
@@ -109,8 +157,10 @@ export declare class ShardManager {
     }): boolean;
     /** Gets a shard by ID. @param id Shard identifier. @returns Gateway instance or undefined. */
     get(id: number): Gateway | undefined;
-    /** Returns each shard's connection state and heartbeat latency. */
+    /** Returns each shard's connection state, lifecycle status and heartbeat latency. */
     health(): ShardHealth[];
+    /** A health report for the parent: shard health and, on request, process metrics. */
+    report(metrics?: boolean): WorkerReport;
     /** Returns information for all managed shards. @returns Shard information snapshots. */
     values(): ShardInfo[];
 }