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>

where C::Item: Encode,

Create a speculative batch atop this journal.

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.

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 from_components( merkle: Merkle<F, E, H::Digest, S>, journal: C, hasher: StandardHasher<H>, apply_batch_size: u64, ) -> Result<Self, Error<F>>

Create a new Journal from the given components after aligning the Merkle structure with the journal.

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 rewind(self, size: u64) -> Result<Self, Error<F>>

Rewind the journal and Merkle structure.

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

Prune both the Merkle structure and journal to the given location.

Returns

The new pruning boundary, which may be less than the requested prune_loc.

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 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::LocationOverflow if start_loc > Family::MAX_LEAVES.
• Returns Error::Merkle with merkle::Error::RangeOutOfBounds if start_loc >= current item count.
• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc 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 if start_loc 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 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, rewind_predicate: fn(&C::Item) -> bool, bagging: Bagging, ) -> Result<Self, Error<F>>

Create a new authenticated Journal.

The backing journal will be rewound to the last item matching rewind_predicate, and the merkle structure will be aligned to match.

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, start_pos: u64, buffer: NonZeroUsize, read_options: ReadOptions, ) -> Result<impl Stream<Item = Result<(u64, C::Item), JournalError>> + Send, JournalError>

Return a stream of all items starting from start_pos, bounded by bounds().

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 rewind(self, size: u64) -> Result<Self, JournalError>

Rewind the journal to the given size, discarding items from the end.

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.

fn rewind_to<P>( self, predicate: P, ) -> impl Future<Output = Result<(Self, u64), Error>> + Send

where P: FnMut(&Self::Item) -> bool + Send,

Rewinds the journal to the last item matching predicate, returning the resulting size. If no item matches, the journal is rewound to the pruning boundary, discarding all unpruned items.

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<(Response<F, C::Item, H::Digest>, FeedbackTx), Error<F>>

Serve a request.