No description
  • C# 97.9%
  • Shell 1.9%
  • Python 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
ferociousbyte 76abb49856
All checks were successful
/ build (push) Successful in 1m50s
Names and revoked certificates are proven end to end in unilayer's suite
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>
2026-11-17 21:16:19 +01:00
.forgejo/workflows What nothing read is gone, comments say what the code does, and the tests share their helpers 2026-11-16 23:33:44 +01:00
plan Names and revoked certificates are proven end to end in unilayer's suite 2026-11-17 21:16:19 +01:00
scripts What nothing read is gone, comments say what the code does, and the tests share their helpers 2026-11-16 23:33:44 +01:00
src What waits for a node's loop is bounded per peer, refusals are reported once per source, and a connection ends with its certificate 2026-11-17 19:58:00 +01:00
tests What waits for a node's loop is bounded per peer, refusals are reported once per source, and a connection ends with its certificate 2026-11-17 19:58:00 +01:00
.gitignore A basic Raft runs in a simulation that checks it under faults, and its checks catch a protocol broken on purpose 2026-11-12 23:24:33 +01:00
CLA.md The contributor agreement, how to contribute, and a workflow that builds and tests every push 2026-11-12 22:35:05 +01:00
CLAUDE.md A push to stable releases raft: CI tags the commit YYYY.M.N once the tests pass 2026-11-15 11:19:22 +01:00
CONTRIBUTING.md The contributor agreement, how to contribute, and a workflow that builds and tests every push 2026-11-12 22:35:05 +01:00
Directory.Build.props The structure, the rules and the plans of a Raft of our own 2026-11-12 22:32:02 +01:00
LICENSE The structure, the rules and the plans of a Raft of our own 2026-11-12 22:32:02 +01:00
README.md Version 1 of the messages is released, a frame is 8 MiB at most, and the copyright is Talaryon Labs' 2026-11-17 00:19:32 +01:00
unilayer.raft.slnx A cluster across three virtual machines holds every check under power cuts, frozen machines and lost disks 2026-11-13 16:39:22 +01:00

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.Raft is 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.