Class WalReader

java.lang.Object

com.loomcache.server.persistence.WalReader

public class WalReader
extends Object

Write-Ahead Log (WAL) reader for recovering Raft log entries from disk.

This utility reads WAL files created by WalWriter and performs recovery: - Parses log entries with their term, index, explicit type when present, and payload bytes - Validates CRC32 checksums to detect corruption - Skips corrupted entries at the end of the file (from crash recovery) - Returns recovery metadata including entries, statistics, and last valid index

Entry format in WAL: - 4 bytes: entry length (big-endian int) - 8 bytes: term (big-endian long) - 8 bytes: index (big-endian long) - 1 byte: entry type for new-format entries - N bytes: payload data - 4 bytes: CRC32 checksum (big-endian int)

Thread-safe: The readAll() method can be called concurrently, but the returned metadata should not be modified.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	WalReader.RecoveryMode
static final record	WalReader.WalRecoveryMetadata	Recovery metadata returned after reading a WAL file.

Constructor Summary

Constructors

Constructor	Description
WalReader()

Method Summary

Modifier and Type	Method	Description
static WalReader.WalRecoveryMetadata	readAll(Path walFile)	Read all entries from a WAL file and validate checksums.
static WalReader.WalRecoveryMetadata	readAll(Path walFile, @Nullable LoomMetrics metrics)	Read all entries from a WAL file and validate checksums with optional metrics.
static WalReader.WalRecoveryMetadata	readAll(Path walFile, @Nullable LoomMetrics metrics, WalReader.RecoveryMode recoveryMode)	Read all entries with explicit recovery behavior for corrupt or torn WAL tails.

Methods inherited from class Object

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

Constructor Details

WalReader

public WalReader()

Method Details

readAll

public static WalReader.WalRecoveryMetadata readAll(Path walFile)
                                             throws IOException

Read all entries from a WAL file and validate checksums.

Performs crash recovery by: 1. Reading entries sequentially from the beginning of the WAL file 2. Validating CRC32 checksum for each entry 3. Stopping at the first corrupted/incomplete entry (crash boundary) 4. Truncating the WAL file at the corruption point to remove corrupt data 5. Returning successfully recovered entries plus recovery statistics

If the WAL file does not exist, returns an empty recovery metadata (no error). If the WAL file is empty or starts with corruption, returns empty entries with statistics.

Entry length validation prevents excessive memory allocation: - Minimum: 20 bytes (term + index + checksum) - Maximum: 100 MB (configurable defense against memory attacks)

Parameters:

walFile - Path to the WAL file to read (must not be null)

Returns:

WalRecoveryMetadata with recovered entries and diagnostic statistics

Throws:

IOException - if file I/O operations fail (e.g., permission denied, disk errors). Note that corruption at the end of the file is NOT an error (expected in crash recovery).

NullPointerException - if walFile is null

readAll

public static WalReader.WalRecoveryMetadata readAll(Path walFile,
 @Nullable LoomMetrics metrics)
                                             throws IOException

Read all entries from a WAL file and validate checksums with optional metrics.

Performs crash recovery by: 1. Reading entries sequentially from the beginning of the WAL file 2. Validating CRC32 checksum for each entry 3. Stopping at the first corrupted/incomplete entry (crash boundary) 4. Returning successfully recovered entries plus recovery statistics

If the WAL file does not exist, returns an empty recovery metadata (no error). If the WAL file is empty or starts with corruption, returns empty entries with statistics.

Entry length validation prevents excessive memory allocation: - Minimum: 20 bytes (term + index + checksum) - Maximum: 100 MB (configurable defense against memory attacks)

Parameters:

walFile - Path to the WAL file to read (must not be null)

metrics - Optional LoomMetrics instance to record CRC validation failures

Returns:

WalRecoveryMetadata with recovered entries and diagnostic statistics

Throws:

IOException - if file I/O operations fail (e.g., permission denied, disk errors). Note that corruption at the end of the file is NOT an error (expected in crash recovery).

NullPointerException - if walFile or metrics is null

readAll

public static WalReader.WalRecoveryMetadata readAll(Path walFile,
 @Nullable LoomMetrics metrics,
 WalReader.RecoveryMode recoveryMode)
                                             throws IOException

Read all entries with explicit recovery behavior for corrupt or torn WAL tails.

Parameters:

walFile - Path to the WAL file to read

metrics - Optional LoomMetrics instance to record CRC validation failures

recoveryMode - Whether to truncate a torn tail or fail before partial recovery

Returns:

WalRecoveryMetadata with recovered entries and diagnostic statistics

Throws:

IOException - if file I/O fails, or corruption is rejected by recoveryMode