lunibee 0.3.3 → 0.4.0

package/dist/rest/limiter.d.ts

@@ -10,6 +10,8 @@ export interface Grant {
     known: boolean;
     /** The window the unit came from (store clock), when the store reports it. */
     resetAt?: number;
+    /** The bucket key the unit came from, when `acquire` moved to another one (see `resolve`). */
+    key?: string;
 }
 /** Context for {@link RateLimiter.applyResponse} beyond the response itself. */
 export interface ApplyResponseOptions {
@@ -75,8 +77,14 @@ export declare class RateLimiter {
      * @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?: {
+    acquire(initialKey: string, signal: AbortSignal | undefined, path: string, options?: {
         global?: string;
+        /**
+         * Resolves the request's bucket key again. Called after waiting on
+         * another worker's probe: its response may have revealed the shared
+         * bucket, whose key differs from the route-derived one.
+         */
+        resolve?: () => Promise<string>;
     }): Promise<Grant>;
     /**
      * Extends the global limit (of `scope`), never shortening a longer one

package/dist/rest/webhook.d.ts

@@ -1,12 +1,12 @@
 import { type RESTFileAttachment } from "./index.js";
-import type { AllowedMentions, APIEmbed, APIMessage, APIMessageComponent } from "@lunibee/types";
+import type { AllowedMentions, APIEmbed, APIMessage, APIMessageComponent } from "../types/index.js";
 /** Where a `WebhookClient` sends: a Discord webhook `url`, or its `id` and `token`. */
 export interface WebhookClientOptions {
     id?: string;
     token?: string;
     url?: string;
 }
-/** A webhook message for `send()` and `editMessage()`; camelCase aliases (`avatarURL`, `threadId`, `allowedMentions`) are accepted beside the wire names. */
+/** A webhook message for `send()` and `editMessage()`, in Discord's wire names. */
 export interface WebhookMessageOptions {
     content?: string;
     username?: string;
@@ -22,12 +22,6 @@ export interface WebhookMessageOptions {
     files?: RESTFileAttachment[];
     flags?: number;
     thread_id?: string;
-    /** Discord.js-familiar alias of `avatar_url`. */
-    avatarURL?: string;
-    /** Discord.js-familiar alias of `thread_id`. */
-    threadId?: string;
-    /** Discord.js-familiar alias of `allowed_mentions`. */
-    allowedMentions?: AllowedMentions;
     allowed_mentions?: AllowedMentions;
 }
 /** Standalone client for sending Discord webhooks. */

package/dist/sharding/bus.d.ts

@@ -66,8 +66,8 @@ export declare class ShardBus {
     broadcast<T>(type: string, data: T): string;
     /**
      * Registers a handler that answers requests of `type`. Its return value (or
-     * thrown error) is sent back to the requesting shard. Discord.js-familiar
-     * replacement for `broadcastEval` that never evaluates received code.
+     * thrown error) is sent back to the requesting shard. Received code is
+     * never evaluated.
      * @returns This bus.
      */
     respond<T, R>(type: string, handler: (data: T, message: ShardMessage<T>) => R | Promise<R>): this;

package/dist/sharding/cluster.d.ts

@@ -1,9 +1,28 @@
 import { type ChildProcess } from "node:child_process";
 import { type ShardReply } from "./bus.js";
+import { type ClusterCountSource } from "./context.js";
 import type { ClusterManagerHealth, ClusterState, WorkerReport } from "./health.js";
+import { type IdentifyEvent } from "./identify.js";
 import type { LeaderLock } from "./leader.js";
 import { type HostStatus, type RemoteOptions } from "./remote.js";
 import { type SupervisorOptions } from "./supervisor.js";
+/** What the `plan` event reports. */
+export interface ClusterPlanInfo {
+    /** The deployment's shard count (Discord's `num_shards`), the same in every worker. */
+    totalShards: number;
+    clusterCount: number;
+    /** `"clusterCount"`, `"shardsPerCluster"` or `"default"` (the number of CPUs). */
+    clusterCountSource: ClusterCountSource;
+    /** The count asked for; larger than `clusterCount` when there were more clusters than shards. */
+    requestedClusterCount: number;
+    clusters: {
+        id: number;
+        shards: number[];
+    }[];
+    maxConcurrency: number;
+    startup: "safe" | "sequential";
+    identifyCoordinated: boolean;
+}
 /** Configuration for managing multiple shard clusters. */
 export interface ClusterManagerOptions {
     /** Discord bot token. */
@@ -13,11 +32,12 @@ export interface ClusterManagerOptions {
     /** Total 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.
+     * A sizing hint for `shardCount: "auto"`: run at least
+     * `ceil(guildCount / guildsPerShard)` shards, and never fewer than Discord
+     * recommends. 1 to 2500 (Discord's limit); Discord recommends about 1000.
+     * It only picks the shard count: Discord puts each guild on shard
+     * `(guild_id >> 22) % shardCount`, so shards get about this many guilds,
+     * not exactly, and ownership never follows from it.
      */
     guildsPerShard?: number;
     /** The bot's guild count for `guildsPerShard`, instead of asking Discord for it. */
@@ -39,6 +59,17 @@ export interface ClusterManagerOptions {
     maxConcurrency?: number;
     /** Ask `/gateway/bot` for `max_concurrency` and the session budget even with a fixed `shardCount`. */
     fetchLimits?: boolean;
+    /**
+     * How shards start across the whole deployment.
+     * - `"safe"` (default): as fast as Discord allows. One IDENTIFY per
+     *   rate-limit key (`shard_id % max_concurrency`) every `identify.interval`,
+     *   keys in parallel; a slot is freed as soon as the IDENTIFY is sent.
+     * - `"sequential"`: one shard at a time across all clusters, in the order
+     *   they ask (cluster by cluster, as they spawn). Each slot is held until that shard is READY (or
+     *   `identify.holdTimeout` passes; workers wait that long for READY), then the next shard waits the interval.
+     *   Slow, for debugging and small bots. Needs IDENTIFY coordination.
+     */
+    startup?: "safe" | "sequential";
     /** IDENTIFY coordination across clusters. On by default. */
     identify?: {
         /** Set `false` to let every cluster pace its own IDENTIFYs. */
@@ -210,6 +241,15 @@ export interface ClusterManagerEvents {
         shardId: number;
         waitMs: number;
     }];
+    /** The allocation of a start: total shards, the cluster count and where it came from, each cluster's shards. */
+    plan: [plan: ClusterPlanInfo];
+    /** The IDENTIFY queue: a shard asked for a slot, got it, or gave it back. */
+    identify: [event: IdentifyEvent];
+    /** `shutdownAll()` finished: every cluster process has exited (or was killed after the timeout). */
+    shutdown: [info: {
+        clusters: number;
+        durationMs: number;
+    }];
     /** Something went wrong that did not stop the deployment (a bad frame, a failed recovery). */
     error: [error: Error];
 }

package/dist/sharding/context.d.ts

@@ -13,6 +13,14 @@ export interface ClusterContext {
     shardIds: number[];
     /** Whether the parent hands out IDENTIFY slots for this cluster. */
     coordinatedIdentify: boolean;
+    /**
+     * `"sequential"`: hold each IDENTIFY slot until the shard is READY, so the
+     * deployment starts one shard at a time. `"safe"` (default): release it once
+     * the IDENTIFY is sent.
+     */
+    startup?: "safe" | "sequential";
+    /** Sequential startup: ms a shard may take to become READY (`LUNIBEE_READY_TIMEOUT`, the parent's `identify.holdTimeout`). */
+    readyTimeout?: number;
 }
 /** Set to `1` in every process `ClusterManager` forks, so a worker can tell it is one. */
 export declare const WORKER_MARKER = "LUNIBEE_CLUSTER_WORKER";
@@ -21,12 +29,46 @@ export declare function isClusterWorker(env?: Record<string, string | undefined>
 /** 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).
+ * Splits shard IDs across clusters in contiguous blocks, in order. When they do
+ * not divide evenly the first clusters get one more: 10 shards over 3 clusters
+ * are `[0-3] [4-6] [7-9]`. The same input always gives the same output.
+ * @returns One list per cluster (empty ones at the end 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[][];
+/** How {@link planClusters} chose the cluster count. */
+export type ClusterCountSource = "clusterCount" | "shardsPerCluster" | "default";
+/** Options for {@link planClusters}; set `clusterCount` or `shardsPerCluster`, not both. */
+export interface ClusterPlanOptions {
+    /** The deployment's shards, in order. */
+    shardIds: readonly number[];
+    /** Split the shards over this many clusters (Mode A). */
+    clusterCount?: number;
+    /** Fill clusters with this many shards each; the last may have fewer (Mode B). */
+    shardsPerCluster?: number;
+    /** Cluster count when neither is set (Mode C), e.g. the number of CPUs. */
+    defaultClusterCount: number;
+}
+/** The result of {@link planClusters}. */
+export interface ClusterPlan {
+    /** Shards of each cluster, by cluster ID. Never empty: there are at most as many clusters as shards. */
+    clusters: number[][];
+    /** Where the cluster count came from. */
+    source: ClusterCountSource;
+    /** The count asked for, before capping at the number of shards. */
+    requested: number;
+}
+/**
+ * Decides which cluster runs which shard, without starting anything:
+ * - `clusterCount`: every shard, split in contiguous blocks over that many clusters;
+ * - `shardsPerCluster`: `ceil(shards / shardsPerCluster)` clusters of that size, the last one partial;
+ * - neither: `defaultClusterCount` clusters.
+ *
+ * There are never more clusters than shards: a larger count is capped (an
+ * empty cluster would hold a process for nothing). Every shard is in exactly one cluster.
+ * @throws {RangeError} For both options at once, or a count that is not a positive integer.
+ */
+export declare function planClusters(options: ClusterPlanOptions): ClusterPlan;
 /**
  * Proves an allocation covers `expected` exactly once.
  * @throws {Error} Naming the missing, duplicate or unexpected shard IDs.

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

@@ -30,7 +30,8 @@ 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).
+ * what Discord reports), but never fewer than the recommendation: a stale or
+ * low guild count must not leave shards over Discord's 2,500-guild limit.
  */
 export declare function resolveShardCount(token: string, info: GatewayBotInfo, options: {
     guildsPerShard?: number;

package/dist/sharding/health.d.ts

@@ -1,4 +1,4 @@
-import type { Gateway } from "@lunibee/ws";
+import type { Gateway } from "../ws/index.js";
 /** Where a shard is in its life, apart from the state of its Gateway socket. */
 export type ShardStatus = 
 /** Created, never connected. */

package/dist/sharding/identify.d.ts

@@ -29,6 +29,18 @@ export interface IdentifyCoordinatorOptions {
         shardId: number;
         waitMs: number;
     }) => void;
+    /** Called for every queue change, for logs and metrics. */
+    onEvent?: (event: IdentifyEvent) => void;
+}
+/** One change in the IDENTIFY queue. `bucket` is the rate-limit key, `shardId % maxConcurrency`. */
+export interface IdentifyEvent {
+    type: "queued" | "granted" | "released" | "expired" | "dropped";
+    /** The cluster that asked. */
+    owner: number;
+    shardId: number;
+    bucket: number;
+    /** `granted`: how long the request waited. */
+    waitedMs?: number;
 }
 /**
  * Hands out IDENTIFY slots for a whole deployment. Every cluster asks the

package/dist/sharding/index.d.ts

@@ -1,5 +1,5 @@
 import { type GatewayBotInfo } from "./gateway-bot.js";
-import { Gateway } from "@lunibee/ws";
+import { Gateway } from "../ws/index.js";
 import { type ClusterContext } from "./context.js";
 import type { ShardHealth, WorkerReport } from "./health.js";
 import { ClusterWorker, type IdentifyGate } from "./worker.js";
@@ -9,17 +9,38 @@ export { BroadcastChannelTransport, IpcTransport, type IpcEndpoint, type ShardBu
 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, ClusterManagerEvents, ClusterInfo, BroadcastResult, RequestOptions, } from "./cluster.js";
-export { allocateShards, assertCompleteAllocation, isClusterWorker, readClusterContext, validateShardIds, type ClusterContext, } from "./context.js";
+export type { ClusterManagerOptions, ClusterManagerEvents, ClusterInfo, BroadcastResult, RequestOptions, ClusterPlanInfo, } from "./cluster.js";
+export { allocateShards, planClusters, type ClusterPlan, type ClusterPlanOptions, type ClusterCountSource, assertCompleteAllocation, isClusterWorker, readClusterContext, validateShardIds, type ClusterContext, } from "./context.js";
 export { ClusterWorker, type IdentifyGate } from "./worker.js";
 export { threadEndpoint, threadFork, type ThreadEndpoint, type ThreadForkOptions, } from "./thread.js";
 export { ClusterHost, type ClusterHostEvents, type ClusterHostOptions, } from "./host.js";
 export type { HostStatus, RemoteOptions } from "./remote.js";
 export { RedisLeaderLock, type LeaderLock, type LeaderRedisClient, type RedisLeaderLockOptions, } from "./leader.js";
 export { RemoteClose, REMOTE_PROTOCOL_VERSION } from "./remote-protocol.js";
-export { IdentifyCoordinator, IDENTIFY_INTERVAL, type IdentifyBudget, type IdentifyCoordinatorOptions, } from "./identify.js";
+export { IdentifyCoordinator, IDENTIFY_INTERVAL, type IdentifyBudget, type IdentifyCoordinatorOptions, type IdentifyEvent, } from "./identify.js";
 export { RequestTracker } from "./requests.js";
 export type { ClusterHealth, ClusterManagerHealth, ClusterState, ShardHealth, ShardStatus, WorkerMetrics, WorkerReport, } from "./health.js";
+/** How long sequential startup waits for a shard's READY before moving on, by default. */
+export declare const SEQUENTIAL_READY_TIMEOUT = 60000;
+/** An IDENTIFY slot source: a cluster worker's `identifyGate`. */
+export interface IdentifySlotGate {
+    acquire(shardId: number): Promise<void>;
+    release(shardId: number): void;
+}
+/**
+ * Connects one shard inside the IDENTIFY queue: takes a slot, connects, and
+ * gives the slot back once the IDENTIFY is sent, or, with `waitForReady`
+ * (sequential startup), once the shard is READY. The slot is always released,
+ * also when connecting fails.
+ * @returns Whether the shard became READY in time (`true` without `waitForReady`).
+ */
+export declare function connectInQueue(gateway: Gateway, shardId: number, gate: IdentifySlotGate, options?: {
+    handshakeTimeout?: number;
+    waitForReady?: boolean;
+    readyTimeout?: number;
+    /** Checked after the slot is granted: true skips connecting (a stale start). */
+    cancelled?: () => boolean;
+}): Promise<boolean>;
 /** Configuration for a sharded Gateway client. */
 export interface ShardManagerOptions {
     /** Bot token. */
@@ -29,11 +50,12 @@ export interface ShardManagerOptions {
     /** 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.
+     * A sizing hint for `shardCount: "auto"`: run at least
+     * `ceil(guildCount / guildsPerShard)` shards, and never fewer than Discord
+     * recommends. 1 to 2500 (Discord's limit); Discord recommends about 1000.
+     * It only picks the shard count: Discord puts each guild on shard
+     * `(guild_id >> 22) % shardCount`, so shards get about this many guilds,
+     * not exactly, and ownership never follows from it.
      */
     guildsPerShard?: number;
     /** The bot's guild count for `guildsPerShard`, instead of asking Discord for it. */
@@ -54,6 +76,19 @@ export interface ShardManagerOptions {
      * How long a startup round waits for its shards to send IDENTIFY/RESUME
      * before the next round's `spawnDelay` starts. Defaults to 15000 ms.
      */ handshakeTimeout?: number;
+    /**
+     * `"safe"` (default): start shards as fast as Discord's IDENTIFY limits
+     * allow. `"sequential"`: one shard at a time, each waiting for the previous
+     * one's READY (up to `readyTimeout`) and then `spawnDelay`. In a cluster
+     * worker this follows the `ClusterManager`'s `startup` option.
+     */
+    startup?: "safe" | "sequential";
+    /**
+     * Sequential startup: how long a shard may take to become READY before the
+     * next one starts (a `shardError` reports it), in ms. Default 60000; in a
+     * cluster worker, the parent's `identify.holdTimeout`.
+     */
+    readyTimeout?: number;
     /** Interval in milliseconds to automatically check for recommended shard count and re-scale if needed. Must be an integer >= 1000. */
     autoScaleInterval?: number;
     /** Optional handler invoked when a background auto-scale check fails. Receives the thrown error. */
@@ -166,5 +201,3 @@ export declare class ShardManager {
     /** Returns information for all managed shards. @returns Shard information snapshots. */
     values(): ShardInfo[];
 }
-/** Discord.js-familiar alias for {@link ShardManager}. */
-export { ShardManager as ShardingManager };