class

Raft::Log::File

Inherits Raft::Log < Reference < Object

On-disk log storage backend with crash recovery.

Stores log entries in an append-only binary file (log.bin), metadata in metadata.bin, and snapshots in snapshot.bin. All multi-byte integers use big-endian encoding. Metadata and snapshot files are written atomically via tmp+rename.

Entry record format: [Index:8B][Term:8B][Type:1B][DataLen:4B][Data:NB]

By default every write is followed by an fsync(2) syscall so that entries are durable against power loss or kernel panics. Pass fsync: false to skip the syscall and rely on OS page-cache writeback instead — acceptable when an external restore path exists (replicated block storage, periodic backups, or a peer that always holds the full log).

log = Raft::Log::File.new("/var/lib/raft/node-1")               # fsync on (default)
log = Raft::Log::File.new("/var/lib/raft/node-1", fsync: false) # page-cache only

Constructors

new(data_dir : String, fsync : Bool = true)

Opens (or creates) a log in data_dir.

See the class-level documentation for the file format and the fsync trade-off.

Source

Instance methods

append(entry : Entry) : Nil

Appends a single entry to the log with conflict detection.

If an existing entry at the same index has a different term, all entries from that index onward are truncated before appending. An entry with matching index and term is skipped (idempotent).

Source
append(entries : Array(Entry)) : Nil

Appends multiple entries to the log with conflict detection.

The default implementation delegates to the single-entry overload. Subclasses may override for batch optimizations (e.g., deferred fsync).

Source
close

Releases any resources held by the log (e.g., file handles).

Source
each_in_range(from : UInt64, to : UInt64, & : Entry -> ) : Nil

Yields each entry in the inclusive range [from, to] without allocating an intermediate array. Preferred over slice on hot paths.

Source
get(index : UInt64) : Entry | Nil

Returns the entry at the given 1-based index, or nil if not present.

Source
last_index

Returns the index of the last entry, or 0 if the log is empty.

Source
last_term

Returns the term of the last entry, or 0 if the log is empty.

Source
load_metadata

Loads the persisted metadata, or returns defaults (term 0, no vote).

Source
load_snapshot

Loads the most recent snapshot, or returns nil if none exists.

Returns a tuple of {last_included_index, last_included_term, snapshot_data}.

Source
save_metadata(meta : Metadata) : Nil

Persists the node's current term and voted-for state.

Source
save_snapshot(last_index : UInt64, last_term : UInt64, data : Bytes) : Nil

Saves a snapshot and compacts the log up to last_index.

All entries with index <= last_index are removed from the log.

Source
slice(from : UInt64, to : UInt64) : Array(Entry)

Returns entries in the inclusive range [from, to].

Source
term_at(index : UInt64) : UInt64 | Nil

Returns the term of the entry at index, or nil if not present.

Source
truncate_from(index : UInt64) : Nil

Removes all entries at index and beyond (inclusive).

Source