|
4 | 4 | //! For an async approach the stream has to implement the `AsyncRead` and `AsyncWrite` traits.
|
5 | 5 | //! That is [`::tokio::io::AsyncRead`] and [`::tokio::io::AsyncWrite`] for tokio and [`::smol::io::AsyncRead`] and [`::smol::io::AsyncWrite`] for smol.
|
6 | 6 | //!
|
| 7 | +//! |
| 8 | +//! |
7 | 9 | //! Features:
|
8 | 10 | //! ----------------------------
|
9 |
| -//! - MQTT v5 |
10 |
| -//! - Runtime agnostic (Smol, Tokio) |
11 |
| -//! - Packets are acknoledged after handler has processed them |
12 |
| -//! - Runs on just a stream so you can use all TCP backends |
13 |
| -//! - Lean |
14 |
| -//! - Keep alive depends on actual communication |
| 11 | +//! - MQTT v5 |
| 12 | +//! - Runtime agnostic (Smol, Tokio) |
| 13 | +//! - Sync |
| 14 | +//! - TLS/TCP |
| 15 | +//! - Lean |
| 16 | +//! - Keep alive depends on actual communication |
| 17 | +//! - This tokio implemention has been fuzzed using cargo-fuzz! |
| 18 | +//! |
| 19 | +//! To do: |
| 20 | +//! ---------------------------- |
| 21 | +//! - Even More testing |
| 22 | +//! - Add TLS examples to repository |
15 | 23 | //!
|
16 |
| -//! To do |
| 24 | +//! Minimum Supported Rust Version (MSRV): |
17 | 25 | //! ----------------------------
|
18 |
| -//! - Even More testing |
| 26 | +//! From 0.3 the tokio and smol variants will require MSRV: 1.75 due to async fn in trait feature. |
19 | 27 | //!
|
20 | 28 | //! Notes:
|
21 | 29 | //! ----------------------------
|
22 |
| -//! - Handlers only get incoming packets |
| 30 | +//! - Your handler should not wait too long |
23 | 31 | //! - Create a new connection when an error or disconnect is encountered
|
| 32 | +//! - Handlers only get incoming packets |
24 | 33 | //!
|
25 | 34 | //! Smol example:
|
26 | 35 | //! ----------------------------
|
27 | 36 | //! ```rust
|
28 |
| -//! use mqrstt::{ |
29 |
| -//! MqttClient, |
30 |
| -//! example_handlers::NOP, |
31 |
| -//! ConnectOptions, |
32 |
| -//! packets::{self, Packet}, |
33 |
| -//! AsyncEventHandler, |
34 |
| -//! NetworkStatus, |
35 |
| -//! NetworkBuilder, |
36 |
| -//! }; |
| 37 | +//! use mqrstt::{example_handlers::NOP, NetworkBuilder, NetworkStatus}; |
37 | 38 | //!
|
38 | 39 | //! smol::block_on(async {
|
39 | 40 | //! // Construct a no op handler
|
40 |
| -//! let mut nop = NOP{}; |
| 41 | +//! let mut nop = NOP {}; |
41 | 42 | //!
|
42 | 43 | //! // In normal operations you would want to loop this connection
|
43 | 44 | //! // To reconnect after a disconnect or error
|
44 |
| -//! let (mut network, client) = NetworkBuilder |
45 |
| -//! ::new_from_client_id("mqrsttSmolExample") |
46 |
| -//! .smol_network(); |
47 |
| -//! let stream = smol::net::TcpStream::connect(("broker.emqx.io", 1883)) |
48 |
| -//! .await |
49 |
| -//! .unwrap(); |
| 45 | +//! let (mut network, client) = NetworkBuilder::new_from_client_id("mqrsttSmolExample").smol_network(); |
| 46 | +//! let stream = smol::net::TcpStream::connect(("broker.emqx.io", 1883)).await.unwrap(); |
50 | 47 | //! network.connect(stream, &mut nop).await.unwrap();
|
51 |
| -//! |
| 48 | +//! |
52 | 49 | //! // This subscribe is only processed when we run the network
|
53 | 50 | //! client.subscribe("mqrstt").await.unwrap();
|
54 | 51 | //!
|
55 |
| -//! let (n, t) = futures::join!( |
56 |
| -//! network.run(&mut nop), |
57 |
| -//! async { |
58 |
| -//! smol::Timer::after(std::time::Duration::from_secs(30)).await; |
59 |
| -//! client.disconnect().await.unwrap(); |
60 |
| -//! } |
61 |
| -//! ); |
62 |
| -//! assert!(n.is_ok()); |
| 52 | +//! let (result, _) = futures::join!(network.run(&mut nop), async { |
| 53 | +//! smol::Timer::after(std::time::Duration::from_secs(30)).await; |
| 54 | +//! client.disconnect().await.unwrap(); |
| 55 | +//! }); |
| 56 | +//! assert!(result.is_ok()); |
| 57 | +//! assert_eq!(result.unwrap(), NetworkStatus::OutgoingDisconnect); |
63 | 58 | //! });
|
64 | 59 | //! ```
|
65 | 60 | //!
|
|
68 | 63 | //! ----------------------------
|
69 | 64 | //! ```rust
|
70 | 65 | //! use mqrstt::{
|
71 |
| -//! MqttClient, |
72 | 66 | //! example_handlers::NOP,
|
73 |
| -//! ConnectOptions, |
74 |
| -//! packets::{self, Packet}, |
75 |
| -//! AsyncEventHandler, |
76 |
| -//! NetworkStatus, |
77 |
| -//! NetworkBuilder, |
| 67 | +//! NetworkBuilder, NetworkStatus, |
78 | 68 | //! };
|
| 69 | +//! |
79 | 70 | //! use tokio::time::Duration;
|
80 | 71 | //!
|
81 | 72 | //! #[tokio::main]
|
82 | 73 | //! async fn main() {
|
83 |
| -//! let (mut network, client) = NetworkBuilder |
84 |
| -//! ::new_from_client_id("TokioTcpPingPongExample") |
85 |
| -//! .tokio_network(); |
86 |
| -//! |
| 74 | +//! let (mut network, client) = NetworkBuilder::new_from_client_id("TokioTcpPingPongExample").tokio_network(); |
87 | 75 | //! // Construct a no op handler
|
88 |
| -//! let mut nop = NOP{}; |
89 |
| -//! |
| 76 | +//! let mut nop = NOP {}; |
90 | 77 | //! // In normal operations you would want to loop this connection
|
91 |
| -//! // To reconnect after a disconnect or error |
92 |
| -//! let stream = tokio::net::TcpStream::connect(("broker.emqx.io", 1883)) |
93 |
| -//! .await |
94 |
| -//! .unwrap(); |
| 78 | +//! // To reconnect after a disconnect or error |
| 79 | +//! let stream = tokio::net::TcpStream::connect(("broker.emqx.io", 1883)).await.unwrap(); |
95 | 80 | //! network.connect(stream, &mut nop).await.unwrap();
|
96 |
| -//! |
| 81 | +//! |
97 | 82 | //! client.subscribe("mqrstt").await.unwrap();
|
98 |
| -//! |
99 |
| -//! let (n, _) = futures::join!( |
100 |
| -//! network.run(&mut nop), |
101 |
| -//! async { |
102 |
| -//! tokio::time::sleep(Duration::from_secs(30)).await; |
103 |
| -//! client.disconnect().await.unwrap(); |
104 |
| -//! } |
105 |
| -//! ); |
106 |
| -//! assert!(n.is_ok()); |
| 83 | +//! // Run the network |
| 84 | +//! let network_handle = tokio::spawn(async move { network.run(&mut nop).await }); |
| 85 | +//! |
| 86 | +//! tokio::time::sleep(Duration::from_secs(30)).await; |
| 87 | +//! client.disconnect().await.unwrap(); |
| 88 | +//! let result = network_handle.await; |
| 89 | +//! assert!(result.is_ok()); |
| 90 | +//! assert_eq!(result.unwrap().unwrap(), NetworkStatus::OutgoingDisconnect); |
107 | 91 | //! }
|
108 | 92 | //! ```
|
109 | 93 |
|
|
0 commit comments