monocoque-rs 0.1.0

High-performance ZeroMQ-compatible messaging runtime built on io_uring
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

//! # Monocoque
//!
//! A high-performance, multi-protocol messaging runtime built on `io_uring`.
//!
//! ## Architecture
//!
//! Monocoque is structured as a **messaging kernel** with clean layering:
//!
//! - **`monocoque-core`**: Lock-free allocators, `io_uring` proactor, SPSC queues
//! - **Protocol crates**: Pure state machines (sans-IO)
//! - **`monocoque`**: Public API surface (this crate)
//!
//! ## Protocols (opt-in via features)
//!
//! Each protocol is gated behind a feature flag to avoid loading unused code:
//!
//! - **`zmq`** - `ZeroMQ` (ZMTP 3.x) implementation
//!
//! ```toml
//! [dependencies]
//! monocoque-rs = { version = "0.1", features = ["zmq"] }
//! ```
//!
//! ## Quick Start
//!
//! ### `ZeroMQ` DEALER Socket (Client)
//!
//! ```rust,no_run
//! # #[cfg(feature = "zmq")]
//! use monocoque::zmq::prelude::*;
//!
//! # #[cfg(feature = "zmq")]
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Connect to a ZeroMQ peer
//! let mut socket = DealerSocket::connect("127.0.0.1:5555").await?;
//!
//! // Send a multipart message
//! socket.send(vec![b"Hello".to_vec().into(), b"World".to_vec().into()]).await?;
//!
//! // Receive a reply
//! if let Ok(Some(msg)) = socket.recv().await {
//!     println!("Received: {:?}", msg);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ### `ZeroMQ` ROUTER Socket (Server)
//!
//! ```rust,no_run
//! # #[cfg(feature = "zmq")]
//! use monocoque::zmq::prelude::*;
//!
//! # #[cfg(feature = "zmq")]
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! // Bind and accept first connection
//! let (listener, mut socket) = RouterSocket::bind("127.0.0.1:5555").await?;
//!
//! // Echo server
//! while let Ok(Some(msg)) = socket.recv().await {
//!     socket.send(msg).await?;
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## Performance
//!
//! - **Zero-copy**: Uses `bytes::Bytes` for refcounted message buffers
//! - **`io_uring`**: Native Linux async I/O (via `compio`)
//! - **Lock-free**: SPSC queues, no shared mutable state in hot paths
//! - **Sans-IO**: Protocol logic is pure, testable, and runtime-agnostic
//!
//! ## Safety
//!
//! - `unsafe` code is isolated to `monocoque-core/src/alloc/` (slab allocator)
//! - All protocol and routing layers are 100% safe Rust
//! - Formal invariants documented in `docs/blueprints/06-safety-model-and-unsafe-audit.md`

#![warn(missing_docs)]
#![warn(clippy::all)]
// Allow some pedantic patterns
#![allow(clippy::module_name_repetitions)]
#![allow(clippy::must_use_candidate)]
#![allow(clippy::needless_pass_by_value)]
#![allow(clippy::future_not_send)] // Runtime-agnostic design
#![allow(clippy::missing_errors_doc)] // Will add gradually
#![allow(clippy::doc_markdown)] // Too many false positives
#![allow(clippy::return_self_not_must_use)] // Builder patterns are obvious
#![allow(clippy::missing_panics_doc)] // Most panics are unreachable
#![allow(clippy::missing_const_for_fn)] // Not always an optimization
#![allow(clippy::multiple_crate_versions)] // Transitive dependencies
#![allow(clippy::doc_lazy_continuation)] // Doc formatting is intentional
#![allow(clippy::manual_let_else)] // Match expressions sometimes clearer
#![allow(clippy::empty_line_after_outer_attr)] // Spacing is intentional

// Re-export core types
pub use bytes::Bytes;
pub use monocoque_core::options::SocketOptions;
pub use monocoque_core::reconnect::{ReconnectError, ReconnectState};
pub use monocoque_core::socket_type::SocketType;

// Protocol modules (opt-in via features)
#[cfg(feature = "zmq")]
pub mod zmq;

/// Development helpers (benches/tests)
#[doc(hidden)]
pub mod dev_tracing;