ClusterManagerOptions
Defined in: packages/sharding/src/cluster.ts:72
Configuration for managing multiple shard clusters.
Properties
Section titled âPropertiesâautoScaleInterval?
Section titled âautoScaleInterval?â
optionalautoScaleInterval?:number
Defined in: packages/sharding/src/cluster.ts:184
Interval in milliseconds to automatically check for recommended shard count and re-scale if needed.
clusterCount?
Section titled âclusterCount?â
optionalclusterCount?: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.
fetchLimits?
Section titled âfetchLimits?â
optionalfetchLimits?:boolean
Defined in: packages/sharding/src/cluster.ts:106
Ask /gateway/bot for max_concurrency and the session budget even with a fixed shardCount.
optionalfork?: (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.
Parameters
Section titled âParametersâstring
Record<string, string | undefined>
Returns
Section titled âReturnsâChildProcess
guildCount?
Section titled âguildCount?â
optionalguildCount?:number
Defined in: packages/sharding/src/cluster.ts:89
The botâs guild count for guildsPerShard, instead of asking Discord for it.
guildsPerShard?
Section titled âguildsPerShard?â
optionalguildsPerShard?: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.
identify?
Section titled âidentify?â
optionalidentify?:object
Defined in: packages/sharding/src/cluster.ts:119
IDENTIFY coordination across clusters. On by default.
coordinate?
Section titled âcoordinate?â
optionalcoordinate?:boolean
Set false to let every cluster pace its own IDENTIFYs.
holdTimeout?
Section titled âholdTimeout?â
optionalholdTimeout?:number
A slot a worker never releases is released after this many ms. Default 60,000.
interval?
Section titled âinterval?â
optionalinterval?:number
Milliseconds between IDENTIFYs on one key. Default 5000.
leader?
Section titled âleader?â
optionalleader?: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
optionalttl?:number
Lock lifetime in ms. Default 10,000; at least 100.
maxConcurrency?
Section titled âmaxConcurrency?â
optionalmaxConcurrency?: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.
maxMessageBytes?
Section titled âmaxMessageBytes?â
optionalmaxMessageBytes?: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.
maxPendingRequests?
Section titled âmaxPendingRequests?â
optionalmaxPendingRequests?:number
Defined in: packages/sharding/src/cluster.ts:155
Most requests waiting for answers at once. Default 10,000.
onAutoScaleError?
Section titled âonAutoScaleError?â
optionalonAutoScaleError?: (error) =>void
Defined in: packages/sharding/src/cluster.ts:186
Optional handler invoked when a background auto-scale check fails. Receives the thrown error.
Parameters
Section titled âParametersâError
Returns
Section titled âReturnsâvoid
reassignOnGiveUp?
Section titled âreassignOnGiveUp?â
optionalreassignOnGiveUp?: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.
remote?
Section titled âremote?â
optionalremote?: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.
requestTimeout?
Section titled ârequestTimeout?â
optionalrequestTimeout?:number
Defined in: packages/sharding/src/cluster.ts:153
Default timeout for request(), requestCluster() and broadcast(). Default 5000.
restartDelay?
Section titled ârestartDelay?â
optionalrestartDelay?:number
Defined in: packages/sharding/src/cluster.ts:196
Delay in milliseconds before re-forking a crashed cluster. Defaults to 5000.
restartOnExit?
Section titled ârestartOnExit?â
optionalrestartOnExit?: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.
shardCount?
Section titled âshardCount?â
optionalshardCount?:number|"auto"
Defined in: packages/sharding/src/cluster.ts:78
Total number of shards. Use âautoâ to request Discordâs recommended count.
shardIds?
Section titled âshardIds?â
optionalshardIds?: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.
shardsPerCluster?
Section titled âshardsPerCluster?â
optionalshardsPerCluster?:number
Defined in: packages/sharding/src/cluster.ts:99
Shards per cluster; the cluster count follows. Not combinable with clusterCount.
shutdownTimeout?
Section titled âshutdownTimeout?â
optionalshutdownTimeout?: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.
spawnInterval?
Section titled âspawnInterval?â
optionalspawnInterval?: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.
startTimeout?
Section titled âstartTimeout?â
optionalstartTimeout?: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.
startup?
Section titled âstartup?â
optionalstartup?:"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) everyidentify.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 (oridentify.holdTimeoutpasses; workers wait that long for READY), then the next shard waits the interval. Slow, for debugging and small bots. Needs IDENTIFY coordination.
supervisor?
Section titled âsupervisor?â
optionalsupervisor?: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.
Type Declaration
Section titled âType DeclarationârestartDelay?
Section titled ârestartDelay?â
optionalrestartDelay?:number
token:
string
Defined in: packages/sharding/src/cluster.ts:74
Discord bot token.
waitForReady?
Section titled âwaitForReady?â
optionalwaitForReady?:boolean
Defined in: packages/sharding/src/cluster.ts:136
Make spawn() wait until every cluster reported ready. Default false.
Methods
Section titled âMethodsâonClusterExit()?
Section titled âonClusterExit()?â
optionalonClusterExit(cluster,code,signal):void
Defined in: packages/sharding/src/cluster.ts:208
Called whenever a cluster process exits, before any restart.
Parameters
Section titled âParametersâcluster
Section titled âclusterânumber | null
Signals | null
Returns
Section titled âReturnsâvoid
onGiveUp()?
Section titled âonGiveUp()?â
optionalonGiveUp(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.
Parameters
Section titled âParametersâcluster
Section titled âclusterâReturns
Section titled âReturnsâvoid