1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
// Copyright (c) 2026 Umberto Gotti
// SPDX-License-Identifier: MIT
//! **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
//!
//! ```rust
//! 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`](observer::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`](no_op_observer::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`](https://crates.io/crates/faction) keeps
//! membership, [`beggar`](https://crates.io/crates/beggar) recovery, `notary`
//! credentials (not yet built), and [`cartel`](https://crates.io/crates/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](https://github.com/umbgtt10/beggar#readme) -- the overview: how it works, validation, project status
//! * [Specification](https://github.com/umbgtt10/beggar/blob/main/spec/SPEC.md) -- normative: this crate is one implementation of it
//! * [Design](https://github.com/umbgtt10/beggar/blob/main/docs/DESIGN.md) -- the design
//! * [ADRs](https://github.com/umbgtt10/beggar/tree/main/docs/ADRs) -- the decisions, one per file
extern crate alloc;