Skip to content

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).

new ClusterManager(options): ClusterManager

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

Creates a cluster manager.

ClusterManagerOptions

Clustering configuration.

ClusterManager

If token or script is missing.

If a numeric option is invalid.

readonly clusters: 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: number = 0

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

Total number of shards in the deployment.

get isLeader(): boolean

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

Whether this coordinator holds the leader lock; always true without leader.

boolean


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).

number | undefined

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.

ReadonlyMap<number, number>


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.

R = unknown

T = unknown

string

T

RequestOptions = {}

Promise<BroadcastResult<R>>


checkAutoScale(): Promise<void>

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

Checks if the recommended shard count has changed and respawns if so.

Promise<void>


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.

number

ClusterInfo | undefined


fetchRecommendedShardCount(): Promise<number>

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

Retrieves Discord’s recommended shard count.

Promise<number>

Recommended shard count.

If discovery fails or returns invalid data.


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.

ClusterManagerHealth


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.

HostStatus[]


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.

void


off<E>(event, listener): this

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

Stops listening for a deployment event.

E extends keyof ClusterManagerEvents

E

(…args) => void

this

This manager.


on<E>(event, listener): this

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

Listens for a deployment event.

E extends keyof ClusterManagerEvents

E

(…args) => void

this

This manager.


ready(timeoutMs?): Promise<void>

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

Resolves when every cluster is ready.

number

Promise<void>

On timeout, or if the manager stops first.


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).

boolean

number

Promise<ClusterManagerHealth>


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.

R = unknown

T = unknown

number

string

T

RequestOptions = {}

Promise<R>

If the shard is not part of this deployment.

If its cluster is down, the handler failed, or no answer arrives in time.


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()).

R = unknown

T = unknown

number

string

T

RequestOptions = {}

Promise<R>

If the cluster is unknown or down, the handler failed, or no answer arrives in time.


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.

number

The new total shard count.

Promise<void>


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.

number = ...

Grace period per child before force-kill. Defaults to the configured shutdownTimeout (5000 ms).

Promise<void>


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.

Promise<void>

If called from a cluster worker (a worker must not start the fleet again).