monocoque/
lib.rs

1//! # Monocoque
2//!
3//! A high-performance, multi-protocol messaging runtime built on `io_uring`.
4//!
5//! ## Architecture
6//!
7//! Monocoque is structured as a **messaging kernel** with clean layering:
8//!
9//! - **`monocoque-core`**: Lock-free allocators, `io_uring` proactor, SPSC queues
10//! - **Protocol crates**: Pure state machines (sans-IO)
11//! - **`monocoque`**: Public API surface (this crate)
12//!
13//! ## Protocols (opt-in via features)
14//!
15//! Each protocol is gated behind a feature flag to avoid loading unused code:
16//!
17//! - **`zmq`** - `ZeroMQ` (ZMTP 3.x) implementation
18//!
19//! ```toml
20//! [dependencies]
21//! monocoque-rs = { version = "0.1", features = ["zmq"] }
22//! ```
23//!
24//! ## Quick Start
25//!
26//! ### `ZeroMQ` DEALER Socket (Client)
27//!
28//! ```rust,no_run
29//! # #[cfg(feature = "zmq")]
30//! use monocoque::zmq::prelude::*;
31//!
32//! # #[cfg(feature = "zmq")]
33//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
34//! // Connect to a ZeroMQ peer
35//! let mut socket = DealerSocket::connect("127.0.0.1:5555").await?;
36//!
37//! // Send a multipart message
38//! socket.send(vec![b"Hello".to_vec().into(), b"World".to_vec().into()]).await?;
39//!
40//! // Receive a reply
41//! if let Ok(Some(msg)) = socket.recv().await {
42//!     println!("Received: {:?}", msg);
43//! }
44//! # Ok(())
45//! # }
46//! ```
47//!
48//! ### `ZeroMQ` ROUTER Socket (Server)
49//!
50//! ```rust,no_run
51//! # #[cfg(feature = "zmq")]
52//! use monocoque::zmq::prelude::*;
53//!
54//! # #[cfg(feature = "zmq")]
55//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
56//! // Bind and accept first connection
57//! let (listener, mut socket) = RouterSocket::bind("127.0.0.1:5555").await?;
58//!
59//! // Echo server
60//! while let Ok(Some(msg)) = socket.recv().await {
61//!     socket.send(msg).await?;
62//! }
63//! # Ok(())
64//! # }
65//! ```
66//!
67//! ## Performance
68//!
69//! - **Zero-copy**: Uses `bytes::Bytes` for refcounted message buffers
70//! - **`io_uring`**: Native Linux async I/O (via `compio`)
71//! - **Lock-free**: SPSC queues, no shared mutable state in hot paths
72//! - **Sans-IO**: Protocol logic is pure, testable, and runtime-agnostic
73//!
74//! ## Safety
75//!
76//! - `unsafe` code is isolated to `monocoque-core/src/alloc/` (slab allocator)
77//! - All protocol and routing layers are 100% safe Rust
78//! - Formal invariants documented in `docs/blueprints/06-safety-model-and-unsafe-audit.md`
79
80#![warn(missing_docs)]
81#![warn(clippy::all)]
82// Allow some pedantic patterns
83#![allow(clippy::module_name_repetitions)]
84#![allow(clippy::must_use_candidate)]
85#![allow(clippy::needless_pass_by_value)]
86#![allow(clippy::future_not_send)] // Runtime-agnostic design
87#![allow(clippy::missing_errors_doc)] // Will add gradually
88#![allow(clippy::doc_markdown)] // Too many false positives
89#![allow(clippy::return_self_not_must_use)] // Builder patterns are obvious
90#![allow(clippy::missing_panics_doc)] // Most panics are unreachable
91#![allow(clippy::missing_const_for_fn)] // Not always an optimization
92#![allow(clippy::multiple_crate_versions)] // Transitive dependencies
93#![allow(clippy::doc_lazy_continuation)] // Doc formatting is intentional
94#![allow(clippy::manual_let_else)] // Match expressions sometimes clearer
95#![allow(clippy::empty_line_after_outer_attr)] // Spacing is intentional
96
97// Re-export core types
98pub use bytes::Bytes;
99pub use monocoque_core::options::SocketOptions;
100pub use monocoque_core::reconnect::{ReconnectError, ReconnectState};
101pub use monocoque_core::socket_type::SocketType;
102
103// Protocol modules (opt-in via features)
104#[cfg(feature = "zmq")]
105pub mod zmq;
106
107/// Development helpers (benches/tests)
108#[doc(hidden)]
109pub mod dev_tracing;
monocoque/lib.rs

monocoque/
lib.rs
