pamoja_loopback/lib.rs
1//! An in-process loopback transport for hardware-free testing and examples.
2//!
3//! [`LoopbackTransport`] implements the core [`Transport`](pamoja_core::Transport)
4//! and [`Receive`](pamoja_core::Receive) traits against a shared in-memory
5//! [`LoopbackBroker`] instead of a network, so examples, the simulators, and the
6//! cross-language conformance scenarios can exercise the full publish/subscribe
7//! path with no broker process and no hardware. Topic filters follow MQTT
8//! semantics, including the `+` single-level and `#` multi-level wildcards.
9//!
10//! Clone one broker into every transport that should share a namespace: a publish
11//! on any transport is delivered to every transport whose subscriptions match.
12//!
13//! [`Faulty`] decorates any transport to inject send failures, so degraded-link
14//! behavior such as store-and-forward retry can be tested deterministically.
15//!
16//! # Examples
17//!
18//! A sensor and a gateway on one broker, with no network between them: the gateway
19//! subscribes to every node's temperature, and a reading published by one node reaches it.
20//!
21//! ```
22//! use pamoja_core::{Receive, Transport};
23//! use pamoja_loopback::{LoopbackBroker, LoopbackTransport};
24//!
25//! # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(async {
26//! let broker = LoopbackBroker::new();
27//! let mut gateway = LoopbackTransport::new(broker.clone());
28//! let mut sensor = LoopbackTransport::new(broker);
29//! gateway.connect().await?;
30//! sensor.connect().await?;
31//!
32//! gateway.subscribe("sensors/+/temperature").await?;
33//! sensor.send("sensors/7/temperature", b"21.5").await?;
34//!
35//! let reading = gateway.recv().await?.expect("the reading arrives");
36//! assert_eq!(reading.topic, "sensors/7/temperature");
37//! assert_eq!(reading.payload, b"21.5");
38//! # Ok::<(), pamoja_core::Error>(())
39//! # }).unwrap();
40//! ```
41
42mod broker;
43mod faulty;
44mod transport;
45
46pub use broker::LoopbackBroker;
47pub use faulty::Faulty;
48pub use pamoja_core::Message;
49pub use transport::LoopbackTransport;