Skip to content
LoomCache

Raft Design

Raft is the safety boundary for LoomCache writes. Mutating commands are appended to a group log, replicated to a majority, committed, and applied before the client receives success. This page covers the components of the consensus layer, its write and read paths, the invariants it enforces, and its behavior under failure.

The following animation shows how a single entry moves through the replicated log:

Raft Log Replication

Waiting for the next client write...

Leaderterm 3commit=6
PUT a=1#4 t2
PUT b=7#5 t2
DEL a#6 t3
▼
State machineDEL a
Follower 1commit=6
PUT a=1#4 t2
PUT b=7#5 t2
DEL a#6 t3
▼
Follower 2commit=6
PUT a=1#4 t2
PUT b=7#5 t2
DEL a#6 t3
▼
uncommittedcommittedcommit indext2/t3 term

Components

Section titled “Components”
  • Each Raft member owns roles, elections, append replication, commit-index advancement, snapshot install, and membership changes.
  • The in-memory Raft index is paired with durable command records when persistence is enabled.
  • Durable Raft metadata stores the state that must survive restarts: current term, voted-for node ID, and durable commit index. A node that finds WAL or snapshot data on disk but no metadata file refuses to start rather than risk a stale-term restart.
  • Leader leases let a leader serve linearizable reads after lease validation.
  • Group management owns one or more Raft members.
  • Election, replication, and log diagnostics publish the Raft Micrometer gauges and counters. Internal validation checks assert Raft invariants during the test suite.

Write path

Section titled “Write path”
  1. The request router resolves the target Raft group.
  2. The leader wraps the request in a durable log record.
  3. The entry is appended locally and replicated to followers.
  4. The leader advances commitIndex after majority acknowledgement.
  5. The applier mutates the state machine and releases the client response.

Read path

Section titled “Read path”

Linearizable reads route to the leader. The leader captures the current commit index, validates its lease, waits for local apply to catch up, and serves the read without another quorum round trip. This fast path requires a valid lease. If the lease has expired or is about to expire, the leader first runs a lease-confirmation AppendEntries round to renew majority acknowledgement before answering. That confirmation is a regular AppendEntries round that also ships any pending entries to lagging followers, and it adds one round trip of latency to that read.

Leader election and the no-op entry

Section titled “Leader election and the no-op entry”

When a node wins an election it immediately appends a no-op entry (an empty log record) in its new term. Until that no-op is committed (termEntryCommitted = true), the new leader refuses to serve linearizable reads and rejects client writes. This is the standard Raft safety property: a leader cannot safely determine the commit point of entries from prior terms until it has committed at least one entry from its own term. The brief stall after each election is expected behavior.

Invariants

Section titled “Invariants”
  • Client success requires a committed log entry.
  • Followers cannot acknowledge conflicting entries at the same term/index.
  • Leaders cannot serve linearizable reads after lease expiry or before the current-term no-op commits.
  • Membership changes are single-server only (etcd-style): a node joins as a learner, catches up, is promoted, and voters are removed one at a time. Joint consensus is intentionally not used, so at most one voter change is in flight.
  • Snapshot install preserves term, vote, commit index, and state-machine data.

Operational details

Section titled “Operational details”

Snapshot transfer is chunked, with a configurable maximum snapshot size. Each completed snapshot file carries a SHA-256 checksum over the full payload; the receiver rejects any chunk sequence that fails verification. Commit-index persistence is coalesced rather than flushed for every commit, which avoids excessive fsync pressure on the metadata file. Learner promotion to voter is gated on bounded replication lag at the moment of the promotion request.

Failure behavior

Section titled “Failure behavior”

Minority partitions cannot elect a leader or commit writes. A failed leader stalls writes until a majority elects a replacement. Lagging followers catch up through AppendEntries or snapshot install. Corrupt durable state fails closed during startup validation.

Verification

Section titled “Verification”

Raft safety, replication, snapshot, log consistency, linearizability, split-brain, network partition, and failover suites exercise this layer. Operators watch leader count, term churn, commit latency, append latency, replication lag, log size, and snapshot-install signals.

Section titled “Related”

LoomCache is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Hazelcast, Inc. or by any other company whose products are named in this documentation. “Hazelcast” is a trademark of Hazelcast, Inc.; references to it are nominative and describe only migration and comparison. All other product and company names are trademarks of their respective owners and are used for identification purposes only.