Module segment 

WAL segment management.

The WAL is split into fixed-size segment files for efficient truncation. Each segment is a standalone WAL file containing records within an LSN range.

Naming convention

Segments are named wal-{first_lsn:020}.seg — zero-padded for lexicographic ordering. This guarantees ls and readdir return segments in LSN order.

Lifecycle

1. Writer creates a new segment when the current segment exceeds target_size.
2. The active segment is the one being appended to.
3. truncate_before(lsn) deletes all sealed segments whose max_lsn < lsn.
4. The active segment is NEVER deleted — only sealed (closed) segments are eligible.

Recovery

On startup, all segment files in the WAL directory are discovered via readdir, sorted by first_lsn, and replayed in order. The last segment is the active one.

Structs

SegmentMeta

Metadata about a WAL segment file on disk.

TruncateResult

Result of a WAL truncation operation.

Constants

DEFAULT_SEGMENT_TARGET_SIZE

Default segment target size: 64 MiB.

Functions

discover_segments

Discover all WAL segments in a directory, sorted by first_lsn.

fsync_directory

Fsync a directory to ensure file creation/deletion metadata is durable.

migrate_legacy_wal

Migrate a legacy single-file WAL to the segmented format.

segment_filename

Build a segment filename from a starting LSN.

segment_path

Build a full segment path within a WAL directory.

truncate_segments

Delete all sealed segments whose maximum LSN is strictly less than checkpoint_lsn.