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

commonware_resolver/
lib.rs
