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`**: Lock-free allocators, runtime facade, SPSC queues
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.1", 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
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 `monocoque-core/src/alloc/` (slab allocator)
79//! - All protocol and routing layers are 100% safe Rust
80//! - Formal invariants documented in `docs/blueprints/06-safety-model-and-unsafe-audit.md`
81
82#![warn(missing_docs)]
83#![warn(clippy::all)]
84// Allow some pedantic patterns
85#![allow(clippy::module_name_repetitions)]
86#![allow(clippy::must_use_candidate)]
87#![allow(clippy::needless_pass_by_value)]
88#![allow(clippy::future_not_send)] // Runtime-agnostic design
89#![allow(clippy::missing_errors_doc)] // Will add gradually
90#![allow(clippy::doc_markdown)] // Too many false positives
91#![allow(clippy::return_self_not_must_use)] // Builder patterns are obvious
92#![allow(clippy::missing_panics_doc)] // Most panics are unreachable
93#![allow(clippy::missing_const_for_fn)] // Not always an optimization
94#![allow(clippy::multiple_crate_versions)] // Transitive dependencies
95#![allow(clippy::doc_lazy_continuation)] // Doc formatting is intentional
96#![allow(clippy::manual_let_else)] // Match expressions sometimes clearer
97#![allow(clippy::empty_line_after_outer_attr)] // Spacing is intentional
98
99// Re-export core types
100pub use bytes::Bytes;
101pub use monocoque_core::options::SocketOptions;
102pub use monocoque_core::reconnect::{ReconnectError, ReconnectState};
103pub use monocoque_core::socket_type::SocketType;
104
105/// Runtime-agnostic networking types (TCP/Unix streams, listeners).
106///
107/// These resolve to the active backend (compio by default, tokio with the
108/// `runtime-tokio` feature). Socket constructors such as `from_unix_stream`
109/// accept the types re-exported here, so application code never names a runtime
110/// crate directly.
111pub use monocoque_core::rt;
112
113// Protocol modules (opt-in via features)
114#[cfg(feature = "zmq")]
115pub mod zmq;
116
117/// Development helpers (benches/tests)
118#[doc(hidden)]
119pub mod dev_tracing;
monocoque/lib.rs

monocoque/
lib.rs
