Durability & recovery

Raft consensus and automatic leadership

Would let a group of nodes agree on the order of writes and elect a new leader automatically when one fails.

ResearchEngine edition 5f8ea3af

What it does

KynetraDB contains a hand-written Raft implementation and an opt-in HTTP transport. It is tested under a deterministic fault simulator and with in-process server tests. The server's own configuration notes call it experimental, and no measurement over a real network exists, so it is a research item and not a high-availability claim.

How it works

The Raft crate is deterministic: nodes are driven by virtual ticks and exchange messages through an injected transport, with no sockets, threads or wall clock of its own. It implements elections, log replication, membership changes with learners that catch up before promotion, snapshots with install-snapshot for lagging or wiped followers, and independent shard groups. A leader lease is anchored on the leader's own send times and is also bounded by real elapsed time, so a stalled process cannot keep a lease past the real time its answers allow. A leader that loses contact with a majority steps down.

Test coverage is simulation-based. A simulator injects partitions, restarts and message loss from a seed and checks safety properties, such as never two leaders in one term and no commit by a minority leader. The default run covers 200 seeds; two further sweeps of 1,000 seeds each are opt-in. The reliability page explains how to read these numbers and what they do not establish.

In the server, setting KYNETRA_RAFT_ENABLED with a node id and a peer list starts a tick loop and two routes: POST /v1/raft/message for node-to-node traffic, which requires the instance service key, and GET /v1/raft/metrics for operators. With KYNETRA_RAFT_QUORUM_WRITES, writes are acknowledged by the consensus group and committed entries are projected into the engine; when leadership moves, the former leader re-points to the new one. The older lease-based election was retired, and the server refuses to start when it is configured.

The server refuses to start Raft with the PostgreSQL backend, because Raft replicates through the local file log. A Raft node must receive its signing, vault and audit secrets from the environment and never generates them.

Where you reach it

  • ConfigKYNETRA_RAFT_ENABLED, KYNETRA_RAFT_NODE_ID, KYNETRA_RAFT_PEERS (id=url,...)
  • ConfigKYNETRA_RAFT_QUORUM_WRITES, KYNETRA_RAFT_QUORUM_TIMEOUT_MS
  • HTTPPOST /v1/raft/message (node-to-node); GET /v1/raft/metrics (operators)

Limits

  • Experimental. The server's own configuration notes describe it as an experimental transport.
  • The evidence is a simulator and in-process tests. No multi-host or real-network measurement is published, and the simulator proves properties of the simulator under the faults it injects.
  • Peer messages travel over HTTP or HTTPS with the instance service key as the credential. Run nodes on a private network or use https URLs.
  • It does not combine with the PostgreSQL backend.
  • It is not a sharded or multi-region deployment. The shard-group code is exercised in simulation and is not a clustered product.

Evidence

  • On this siteReliability: how the Raft simulation is read
  • TestsCovered in the engine repository by more than 110 Raft tests (elections, leases, check-quorum, membership, snapshots, shard groups, seeded fault sweeps) and more than 100 server tests for the HTTP transport, authentication and projection

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

This is not available in the preview. Request a preview to discuss the current scope.