memberlist_plumtree/
lib.rs

1//! # memberlist-plumtree
2//!
3//! Plumtree (Epidemic Broadcast Trees) implementation built on top of memberlist.
4//!
5//! Plumtree combines the efficiency of tree-based broadcast (O(n) messages) with
6//! the reliability of gossip protocols through a hybrid push/lazy-push approach.
7//!
8//! ## How Plumtree Works
9//!
10//! - **Eager Push**: Full messages are sent along spanning tree edges (eager peers)
11//! - **Lazy Push**: Message announcements (IHave) are sent to non-tree peers (lazy peers)
12//! - **Self-Healing**: When a node receives an IHave for a missing message, it grafts
13//!   the sender into its eager set, automatically repairing the tree
14//!
15//! ## Example
16//!
17//! ```ignore
18//! use memberlist_plumtree::{Plumtree, PlumtreeConfig, PlumtreeDelegate};
19//! use bytes::Bytes;
20//!
21//! // Define a delegate to receive messages
22//! struct MyDelegate;
23//! impl PlumtreeDelegate for MyDelegate {
24//!     fn on_deliver(&self, msg_id: MessageId, payload: Bytes) {
25//!         println!("Received message: {:?}", payload);
26//!     }
27//! }
28//!
29//! // Create Plumtree instance
30//! let (plumtree, handle) = Plumtree::new(
31//!     node_id,
32//!     PlumtreeConfig::lan(),
33//!     MyDelegate,
34//! );
35//!
36//! // Add peers (from memberlist membership)
37//! plumtree.add_peer(peer_id);
38//!
39//! // Broadcast a message to all nodes
40//! let msg_id = plumtree.broadcast(b"hello world").await?;
41//! ```
42
43#![cfg_attr(docsrs, feature(doc_cfg))]
44#![deny(missing_docs)]
45#![allow(clippy::type_complexity)]
46
47mod adaptive_batcher;
48mod bridge;
49mod cleanup_tuner;
50mod config;
51mod error;
52mod health;
53mod integration;
54mod message;
55mod peer_scoring;
56mod peer_state;
57
58mod plumtree;
59mod pooled_transport;
60mod rate_limiter;
61mod runner;
62mod scheduler;
63pub mod testing;
64mod transport;
65
66#[cfg(feature = "metrics")]
67mod metrics;
68
69#[cfg(test)]
70mod peer_state_test;
71
72// Re-export adaptive batcher types
73pub use adaptive_batcher::{AdaptiveBatcher, BatcherConfig, BatcherStats};
74
75// Re-export cleanup tuner types
76pub use cleanup_tuner::{
77    BackpressureHint, CleanupConfig, CleanupParameters, CleanupReason, CleanupStats, CleanupTuner,
78    EfficiencyTrend, PressureTrend,
79};
80
81// Re-export config types
82pub use config::PlumtreeConfig;
83
84// Re-export error types
85pub use error::{Error, ErrorKind, Result};
86
87// Re-export health types
88pub use health::{
89    CacheHealth, DeliveryHealth, HealthReport, HealthReportBuilder, HealthStatus, PeerHealth,
90};
91
92// Re-export message types
93pub use message::{
94    CacheStats, MessageCache, MessageId, MessageTag, PlumtreeMessage, PlumtreeMessageRef,
95};
96
97// Re-export peer state types
98pub use peer_state::{
99    AddPeerResult, PeerState, PeerStateBuilder, PeerStats, PeerTopology, RemovePeerResult,
100};
101
102// Re-export peer scoring types
103pub use peer_scoring::{PeerScore, PeerScoring, ScoringConfig, ScoringStats};
104
105// Re-export core plumtree types
106pub use plumtree::{
107    IncomingMessage, NoopDelegate, OutgoingMessage, Plumtree, PlumtreeDelegate, PlumtreeHandle,
108    SeenMapStats,
109};
110
111// Re-export runner types
112pub use runner::{create_plumtree_with_channels, PlumtreeRunnerWithTransport};
113
114// Re-export deprecated runner for backwards compatibility
115#[allow(deprecated)]
116pub use runner::{PlumtreeRunner, PlumtreeRunnerBuilder};
117
118// Re-export integration types
119pub use integration::{
120    decode_plumtree_envelope, decode_plumtree_message, encode_plumtree_envelope,
121    encode_plumtree_envelope_into, encode_plumtree_message, envelope_encoded_len,
122    is_plumtree_message, BroadcastEnvelope, IdCodec, PlumtreeEventHandler, PlumtreeMemberlist,
123    PlumtreeNodeDelegate,
124};
125
126// Re-export scheduler types
127pub use scheduler::{ExpiredGraft, GraftTimer, IHaveQueue, IHaveScheduler, PendingIHave};
128
129// Re-export rate limiter types
130pub use rate_limiter::{GlobalRateLimiter, RateLimiter};
131
132// Re-export transport types
133pub use transport::{ChannelTransport, ChannelTransportError, NoopTransport, Transport};
134
135// Re-export QUIC transport types (requires "quic" feature)
136#[cfg(feature = "quic")]
137#[cfg_attr(docsrs, doc(cfg(feature = "quic")))]
138pub use transport::quic::{
139    CongestionConfig, CongestionController, ConnectionConfig, ConnectionStats, MapPeerResolver,
140    MessagePriorities, MigrationConfig, PeerResolver, PlumtreeQuicConfig, QuicConfig, QuicError,
141    QuicStats, QuicTransport, StreamConfig, TlsConfig, ZeroRttConfig,
142};
143
144// Re-export pooled transport types
145pub use pooled_transport::{PoolConfig, PoolStats, PooledTransport, PooledTransportError};
146
147// Re-export scheduler failure types
148pub use scheduler::FailedGraft;
149
150// Re-export bridge types for Plumtree-Memberlist integration
151pub use bridge::{
152    AddressExtractor, BridgeConfig, BridgeEventDelegate, LazarusHandle, LazarusStats,
153    MemberlistStack, MemberlistStackError, PlumtreeBridge, PlumtreeStackBuilder,
154};
155
156// Re-export persistence module for peer state recovery
157pub use bridge::persistence;
158
159/// Re-export memberlist-core types for convenience
160pub mod memberlist {
161    pub use memberlist_core::*;
162}
memberlist_plumtree/lib.rs

memberlist_plumtree/
lib.rs
