Module wal 

Write-Ahead Log

Write-Ahead Log (WAL) for the Chronix time-series database.

The WAL provides durable, crash-safe persistence of write operations. Every write is first logged to the WAL before being applied to the memtable. On crash recovery, the WAL is replayed to reconstruct in-memory state.

Record Format

Each WAL record is:

[crc32c: u32][length: u32][sequence_no: u64][record_type: u8][payload_version: u8][payload: [u8]]

The record_type discriminant enables forward-compatible payload handling.

File Format

WAL files start with a header:

[magic: b"CXWL"][version: u16]

Files are named wal_{sequence_start}.cxwl and rotated when they exceed max_file_size.

Structs

WalReader

Sequential WAL file reader with CRC verification.

WalRecord

A single WAL record as read from disk.

WalWriter

Write-Ahead Log writer.

Enums

WalRecordType

WAL record types — discriminant for forward-compatible payload handling.

Constants

BATCH_MAGIC

Magic header for batch-framed payloads inside a WAL record.

WAL_HEADER_SIZE

WAL file header size: 4 (magic) + 2 (version) = 6 bytes.

WAL_MAGIC

WAL file magic bytes.

WAL_PAYLOAD_VERSION

Current payload serialisation version.

WAL_RECORD_HEADER_SIZE

WAL record header size: 4 (crc) + 4 (length) + 8 (sequence) + 1 (record_type) + 1 (payload_version) = 18 bytes.

WAL_VERSION

Current WAL format version — 1, the first that ships.

Traits

WalSink

A WAL data file: a durable file that can also seek.

Functions

decode_batch_payload

Decode a batch-framed payload back into individual sub-payloads.

encode_batch_payload

Encode multiple payloads into a single batch-framed payload.

replay_all

Replay all WAL files in a directory in sequence order.

replay_range

Replay WAL records from start_sequence (exclusive) up to and including target_sequence.