Cluster

Defined in: src/cluster/Cluster.ts:110

The Cluster is a single-instance “extension” attached to an ActorSystem. It owns a Transport, a gossip-based membership view, a failure detector and the plumbing that dispatches inbound envelope messages to local actors.

Properties

selfAddress

readonly selfAddress: NodeAddress

Defined in: src/cluster/Cluster.ts:111

---

selfRoles

readonly selfRoles: ReadonlySet<string>

Defined in: src/cluster/Cluster.ts:112

---

system

readonly system: ActorSystem

Defined in: src/cluster/Cluster.ts:113

---

transport

readonly transport: Transport

Defined in: src/cluster/Cluster.ts:114

Accessors

sharding

Get Signature

get sharding(): ClusterSharding

Defined in: src/cluster/Cluster.ts:315

The cluster’s sharding facade. Lazily constructs (and memoises) a single ClusterSharding instance per ActorSystem so callers can start regions inline:

const region = cluster.sharding.start('cart', CartActor, {
  extractEntityId: (m) => m.entityId,
});

Equivalent to ClusterSharding.get(cluster.system, cluster) — which still works for callers that prefer the explicit form.

Returns

ClusterSharding

---

singleton

Get Signature

get singleton(): ClusterSingleton

Defined in: src/cluster/Cluster.ts:331

The cluster’s singleton facade. Binds the ClusterSingleton extension to this Cluster on first access, so starting one hands back the ref directly:

const scheduler = cluster.singleton.start(JobSchedulerActor);
scheduler.tell({ kind: 'schedule', jobId: '42' });

Equivalent to ClusterSingleton.get(cluster.system, cluster) — which still works for callers that hold the two separately.

Returns

ClusterSingleton

Methods

_onWire()

_onWire(kind, handler): () => void

Defined in: src/cluster/Cluster.ts:504

Register a handler for a specific wire-message discriminator.

Parameters

kind

string

handler

(message, from) => void

Returns

() => void

---

_publishClusterEvent()

_publishClusterEvent(event): void

Defined in: src/cluster/Cluster.ts:480

Publish a cluster event that this Cluster did not produce itself.

Membership events all originate here, but ShardMapChanged is derived from state only the sharding coordinator has, and it has to surface on every node rather than just the leader’s. Rather than let sharding reach into emit, it goes through this door — same listeners, same event stream.

Parameters

event

ClusterEvent

Returns

void

---

_registerEnvelopeHandler()

_registerEnvelopeHandler(path, handler): () => void

Defined in: src/cluster/Cluster.ts:485

Route envelopes addressed to path to handler. Returns unsubscribe.

Parameters

path

string

handler

EnvelopeHandler

Returns

() => void

---

_sendEnvelope()

_sendEnvelope(to, env): void

Defined in: src/cluster/Cluster.ts:498

Send an envelope to a remote node. Used by RemoteActorRef and by the PubSub / Singleton extensions. Any ActorRef embedded in the user payload is rewritten to a WireActorRef marker here — this is the single chokepoint where every cross-node message leaves, so hooking the encode step once covers all paths (sharding, pub-sub, singleton, direct remote-ref). Receiving nodes decode in onEnvelope.

Parameters

to

NodeAddress

env

EnvelopeMessage

Returns

void

---

_setEnvelopeHandler()

_setEnvelopeHandler(handler): void

Defined in: src/cluster/Cluster.ts:467

Register a handler for inbound user envelopes. Kept for backward compatibility — prefer _registerEnvelopeHandler(path, handler) which allows multiple extensions (ClusterSharding, DistributedPubSub, …) to share the envelope pipeline.

Parameters

handler

EnvelopeHandler

Returns

void

---

down()

down(addr): boolean

Defined in: src/cluster/Cluster.ts:523

Operator-initiated force-down of a remote peer (#56). Mirrors the private evaluateDowning path: marks the peer down, emits the lifecycle events, tombstones with removedAt so stale gossip can’t resurrect it, and tells the failure detector to forget it.

Returns true if a member was found and downed, false if the address was unknown or already terminal (down/removed).

Intended for operator tooling — the management HTTP endpoint POST /cluster/down calls this directly. Don’t use it as a replacement for the failure detector / downing provider in normal flow; it’s a manual override.

Parameters

addr

string | NodeAddress

Returns

boolean

---

getMembers()

getMembers(): readonly Member[]

Defined in: src/cluster/Cluster.ts:415

Current snapshot of known members. removed entries are kept internally as tombstones (so stale gossip can’t resurrect them via the merge path) but are filtered out here — the public contract is “members the cluster currently considers part of the topology”.

Returns

readonly Member[]

---

isLeader()

isLeader(): boolean

Defined in: src/cluster/Cluster.ts:457

True if this node is currently the leader.

Returns

boolean

---

leader()

leader(): Option<Member>

Defined in: src/cluster/Cluster.ts:451

The cluster leader: the lowest-addressed up-member.

Not the oldest member, which is what this used to claim and what Akka actually does (#525). Address order and join order are unrelated, so a node that joins last leads immediately if its host/port sorts first — and it takes over whatever the leader hosts, including cluster singletons.

The property the leader is for is that every node names the same one from gossip it already has, and address order gives that without a monotonic join sequence in the gossip payload. Worth knowing when you reason about which node ends up leading: it is decided by addressing, not by uptime, so it is stable across restarts of the same pod and unstable across a re-address.

Returns

Option<Member>

---

leave()

leave(): Promise<void>

Defined in: src/cluster/Cluster.ts:545

Gracefully leave the cluster (broadcast leave, stop transport).

Returns

Promise<void>

---

reachableMembers()

reachableMembers(): Member[]

Defined in: src/cluster/Cluster.ts:427

Reachable members (up + joining + leaving).

Returns

Member[]

---

subscribe()

subscribe(listener, options?): () => void

Defined in: src/cluster/Cluster.ts:341

Subscribe to membership events. The listener is immediately replayed the membership that already exists, so a late subscriber still sees the world it joined; options.replayMode chooses the form — see ClusterSubscriptionReplayMode.

Parameters

listener

(event) => void

options?

replayMode?

ClusterSubscriptionReplayMode

Returns

() => void

---

upMembers()

upMembers(): Member[]

Defined in: src/cluster/Cluster.ts:420

Members in the up state, ordered by address — the “active set”.

Returns

Member[]

---

upMembersWithRole()

upMembersWithRole(role): Member[]

Defined in: src/cluster/Cluster.ts:432

Up members that carry the given role tag.

Parameters

role

string

Returns

Member[]

---

bootstrap()

static bootstrap(options): Promise<BootstrappedCluster>

Defined in: src/cluster/Cluster.ts:294

One-call bootstrap — creates the ActorSystem, joins the cluster, starts the Receptionist, waits for SelfUp, and wires SIGTERM/SIGINT shutdown. The headline shape for the clustered case:

const { system, cluster, shutdown } = await Cluster.bootstrap({ name: 'my-app' });

Build the argument with ClusterBootstrapOptions.create(name). For the power-user path (own ActorSystem.create, own Cluster.join, own signal wiring) keep using those directly — this is purely additive sugar.

The helper lives in ClusterBootstrap.ts and is loaded lazily here to avoid a static import cycle (ClusterBootstrap ↔ Cluster.join).

Parameters

options

ClusterBootstrapOptions

Returns

Promise<BootstrappedCluster>

---

join()

static join(system, options): Promise<Cluster>

Defined in: src/cluster/Cluster.ts:253

Entry point: start the cluster and attempt to contact seed nodes.

Also publishes the instance to the ClusterExtension, which is what makes system.cluster, context.cluster and an actor’s this.cluster resolve — so a clustered actor no longer has to have the Cluster threaded in through its constructor (#833).

Registration happens before _start on purpose: startup already emits MemberJoined / SelfUp, and a subscriber woken by SelfUp asking system.cluster must not be told there is none. A failed start puts the previous value back rather than leaving a cluster that never bound its transport reachable system-wide.

Parameters

system

ActorSystem

options

ClusterOptions

Returns

Promise<Cluster>