Struct WalWriter 

pub struct WalWriter { /* private fields */ }

Append-only WAL writer.

Opens (or creates) a file in append mode and writes one JSONL line per event, using file locking for concurrent access safety and fsync after each write for durability.

Example

use runtimo_core::{WalWriter, WalEvent, WalEventType};
use std::path::Path;

let mut wal = WalWriter::create(Path::new("/tmp/app.wal")).unwrap();
wal.append(WalEvent {
    seq: 0, ts: 1715800000,
    event_type: WalEventType::JobStarted,
    job_id: "job1".into(),
    capability: None, output: None, error: None,
}).unwrap();

Implementations

impl WalWriter

pub fn create(path: &Path) -> Result<Self>

Creates or opens a WAL file at the given path.

The file is opened in append mode. Existing content is preserved.

Errors

Returns Error::WalError if the file cannot be created or opened.

pub fn append(&mut self, event: WalEvent) -> Result<()>

Appends an event to the WAL using true append mode (P0 FIX).

Opens the file in append mode, acquires an exclusive lock, writes the JSONL line, fsyncs, then releases the lock. This is O(1) per write instead of O(N) read-rewrite, and the lock is held during the entire write operation preventing concurrent write loss.

Increments the internal sequence counter after a successful write.

Errors

Returns Error::WalError on serialization or I/O failure.

pub fn seq(&self) -> u64

Returns the current sequence number (next event will use this value).

impl WalWriter

WAL cleanup and rotation utilities.

pub fn rotate( path: &Path, max_size_bytes: u64, max_rotations: usize, ) -> Result<()>

Rotates the WAL when it exceeds max_size_bytes.

Moves the current WAL to {path}.1 (shifting older rotations), then creates a fresh empty WAL. Keeps at most max_rotations old files. FINDING #15: basic WAL rotation to prevent unbounded growth.

pub fn cleanup(path: &Path, max_age_secs: u64) -> Result<usize>

Cleans up WAL entries older than max_age_secs.

Writes retained events to a temporary file, then atomically renames it over the original WAL. This prevents event loss if another writer appends during cleanup.

Arguments

• path - Path to WAL file
• max_age_secs - Maximum age in seconds

Returns

• Ok(usize) - Number of entries removed
• Err(Error) - Cleanup failure