monocoque/
lib.rs

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

monocoque/
lib.rs
