Struct SnapshotWriter 

pub struct SnapshotWriter { /* private fields */ }

Append-only snapshot writer.

Streams KvUpdate records to disk via a buffered writer. No in-memory state beyond the file handle and a byte counter for compaction triggering.

Compacts automatically when bytes written since last compaction exceeds compact_threshold. Compaction replays the log into a transient HashMap, rewrites via tempfile+rename, and reopens for append.

Implementations

impl SnapshotWriter

pub fn open(path: &Path, compact_threshold: u64) -> Result<Self, SnapshotError>

Open or create a snapshot log.

If the file doesn’t exist, writes the header. If it exists, opens for append. compact_threshold controls how many bytes accumulate before an automatic compaction.

pub fn write_update(&mut self, update: &KvUpdate) -> Result<(), SnapshotError>

Write a single KvUpdate record to the log.

Buffered — does not flush to disk until checkpoint.

pub fn checkpoint( &mut self, cursor: &WatchCursor, ) -> Result<bool, SnapshotError>

Write a cursor checkpoint and flush the buffer to the OS.

The flush is a write(2) into the page cache — it survives a process crash, but NOT power loss: there is no fsync on this path. The durable sync_all happens in compact. That’s deliberate — the snapshot is a cache backed by NATS and checkpoints are frequent, so an fsync per checkpoint isn’t worth its latency; a tail lost to power loss is rebuilt from a NATS scan + watch replay.

Returns true when the log has grown past the compaction threshold and the caller should run compact. Separating the check from the I/O lets async callers offload compaction to a blocking task instead of stalling the executor.

pub fn flush(&mut self) -> Result<(), SnapshotError>

Flush the buffer to disk without writing a cursor record.

pub fn compact(&mut self) -> Result<(), SnapshotError>

Compact the snapshot log: replay, deduplicate, and rewrite.

Performs synchronous file I/O. In async contexts, run via spawn_blocking to avoid stalling the executor.