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_concurrencykeys 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
Section titled “Import”import { ShardManager } from "@lunibee/sharding";// also re-exported:import { ShardManager, GatewayIntentBits } from "lunibee";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.
Quick start
Section titled “Quick start”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.
Constructor
Section titled “Constructor”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:
TypeErrorfor a missing or blanktoken, orintentsthat is not an array;RangeErrorfor ashardCountthat is not a positive integer, aguildsPerShardoutside 1–2500 or used withoutshardCount: "auto", invalid or duplicateshardIds(checked now with a fixed count, atconnect()with"auto"), anautoScaleIntervalthat is not an integer of at least 1000, a negative or non-finitespawnDelay, amaxConcurrencythat is not a positive integer, a negativehandshakeTimeout, or areadyTimeoutthat is not a positive number;- inside a cluster worker,
RangeErrorforshardCount: "auto", ashardCountthat differs from the cluster’s, orshardIdsthat are not a subset of the cluster’s shards, andTypeErrorforautoScaleInterval(auto-scaling belongs toClusterManagerthere).
With a number for shardCount, the Gateways are created in the constructor. With "auto", they are created by the first connect().
Properties
Section titled “Properties”| 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. |
Methods
Section titled “Methods”connect()
Section titled “connect()”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/botwas read (with"auto", or afterfetchGatewayInfo()) 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 ascause. Withreconnect: truea Gateway keeps retrying instead of rejecting, so this is mostly seen withreconnect: falseor a refused IDENTIFY slot. - With
shardCount: "auto", starts theautoScaleIntervaltimer. Callingconnect()again replaces that timer instead of adding one.
await manager.connect();destroy()
Section titled “destroy()”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();addShards(shardIds)
Section titled “addShards(shardIds)”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
RangeErrorif 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]);reshard(count)
Section titled “reshard(count)”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.
checkAutoScale()
Section titled “checkAutoScale()”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.
fetchRecommendedShardCount()
Section titled “fetchRecommendedShardCount()”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();fetchGatewayInfo()
Section titled “fetchGatewayInfo()”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);getShardIdForGuild(guildId)
Section titled “getShardIdForGuild(guildId)”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 });get(id)
Section titled “get(id)”The Gateway of shard id, or undefined.
values()
Section titled “values()”A ShardInfo[] snapshot of the owned shards:
interface ShardInfo { id: number; // shard ID gateway: Gateway; // its connection}health()
Section titled “health()”A ShardHealth entry per owned shard.
report(metrics?)
Section titled “report(metrics?)”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.
on(event, listener), off(event, listener)
Section titled “on(event, listener), off(event, listener)”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.
Events
Section titled “Events”| 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.
Shard count
Section titled “Shard count”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();Helpers
Section titled “Helpers”All exported from @lunibee/sharding and lunibee.
fetchGatewayBot(token)
Section titled “fetchGatewayBot(token)”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.
fetchGuildCount(token)
Section titled “fetchGuildCount(token)”GET /applications/@me and returns approximate_guild_count. Throws for a non-2xx answer or a missing or invalid count.
shardsForGuilds(guilds, guildsPerShard)
Section titled “shardsForGuilds(guilds, guildsPerShard)”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); // 1shardsForGuilds(2501, 1000); // 3MAX_GUILDS_PER_SHARD
Section titled “MAX_GUILDS_PER_SHARD”2500.
IDENTIFY pacing
Section titled “IDENTIFY pacing”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)”- The concurrency is
maxConcurrency, else Discord’smax_concurrencyif/gateway/botwas read, else 1. An override is capped at Discord’s value when that is known. - 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. - Before the next round, the manager waits for every shard of this round to send IDENTIFY or RESUME (up to
handshakeTimeout), then waitsspawnDelay. The interval is measured from the handshake, not from the socket opening, so a slow HELLO cannot squeeze two IDENTIFYs on one key together. - If the remembered session budget has fewer IDENTIFYs left than shards to start,
connect()throwsSession 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.
An IDENTIFY gate
Section titled “An IDENTIFY gate”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.
IdentifyCoordinator
Section titled “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.
Inside a cluster worker
Section titled “Inside a cluster worker”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), withshardCountset to the deployment total (SHARD_COUNT); - uses this process’s
ClusterWorker(ClusterWorker.current()) to answer the parent’s health requests withreport()and its shard-assignment requests withaddShards(); - when the parent coordinates IDENTIFY (
LUNIBEE_IDENTIFY=coordinated, the default), takes every IDENTIFY slot from the parent throughClusterWorker.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)istruewhenLUNIBEE_CLUSTER_WORKERis"1".readClusterContext(env = process.env)returnsnulloutside a worker, and throwsRangeErrorwhen the variables are present but malformed (not non-negative integers, or shard IDs outsideSHARD_COUNTor repeated).
ClusterWorker, allocateShards(), validateShardIds() and the parent side are documented in ClusterManager.
Health
Section titled “Health”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 }).
ShardSupervisor
Section titled “ShardSupervisor”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]Shutdown
Section titled “Shutdown”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.