Struct Journal 

pub struct Journal<F, E, C, H, S>
where
    F: Family,
    E: Context,
    C: Contiguous<Item: EncodeShared>,
    H: Hasher,
    S: Strategy,
{ /* private fields */ }

An append-only data structure that maintains a sequential journal of items alongside a Merkle-family structure. The item at index i in the journal corresponds to the leaf at Location i in the Merkle structure. This structure enables efficient proofs that an item is included in the journal at a specific location.

Implementations

impl<F, E, C, H, S> Journal<F, E, C, H, S>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher, S: Strategy,

pub fn size(&self) -> Location<F>

Returns the Location of the next item appended to the journal.

pub fn root(&self, inactive_peaks: usize) -> Result<H::Digest, Error<F>>

Compute the root of the Merkle structure using inactive_peaks and the bagging carried by the journal’s hasher.

pub const fn strategy(&self) -> &S

Return a reference to the merkleization strategy.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, C::Item, S>

Create a speculative batch atop this journal.

pub async fn proof( &self, start_loc: Location<F>, max_ops: NonZeroU64, inactive_peaks: usize, ) -> Result<(Proof<F, H::Digest>, Vec<C::Item>), Error<F>>

Generate a proof of inclusion for items starting at start_loc.

Returns a proof and the items corresponding to the leaves in the range start_loc..end_loc, where end_loc is the minimum of the current item count and start_loc + max_ops.

Errors

• Returns Error::Merkle with merkle::Error::RangeOutOfBounds if start_loc >= current item count.
• Returns Error::Journal with crate::journal::Error::ItemPruned or Error::Merkle with merkle::Error::ElementPruned if a required item or Merkle node has been pruned.

pub fn speculative_proof( &self, batch: &MerkleizedBatch<F, H::Digest, C::Item, S>, inactive_peaks: usize, ) -> Result<Proof<F, H::Digest>, Error<F>>

Inclusion proof for the items batch appends, anchored at the batch’s speculative tip.

Nodes below the batch chain are read from this journal’s Merkle store, which retains them at least until the batch’s changes are flushed.

pub fn speculative_pinned_nodes( &self, batch: &MerkleizedBatch<F, H::Digest, C::Item, S>, ) -> Result<Vec<H::Digest>, Error<F>>

Merkle frontier at the first item batch appends (Family::nodes_to_pin).

Nodes below the batch chain are read from this journal’s Merkle store, which retains them at least until the batch’s changes are flushed.

pub async fn historical_proof( &self, historical_leaves: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, inactive_peaks: usize, ) -> Result<(Proof<F, H::Digest>, Vec<C::Item>), Error<F>>

Generate a historical proof with respect to the state of the Merkle structure when it had historical_leaves leaves.

Returns a proof and the items corresponding to the leaves in the range start_loc..end_loc, where end_loc is the minimum of historical_leaves and start_loc + max_ops.

Errors

• Returns Error::Merkle with merkle::Error::RangeOutOfBounds if start_loc >= historical_leaves or historical_leaves > number of items in the journal.
• Returns Error::Journal with crate::journal::Error::ItemPruned or Error::Merkle with merkle::Error::ElementPruned if a required item or Merkle node has been pruned.

impl<F, E, C, H, S> Journal<F, E, C, H, S>

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,

pub async fn start_sync(self) -> Result<(Self, Handle<()>), Error<F>>

Begin durably persisting the journal.

Awaiting the returned Handle provides the same durability guarantee as Self::commit. Also tries to advance the recovery watermarks to bound startup recovery. Use Self::sync to guarantee no recovery is needed.

pub async fn commit(self) -> Result<Self, Error<F>>

Durably persist the journal. This is faster than sync() but does not guarantee that the Merkle structure is durably persisted, meaning recovery may be required on startup in the event of a crash.

pub async fn from_components( merkle: Merkle<F, E, H::Digest, S>, journal: C, hasher: StandardHasher<H>, apply_batch_size: NonZeroU64, ) -> Result<Self, Error<F>>

Create a Journal, replaying any journal operations missing from Merkle.

Returns an error if the Merkle tree extends past the journal end.

pub async fn append( self, item: &C::Item, ) -> Result<(Self, Location<F>), Error<F>>

Append an item to the journal and update the Merkle structure.

pub async fn apply_batch( self, batch: &MerkleizedBatch<F, H::Digest, C::Item, S>, ) -> Result<Self, Error<F>>

Apply a batch to the journal.

A batch is valid if the journal has not been modified since the batch chain was created, or if only ancestors of this batch have been applied. Already-committed ancestors are skipped automatically. Applying a batch from a different fork returns an error.

pub async fn prune( self, prune_loc: Location<F>, ) -> Result<(Self, Location<F>), Error<F>>

Prune journal items before prune_loc, then raise the Merkle pruning boundary to the journal’s retained start if it is lower.

Returns

The journal’s retained start, which may be less than prune_loc. After state sync, the Merkle pruning boundary can remain above the returned start.

pub async fn destroy(self) -> Result<(), Error<F>>

Destroy the authenticated journal, removing all data from disk.

pub async fn sync(self) -> Result<Self, Error<F>>

Durably persist the journal, ensuring no recovery is required on startup.

impl<F, E, C, H, S> Journal<F, E, C, H, S>

where F: Family, E: Context, C: Backing<E, Item: EncodeShared>, H: Hasher, S: Strategy,

pub async fn new( context: E, merkle_cfg: Config<S>, journal_cfg: C::Config, predicate: fn(&C::Item) -> bool, bagging: Bagging, ) -> Result<Self, Error<F>>

Create an authenticated journal ending at its last matching item.

An empty retained range preserves its append position.

pub async fn init_at_most( context: E, merkle_cfg: Config<S>, journal_cfg: C::Config, max_size: u64, predicate: fn(&C::Item) -> bool, bagging: Bagging, ) -> Result<Self, Error<F>>

Recover a journal whose last matching item ends at or below max_size.

Initialization durably discards the suffix before returning. A cap below retained history, or pruned history with no matching retained item, returns a pruning error.

Trait Implementations

impl<F, E, C, H, S> Contiguous for Journal<F, E, C, H, S>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher, S: Strategy,

type Item = <C as Contiguous>::Item

The type of items stored in the journal.

fn bounds(&self) -> Range<u64>

Returns [start, end) with a guaranteed stable pruning boundary.

async fn read(&self, position: u64) -> Result<C::Item, JournalError>

Read the item at the given position.

async fn read_many( &self, positions: &[u64], ) -> Result<Vec<C::Item>, JournalError>

Read multiple items at the given positions, which must be strictly increasing.

fn try_read_sync(&self, position: u64) -> Option<C::Item>

Read an item if it can be done synchronously (e.g. without I/O), returning None otherwise. Decode failures surface as None and the async read path reports the error.

fn try_read_many_sync(&self, positions: &[u64]) -> Vec<Option<C::Item>>

Probe multiple strictly increasing positions, serving those that can be read synchronously (e.g. from a page cache) and returning one slot per position. Positions that require I/O, fail to decode, or fall outside bounds() decline to None. The async read paths are the sole error authority for declined positions.

async fn replay( &self, range: Range<u64>, buffer: NonZeroUsize, read_options: ReadOptions, ) -> Result<impl Stream<Item = Result<Batch<C::Item>, JournalError>> + Send, JournalError>

Return a stream of the items in range as Batches of consecutive items, in position order. range must fall within bounds(). An empty range within bounds() yields an empty stream.

impl<F, E, C, H, S> Debug for Journal<F, E, C, H, S>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared>, H: Hasher, S: Strategy,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<F, E, C, H, S> Mutable for Journal<F, E, C, H, S>

where F: Family, E: Context, C: Mutable<Item: EncodeShared>, H: Hasher, S: Strategy,

async fn append(self, item: &Self::Item) -> Result<(Self, u64), JournalError>

Append a new item to the journal, returning its position.

async fn append_many( self, items: Many<'_, Self::Item>, ) -> Result<(Self, u64), JournalError>

Append items to the journal, returning the position of the last item appended.

async fn prune(self, min_position: u64) -> Result<(Self, bool), JournalError>

Prune items at positions strictly less than min_position.

async fn start_sync(self) -> Result<(Self, Handle<()>), JournalError>

Begin durably persisting the current state of the journal.

async fn commit(self) -> Result<Self, JournalError>

Durably persist the journal, guaranteeing the current state will survive a crash.

async fn sync(self) -> Result<Self, JournalError>

Durably persist the journal, guaranteeing the current state will survive a crash, and that no recovery will be needed on startup.

async fn destroy(self) -> Result<(), JournalError>

Destroy the journal, removing all associated storage.

impl<F, E, C, H, S> Source for Journal<F, E, C, H, S>

where F: Family, E: Context, C: Contiguous<Item: EncodeShared + Floored<F>>, H: Hasher, S: Strategy,

type Family = F

The merkle family backing this source’s proofs.

type Digest = <H as Hasher>::Digest

The digest type used in this source’s proofs.

type Op = <C as Contiguous>::Item

The type of operations this source yields.

type Error = Error<F>

Why this source could not answer.

async fn serve(&self, request: Request<F>) -> Result<Self>

Serves a response with optional Feedback for reporting its validity.