- C# 97.9%
- Shell 1.9%
- Python 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
/ build (push) Successful in 1m50s
Scenario 19 of unilayer's end-to-end suite: three nodes in containers on the raft engine take certificates with their addresses and both settings, node by node; a certificate of the CA for another address and one revoked while its node runs are not heard, and each node is heard again with a new one. 174 of 174 begun on the raft engine, 194 of 194 begun on DotNext. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> |
||
| .forgejo/workflows | ||
| plan | ||
| scripts | ||
| src | ||
| tests | ||
| .gitignore | ||
| CLA.md | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| Directory.Build.props | ||
| LICENSE | ||
| README.md | ||
| unilayer.raft.slnx | ||
unilayer raft
unilayer.Raft is an implementation of the Raft consensus algorithm, built for
unilayer's cluster mode and usable without it: a replicated log that
a few nodes agree on, with one leader that takes the writes.
Status: elections, replication, snapshots, membership, reads and handover, in a simulation and on real nodes. The protocol's step function - pre-vote, stickiness, check quorum, a window per follower - and the simulation that checks it under faults exist (plan/01 to 03), and so do the log on disk (plan/04), real nodes over TCP with mutual TLS (plan/05), snapshots that a node restores while it goes on taking part (plan/06), and members changed one at a time, with a node that lost its disk kept from voting until it has caught up (plan/07), and reads on any node that see every acknowledged write, and the lead handed over on request (plan/08). Not yet measured on unilayer.cloud (plan/09). The rules are in CLAUDE.md, the plans in plan/. unilayer runs on DotNext's Raft until this one passes its own simulation and unilayer's cluster suite.
Why
unilayer's cluster mode replicates every write through a Raft log and applies it to the PostgreSQL of each node. With DotNext below it, a few things could only be worked around, not fixed (found in unilayer's load and failure tests, November 2026; the details are in plan/README.md):
- A node asks every member before it stands for election and waits for all answers, and the leader's round of replication waits for a member it can't reach. Raft needs a majority for either. A leader that hung was replaced after the request timeout, not after the election timeout.
- A snapshot is applied inside the request that brings it, with the log locked: the node answers nothing until its state is restored.
- The log is written to disk once per commit, and its page size is fixed when it is created.
- It can't be tested without real sockets and real time, so a rare interleaving shows once in ten runs of a suite that takes eight minutes.
What it is built on
- The protocol does no I/O.
unilayer.Raftis given the time, the messages that arrived and what the disk has written, and answers with what to send, what to write and what to apply. It reads no clock, opens no socket and starts no thread. - So a whole cluster runs in one thread, from a seed. The simulation drives several nodes over a network that delays, drops, duplicates and partitions, and disks that lose what was not synced, and checks after every step what must never happen: two leaders in one term, two different entries at one index, an acknowledged write that is gone. A failing run is its seed, and runs again the same way.
- A majority is enough, always. No election, no commit and no read waits for a member that is not needed for it.
- It knows nothing of what it replicates. Entries are bytes, a snapshot is a reference the application understands. No PostgreSQL, no unilayer, no HTTP.
Structure
| Project | Content |
|---|---|
src/unilayer.Raft |
The protocol: elections, replication, membership, reads. References nothing |
src/unilayer.Raft.Log |
The log on disk: segments, checksums, one fsync for many entries |
src/unilayer.Raft.Transport |
The messages between nodes over TCP with mutual TLS |
src/unilayer.Raft.Hosting |
A running node: the protocol driven by a real clock, the log and the transport. What an application references |
tests/unilayer.Raft.Simulation |
A cluster in one thread: network, disks and clocks decided by a seed, and the checks |
tests/unilayer.Raft.Tests |
The tests of all of the above, and of the rules between the projects |
tests/unilayer.Raft.Cluster |
A cluster across virtual machines: a node with a small application, a driver of clients and faults, the checks of what the clients saw |
Building and testing
.NET 10.
dotnet build unilayer.raft.slnx
dotnet test unilayer.raft.slnx
A cluster across virtual machines (qemu with KVM, a Debian cloud image, no root needed) runs outside dotnet test;
how, and what it found, is in plan/05:
tests/unilayer.Raft.Cluster/vm.sh up 5
tests/unilayer.Raft.Cluster/vm.sh deploy
dotnet run --project tests/unilayer.Raft.Cluster -c Release -- drive --nodes 5 --overlap 2 --vm tests/unilayer.Raft.Cluster/vm.sh --seconds 120 --seed 1
Contributing
See CONTRIBUTING.md; a first contribution needs the Contributor License Agreement.
License
Copyright (C) 2026 Talaryon Labs. AGPL-3.0-only, as unilayer and its storage service.