monocoque_zmtp/
lib.rs

1//! # Monocoque ZMTP
2//!
3//! **Internal protocol implementation crate for Monocoque.**
4//!
5//! ⚠️ **This is an internal implementation detail. Use the `monocoque` crate for the public API.**
6//!
7//! This crate provides the low-level ZMTP 3.1 protocol implementation with direct stream I/O.
8//! For application development, use `monocoque::zmq::*` which provides a higher-level, more
9//! ergonomic API with proper error handling and convenience methods.
10//!
11//! ## Socket Types (Internal API)
12//!
13//! - **DEALER**: Asynchronous request-reply with load balancing
14//! - **ROUTER**: Server-side routing with identity-based addressing  
15//! - **REQ**: Synchronous request-reply client (strict alternation)
16//! - **REP**: Synchronous reply server (stateful envelope tracking)
17//! - **PUB**: Publisher for broadcasting events
18//! - **SUB**: Subscriber with topic-based filtering
19//! - **PUSH**: Pipeline push for task distribution
20//! - **PULL**: Pipeline pull for task reception
21//! - **PAIR**: Exclusive peer-to-peer communication
22//!
23//! ## For Application Development
24//!
25//! ```toml
26//! [dependencies]
27//! monocoque-rs = { version = "0.3", features = ["zmq"] }
28//! ```
29//!
30//! ```rust,ignore
31//! use monocoque::zmq::DealerSocket;
32//!
33//! #[compio::main]
34//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
35//!     let mut socket = DealerSocket::connect("127.0.0.1:5555").await?;
36//!     socket.send(vec![b"Hello!".into()]).await?;
37//!     let response = socket.recv().await;
38//!     Ok(())
39//! }
40//! ```
41//!
42//! ## Features
43//!
44//! - **Zero-copy**: Messages use `Bytes` for efficient sharing
45//! - **Runtime backends**: high-performance async I/O via `compio` (io_uring), tokio, or smol
46
47// Pedantic lints configuration
48#![allow(clippy::module_name_repetitions)]
49#![allow(clippy::return_self_not_must_use)] // Builder patterns are self-documenting
50#![allow(clippy::missing_errors_doc)] // Error types are self-explanatory
51#![allow(clippy::missing_panics_doc)] // Most panics are in unreachable paths or debug code
52#![allow(clippy::missing_const_for_fn)] // Const fn optimization not always beneficial
53#![allow(clippy::multiple_crate_versions)] // Transitive dependency management
54#![allow(clippy::future_not_send)] // Intentional: tied to the thread-per-core runtime model
55#![allow(clippy::missing_fields_in_debug)] // Debug impls are simplified for brevity
56#![allow(clippy::should_implement_trait)] // Custom method names are intentional
57#![allow(clippy::doc_lazy_continuation)] // Doc formatting false positives
58#![allow(clippy::empty_line_after_doc_comments)] // Doc spacing is intentional
59#![allow(clippy::duplicated_attributes)] // Allow duplicates for clarity
60//! - **Sans-IO protocol**: Testable, runtime-agnostic design
61//! - **Type-safe**: No unsafe code in protocol layer
62//! - **Interoperable**: Compatible with libzmq
63
64// Allow some pedantic lints
65#![allow(clippy::cast_possible_truncation)]
66#![allow(clippy::cast_sign_loss)]
67#![allow(clippy::items_after_statements)]
68#![allow(clippy::module_name_repetitions)]
69#![allow(clippy::must_use_candidate)]
70#![allow(clippy::needless_pass_by_value)]
71#![allow(clippy::needless_pass_by_ref_mut)]
72#![allow(clippy::match_same_arms)]
73#![allow(clippy::unused_async)]
74#![allow(clippy::let_underscore_future)]
75#![allow(clippy::future_not_send)] // Runtime-agnostic design
76#![allow(clippy::uninlined_format_args)] // Style preference
77#![allow(clippy::missing_errors_doc)] // Will add gradually
78#![allow(clippy::doc_markdown)] // Too many false positives
79#![allow(clippy::while_let_loop)] // Sometimes clearer as explicit loop
80#![allow(clippy::option_if_let_else)] // Sometimes clearer as if/else
81#![allow(clippy::never_loop)] // State machines use loop with early returns
82
83// Internal modules (not part of public API)
84pub(crate) mod base;
85pub mod codec;
86mod greeting;
87mod handshake;
88mod inproc_stream;
89mod utils;
90
91// Public protocol types
92pub mod adapters;
93/// Sans-IO ZMTP session and related types.
94pub mod session;
95pub mod socket_trait;
96pub mod stream_sink;
97
98// Security mechanisms
99pub mod security;
100
101// Socket implementations
102pub mod dealer;
103pub mod pair;
104pub mod proxy;
105/// PUB socket implementation.
106pub mod publisher;
107pub mod pull;
108pub mod push;
109pub mod rep;
110pub mod req;
111pub mod router;
112pub mod stream;
113pub mod subscriber;
114pub mod xpub;
115pub mod xsub;
116
117// Re-export socket types for clean API
118pub use dealer::DealerSocket;
119pub use pair::PairSocket;
120pub use publisher::PubSocket;
121pub use pull::PullSocket;
122pub use push::PushSocket;
123pub use rep::RepSocket;
124pub use req::ReqSocket;
125pub use router::RouterSocket;
126pub use stream::StreamSocket;
127pub use subscriber::SubSocket;
128pub use xpub::XPubSocket;
129pub use xsub::XSubSocket;
130
131// Re-export commonly used types
132pub use session::{SocketType, ZmtpSession};
133pub use socket_trait::Socket;
134
135// Wire-parser entry points reachable from the fuzz crate (monocoque-fuzz).
136// This is an internal implementation crate, so exposing the greeting and READY
137// command parsers here widens no public-facing (monocoque) API surface.
138pub use greeting::ZmtpGreeting;
139pub use handshake::parse_ready_command;
140
141/// Prelude module for convenient imports
142///
143/// ```rust
144/// use monocoque_zmtp::prelude::*;
145/// ```
146pub mod prelude {
147    pub use super::session::SocketType;
148    pub use super::socket_trait::Socket;
149    pub use super::stream_sink::{SocketSink, SocketStream, SocketStreamSink};
150    pub use super::{
151        DealerSocket, PairSocket, PubSocket, PullSocket, PushSocket, RepSocket, ReqSocket,
152        RouterSocket, SubSocket, XPubSocket, XSubSocket,
153    };
154    pub use bytes::Bytes;
155}
monocoque_zmtp/lib.rs

monocoque_zmtp/
lib.rs
