Module journal 

File-based persistence for an MQTT session.

This module is a thin I/O driver: it owns the journal file handle and shuttles bytes between the file and the sans-io types from finmqtt_core::session::journal. All framing, CRC validation, op serialisation, and snapshot logic live in the core crate.

tokio would dispatch each individual async filesystem call to its blocking thread pool anyway, so each logical operation here runs its whole sequence of std::fs syscalls inside a single [tokio::task::spawn_blocking] call rather than bouncing back to the runtime between syscalls.

File layout

A journal file starts with an 8-byte header naming the format version, followed by CRC-framed records of session operations. On startup the file is replayed frame-by-frame via finmqtt_core::session::journal::JournalReader. If the tail is corrupt or truncated, the file is truncated to the last valid frame boundary.

If the header is missing or unsupported (including a pre-header journal), the file cannot be interpreted at all: it is renamed aside as a .corrupt-<unix millis>-<seq> backup and a fresh session is returned. A frame that decodes to malformed ops is a different problem – an encoding/decoding bug, not on-disk corruption – so it is reported as a load error instead of being silently discarded.

Compaction writes a fresh header and snapshot to a temp file and atomically renames it over the live journal.

Re-exports

pub use self::read::load;

Modules

backup 🔒

Backing up unreadable journal files as .corrupt-* siblings and pruning old backups.

file 🔒

Low-level journal file primitives: the append handle, write-rollback guard, and the fsync/truncate/temp-path helpers built on std::fs.

read 🔒

Loading a session by replaying a journal file frame by frame.

Structs

Writer

Append-only writer for a journal file with compaction support.

Enums

CompactOutcome 🔒

Result of Writer::compact’s blocking work, distinguishing whether the rename that makes the new file live was reached: that is the point past which the writer’s old handle is stale and must be replaced (or, on failure to do so, discarded) rather than reused.

Functions

blocking 🔒

Runs a blocking filesystem closure on tokio’s blocking pool, flattening a task-join failure (only possible on panic) into an I/O error.