ClusterOptionsType

ClusterOptionsType = object

Defined in: src/cluster/ClusterOptions.ts:106

Plain options-object shape accepted by Cluster.join.

Properties

downing?

readonly optional downing?: DowningProvider

Defined in: src/cluster/ClusterOptions.ts:203

Optional split-brain resolver. When provided, the cluster invokes provider.decide(view) whenever a member transitions to / from unreachable, and force-downs every address in the returned set (regardless of failure-detector state). Without a provider, the cluster relies solely on the failure detector’s elapsed-time unreachable → down → removed cascade — fine for unilateral crashes, weak under network partitions.

See src/cluster/downing/ for the bundled strategies (KeepMajority, KeepOldest, KeepReferee, StaticQuorum, LeaseMajority).

---

failureDetector?

readonly optional failureDetector?: Partial<FailureDetectorOptionsType>

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

Failure detector thresholds.

---

gossipIntervalMs?

readonly optional gossipIntervalMs?: number

Defined in: src/cluster/ClusterOptions.ts:118

How often gossip is pushed to a random reachable peer.

---

host

readonly host: string

Defined in: src/cluster/ClusterOptions.ts:107

---

maxFrameBytes?

readonly optional maxFrameBytes?: number

Defined in: src/cluster/ClusterOptions.ts:214

Per-frame cap on the cluster wire, in bytes. Frames whose length-prefix exceeds it are rejected before any payload is buffered, so it bounds what one peer can make this node hold.

Only applies to the transport the cluster builds for itself — an explicit transport carries its own cap, set where it is constructed. Default: 16 MiB (DEFAULT_MAX_FRAME_BYTES); lower it on a network that crosses a semi-trusted boundary.

---

maxMembers?

readonly optional maxMembers?: number

Defined in: src/cluster/ClusterOptions.ts:233

Cap on live (non-tombstone) entries in the local member map — the addresses gossip is allowed to introduce. 0 disables the cap.

maxFrameBytes bounds one frame; this bounds what a sequence of well-formed frames can accumulate. Membership is filled from unauthenticated gossip, so a peer with standing can name addresses this node has never seen and get an entry allocated for each, with no join involved (#138). Phantom entries in an active status are reclaimed by the failure detector after downAfterMs, which makes this the narrower of the two caps: it bounds the burst, not the residue.

Default: 1000 — far above any cluster this framework is built for, and far below the ~110 000 entries at which this node’s own gossip frame outgrows maxFrameBytes and its peers start dropping the connection. Lower it where the legitimate node count is known: a cap set far above real usage bounds very little.

---

maxTombstones?

readonly optional maxTombstones?: number

Defined in: src/cluster/ClusterOptions.ts:250

Cap on removed tombstones in the local member map. 0 disables it.

The load-bearing half of the pair. A tombstone carries no liveness, so the failure detector never reclaims it — only tombstoneTtlMs does, a day later. A peer that gossips removed records for addresses this node has never seen therefore parks entries here for 24 h, which is the only variant of #138 that actually accumulates.

Refusing one costs nothing: a tombstone for an address with no local record suppresses nothing that exists. Locally-minted tombstones (leave, a downing decision, down()) convert an entry that is already present and are never subject to the cap.

Default: 10 000.

---

maxVersionSkewMs?

readonly optional maxVersionSkewMs?: number

Defined in: src/cluster/ClusterOptions.ts:172

How far ahead of the local clock a gossiped member version may be — the single cap on the merge path, whether the record introduces an address or updates one already on file.

It bounds how far into the future an unauthenticated peer can pre-date a claim. Without it such a squat out-versions the real node’s own record, and the leader promotes the phantom into the active set carrying the attacker’s roles — which is what routing, sharding placement, singleton hosting and downing quorums are computed from (#114).

It applies to every merge because the narrower reading — “only where an address is introduced” — could be stepped around by introducing the address first: two records for it in one frame, or an empty frame that makes the sender fallback file it. See Cluster.admitsVersion.

Default: 5 min — comfortably above any NTP-disciplined clock. A refusal is not exclusion (the sender fallback still records the address, at version 1 without roles), but it is durable: a node whose clock runs further ahead than this stays role-less until its clock comes back. Raise it for a deployment whose clocks are known to run loose.

---

port

readonly port: number

Defined in: src/cluster/ClusterOptions.ts:108

---

roles?

readonly optional roles?: string[]

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

Role tags exposed to other members — used to constrain sharding placement.

---

seedRetryIntervalMs?

readonly optional seedRetryIntervalMs?: number

Defined in: src/cluster/ClusterOptions.ts:120

How often to resend the initial join gossip to seeds until self is Up.

---

seeds?

readonly optional seeds?: string[]

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

Other nodes this node should try to contact on startup.

---

selfElection?

readonly optional selfElection?: SelfElectionPolicy

Defined in: src/cluster/ClusterOptions.ts:190

When this node may declare itself the first member of a new cluster — see SelfElectionPolicy. Default: 'immediate'.

Deliberately absent from ClusterConfigDefaults: it is per-node identity, not tuning, exactly like seeds and roles. A HOCON leaf would be applied to every node of a deployment identically, and both uniform answers are wrong — all-'never' never starts a cluster, and all-<delay> has every node self-elect at the same moment, which is the split brain this option exists to close.

---

tombstoneMinRetentionMs?

readonly optional tombstoneMinRetentionMs?: number

Defined in: src/cluster/ClusterOptions.ts:149

Minimum age before a tombstone is eligible for pruning, regardless of tombstoneTtlMs. Defaults to 6 × downAfterMs, which gives a few failure-detector rounds of breathing room so peers that haven’t fully converged still see the tombstone before it vanishes. Mostly relevant for tests that set a very low TTL.

0 means the same thing as leaving it unset — derive the floor from the failure detector — rather than “no floor at all”. The distinction matters because the HOCON leaf ships with 0s as its documented default, and a config file that spells a default out must behave like one that omits it (#841).

---

tombstonePruneIntervalMs?

readonly optional tombstonePruneIntervalMs?: number

Defined in: src/cluster/ClusterOptions.ts:135

How often the tombstone-prune pass runs. Default 5 min — small enough that a freshly-expired tombstone disappears within one pruning window, large enough to be negligible CPU.

---

tombstoneTtlMs?

readonly optional tombstoneTtlMs?: number

Defined in: src/cluster/ClusterOptions.ts:129

How long to keep a removed tombstone in the local members map before pruning it. Tombstones exist so stale gossip from a slow peer can’t resurrect a definitively-removed address; the TTL caps their accumulation in long-running clusters with frequent node churn (#75). Default 24 h — comfortably above any realistic gossip-propagation lag.

---

transport?

readonly optional transport?: Transport

Defined in: src/cluster/ClusterOptions.ts:116

Override the transport (e.g. InMemoryTransport for tests).

---

weaklyUpAfterMs?

readonly optional weaklyUpAfterMs?: number

Defined in: src/cluster/ClusterOptions.ts:178

Auto-promote a joining member to weakly-up after this many ms if convergence (leader + up transition) hasn’t happened yet. Set to 0 to disable. Default: 0 (disabled — opt-in only).