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

commonware_resolver/
lib.rs
