Skip to content

ShardManager

ShardManager (from @lunibee/sharding) runs several Gateway connections, one per shard, in one process. It:

  • works out the shard count (fixed, Discord’s recommendation, or sized by guild count);
  • starts shards without breaking Discord’s IDENTIFY limits (one per rate-limit key every 5 s, max_concurrency keys at once, and the daily session budget);
  • reports shard lifecycle events and per-shard health;
  • inside a worker forked by ClusterManager, owns only that cluster’s shards, takes IDENTIFY slots from the parent and reports readiness and health to it.

Sharding is required once a bot is in 2,500 guilds. Below that, use Client. For several processes or machines, see ClusterManager; for messages between shards, see ShardBus; for the concepts, see Sharding.

import { ShardManager } from "@lunibee/sharding";
// also re-exported:
import { ShardManager, GatewayIntentBits } from "lunibee";

The examples below are TypeScript; the JavaScript is the same without type annotations.

import { ShardManager, GatewayIntentBits } from "lunibee";
const manager = new ShardManager({
token: process.env.DISCORD_TOKEN!,
intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages],
shardCount: 4,
});
// With a fixed shard count the Gateways exist now, so dispatch listeners
// can be attached before anything connects.
for (const { id, gateway } of manager.values()) {
gateway.on("MESSAGE_CREATE", (message) => handleMessage(id, message));
}
manager.on("shardReady", (id) => console.log(`shard ${id} ready`));
manager.on("shardError", (id, error) => console.error(`shard ${id}`, error));
manager.on("ready", () => console.log("all shards ready"));
await manager.connect();
process.on("SIGINT", () => {
manager.destroy();
process.exit(0);
});

ShardManager gives you raw Gateways: dispatches are d payloads, the same as with a bare Gateway. Its own events (below) are about shard lifecycle only.

new ShardManager(options: ShardManagerOptions)
Option Type Default Description
token string — Bot token. Required.
intents GatewayIntentResolvable — Required. An array of GatewayIntentBits, used by every shard.
shardCount number | "auto" 1 Total shards in the deployment. "auto" asks Discord when connect() runs. Inside a cluster worker it defaults to the cluster’s count. See Shard count.
guildsPerShard number — With shardCount: "auto" only, a sizing hint: at least ceil(guilds / guildsPerShard) shards, and never fewer than Discord recommends. An integer from 1 to 2500. It never decides which shard owns a guild.
guildCount number asked from Discord The guild count for guildsPerShard, so no extra request is made. A non-negative integer.
shardIds number[] every shard, or the cluster’s own list The shards this manager runs, out of shardCount. Unique integers in [0, shardCount).
reconnect boolean true Passed to every Gateway: reconnect automatically after a close that is not fatal.
spawnDelay number 5000 Milliseconds between startup rounds when pacing locally. 0 drops the handshake wait and the delay, so each round starts as soon as the previous round’s sockets are open. See IDENTIFY pacing.
maxConcurrency number Discord’s max_concurrency if known, else 1 Shards per startup round when pacing locally. Capped at Discord’s value when it is known.
startup (0.4.0) "safe" | "sequential" "safe", or the cluster’s "sequential" starts one shard at a time: each waits for the previous one’s READY (up to readyTimeout; a shardError says when it timed out) and then spawnDelay. In a cluster worker it follows ClusterManager’s startup, and the slot from the parent is held until READY.
readyTimeout (0.4.0) number 60000, or the cluster’s Sequential startup: ms a shard may take to become READY before the next one starts. A positive number. In a cluster worker it defaults to the parent’s identify.holdTimeout.
handshakeTimeout number 15000 How long a startup round waits for its shards to send IDENTIFY or RESUME before the next spawnDelay starts, in ms. With an IDENTIFY gate, how long a shard holds its slot waiting for the handshake.
autoScaleInterval number — With shardCount: "auto": re-check the shard count this often, in ms, and reshard when it changes. An integer of at least 1000. With a fixed count no timer is started.
onAutoScaleError (error: unknown) => void — Called when a background auto-scale check fails.
cluster ClusterContext | false read from the environment The worker contract. false ignores it; a ClusterContext overrides it. See Inside a cluster worker.
identify IdentifyGate | false the parent, inside a coordinated cluster Where IDENTIFY slots come from. false paces locally with spawnDelay.
worker ClusterWorker | false this process’s ClusterWorker inside a cluster The worker that answers the parent’s health and shard-assignment requests and is told when the shards are ready.

The constructor throws:

  • TypeError for a missing or blank token, or intents that is not an array;
  • RangeError for a shardCount that is not a positive integer, a guildsPerShard outside 1–2500 or used without shardCount: "auto", invalid or duplicate shardIds (checked now with a fixed count, at connect() with "auto"), an autoScaleInterval that is not an integer of at least 1000, a negative or non-finite spawnDelay, a maxConcurrency that is not a positive integer, a negative handshakeTimeout, or a readyTimeout that is not a positive number;
  • inside a cluster worker, RangeError for shardCount: "auto", a shardCount that differs from the cluster’s, or shardIds that are not a subset of the cluster’s shards, and TypeError for autoScaleInterval (auto-scaling belongs to ClusterManager there).

With a number for shardCount, the Gateways are created in the constructor. With "auto", they are created by the first connect().

Property Type Description
shards Map<number, Gateway> The shards this manager owns, by shard ID.
shardCount number Total shards in the deployment (Discord’s num_shards) once the shard set exists; 0 before that and after destroy().
shardIds number[] IDs of the owned shards, ascending.
ShardManager.IDENTIFY_INTERVAL number (static) 5000, Discord’s minimum interval between IDENTIFYs on one rate-limit key.

Creates the shard set if it does not exist yet (resolving "auto" first; a destroyed manager is rebuilt), then connects every shard that has no live socket. Returns when every started shard’s socket is open; listen for ready (or shardReady) to know when sessions are identified.

  • Shards that already have a live socket are left alone and do not count against the session budget.
  • Without an IDENTIFY gate, shards start in rounds paced by spawnDelay. With a gate, every shard waits for its slot. See IDENTIFY pacing.
  • When /gateway/bot was read (with "auto", or after fetchGatewayInfo()) and the session budget has fewer IDENTIFYs left than shards to start, it throws before starting any and leaves running shards alone.
  • If a shard fails to connect, it destroys the whole shard set and throws Error("Failed to connect shard N.") with the shard’s error as cause. With reconnect: true a Gateway keeps retrying instead of rejecting, so this is mostly seen with reconnect: false or a refused IDENTIFY slot.
  • With shardCount: "auto", starts the autoScaleInterval timer. Calling connect() again replaces that timer instead of adding one.
await manager.connect();

Closes every shard, clears shards, the health records and the auto-scale timer, and sets shardCount to 0. The next connect() builds a new shard set with new Gateway objects, so listeners attached to the old Gateways are not carried over.

manager.destroy();

Takes over more shards of the same deployment and connects them through the same IDENTIFY path as connect(). ClusterManager uses it to move a failed cluster’s shards to a healthy one (reassignOnGiveUp).

  • Throws RangeError if an ID is outside [0, shardCount), listed twice, or already owned.
  • Creates the shard set first if needed.
  • If a new shard fails to connect, only the new shards are closed and removed, and the error is thrown; the shards that were already running keep their sessions.
await manager.addShards([6, 7]);

Sets shardCount to count, destroys every shard and connects again. Every session is closed, so this is a full restart of the shard set, not a rolling one. With shardIds set, those IDs must still fit the new count.

Does nothing unless the manager was created with shardCount: "auto". Otherwise resolves the shard count again (Discord’s recommendation, or guildsPerShard) and calls reshard() when it differs from shardCount. Failures are passed to onAutoScaleError and never thrown. autoScaleInterval calls it on a timer; a manager keeps auto-scaling after a reshard.

Resolves the shard count "auto" would use: Discord’s recommendation from /gateway/bot, or with guildsPerShard, the larger of that and shardsForGuilds(guildCount ?? fetchGuildCount(token), guildsPerShard). Throws if a request fails or Discord’s answer is unusable.

const count = await manager.fetchRecommendedShardCount();

Reads GET /gateway/bot and remembers the answer: the recommended shard count, and sessionStartLimit (total, remaining, resetAfter, maxConcurrency) when Discord sent one. The next connect() uses it for maxConcurrency and the session-budget check. Returns a GatewayBotInfo.

const info = await manager.fetchGatewayInfo();
console.log(info.shards, info.sessionStartLimit?.remaining);

The shard that receives a guild’s events, by Discord’s formula (guildId >> 22) % shardCount:

const shardId = manager.getShardIdForGuild("175928847299117063");

It keeps using the last shard count after destroy() and during a reshard, so a guild maps to the same shard until the new set exists. It does not check that this manager owns that shard; manager.get(shardId) is undefined when it does not.

sendVoiceState(guildId, channelId, options?)

Section titled “sendVoiceState(guildId, channelId, options?)”

Sends a voice state update (opcode 4) on the shard that owns the guild. options is { selfMute?, selfDeaf? }; channelId: null leaves the channel. Returns false when that shard is not owned here or is not connected.

manager.sendVoiceState(guildId, voiceChannelId, { selfDeaf: true });

The Gateway of shard id, or undefined.

A ShardInfo[] snapshot of the owned shards:

interface ShardInfo {
id: number; // shard ID
gateway: Gateway; // its connection
}

A ShardHealth entry per owned shard.

A WorkerReport for a cluster parent: health() plus reportedAt, and with metrics: true the process’s memory and CPU numbers. A cluster worker answers the parent’s health requests with it.

Add or remove a listener for one of the events. Both return the manager. An exception thrown by a listener is caught and dropped, so it cannot disturb a shard.

Event Arguments When
shardReady shardId: number The shard received READY.
shardResume shardId: number The shard resumed its session (RESUMED).
shardDisconnect shardId: number, close: { code: number; action: string } The shard’s socket closed. action is "resume", "identify" or "stop"; the Gateway may reconnect by itself. See close codes.
shardError shardId: number, error: Error The shard’s Gateway emitted error.
shardUnstable shardId: number, info: { reconnects: number; delay: number } The shard reconnected too often too fast and is backing off (the Gateway’s unstable event).
shardCreate shardId: number, gateway: Gateway A shard’s Gateway was created and has not connected yet. Attach dispatch listeners here; fires again for new Gateways after destroy() + connect() or reshard().
ready — Every owned shard is ready. Emitted again each time all shards are ready after one dropped (disconnected or became unstable).
manager.on("shardDisconnect", (id, { code, action }) => {
console.warn(`shard ${id} closed with ${code}, next: ${action}`);
});

Inside a cluster worker, ready also tells the parent that the cluster is ready and pushes a health report to it.

shardCount Result
a number That many shards.
omitted 1, or the cluster’s count inside a worker.
"auto" Discord’s recommendation from GET /gateway/bot, read by the first connect().
"auto" with guildsPerShard max(recommended, ceil(guilds / guildsPerShard)), where guilds is guildCount or approximate_guild_count from GET /applications/@me. A stale or low guild count can only add shards, never drop below Discord’s recommendation (0.4.0).

Discord assigns guilds to shards by their ID, so guildsPerShard sets the average per shard, not an exact split. Discord’s hard limit is 2,500 guilds per shard and it recommends about 1,000.

const manager = new ShardManager({
token,
intents: [GatewayIntentBits.Guilds],
shardCount: "auto",
guildsPerShard: 1000,
autoScaleInterval: 6 * 60 * 60 * 1000, // re-check every 6 hours
onAutoScaleError: (error) => console.error("auto-scale failed", error),
});

With "auto", the Gateways do not exist until connect() creates them. Attach dispatch listeners in shardCreate, which fires for each new Gateway before it connects, so no event is missed. It also fires for the new Gateways after destroy() + connect() or reshard():

const manager = new ShardManager({ token, intents, shardCount: "auto" });
manager.on("shardCreate", (shardId, gateway) => gateway.on("GUILD_CREATE", onGuild));
await manager.connect();

All exported from @lunibee/sharding and lunibee.

GET /gateway/bot. Returns:

interface GatewayBotInfo {
shards: number; // recommended shard count
sessionStartLimit?: { // only when Discord sent all four fields
total: number;
remaining: number;
resetAfter: number; // ms until `remaining` resets
maxConcurrency: number; // at least 1
};
}

Throws Error("Gateway discovery failed with status N") for a non-2xx answer and an error for a shard count that is not a positive integer.

GET /applications/@me and returns approximate_guild_count. Throws for a non-2xx answer or a missing or invalid count.

Math.max(1, Math.ceil(guilds / guildsPerShard)). Throws RangeError unless guildsPerShard is an integer from 1 to 2500 and guilds a non-negative integer.

shardsForGuilds(0, 1000); // 1
shardsForGuilds(2501, 1000); // 3

2500.

Discord allows one IDENTIFY per rate-limit key every 5 seconds. The key is shardId % max_concurrency, so a bot with max_concurrency 16 can identify 16 shards at once, one per key. On top of that, session_start_limit caps how many IDENTIFYs a bot may send per day. Going over either gets close code 4008 or invalid sessions.

ShardManager paces in one of two ways.

Local pacing (the default outside a coordinated cluster)

Section titled “Local pacing (the default outside a coordinated cluster)”
  1. The concurrency is maxConcurrency, else Discord’s max_concurrency if /gateway/bot was read, else 1. An override is capped at Discord’s value when that is known.
  2. Shards to start are put in buckets by id % concurrency. Round n starts the n-th shard of every bucket together, so a round never puts two shards on one key.
  3. Before the next round, the manager waits for every shard of this round to send IDENTIFY or RESUME (up to handshakeTimeout), then waits spawnDelay. The interval is measured from the handshake, not from the socket opening, so a slow HELLO cannot squeeze two IDENTIFYs on one key together.
  4. If the remembered session budget has fewer IDENTIFYs left than shards to start, connect() throws Session start limit exhausted: … before starting any.

With concurrency 1 and the defaults, N shards take about (N − 1) × (handshake + 5 s) to start. spawnDelay: 0 removes the wait between rounds; use it only when something else paces the handshakes.

The budget check uses the answer remembered from the last /gateway/bot read, counted down by one for each shard this manager starts (so addShards() after connect() checks against what is left). Call fetchGatewayInfo() to replace it with Discord’s current value. Without a read (a fixed shardCount and no fetchGatewayInfo()), there is no budget check.

With an identify gate, every shard to start calls gate.acquire(shardId) in parallel, connects once it resolves, waits for its IDENTIFY or RESUME to be sent (up to handshakeTimeout), then calls gate.release(shardId). The gate decides the spacing; spawnDelay, maxConcurrency and the local budget check are not used.

interface IdentifyGate {
acquire(shardId: number): Promise<void>; // resolves when the shard may IDENTIFY now
release(shardId: number): void; // the shard has sent its IDENTIFY
}

Inside a coordinated cluster the gate is the parent ClusterManager (see below). Outside one you can pass your own, for example backed by a lock shared between processes, or by an IdentifyCoordinator.

The scheduler ClusterManager runs in the parent to hand out IDENTIFY slots to every cluster. It can be used on its own.

new IdentifyCoordinator(options?: IdentifyCoordinatorOptions)
Option Type Default Description
maxConcurrency number 1 Discord’s max_concurrency. Shards with the same id % maxConcurrency share a key. A positive integer.
interval number 5000 (IDENTIFY_INTERVAL) Milliseconds between two IDENTIFYs on one key, counted from the release. Not negative.
budget IdentifyBudget — The session budget. Without it the coordinator paces but never blocks on a budget.
holdTimeout number 60000 A granted slot that is not released within this many ms is released for its holder. Above 0.
onBudgetWait (info: { shardId: number; waitMs: number }) => void — Called when the next request on a key has to wait for the budget to reset. Can be called more than once for the same wait.
now, schedule, cancel functions Date.now, setTimeout (unref’d), clearTimeout Clock and timer, for tests.
interface IdentifyBudget {
total: number; // session_start_limit.total
remaining: number; // session_start_limit.remaining
resetAfter: number; // ms until `remaining` resets, counted from construction
period?: number; // ms between later resets; default 24 h
}

The constructor throws RangeError for a maxConcurrency that is not a positive integer, a negative interval, a holdTimeout of 0 or less, or a budget.period of 0 or less.

Member Description
acquire(owner, shardId) Waits for the shard’s turn on key shardId % maxConcurrency. Resolves when it may IDENTIFY now. Rejects if owner is dropped or the coordinator closes first. owner is any number identifying the requester (a cluster ID in ClusterManager).
release(owner, shardId) The shard has sent its IDENTIFY: its key rests for interval. Ignored unless that owner and shard hold the slot.
drop(owner, reason?) Rejects the owner’s waiting requests and frees the slots it holds.
close() Rejects every waiter, stops the timer and refuses new requests.
pump() Grants every slot that is due and arms one timer for the next. Called internally; tests call it after moving the clock.
maxConcurrency The concurrency in use.
remaining IDENTIFYs left in the budget, or undefined without one.
waiting Requests waiting for a slot.
holding Slots granted and not released yet.

Each grant takes one from remaining. At 0, requests wait until the reset time, when remaining is set back to total and the next reset is one period later, so a later exhaustion also waits instead of failing.

Using one as the gate of a single-process ShardManager, so an exhausted budget waits for the reset instead of throwing:

import { IdentifyCoordinator, ShardManager, fetchGatewayBot } from "lunibee";
const info = await fetchGatewayBot(token);
const limit = info.sessionStartLimit;
const coordinator = new IdentifyCoordinator({
maxConcurrency: limit?.maxConcurrency ?? 1,
...(limit && {
budget: { total: limit.total, remaining: limit.remaining, resetAfter: limit.resetAfter },
}),
onBudgetWait: ({ shardId, waitMs }) =>
console.warn(`shard ${shardId} waits ${Math.ceil(waitMs / 1000)}s for the session budget`),
});
const manager = new ShardManager({
token,
intents,
shardCount: info.shards,
identify: {
acquire: (shardId) => coordinator.acquire(0, shardId),
release: (shardId) => coordinator.release(0, shardId),
},
});
await manager.connect();

IDENTIFY_INTERVAL (5000) is exported as a constant as well as ShardManager.IDENTIFY_INTERVAL.

A process forked by ClusterManager gets the worker contract in its environment. ShardManager reads it with readClusterContext() unless cluster: false is passed, and then:

  • runs only the cluster’s shards (SHARD_LIST), with shardCount set to the deployment total (SHARD_COUNT);
  • uses this process’s ClusterWorker (ClusterWorker.current()) to answer the parent’s health requests with report() and its shard-assignment requests with addShards();
  • when the parent coordinates IDENTIFY (LUNIBEE_IDENTIFY=coordinated, the default), takes every IDENTIFY slot from the parent through ClusterWorker.identifyGate, so the limits hold across all clusters;
  • on ready, tells the parent the cluster is ready (ClusterWorker.ready()) and pushes a health report.

The worker script needs no sharding options:

import { ShardManager, ShardBus, GatewayIntentBits } from "lunibee";
const manager = new ShardManager({
token: process.env.DISCORD_TOKEN!,
intents: [GatewayIntentBits.Guilds],
});
for (const id of manager.shardIds)
new ShardBus(id, "my-bot").respond("guildCount", () => countGuilds(id));
await manager.connect();

shardCount: "auto" and autoScaleInterval are refused in a worker: the parent decides the shard count. shardIds may narrow the cluster’s list but not go outside it.

Overrides:

Option Effect
cluster: false Ignore the environment: behave like a standalone manager. No worker and no gate are attached unless passed.
cluster: context Use this ClusterContext instead of the environment. ClusterWorker.current() is not attached automatically; pass worker (and the gate follows context.coordinatedIdentify).
worker: false Do not answer the parent or report readiness. Without a worker there is also no coordinated gate.
identify: false Pace locally with spawnDelay instead of asking the parent.

ClusterContext, readClusterContext(), isClusterWorker()

Section titled “ClusterContext, readClusterContext(), isClusterWorker()”
interface ClusterContext {
clusterId: number; // CLUSTER_ID
clusterCount: number; // CLUSTER_COUNT
shardCount: number; // SHARD_COUNT, the deployment total
shardIds: number[]; // SHARD_LIST, comma separated
coordinatedIdentify: boolean; // LUNIBEE_IDENTIFY === "coordinated"
}
  • isClusterWorker(env = process.env) is true when LUNIBEE_CLUSTER_WORKER is "1".
  • readClusterContext(env = process.env) returns null outside a worker, and throws RangeError when the variables are present but malformed (not non-negative integers, or shard IDs outside SHARD_COUNT or repeated).

ClusterWorker, allocateShards(), validateShardIds() and the parent side are documented in ClusterManager.

health() returns one ShardHealth per owned shard:

interface ShardHealth {
id: number;
state: GatewayState; // the Gateway's connection state
ping: number; // last heartbeat round trip in ms, -1 before the first ACK
status: ShardStatus; // lifecycle, see below
readyAt?: number; // epoch ms the shard last became ready
disconnectedAt?: number; // epoch ms its socket last closed
}
ShardStatus Meaning
"idle" Created, never started.
"connecting" Started by connect()/addShards(), or waiting for its IDENTIFY slot.
"ready" READY or RESUMED received; events are flowing.
"disconnected" The socket closed; the Gateway may be reconnecting by itself.
"unstable" The Gateway reported repeated reconnects and is backing off.
"destroyed" Set by destroy(). Because destroy() also removes the shards, health() returns an empty list afterwards rather than "destroyed" entries.

state is the socket-level GatewayState; status is the shard’s lifecycle as the manager sees it.

for (const shard of manager.health())
console.log(shard.id, shard.status, shard.state, `${shard.ping}ms`);

report(metrics?) wraps it for a cluster parent:

interface WorkerReport {
shards: ShardHealth[];
metrics?: WorkerMetrics; // only with report(true)
reportedAt: number; // epoch ms
}
interface WorkerMetrics {
rssBytes: number; // process.memoryUsage().rss
heapUsedBytes: number; // process.memoryUsage().heapUsed
cpuUserMicros: number; // process.cpuUsage().user
cpuSystemMicros: number; // process.cpuUsage().system
}

The parent asks for metrics with ClusterManager.refreshHealth({ metrics: true }).

The restart policy ClusterManager uses for crashed clusters. It only does arithmetic on timestamps; it does not fork, kill or emit anything. ClusterManager builds one from its restartDelay and supervisor options and reports the outcome as its clusterRestart, clusterUnstable and clusterGiveUp events (see ClusterManager).

new ShardSupervisor(options?: SupervisorOptions, random?: () => number)
Option Type Default Description
restartDelay number 5000 Delay before the first restart, in ms. Not negative.
backoff number 1 Each further crash inside window multiplies the delay by this. At least 1; 1 is a fixed delay.
maxDelay number 300000 (5 min) Cap on the delay before jitter. Not negative.
jitter number 0 Random spread added to each delay, as a fraction of it, from 0 to 1.
maxRestarts number Infinity Give up after this many restarts inside window. Not negative.
window number 60000 The span over which restarts are counted, in ms; older crashes are forgotten. Above 0.

Invalid values throw RangeError. random defaults to Math.random; inject it for tests.

Method Description
next(id, now = Date.now()) Records a crash of cluster id. Returns the delay before restarting it, or null to give up because it already restarted maxRestarts times inside window. Giving up clears its history.
reset(id?) Forgets one cluster’s crashes, or every cluster’s.

The delay for the n-th crash inside the window is min(maxDelay, round(min(maxDelay, restartDelay × backoff^(n−1)) × (1 + jitter × random()))): jitter spreads the delay, and maxDelay stays the longest wait.

const supervisor = new ShardSupervisor(
{ restartDelay: 100, backoff: 2, maxDelay: 350, jitter: 0.5 },
() => 1,
);
[0, 1, 2, 3].map((t) => supervisor.next(7, t)); // [150, 300, 350, 350]

destroy() closes every Gateway and clears the auto-scale timer; nothing else keeps the process alive. Inside a cluster worker, the parent stops the process with SIGTERM (then SIGKILL after its shutdownTimeout), so close the shards on SIGTERM:

process.on("SIGTERM", () => {
manager.destroy();
process.exit(0);
});

A ClusterWorker exits the process by itself when the parent’s IPC channel closes, so an orphaned worker does not keep its sessions running beside a replacement.