VL.IO.Raft 1.0.8

VL.IO.Raft

Distributed leader election for vvvv gamma using the Raft consensus algorithm.

Built on DotNext.Net.Cluster (v5.x, net8.0).

Node: LeaderElection (IO.Raft)

Runs a Raft consensus cluster among a fixed set of known machines and surfaces the elected leader.

Inputs

Outputs

Usage

1. Add the LeaderElection node to your patch on every machine.
2. Connect the same Hosts spread to all instances (e.g. ["192.168.1.10", "192.168.1.11", "192.168.1.12"]).
3. Set LocalId to this machine's index in that list (0 on the first machine, 1 on the second, etc.).
4. Set Enable to true.

All machines should converge on the same leader within ~1 second. If the current leader goes offline, the remaining nodes elect a new one automatically.

Election Priority

Standard Raft uses randomised election timeouts to break ties — the node that times out first becomes a candidate and usually wins. With Prioritize = false (the default) all nodes use the same timeout range and have equal chance of winning.

When Prioritize = true, the timeout is scaled by LocalId:

LowerElectionTimeout = 150 + LocalId × 50 ms
UpperElectionTimeout = 300 + LocalId × 50 ms

Node 0 uses 150–300 ms, node 1 uses 200–350 ms, and so on. In a healthy cluster, node 0 will almost always win. If node 0 is offline, node 1 wins, and so on.

Node Rejoin Behaviour

When a machine crashes and restarts, it reconnects to the cluster automatically. The current leader sends heartbeats to all known members; the rejoining node receives one within a heartbeat interval and updates its Leader and IsLeader outputs accordingly.

This works without any extra configuration because the static member list means all nodes always know each other's addresses.

One thing to be aware of: if the rejoining node was the previous leader, the remaining nodes will have already elected a replacement (provided a majority stayed online). The rejoining node becomes a follower under the new leader and will not automatically reclaim leadership — even if it has the lowest LocalId. It would only win a subsequent election if the current leader goes offline.

Notes

• All machines must use the same Hosts list in the same order.
• The cluster uses a static membership list. All nodes start with ColdStart = true and immediately hold an election. Each node's member list is pre-seeded with all configured peers so that proper quorum (majority) is required — no node can win a solo election when others are reachable.
• Transport is TCP (no ASP.NET Core required). See DotNext transport options for HTTP alternatives.
• This library uses ConsensusOnlyState (the DotNext default) — no data is replicated, only the leader identity is established.

Quorum and fault tolerance

2-node clusters: a 2-node cluster requires both nodes to be online for any election to succeed. This is an inherent Raft property, not a library limitation. Consider a 3-node cluster for fault tolerance.

Arbitrary startup order: nodes that start early will fail their elections (cannot reach majority of a still-offline cluster) and keep retrying with randomised timeouts. Once a majority of configured nodes is online, an election succeeds automatically — no restart or manual intervention required.

Getting started

• Install as described here via commandline:

  nuget VL.IO.Raft

• The near future: Install the VL.IO.Raft NuGet package via the vvvv package manager.

• Usage examples and more information are included in the pack and can be found via the Help Browser

Upgrading to DotNext 6.x

DotNext 6.x requires net10 and has an incompatible wire protocol. To upgrade:

1. Update DotNext.Net.Cluster to 6.* in src/VL.IO.Raft.csproj.
2. Rebuild.
3. Update all cluster nodes simultaneously — a mixed 5.x/6.x cluster will not work.

References

• DotNext Raft overview
• IRaftCluster API
• IClusterMember API
• Raft paper (Ongaro & Ousterhout, 2014)

Credits

Initial development was sponsored by Refik Anadol Studio.