ClusterManager
Defined in: packages/sharding/src/cluster.ts:345
Orchestrates cluster processes: forks one worker per cluster, gives each a fixed set of shards, restarts crashed clusters with backoff, hands out IDENTIFY slots across all of them, routes shard-bus messages to the cluster that owns the target shard, and answers requests, broadcasts and health queries for the whole deployment.
Ownership: the ClusterManager decides which cluster owns which shard and
keeps processes alive; the ShardManager inside each worker runs those
shards’ Gateways. A shard is never owned by two clusters at once.
Works under Node.js and Bun (child_process.fork() with IPC).
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new ClusterManager(
options):ClusterManager
Defined in: packages/sharding/src/cluster.ts:401
Creates a cluster manager.
Parameters
Section titled “Parameters”options
Section titled “options”Clustering configuration.
Returns
Section titled “Returns”ClusterManager
Throws
Section titled “Throws”If token or script is missing.
Throws
Section titled “Throws”If a numeric option is invalid.
Properties
Section titled “Properties”clusters
Section titled “clusters”
readonlyclusters:Map<number,ClusterInfo>
Defined in: packages/sharding/src/cluster.ts:347
Live clusters (starting or ready) indexed by cluster ID. A crashed cluster leaves this map until it is restarted.
shardCount
Section titled “shardCount”shardCount:
number=0
Defined in: packages/sharding/src/cluster.ts:349
Total number of shards in the deployment.
Accessors
Section titled “Accessors”isLeader
Section titled “isLeader”Get Signature
Section titled “Get Signature”get isLeader():
boolean
Defined in: packages/sharding/src/cluster.ts:715
Whether this coordinator holds the leader lock; always true without leader.
Returns
Section titled “Returns”boolean
remotePort
Section titled “remotePort”Get Signature
Section titled “Get Signature”get remotePort():
number|undefined
Defined in: packages/sharding/src/cluster.ts:863
The port hosts connect to, once the listener is open (useful with remote.port: 0).
Returns
Section titled “Returns”number | undefined
Methods
Section titled “Methods”assignments()
Section titled “assignments()”assignments():
ReadonlyMap<number,number>
Defined in: packages/sharding/src/cluster.ts:544
Which cluster owns each shard. A copy: change ownership through recovery, not by writing to it.
Returns
Section titled “Returns”ReadonlyMap<number, number>
broadcast()
Section titled “broadcast()”broadcast<
R,T>(type,data,options?):Promise<BroadcastResult<R>>
Defined in: packages/sharding/src/cluster.ts:1526
Asks every shard of every live cluster and collects the answers. Shards
whose cluster is down, or that do not answer in time, are listed in
missing; it does not reject for them.
Type Parameters
Section titled “Type Parameters”R = unknown
T = unknown
Parameters
Section titled “Parameters”string
T
options?
Section titled “options?”RequestOptions = {}
Returns
Section titled “Returns”Promise<BroadcastResult<R>>
checkAutoScale()
Section titled “checkAutoScale()”checkAutoScale():
Promise<void>
Defined in: packages/sharding/src/cluster.ts:1773
Checks if the recommended shard count has changed and respawns if so.
Returns
Section titled “Returns”Promise<void>
clusterForShard()
Section titled “clusterForShard()”clusterForShard(
shardId):ClusterInfo|undefined
Defined in: packages/sharding/src/cluster.ts:538
The cluster that owns a shard, or undefined when the shard is not part of this deployment.
Parameters
Section titled “Parameters”shardId
Section titled “shardId”number
Returns
Section titled “Returns”ClusterInfo | undefined
fetchRecommendedShardCount()
Section titled “fetchRecommendedShardCount()”fetchRecommendedShardCount():
Promise<number>
Defined in: packages/sharding/src/cluster.ts:529
Retrieves Discord’s recommended shard count.
Returns
Section titled “Returns”Promise<number>
Recommended shard count.
Throws
Section titled “Throws”If discovery fails or returns invalid data.
health()
Section titled “health()”health():
ClusterManagerHealth
Defined in: packages/sharding/src/cluster.ts:1691
The last known health of every cluster and shard. Reads what the workers last reported; nothing is sent. Use refreshHealth for fresh numbers.
Returns
Section titled “Returns”hosts()
Section titled “hosts()”hosts():
HostStatus[]
Defined in: packages/sharding/src/cluster.ts:868
The hosts of this deployment: connected or not, and the clusters on each. Empty without remote.
Returns
Section titled “Returns”killAll()
Section titled “killAll()”killAll():
void
Defined in: packages/sharding/src/cluster.ts:1901
Immediately sends SIGTERM to every cluster process (no grace period, no SIGKILL escalation) and clears the cluster map. Prefer shutdownAll for a graceful stop.
Returns
Section titled “Returns”void
off<
E>(event,listener):this
Defined in: packages/sharding/src/cluster.ts:508
Stops listening for a deployment event.
Type Parameters
Section titled “Type Parameters”E extends keyof ClusterManagerEvents
Parameters
Section titled “Parameters”E
listener
Section titled “listener”(…args) => void
Returns
Section titled “Returns”this
This manager.
on<
E>(event,listener):this
Defined in: packages/sharding/src/cluster.ts:497
Listens for a deployment event.
Type Parameters
Section titled “Type Parameters”E extends keyof ClusterManagerEvents
Parameters
Section titled “Parameters”E
listener
Section titled “listener”(…args) => void
Returns
Section titled “Returns”this
This manager.
ready()
Section titled “ready()”ready(
timeoutMs?):Promise<void>
Defined in: packages/sharding/src/cluster.ts:1617
Resolves when every cluster is ready.
Parameters
Section titled “Parameters”timeoutMs?
Section titled “timeoutMs?”number
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”On timeout, or if the manager stops first.
refreshHealth()
Section titled “refreshHealth()”refreshHealth(
options?):Promise<ClusterManagerHealth>
Defined in: packages/sharding/src/cluster.ts:1752
Asks every live cluster for a fresh report, then returns health. A cluster that does not answer in time keeps its last report; it is not treated as failed (only its process exiting does that).
Parameters
Section titled “Parameters”options?
Section titled “options?”metrics?
Section titled “metrics?”boolean
timeoutMs?
Section titled “timeoutMs?”number
Returns
Section titled “Returns”Promise<ClusterManagerHealth>
request()
Section titled “request()”request<
R,T>(shardId,type,data,options?):Promise<R>
Defined in: packages/sharding/src/cluster.ts:1477
Sends a request to one shard and resolves with its handler’s result.
Type Parameters
Section titled “Type Parameters”R = unknown
T = unknown
Parameters
Section titled “Parameters”shardId
Section titled “shardId”number
string
T
options?
Section titled “options?”RequestOptions = {}
Returns
Section titled “Returns”Promise<R>
Throws
Section titled “Throws”If the shard is not part of this deployment.
Throws
Section titled “Throws”If its cluster is down, the handler failed, or no answer arrives in time.
requestCluster()
Section titled “requestCluster()”requestCluster<
R,T>(clusterId,type,data,options?):Promise<R>
Defined in: packages/sharding/src/cluster.ts:1581
Sends a request to a cluster’s worker (see ClusterWorker.onRequest()).
Type Parameters
Section titled “Type Parameters”R = unknown
T = unknown
Parameters
Section titled “Parameters”clusterId
Section titled “clusterId”number
string
T
options?
Section titled “options?”RequestOptions = {}
Returns
Section titled “Returns”Promise<R>
Throws
Section titled “Throws”If the cluster is unknown or down, the handler failed, or no answer arrives in time.
respawn()
Section titled “respawn()”respawn(
newShardCount):Promise<void>
Defined in: packages/sharding/src/cluster.ts:1790
Gracefully shuts the existing clusters down and respawns them with the new shard count.
Parameters
Section titled “Parameters”newShardCount
Section titled “newShardCount”number
The new total shard count.
Returns
Section titled “Returns”Promise<void>
shutdownAll()
Section titled “shutdownAll()”shutdownAll(
timeoutMs?):Promise<void>
Defined in: packages/sharding/src/cluster.ts:1805
Gracefully stops all active clusters: sends SIGTERM, awaits each child’s clean exit, and force-kills (SIGKILL) only children that outlast the shutdown timeout. Safe to call twice or concurrently; cancels restarts, timers and pending requests.
Parameters
Section titled “Parameters”timeoutMs?
Section titled “timeoutMs?”number = ...
Grace period per child before force-kill. Defaults to the configured shutdownTimeout (5000 ms).
Returns
Section titled “Returns”Promise<void>
spawn()
Section titled “spawn()”spawn():
Promise<void>
Defined in: packages/sharding/src/cluster.ts:553
Spawns all clusters. Calling it again while clusters run, or while the first call is still starting them, returns the same promise.
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”If called from a cluster worker (a worker must not start the fleet again).