pamoja_core/
transport.rs

1//! The transport abstraction: how bytes move between the SDK and a device or peer.
2
3use core::future::Future;
4
5use crate::error::Result;
6
7/// A bidirectional, topic-addressed message transport.
8///
9/// Implementations include MQTT, CoAP, LoRa, serial, and CAN. They are expected
10/// to handle reconnection and backpressure internally so that callers see a
11/// uniform, protocol-agnostic surface.
12///
13/// The returned futures are `Send`, so a transport can be driven from a task on
14/// a multi-threaded runtime and can be erased behind a trait object that is.
15/// Both matter in practice: a gateway ticks its links from spawned tasks, and a
16/// transport ladder holds rungs of different concrete types in one list. An
17/// implementation written as `async fn` satisfies this as long as everything it
18/// holds across an await is `Send`, which every transport here already is.
19pub trait Transport {
20    /// Establishes the connection to the broker, peer, or bus.
21    ///
22    /// # Returns
23    ///
24    /// `Ok(())` once the transport is connected and ready to carry traffic.
25    ///
26    /// # Errors
27    ///
28    /// Returns [`Error::Transport`](crate::Error::Transport) if the connection
29    /// cannot be established.
30    fn connect(&mut self) -> impl Future<Output = Result<()>> + Send;
31
32    /// Publishes a payload to a topic.
33    ///
34    /// # Arguments
35    ///
36    /// * `topic` - the destination topic or channel address.
37    /// * `payload` - the raw bytes to publish.
38    ///
39    /// # Returns
40    ///
41    /// `Ok(())` once the payload has been handed to the transport for delivery.
42    ///
43    /// # Errors
44    ///
45    /// Returns [`Error::Transport`](crate::Error::Transport) if the payload cannot
46    /// be sent, or [`Error::Closed`](crate::Error::Closed) if the transport is not
47    /// connected.
48    fn send(&mut self, topic: &str, payload: &[u8]) -> impl Future<Output = Result<()>> + Send;
49
50    /// Subscribes to a topic so that matching payloads are routed to this transport.
51    ///
52    /// # Arguments
53    ///
54    /// * `topic` - the topic or channel filter to subscribe to.
55    ///
56    /// # Returns
57    ///
58    /// `Ok(())` once the subscription is registered with the transport.
59    ///
60    /// # Errors
61    ///
62    /// Returns [`Error::Transport`](crate::Error::Transport) if the subscription
63    /// is rejected, or [`Error::Closed`](crate::Error::Closed) if the transport is
64    /// not connected.
65    fn subscribe(&mut self, topic: &str) -> impl Future<Output = Result<()>> + Send;
66}
pamoja_core/transport.rs

pamoja_core/
transport.rs
