Class RaftMetadataStore

java.lang.Object

com.loomcache.server.persistence.RaftMetadataStore

public class RaftMetadataStore
extends Object

Persistent storage for Raft metadata: currentTerm, votedFor, and the highest commit index durably represented in the local state machine.

Per Raft paper §5.2, these fields MUST be persisted to durable storage before responding to any RPC. Without persistence, a crashed node restarts at term 0 and may vote twice in the same term, violating Election Safety.

Implementation uses atomic file replacement (write-temp, fsync, rename) to ensure crash-safe updates. The file format is a simple text file:

  currentTerm=<long>
  votedFor=<string|null>
  commitIndex=<long>

Since:

1.5

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	RaftMetadataStore.RaftMetadata	Recovered Raft metadata.

Constructor Summary

Constructors

Constructor	Description
RaftMetadataStore(String nodeId, Path dir)	Creates a metadata store in the given directory.

Method Summary

Modifier and Type	Method	Description
RaftMetadataStore.RaftMetadata	load()	Load persisted metadata from disk.
void	persist(long currentTerm, @Nullable String votedFor)	Persist currentTerm and votedFor atomically to disk with fsync.
void	persist(long currentTerm, @Nullable String votedFor, long commitIndex)	Persist currentTerm, votedFor, and commitIndex atomically to disk with fsync.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

RaftMetadataStore

public RaftMetadataStore(String nodeId,
 Path dir)

Creates a metadata store in the given directory.

Parameters:

nodeId - the Raft node identifier (for logging)

dir - the directory to store metadata in (must exist and be writable)

Method Details

persist

public void persist(long currentTerm,
 @Nullable String votedFor)
             throws IOException

Persist currentTerm and votedFor atomically to disk with fsync. This MUST be called before responding to any vote request or term change.

Parameters:

currentTerm - the current term (must be non-negative)

votedFor - the candidate voted for in this term, or null if no vote cast

Throws:

IOException - if the write or fsync fails

persist

public void persist(long currentTerm,
 @Nullable String votedFor,
 long commitIndex)
             throws IOException

Persist currentTerm, votedFor, and commitIndex atomically to disk with fsync.

Parameters:

currentTerm - the current term (must be non-negative)

votedFor - the candidate voted for in this term, or null if no vote cast

commitIndex - the highest committed index durably represented locally

Throws:

IOException - if the write or fsync fails

load

public RaftMetadataStore.RaftMetadata load()
                                    throws IOException

Load persisted metadata from disk.

Returns:

the recovered metadata, or defaults (term=0, votedFor=null, commitIndex=0) if no file exists

Throws:

IOException - if the file exists but cannot be read or parsed