Skip to content

ClusterManagerOptions

Defined in: packages/sharding/src/cluster.ts:72

Configuration for managing multiple shard clusters.

optional autoScaleInterval?: number

Defined in: packages/sharding/src/cluster.ts:184

Interval in milliseconds to automatically check for recommended shard count and re-scale if needed.


optional clusterCount?: number

Defined in: packages/sharding/src/cluster.ts:97

Number of clusters to spawn. Defaults to the number of logical CPUs. Not combinable with shardsPerCluster.


optional fetchLimits?: boolean

Defined in: packages/sharding/src/cluster.ts:106

Ask /gateway/bot for max_concurrency and the session budget even with a fixed shardCount.


optional fork?: (script, env) => ChildProcess

Defined in: packages/sharding/src/cluster.ts:179

Starts a worker process. Defaults to child_process.fork(); replace it for tests or custom launchers.

string

Record<string, string | undefined>

ChildProcess


optional guildCount?: number

Defined in: packages/sharding/src/cluster.ts:89

The bot’s guild count for guildsPerShard, instead of asking Discord for it.


optional guildsPerShard?: number

Defined in: packages/sharding/src/cluster.ts:87

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.


optional identify?: object

Defined in: packages/sharding/src/cluster.ts:119

IDENTIFY coordination across clusters. On by default.

optional coordinate?: boolean

Set false to let every cluster pace its own IDENTIFYs.

optional holdTimeout?: number

A slot a worker never releases is released after this many ms. Default 60,000.

optional interval?: number

Milliseconds between IDENTIFYs on one key. Default 5000.


optional leader?: object

Defined in: packages/sharding/src/cluster.ts:173

Run several coordinators of one deployment, one active at a time, so a standby takes over when the active one dies (RedisLeaderLock, or your own LeaderLock). spawn() waits until this coordinator holds the lock. The leader renews it every quarter of ttl; if it cannot for half of ttl (or another holds it) it kills every cluster at once, closes the host listener, and waits to lead again. A new leader waits two remote.leases before it starts clusters, so the previous leader’s hosts have fenced themselves. Point hosts at every coordinator (ClusterHost url as a list).

lock: LeaderLock

optional ttl?: number

Lock lifetime in ms. Default 10,000; at least 100.


optional maxConcurrency?: number

Defined in: packages/sharding/src/cluster.ts:104

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.


optional maxMessageBytes?: number

Defined in: packages/sharding/src/cluster.ts:151

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.


optional maxPendingRequests?: number

Defined in: packages/sharding/src/cluster.ts:155

Most requests waiting for answers at once. Default 10,000.


optional onAutoScaleError?: (error) => void

Defined in: packages/sharding/src/cluster.ts:186

Optional handler invoked when a background auto-scale check fails. Receives the thrown error.

Error

void


optional reassignOnGiveUp?: boolean

Defined in: packages/sharding/src/cluster.ts:142

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.


optional remote?: RemoteOptions

Defined in: packages/sharding/src/cluster.ts:161

Accept hosts on other machines. The coordinator listens for ClusterHost agents, places clusters on them and supervises those workers like local ones. See RemoteOptions.


optional requestTimeout?: number

Defined in: packages/sharding/src/cluster.ts:153

Default timeout for request(), requestCluster() and broadcast(). Default 5000.


optional restartDelay?: number

Defined in: packages/sharding/src/cluster.ts:196

Delay in milliseconds before re-forking a crashed cluster. Defaults to 5000.


optional restartOnExit?: boolean

Defined in: packages/sharding/src/cluster.ts:194

Whether a cluster that exits unexpectedly is re-forked with the same shard assignment. Defaults to true: without it a crashed child leaves its shards permanently offline and nothing reports it.


script: string

Defined in: packages/sharding/src/cluster.ts:76

Path to the worker script to execute for each cluster.


optional shardCount?: number | "auto"

Defined in: packages/sharding/src/cluster.ts:78

Total number of shards. Use “auto” to request Discord’s recommended count.


optional shardIds?: number[]

Defined in: packages/sharding/src/cluster.ts:95

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.


optional shardsPerCluster?: number

Defined in: packages/sharding/src/cluster.ts:99

Shards per cluster; the cluster count follows. Not combinable with clusterCount.


optional shutdownTimeout?: number

Defined in: packages/sharding/src/cluster.ts:188

Grace period in milliseconds to await a cluster’s clean exit after SIGTERM before force-killing. Defaults to 5000.


optional spawnInterval?: number

Defined in: packages/sharding/src/cluster.ts:128

Milliseconds between forking two clusters, to spread the CPU cost of starting. Default 500. IDENTIFY pacing does not depend on it.


optional startTimeout?: number

Defined in: packages/sharding/src/cluster.ts:134

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.


optional startup?: "safe" | "sequential"

Defined in: packages/sharding/src/cluster.ts:117

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.

optional supervisor?: Omit<SupervisorOptions, "restartDelay"> & object

Defined in: packages/sharding/src/cluster.ts:202

Backoff, jitter and a give-up limit for restarts. restartDelay is its first delay unless it sets its own. The default restarts every crash after a fixed delay, as before.

optional restartDelay?: number


token: string

Defined in: packages/sharding/src/cluster.ts:74

Discord bot token.


optional waitForReady?: boolean

Defined in: packages/sharding/src/cluster.ts:136

Make spawn() wait until every cluster reported ready. Default false.

optional onClusterExit(cluster, code, signal): void

Defined in: packages/sharding/src/cluster.ts:208

Called whenever a cluster process exits, before any restart.

ClusterInfo

number | null

Signals | null

void


optional onGiveUp(cluster): void

Defined in: packages/sharding/src/cluster.ts:206

Called when a cluster crashed more often than supervisor.maxRestarts allows and will not be restarted.

ClusterInfo

void