Cluster

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

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:135

---

selfRoles

readonly selfRoles: ReadonlySet<string>

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

---

system

readonly system: ActorSystem

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

---

transport

readonly transport: Transport

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

Accessors

sharding

Get Signature

get sharding(): ClusterSharding

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

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

Methods

_onWire()

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

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

Register a handler for a specific wire-message discriminator.

Parameters

kind

string

handler

(msg, from) => void

Returns

() => void

---

_registerEnvelopeHandler()

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

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

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:337

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

Parameters

to

NodeAddress

env

EnvelopeMsg

Returns

void

---

_setEnvelopeHandler()

_setEnvelopeHandler(handler): void

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

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:362

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:281

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:309

True if this node is currently the leader.

Returns

boolean

---

leader()

leader(): Option<Member>

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

The oldest up-member is the cluster leader (deterministic across nodes).

Returns

Option<Member>

---

leave()

leave(): Promise<void>

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

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

Returns

Promise<void>

---

reachableMembers()

reachableMembers(): Member[]

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

Reachable members (up + joining + leaving).

Returns

Member[]

---

subscribe()

subscribe(listener): () => void

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

Subscribe to membership events. The listener is immediately replayed the current cluster state as a series of Member/SelfUp events so that late subscribers still see the world they joined.

Parameters

listener

(event) => void

Returns

() => void

---

upMembers()

upMembers(): Member[]

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

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

Returns

Member[]

---

upMembersWithRole()

upMembersWithRole(role): Member[]

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

Up members that carry the given role tag.

Parameters

role

string

Returns

Member[]

---

bootstrap()

static bootstrap(opts): Promise<BootstrappedCluster>

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

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' });

For full configuration knobs see ClusterBootstrapOptions. 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

opts

ClusterBootstrapOptions

Returns

Promise<BootstrappedCluster>

---

join()

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

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

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

Parameters

system

ActorSystem

settings

ClusterSettings

Returns

Promise<Cluster>