Struct Keyless 

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

A keyless authenticated database.

Implementations

impl<F: Family, E: Context, V: FixedValue, H: Hasher, S: Strategy> Keyless<F, E, FixedEncoding<V>, Journal<E, Operation<F, FixedEncoding<V>>>, H, S>

pub async fn init(context: E, cfg: Config<S>) -> Result<Self, Error<F>>

Returns a Db initialized from cfg. Any uncommitted operations will be discarded and the state of the db will be as of the last committed operation.

impl<F: Family, E: Context, V: VariableValue, H: Hasher, S: Strategy> Keyless<F, E, VariableEncoding<V>, Journal<E, Operation<F, VariableEncoding<V>>>, H, S>

pub async fn init( context: E, cfg: Config<<Operation<F, V> as Read>::Cfg, S>, ) -> Result<Self, Error<F>>

Returns a Db initialized from cfg. Any uncommitted operations will be discarded and the state of the db will be as of the last committed operation.

impl<F, E, V, C, H, S> Keyless<F, E, V, C, H, S>

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

pub async fn get(&self, loc: Location<F>) -> Result<Option<V::Value>, Error<F>>

Get the value at location loc in the database.

Errors

Returns Error::LocationOutOfBounds if loc >= self.bounds().end.

pub async fn get_many( &self, locs: &[Location<F>], ) -> Result<Vec<Option<V::Value>>, Error<F>>

Batch read values at multiple locations.

Locations must be strictly increasing. Returns results in the same order as the input locations.

Errors

Returns Error::LocationOutOfBounds if any location >= bounds().end.

pub const fn last_commit_loc(&self) -> Location<F>

Returns the location of the last commit.

pub const fn inactivity_floor_loc(&self) -> Location<F>

Returns the inactivity floor declared by the last committed batch.

pub fn bounds(&self) -> Range<Location<F>>

Return [start, end) where start and end - 1 are the Locations of the oldest and newest retained operations respectively.

pub const fn sync_boundary(&self) -> Location<F>

Return the most recent location from which this database can safely be synced, and the upper bound on Self::prune’s loc. For keyless databases, this equals the inactivity floor declared by the last committed batch.

pub async fn get_metadata(&self) -> Result<Option<V::Value>, Error<F>>

Get the metadata associated with the last commit.

pub const fn root(&self) -> H::Digest

Return the root of the db.

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

Return a reference to the merkleization strategy.

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

Generate and return:

1. a proof of all operations applied to the db in the range starting at (and including) location start_loc, and ending at the first of either:
   • the last operation performed, or
   • the operation max_ops from the start.
2. the operations corresponding to the leaves in this range.

Errors

• Returns Error::Merkle with crate::merkle::Error::RangeOutOfBounds if start_loc

  = the number of operations.

• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc has been pruned.

pub async fn historical_proof( &self, op_count: Location<F>, start_loc: Location<F>, max_ops: NonZeroU64, ) -> Result<(Proof<F, H::Digest>, Vec<Operation<F, V>>), Error<F>>

Analogous to proof, but with respect to the state of the Merkle structure when it had op_count operations.

op_count must be the size of a commit boundary.

Errors

• Returns Error::Merkle with crate::merkle::Error::RangeOutOfBounds if start_loc

  = op_count or op_count > number of operations.

• Returns Error::Journal with crate::journal::Error::ItemPruned if start_loc has been pruned.
• Returns Error::HistoricalFloorPruned if op_count - 1 is retained but is not a commit op.

pub async fn pinned_nodes_at( &self, loc: Location<F>, ) -> Result<Vec<H::Digest>, Error<F>>

Return the pinned Merkle nodes for a lower operation boundary of loc.

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

Prune historical operations prior to loc. This does not affect the db’s root.

prune requires no prior commit. After a crash, the database remains recoverable; uncommitted operations are not guaranteed to survive.

Errors

• Returns Error::PruneBeyondMinRequired if loc > the inactivity floor.

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

Rewind the database to size operations, where size is the location of the next append.

This rewinds both the operations journal and its Merkle structure to the historical state at size. The inactivity floor is restored from the rewind target commit operation, so the post-rewind floor matches the floor that was in effect at that commit.

Errors

• Returns Error::Journal with crate::journal::Error::InvalidRewind if size is 0 or exceeds the current committed size.
• Returns Error::Journal with crate::journal::Error::ItemPruned if the operation at size - 1 has been pruned.
• Returns Error::UnexpectedData if the operation at size - 1 is not a commit.

Any error from this method is fatal for this handle. Rewind may mutate journal state before this method finishes updating in-memory rewind state. Callers must drop this database handle after any Err from rewind and reopen from storage.

A successful rewind is not restart-stable until a subsequent Self::commit or Self::sync completes, or until the handle returned by a subsequent Self::start_sync completes.

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

Sync all database state to disk. While this isn’t necessary to ensure durability of committed operations, periodic invocation may reduce memory usage and the time required to recover the database on restart.

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

Begin durably persisting the journal state published by prior Keyless::apply_batch calls.

Awaiting the returned Handle provides the same durability guarantee as Self::commit, plus a best-effort attempt to bound the recovery needed on startup. Use Self::sync to guarantee none is needed. A new sync waits for the prior sync before starting. Failures of the deferred durability work surface on the returned handle. A failed data sync also fails the next durability operation. A failed recovery-watermark sync is not observed by Self::commit, and a failed merkle-node sync may not be. Both resurface on the next Self::sync.

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

Durably commit the journal state published by prior Keyless::apply_batch calls.

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

Destroy the db, removing all data from disk.

pub fn new_batch(&self) -> UnmerkleizedBatch<F, H, V, S>

Create a new speculative batch of operations with this database as its parent.

pub fn to_batch(&self) -> Arc<MerkleizedBatch<F, H::Digest, V, S>>

Create an initial batch::MerkleizedBatch from the committed DB state.

pub fn validate_batch( &self, batch: &MerkleizedBatch<F, H::Digest, V, S>, ) -> Result<(), Error<F>>

Check that batch can be applied to the database in its current state, without applying it.

Self::apply_batch runs the same validation but consumes the database when it fails; callers that want to reject a bad batch and keep the handle can check first.

pub async fn apply_batch( self, batch: Arc<MerkleizedBatch<F, H::Digest, V, S>>, ) -> Result<(Self, Range<Location<F>>), Error<F>>

Apply a batch::MerkleizedBatch to the database.

A batch is valid only if every batch applied to the database since this batch’s ancestor chain was created is an ancestor of this batch. Applying a batch from a different fork returns Error::StaleBatch (see crate::qmdb::batch_chain for more details).

Every commit operation in the batch chain (each unapplied ancestor’s commit plus the tip’s) must satisfy two per-commit invariants:

1. The floor is monotonically non-decreasing across the chain, starting from the database’s current inactivity floor.
2. The floor is at most the commit operation’s own location (total_size - 1 at that point). A floor past the commit would let a later prune(floor) remove the last readable commit from the journal.

Violations return Error::FloorRegressed or Error::FloorBeyondSize identifying the offending floor and the bound it crossed (the prior validated floor, or the commit location, respectively). Floor validation happens before any journal mutation, so on floor errors the on-disk state is unchanged and reopening recovers the database as it was.

Returns the range of locations written.

This publishes the batch to the in-memory database state and appends it to the journal. Call Keyless::commit or Keyless::sync, or await the handle returned by Keyless::start_sync, to make the applied state durable.

Trait Implementations

impl<F, E, V, C, H, S> Database for Keyless<F, E, V, C, H, S>

where F: Family, E: Context, V: ValueEncoding + Codec, C: Mutable<Item = Operation<F, V>> + Journal<F, Context = E, Op = Operation<F, V>>, C::Config: Clone + Send, H: Hasher, S: Strategy, Operation<F, V>: EncodeShared,

async fn from_sync_result( context: Self::Context, config: Self::Config, log: Self::Journal, pinned_nodes: Option<Vec<Self::Digest>>, range: NonEmptyRange<Location<F>>, apply_batch_size: NonZeroU64, ) -> Result<Self, Error<F>>

Returns a Keyless db initialized from data collected in the sync process.

Behavior

This method handles different initialization scenarios based on existing data:

• If the Merkle journal is empty or the last item is before the range start, it creates a fresh Merkle structure from the provided pinned_nodes
• If the Merkle journal has data but is incomplete (has length < range end), missing operations from the log are applied to bring it up to the target state
• If the Merkle journal has data beyond the range end, it is rewound to match the sync target

Returns

A Keyless db populated with the state from the given range.

type Family = F

type Op = Operation<F, V>

type Journal = C

type Hasher = H

type Config = Config<<C as Journal<F>>::Config, S>

type Digest = <H as Hasher>::Digest

type Context = E

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

Persist any state that must remain provisional until the engine verifies the rebuilt root.

async fn local_pinned_nodes( context: Self::Context, config: &Self::Config, target: &Target<F, Self::Digest>, journal: &Self::Journal, ) -> Result<Option<Vec<Self::Digest>>, Error<F>>

Return locally available pinned nodes for the target, if persisted local state can authenticate them.

fn root(&self) -> Self::Digest

Get the root digest of the database for verification

impl<F, E, V, C, H, S> Debug for Keyless<F, E, V, C, H, S>

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

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

Formats the value using the given formatter.

impl<F, E, V, C, H, S> Source for Keyless<F, E, V, C, H, S>

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

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 = Operation<F, V>

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, Self::Op, Self::Digest>, FeedbackTx), Self::Error>

Serve a request.