de_mls/ds/
mod.rs

1//! Delivery Service — transport-agnostic messaging layer.
2//!
3//! This module defines the `DeliveryService` trait and its supporting types
4//! (`OutboundPacket`, `InboundPacket`, `DeliveryServiceError`), plus a concrete
5//! implementation backed by the Waku relay protocol (requires the **`waku`**
6//! cargo feature).
7//!
8//! # Architecture
9//!
10//! ```text
11//! src/ds/
12//! ├── transport.rs      DeliveryService trait, OutboundPacket, InboundPacket
13//! ├── error.rs          DeliveryServiceError
14//! ├── topic_filter.rs   TopicFilter (HashSet-based async allowlist)
15//! └── waku/             Waku relay implementation
16//!     ├── mod.rs        WakuDeliveryService, WakuConfig, content-topic helpers
17//!     ├── sys.rs        Raw FFI bindings to libwaku (C trampoline pattern)
18//!     └── wrapper.rs    Safe synchronous WakuNodeCtx wrapper
19//! ```
20//!
21//! # Usage (requires `waku` feature)
22//!
23//! ```rust,ignore
24//! use de_mls::ds::{WakuDeliveryService, WakuConfig, DeliveryService, OutboundPacket};
25//!
26//! // Start the node — blocks until the embedded Waku node is ready.
27//! let result = WakuDeliveryService::start(WakuConfig {
28//!     node_port: 60000,
29//!     discv5: true,
30//!     discv5_udp_port: 61000,
31//!     ..Default::default()
32//! })?;
33//!
34//! // The local ENR can be passed to other nodes for bootstrapping.
35//! if let Some(enr) = &result.enr {
36//!     println!("Share this ENR with peers: {enr}");
37//! }
38//!
39//! let ds = result.service;
40//!
41//! // Subscribe to inbound messages (multiple subscribers allowed).
42//! let rx = ds.subscribe();
43//! std::thread::spawn(move || {
44//!     while let Ok(pkt) = rx.recv() {
45//!         println!("got {} bytes for group {}", pkt.payload.len(), pkt.group_id);
46//!     }
47//! });
48//!
49//! // Send a message.
50//! ds.send(OutboundPacket::new(
51//!     b"hello".to_vec(),
52//!     "app_msg",
53//!     "my-group",
54//!     b"app-instance-id",
55//! ))?;
56//!
57//! // Explicit shutdown (or just drop all clones).
58//! ds.shutdown();
59//! # Ok::<(), de_mls::ds::DeliveryServiceError>(())
60//! ```
61//!
62//! # Threading model
63//!
64//! The entire DS layer is **synchronous** — no tokio dependency. The Waku
65//! implementation runs an embedded node on a dedicated `std::thread`. Callers
66//! in an async context should wrap `DeliveryService::send` in
67//! `tokio::task::spawn_blocking`.
68
69mod error;
70mod topic_filter;
71mod transport;
72
73#[cfg(feature = "waku")]
74mod waku;
75
76/// Protocol version embedded in content topics.
77pub const GROUP_VERSION: &str = "1";
78/// Subtopic identifier for application messages.
79pub const APP_MSG_SUBTOPIC: &str = "app_msg";
80/// Subtopic identifier for MLS welcome messages.
81pub const WELCOME_SUBTOPIC: &str = "welcome";
82/// All subtopics that each group subscribes to.
83pub const SUBTOPICS: [&str; 2] = [APP_MSG_SUBTOPIC, WELCOME_SUBTOPIC];
84
85pub use error::DeliveryServiceError;
86pub use topic_filter::TopicFilter;
87pub use transport::{DeliveryService, InboundPacket, OutboundPacket};
88
89#[cfg(feature = "waku")]
90pub use waku::{
91    WakuConfig, WakuDeliveryService, WakuStartResult, build_content_topic, build_content_topics,
92    pubsub_topic,
93};
de_mls/ds/mod.rs

de_mls/ds/
mod.rs
