commonware-collector 2026.5.0

Collect responses to committable requests.
Documentation 
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

//! Collect responses to [Committable] requests.
//!
//! # Status
//!
//! Stability varies by primitive. See [README](https://github.com/commonwarexyz/monorepo#stability) for details.

#![doc(
    html_logo_url = "https://commonware.xyz/imgs/rustdoc_logo.svg",
    html_favicon_url = "https://commonware.xyz/favicon.ico"
)]

commonware_macros::stability_scope!(ALPHA {
    use commonware_actor::Feedback;
    use commonware_codec::Codec;
    use commonware_cryptography::{Committable, Digestible, PublicKey};
    use commonware_p2p::Recipients;
    use commonware_utils::channel::oneshot;

    pub mod p2p;

    /// An [Originator] sends requests out to a set of [Handler]s and collects replies.
    pub trait Originator: Clone + Send + 'static {
        /// The [PublicKey] of a recipient.
        type PublicKey: PublicKey;

        /// The type of request to send.
        type Request: Committable + Digestible + Codec;

        /// Enqueues a `Request` to a set of [Recipients].
        fn send(
            &mut self,
            recipients: Recipients<Self::PublicKey>,
            request: Self::Request,
        ) -> Feedback;

        /// Enqueues cancellation of a request by `commitment`, ignoring any future responses.
        ///
        /// Tracked commitments are not removed until explicitly cancelled.
        fn cancel(&mut self, commitment: <Self::Request as Committable>::Commitment) -> Feedback;
    }

    /// A [Handler] receives requests and (optionally) sends replies.
    pub trait Handler: Clone + Send + 'static {
        /// The [PublicKey] of the [Originator].
        type PublicKey: PublicKey;

        /// The type of request received.
        type Request: Committable + Digestible + Codec;

        /// The type of response to send.
        type Response: Committable<Commitment = <Self::Request as Committable>::Commitment>
            + Digestible<Digest = <Self::Request as Digestible>::Digest>
            + Codec;

        /// Processes a `request` from an [Originator] and (optionally) send a response.
        ///
        /// If no response is needed, the `responder` should be dropped.
        fn process(
            &mut self,
            origin: Self::PublicKey,
            request: Self::Request,
            response: oneshot::Sender<Self::Response>,
        );
    }

    /// A [Monitor] collects responses from [Handler]s.
    pub trait Monitor: Clone + Send + 'static {
        /// The [PublicKey] of the [Handler].
        type PublicKey: PublicKey;

        /// The type of response collected.
        type Response: Committable + Digestible + Codec;

        /// Called for each response collected with the number of responses collected so far for
        /// the same commitment.
        ///
        /// [Monitor::collected] is only called once per `handler`.
        fn collected(
            &mut self,
            handler: Self::PublicKey,
            response: Self::Response,
            count: usize,
        );
    }
});