ClusterBootstrapOptionsType

ClusterBootstrapOptionsType = object

Defined in: src/cluster/ClusterBootstrapOptions.ts:28

Options accepted by Cluster.bootstrap. Everything is optional except name; sensible defaults turn the call into a single-line hello-cluster. Build one with ClusterBootstrapOptions.

Properties

awaitReady?

readonly optional awaitReady?: boolean | number

Defined in: src/cluster/ClusterBootstrapOptions.ts:146

Wait for this node’s SelfUp event before resolving.

• true (default) — wait up to 5 000 ms.
• false / 0 — return immediately.
• a number — wait at most that many ms.

On timeout the returned promise still resolves — the cluster keeps trying in the background. Set a custom value when seed contact is slow (e.g. K8s pod start lag).

---

config?

readonly optional config?: ActorSystemOptionsType["config"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:37

---

configFile?

readonly optional configFile?: ActorSystemOptionsType["configFile"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:38

---

discovery?

readonly optional discovery?: "auto" | "kubernetes" | "dns" | "config" | SeedProvider | { providers: ReadonlyArray<SeedProvider>; }

Defined in: src/cluster/ClusterBootstrapOptions.ts:86

Discovery strategy. Values:

• 'auto' (default) — env-driven autoDiscovery chain.
• 'kubernetes' | 'dns' | 'config' — pin to a single provider, still configured from env vars.
• a SeedProvider instance — use as-is.
• { providers: [...] } — assemble a custom aggregate chain.

Ignored when seeds is set.

---

downing?

readonly optional downing?: ClusterOptionsType["downing"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:126

---

failureDetector?

readonly optional failureDetector?: ClusterOptionsType["failureDetector"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:124

---

gossipIntervalMs?

readonly optional gossipIntervalMs?: ClusterOptionsType["gossipIntervalMs"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:125

---

host?

readonly optional host?: string

Defined in: src/cluster/ClusterBootstrapOptions.ts:58

Bind host. Default resolution order:

1. options.host
2. process.env.POD_IP (Kubernetes)
3. process.env.HOSTNAME
4. '0.0.0.0'

---

logger?

readonly optional logger?: ActorSystemOptionsType["logger"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:35

Optional logger / log level / config overrides — forwarded to ActorSystem.create.

---

logLevel?

readonly optional logLevel?: ActorSystemOptionsType["logLevel"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:36

---

name

readonly name: string

Defined in: src/cluster/ClusterBootstrapOptions.ts:32

ActorSystem name.

---

persistence?

readonly optional persistence?: ActorSystemOptionsType["persistence"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:39

---

port?

readonly optional port?: number

Defined in: src/cluster/ClusterBootstrapOptions.ts:64

Bind port. Default: process.env.CLUSTER_PORT (when present and a finite integer), otherwise 2552.

---

receptionist?

readonly optional receptionist?: boolean

Defined in: src/cluster/ClusterBootstrapOptions.ts:133

Auto-start the Receptionist extension so service-key lookups (Find, Subscribe) work without explicit wiring. Default: true.

---

roles?

readonly optional roles?: ClusterOptionsType["roles"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:123

---

seeds?

readonly optional seeds?: ReadonlyArray<string>

Defined in: src/cluster/ClusterBootstrapOptions.ts:73

Explicit seed list. When set, discovery is ignored and the cluster contacts exactly these addresses.

---

shutdownOnSignals?

readonly optional shutdownOnSignals?: boolean | ReadonlyArray<NodeJS.Signals>

Defined in: src/cluster/ClusterBootstrapOptions.ts:47

Whether the bootstrap helper installs SIGTERM + SIGINT handlers that call the returned shutdown() once. Set to a list of signals to customise, or to false to disable. Default: ['SIGTERM', 'SIGINT'].

---

stableObservation?

readonly optional stableObservation?: boolean | StableObservationTuning

Defined in: src/cluster/ClusterBootstrapOptions.ts:121

Run the stable-observation phase before joining (#148).

• unset / false (default) — resolve the seeds once and join, the v0.9.0 behaviour.
• true — poll discovery until the contact-point set has been unchanged for the stable margin, then let exactly one node (the lowest-addressed) form a cluster if no peer promoted it in time.
• an options object — the same, with the timings overridden. Unset fields fall through to actor-ts.cluster.bootstrap.* and then to the built-in defaults.

Turn it on wherever nodes start simultaneously and discovery is dynamic — a Kubernetes Deployment, an autoscaling group, anything where DNS propagation races pod readiness. It closes the cold-start split brain (each node forming a cluster out of the subset it happened to see) and the symmetric-seed-list deadlock (every node listing every other, so no node has the empty seed list that 'immediate' self-election needs).

It costs at least stableMarginMs of startup latency and requires this node’s advertised host to be a real address rather than a wildcard — the election is ordered on it (see #944).

Works with an explicit seeds list too: discovery is then a fixed set, the margin is satisfied on the second poll, and what remains is the election — which is exactly what a symmetric seed list is missing.

---

transport?

readonly optional transport?: ClusterOptionsType["transport"]

Defined in: src/cluster/ClusterBootstrapOptions.ts:67

Transport override. Default: TcpTransport.