pub struct Journal<'a> { /* private fields */ }Expand description
A live, exclusively-locked handle to one release run’s journal.
Holds the single-active-cut lock for its entire lifetime (dropping the handle
releases it) and mediates every mutation through the append-then-apply
discipline. Construct it with Journal::create (a new run) or
Journal::open (resume an existing one).
Implementations§
Source§impl<'a> Journal<'a>
impl<'a> Journal<'a>
Sourcepub fn create(
store: &'a dyn JournalStore,
clock: &'a dyn Clock,
idgen: &dyn IdGen,
paths: JournalPaths,
plan_id: String,
version: String,
targets: Vec<String>,
) -> Result<Self>
pub fn create( store: &'a dyn JournalStore, clock: &'a dyn Clock, idgen: &dyn IdGen, paths: JournalPaths, plan_id: String, version: String, targets: Vec<String>, ) -> Result<Self>
Create a brand-new run: take the single-active-cut lock, mint a run_id
via idgen, and record the RunCreated event (which is also persisted to
a fresh manifest).
§Errors
io::ErrorKind::WouldBlock if another cut/resume holds the lock, plus
any store error appending the first event or writing the manifest.
Sourcepub fn open(
store: &'a dyn JournalStore,
clock: &'a dyn Clock,
paths: JournalPaths,
run_id: &str,
) -> Result<Self>
pub fn open( store: &'a dyn JournalStore, clock: &'a dyn Clock, paths: JournalPaths, run_id: &str, ) -> Result<Self>
Resume an existing run: take the single-active-cut lock, rebuild state from the journal (the source of truth), and best-effort re-persist the manifest cache so it reflects the log even if a prior crash left it stale.
A manifest-write failure here is not fatal: the manifest is disposable and the in-memory state is already authoritative (rebuilt from the log), so a transient cache-write error must not brick an otherwise-recoverable run.
§Errors
io::ErrorKind::WouldBlock if the lock is held, io::ErrorKind::NotFound
if the run has no journal, io::ErrorKind::InvalidInput for a malformed
run_id, plus any store/parse error reading the log.
Sourcepub fn paths(&self) -> &JournalPaths
pub fn paths(&self) -> &JournalPaths
The resolved paths this journal writes to.
Sourcepub fn append(&mut self, kind: EventKind) -> Result<&RunState>
pub fn append(&mut self, kind: EventKind) -> Result<&RunState>
Record a fact with append-then-apply atomicity, returning the updated state.
The sequence is strictly: (1) serialize and durably fsync the event to the log (the source of truth), (2) apply it to the in-memory projection, (3) best-effort rewrite the disposable manifest cache.
Step 3 failing does not fail the append: once step 1 returns the event
is committed, so reporting Err would tempt the caller to retry an
already-committed fact. A stale manifest self-heals on the next append or
Journal::open. Only a step-1 failure is fatal, and it leaves the state
untouched.
This is a low-level append of a raw EventKind (seq/ts/
idempotency_key are assigned here). It does not validate release
state-machine ordering — that policy belongs to the coordinator; the
reducer only guarantees replay-idempotency and terminal-state freezing.
§Errors
A store error from the durable append (step 1), or an event that fails to serialize.