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

monocoque/
lib.rs
