Skip to main content

Crate beggar

Crate beggar 

Source
Expand description

A no_std, zero-unsafe, protocol-independent recovery registry.

A recovery is a collection of chunks – a request for blocks, a lagging follower’s missing log entries, a snapshot sent in pieces – and beggar accounts for which of them have moved, at both ends of a transfer. It knows sessions, chunk counts, chunk ids and node ids, and nothing else: what a chunk holds, in what order chunks move, which protocol moves them and under what policy are the caller’s.

All five slices are built – conformant to version 0.7.0 of the specification in the repository’s spec/.

§What it does

Both ends of a transfer: StartRecovery and SendRecoveryPartial on the side that holds the chunks, AdoptRecovery and ReceiveRecoveryPartial on the other, each accounting the session to completion; CancelRecovery, which ends a session for a reason of the caller’s own type, recorded and never read; the queries – ListRecoveries, ShowRecovery, ListMissingChunks, and ShowRegistry, the checkpoint. An instance is created fresh, or from a checkpoint for a replay.

A finished session – completed or cancelled – is evicted; the instance’s retention keeps that many of them, the latest to finish, as they stood, for the queries to read. It changes what a query answers and nothing else, and it has no default: every instance states its own, 0 where nothing is to be kept. An optional bound on open sessions refuses an open past it.

Recovery is a supplicant – a node that fell behind asks, the peer may refuse, and if ignored its only recourse is to ask again – which is why the crate is not called sync or catchup.

§Why beggar

  • Deterministic – every output is a function of the command and the session’s record
  • Specified – a normative specification with conformance vectors; this crate is one implementation of it
  • Replayable – every receipt is numbered by beggar, so a log rebuilds the registry and a gap proves a lost line
  • Zero unsafe – #![forbid(unsafe_code)]
  • no_std + alloc – a session’s size follows the gaps in what has arrived, not its chunk count, so it runs on a microcontroller as on a server

§Example

use beggar::beggar::Beggar;
use beggar::command::Command;
use beggar::fresh::Fresh;
use beggar::instance_id::InstanceId;
use beggar::no_op_observer::NoOpObserver;
use beggar::origin::Origin;
use beggar::output::Output;

// The caller's own reasons for giving a transfer up: beggar records them and
// never reads them.
#[derive(Debug, Clone, PartialEq, Eq)]
enum Reason {
    PeerFailed,
}

fn fresh(node: u64) -> Beggar<Reason> {
    Beggar::new(
        Origin::Fresh(Fresh { instance: InstanceId { node, incarnation: 1 }, retention: 0, bound: None }),
        Box::new(NoOpObserver),
    )
}

// Node 1 holds ten chunks node 2 lacks: it starts the session, and beggar names it.
let mut sender = fresh(1);
let Output::RecoveryStarted { session_id } = sender
    .process(Command::StartRecovery { chunks: 10, sender: 1, receiver: 2 })
    .output
else {
    unreachable!("a fresh registry starts a well-formed session")
};

// Node 2 adopts the session under that name, with the count node 1 stated.
let mut receiver = fresh(2);
let _ = receiver.process(Command::AdoptRecovery { session_id, chunks: 10, sender: 1, receiver: 2 });

// Chunks 1 to 6 move; each end records the run on its own side.
let _ = sender.process(Command::SendRecoveryPartial { session_id, first: 1, last: 6, sender: 1, receiver: 2 });
let receipt =
    receiver.process(Command::ReceiveRecoveryPartial { session_id, first: 1, last: 6, sender: 1, receiver: 2 });
assert_eq!(receipt.output, Output::RecoveryAdvanced { held: 6, chunks: 10 });

// What node 2 still lacks, as maximal runs.
let missing = receiver.process(Command::ListMissingChunks { session_id }).output;
assert_eq!(missing, Output::MissingChunksListed { missing: vec![7..=10] });

// The rest arrives, and the session completes.
let receipt =
    receiver.process(Command::ReceiveRecoveryPartial { session_id, first: 7, last: 10, sender: 1, receiver: 2 });
assert_eq!(receipt.output, Output::RecoveryCompleted);

// Node 1 gives up on its end, for a reason of its own.
let receipt = sender.process(Command::CancelRecovery { session_id, reason: Reason::PeerFailed });
assert_eq!(receipt.output, Output::RecoveryCancelled(Reason::PeerFailed));

§Observer

Every call is reported to the Observer the instance is constructed with: the command and its receipt, once, by the time process returns. It answers nothing, so beggar’s answers do not depend on it. NoOpObserver is provided for the “just drive it” case.

§Siblings

Beggar is one of four bookkeepers a consensus protocol orchestrates, none aware of the others: faction keeps membership, beggar recovery, notary credentials (not yet built), and cartel consensus. All are no_std, protocol-independent and specified, each with one entry point and an observer. Faction is a state machine; beggar, like cartel, is a registry: every outcome is a function of the command and the session’s record.

§Further reading

  • README – the overview: how it works, validation, project status
  • Specification – normative: this crate is one implementation of it
  • Design – the design
  • ADRs – the decisions, one per file

Modules§

beggar
checkpoint
chunk_set
command
fresh
instance_id
no_op_observer
observer
origin
output
receipt
registry
rejection
retained_record
rows
session_id
session_record
side