commonware_resolver/
lib.rs

1//! Resolve data identified by a fixed-length key.
2
3#![doc(
4    html_logo_url = "https://commonware.xyz/imgs/rustdoc_logo.svg",
5    html_favicon_url = "https://commonware.xyz/favicon.ico"
6)]
7
8use commonware_cryptography::PublicKey;
9use commonware_utils::{vec::NonEmptyVec, Span};
10use std::future::Future;
11
12pub mod p2p;
13
14/// Notified when data is available, and must validate it.
15pub trait Consumer: Clone + Send + 'static {
16    /// Type used to uniquely identify data.
17    type Key: Span;
18
19    /// Type of data to retrieve.
20    type Value;
21
22    /// Type used to indicate why data is not available.
23    type Failure;
24
25    /// Deliver data to the consumer.
26    ///
27    /// Returns `true` if the data is valid.
28    fn deliver(&mut self, key: Self::Key, value: Self::Value) -> impl Future<Output = bool> + Send;
29
30    /// Let the consumer know that the data is not being fetched anymore.
31    ///
32    /// The failure is used to indicate why.
33    fn failed(&mut self, key: Self::Key, failure: Self::Failure)
34        -> impl Future<Output = ()> + Send;
35}
36
37/// Responsible for fetching data and notifying a `Consumer`.
38pub trait Resolver: Clone + Send + 'static {
39    /// Type used to uniquely identify data.
40    type Key: Span;
41
42    /// Type used to identify peers for targeted fetches.
43    type PublicKey: PublicKey;
44
45    /// Initiate a fetch request for a single key.
46    fn fetch(&mut self, key: Self::Key) -> impl Future<Output = ()> + Send;
47
48    /// Initiate a fetch request for a batch of keys.
49    fn fetch_all(&mut self, keys: Vec<Self::Key>) -> impl Future<Output = ()> + Send;
50
51    /// Initiate a fetch request restricted to specific target peers.
52    ///
53    /// Only target peers are tried, there is no fallback to other peers. Targets
54    /// persist through transient failures (timeout, "no data" response, send failure)
55    /// since the peer might be slow or might receive the data later.
56    ///
57    /// If a fetch is already in progress for this key:
58    /// - If the existing fetch has targets, the new targets are added to the set
59    /// - If the existing fetch has no targets (can try any peer), it remains
60    ///   unrestricted (this call is ignored)
61    ///
62    /// To clear targeting and fall back to any peer, call [`fetch`](Self::fetch).
63    ///
64    /// Targets are automatically cleared when the fetch succeeds or is canceled.
65    /// When a peer is blocked (sent invalid data), only that peer is removed
66    /// from the target set.
67    fn fetch_targeted(
68        &mut self,
69        key: Self::Key,
70        targets: NonEmptyVec<Self::PublicKey>,
71    ) -> impl Future<Output = ()> + Send;
72
73    /// Initiate fetch requests for multiple keys, each with their own targets.
74    ///
75    /// See [`fetch_targeted`](Self::fetch_targeted) for details on target behavior.
76    fn fetch_all_targeted(
77        &mut self,
78        requests: Vec<(Self::Key, NonEmptyVec<Self::PublicKey>)>,
79    ) -> impl Future<Output = ()> + Send;
80
81    /// Cancel a fetch request.
82    fn cancel(&mut self, key: Self::Key) -> impl Future<Output = ()> + Send;
83
84    /// Cancel all fetch requests.
85    fn clear(&mut self) -> impl Future<Output = ()> + Send;
86
87    /// Retain only the fetch requests that satisfy the predicate.
88    fn retain(
89        &mut self,
90        predicate: impl Fn(&Self::Key) -> bool + Send + 'static,
91    ) -> impl Future<Output = ()> + Send;
92}
commonware_resolver/lib.rs

commonware_resolver/
lib.rs
