kitsune2_api/
gossip.rs

1//! Gossip related types.
2
3use crate::fetch::DynFetch;
4use crate::peer_store::DynPeerStore;
5use crate::transport::DynTransport;
6use crate::{
7    builder, config, BoxFut, DhtArc, DynLocalAgentStore, DynOpStore,
8    DynPeerMetaStore, K2Result, SpaceId, StoredOp, Timestamp, Url,
9};
10use serde::{Deserialize, Serialize};
11use std::collections::HashMap;
12use std::sync::Arc;
13
14/// Request for a gossip state summary.
15#[derive(Debug, Clone)]
16pub struct GossipStateSummaryRequest {
17    /// Include DHT summary in the response.
18    pub include_dht_summary: bool,
19}
20
21/// Represents the ability to sync DHT data with other agents through background communication.
22pub trait Gossip: 'static + Send + Sync + std::fmt::Debug {
23    /// Inform the gossip module that a set of ops have been stored.
24    ///
25    /// This is not expected to be called directly. It is intended to be used by the
26    /// space that owns this gossip module. See [crate::space::Space::inform_ops_stored].
27    fn inform_ops_stored(&self, ops: Vec<StoredOp>)
28        -> BoxFut<'_, K2Result<()>>;
29
30    /// Get a state summary from the gossip module.
31    fn get_state_summary(
32        &self,
33        request: GossipStateSummaryRequest,
34    ) -> BoxFut<'_, K2Result<GossipStateSummary>>;
35}
36
37/// Trait-object [Gossip].
38pub type DynGossip = Arc<dyn Gossip>;
39
40/// A factory for constructing [Gossip] instances.
41pub trait GossipFactory: 'static + Send + Sync + std::fmt::Debug {
42    /// Help the builder construct a default config from the chosen
43    /// module factories.
44    fn default_config(&self, config: &mut config::Config) -> K2Result<()>;
45
46    /// Validate configuration.
47    fn validate_config(&self, config: &config::Config) -> K2Result<()>;
48
49    /// Construct a gossip instance.
50    #[allow(clippy::too_many_arguments)]
51    fn create(
52        &self,
53        builder: Arc<builder::Builder>,
54        space_id: SpaceId,
55        peer_store: DynPeerStore,
56        local_agent_store: DynLocalAgentStore,
57        peer_meta_store: DynPeerMetaStore,
58        op_store: DynOpStore,
59        transport: DynTransport,
60        fetch: DynFetch,
61    ) -> BoxFut<'static, K2Result<DynGossip>>;
62}
63
64/// Trait-object [GossipFactory].
65pub type DynGossipFactory = Arc<dyn GossipFactory>;
66
67/// DHT segment state.
68#[derive(Debug, Clone, Serialize, Deserialize)]
69pub struct DhtSegmentState {
70    /// The top hash of the DHT ring segment.
71    pub disc_top_hash: bytes::Bytes,
72    /// The boundary timestamp of the DHT ring segment.
73    pub disc_boundary: Timestamp,
74    /// The top hashes of each DHT ring segment.
75    pub ring_top_hashes: Vec<bytes::Bytes>,
76}
77
78/// Peer metadata dump.
79#[derive(Debug, Clone, Serialize, Deserialize)]
80pub struct PeerMeta {
81    /// The timestamp of the last gossip round.
82    pub last_gossip_timestamp: Option<Timestamp>,
83    /// The bookmark of the last op bookmark received.
84    pub new_ops_bookmark: Option<Timestamp>,
85    /// The number of behavior errors observed.
86    pub peer_behavior_errors: Option<u32>,
87    /// The number of local errors.
88    pub local_errors: Option<u32>,
89    /// The number of busy peer errors.
90    pub peer_busy: Option<u32>,
91    /// The number of terminated rounds.
92    ///
93    /// Note that termination is not necessarily an error.
94    pub peer_terminated: Option<u32>,
95    /// The number of completed rounds.
96    pub completed_rounds: Option<u32>,
97    /// The number of peer timeouts.
98    pub peer_timeouts: Option<u32>,
99    /// Whether this peer has declared itself as offline, and no longer reachable, with a tombstone.
100    pub is_tombstone: bool,
101    /// The storage arc that this peer is declaring.
102    pub storage_arc: DhtArc,
103}
104
105/// Gossip round state summary.
106#[derive(Debug, Clone, Serialize, Deserialize)]
107pub struct GossipRoundStateSummary {
108    /// The URL of the peer with which the round is initiated.
109    pub session_with_peer: Url,
110}
111
112/// Gossip state summary.
113#[derive(Debug, Clone, Serialize, Deserialize)]
114pub struct GossipStateSummary {
115    /// The current initiated round summary.
116    pub initiated_round: Option<GossipRoundStateSummary>,
117    /// The list of accepted round summaries.
118    pub accepted_rounds: Vec<GossipRoundStateSummary>,
119    /// DHT summary.
120    pub dht_summary: HashMap<String, DhtSegmentState>,
121    /// Peer metadata dump for each agent in this space.
122    pub peer_meta: HashMap<Url, PeerMeta>,
123}
kitsune2_api/gossip.rs

kitsune2_api/
gossip.rs
