Module reader 

WalStreamReader — production reader-side surface.

Consumes the byte stream produced by super::BufferedWalSink (or any [u64 BE length prefix][payload]-framed sequence beginning with a recognised StreamMagic tag) and yields per-record payload borrows. The complement to the writer-side super::BufferedWalSink.

Streaming-iterator pattern

WalStreamReader::next_record returns Option<&[u8]> where the borrow is tied to &mut self — the slice is valid until the next call mutates the internal buffer. Callers decode the borrowed payload (typically via postcard::from_bytes::<WalRecord>) inside the loop iteration and must not retain the slice across iterations. This avoids the per-record allocation that an owned Vec<u8> return would force, at the cost of giving up std::iter::Iterator (whose lifetime contract precludes the borrow tie).

Fail-secure framing posture

Five reject paths cover the framing surface:

1. Unknown magic at stream open → WalExportError::UnsupportedStreamVersion. Stack-only 8-byte read, no heap alloc pre-rejection (fail-fast).
2. Truncated header (fewer than 8 bytes) at open → InvalidFramingReason::HeaderMissing via Truncated mapping.
3. Length prefix exceeds bound → InvalidFramingReason::LengthExceedsMax rejection BEFORE allocating the payload buffer (16 MiB fail-secure ceiling).
4. Length prefix zero → InvalidFramingReason::LengthZero.
5. Premature EOF mid-record (length prefix complete but payload short) → InvalidFramingReason::Truncated.

Clean EOF (zero bytes available at the start of the next record) returns Ok(None) — distinguishable from torn headers via a single-byte probe before committing to the full 8-byte read.

Bridge to integration round-trip tests

The sibling round_trip_tests module’s parse_stream test helper duplicates the framing logic to keep that module independent of this reader API; this module hosts the production-grade equivalent for non-test callers.

Structs

StreamingWalReader

Concrete WalStreamReader impl over an arbitrary std::io::Read.

Traits

WalStreamReader

Reader-side trait — next_record plus cumulative_position.