Axis
A fault-tolerant, strongly consistent distributed key-value store designed for coordination, distributed locking, and metadata management.
Overview
Axis is a fault-tolerant, strongly consistent distributed key-value store for coordination, distributed locking, and metadata management. Inspired by etcd: same core data model, built from first principles in Java.
Features
- Replicated log and total ordering. All writes serialize through a Raft consensus log. Every mutation has a unique, immutable position in a total order the cluster agrees on.
- Linearizable reads and writes. Every read reflects all writes that completed before it. Clients see a consistent, up-to-date view regardless of which node they connect to.
- Multi-version history. Every write creates a new revision. The full history of every key is retained. Nothing is overwritten in place.
- Historical reads. Read any key or range as it existed at any past revision.
- TTL leases. Keys attach to leases. When a lease expires or is revoked, all attached keys are deleted atomically. Foundation for session management, distributed locks, and ephemeral registrations.
- Range scans. Scan key ranges with filtering by revision window and sorting by key, value, version, or revision.
- Transactions. Atomic operations with condition evaluation and success/failure branches. Conditions compare version, revision, value, or lease ID.
Architecture
Axis runs as a cluster of replicated nodes. Every request (read or write) enters through the gRPC layer of any node, passes through the consensus layer where writes are serialized and replicated, then lands on the storage layer.
MVCC store
The MVCC store is the versioned key-value layer. Every write advances a global, monotonically increasing revision (the logical clock of the store). Each key has a history on this timeline: a sequence of revisions showing when it was created, updated, deleted, and possibly recreated.
No revision is ever overwritten. Any past state is queryable by specifying a revision. The store is single-writer, multiple-reader; each reader is pinned to a snapshot at the revision it started.
Write-ahead log
The WAL is an append-only, segmented log that makes Raft entries durable before they are applied to the state machine. Each record carries a CRC32 checksum that chains to the next, so any truncation, gap, or silent corruption breaks the chain and is detectable on recovery.
Consensus
The SequentialExecutor is the entry point for all reads and writes. It drives Raft through a process-advance loop, proposes commands as log entries, and applies committed entries to the state machine in the order Raft commits them.
Leadership is managed automatically. If the current leader fails, a new election runs without operator intervention. Writes proposed to a non-leader are forwarded to the current leader.
Lease store
Each lease is a timer object: a numeric ID, a TTL granted at creation, and a set of attached keys. Only the cluster leader schedules and enforces expiry, but all nodes apply it identically through Raft.
To survive leader failover, the leader periodically replicates a LeaseCheckpoint entry carrying the remaining TTL of each active lease.
Backend
The backend is a storage abstraction layer beneath the MVCC and Lease stores. The only implementation is backend-lmdb: an embedded, memory-mapped storage engine with native support for concurrent readers and a single writer.
Components
Axis depends on two purpose-built components developed as part of the same effort:
- Jaft. The Raft consensus layer. Covers leader election, log replication, membership changes, and the process-advance loop.
- versioned-index. The copy-on-write B+ tree used inside the MVCC layer as the in-memory key timeline index.
Background
Axis is a project to learn distributed systems and storage engine fundamentals by building them from first principles: consensus, replication, coordination, consistency models, MVCC, and lease management.
References