Skip to main content

Crate monocoque

Crate monocoque 

Source
Expand description

§Monocoque

A high-performance, multi-protocol messaging runtime. It runs on io_uring (via compio) by default, with optional tokio and smol backends for portability.

§Architecture

Monocoque is structured as a messaging kernel with clean layering:

  • monocoque-core: runtime facade, owned-buffer I/O helpers, zero-copy buffers
  • Protocol crates: Pure state machines (sans-IO)
  • monocoque: Public API surface (this crate)

§Protocols (opt-in via features)

Each protocol is gated behind a feature flag to avoid loading unused code:

  • zmq - ZeroMQ (ZMTP 3.x) implementation
[dependencies]
monocoque-rs = { version = "0.3", features = ["zmq"] }

§Quick Start

§ZeroMQ DEALER Socket (Client)

use monocoque::zmq::prelude::*;

// Connect to a ZeroMQ peer
let mut socket = DealerSocket::connect("127.0.0.1:5555").await?;

// Send a multipart message
socket.send(vec![b"Hello".to_vec().into(), b"World".to_vec().into()]).await?;

// Receive a reply
if let Ok(Some(msg)) = socket.recv().await {
    println!("Received: {:?}", msg);
}

§ZeroMQ ROUTER Socket (Server)

use monocoque::zmq::prelude::*;

// Bind and accept first connection
let (listener, mut socket) = RouterSocket::bind("127.0.0.1:5555").await?;

// Echo server
while let Ok(Some(msg)) = socket.recv().await {
    socket.send(msg).await?;
}

§Performance

  • Zero-copy: Uses bytes::Bytes for refcounted message buffers
  • Runtime backends: native io_uring via compio (default), or tokio or smol
  • Lock-free: SPSC queues, no shared mutable state in hot paths
  • Sans-IO: Protocol logic is pure, testable, and runtime-agnostic

§Safety

  • unsafe code is isolated to the owned-buffer read helpers in monocoque-core/src/io.rs and the raw-socket tuning in tcp.rs
  • All protocol and routing layers are 100% safe Rust
  • Formal invariants documented in docs/blueprints/06-safety-model-and-unsafe-audit.md

Modules§

rt
Runtime-agnostic networking types (TCP/Unix streams, listeners).
zmq
ZeroMQ protocol implementation.

Structs§

Bytes
A cheaply cloneable and sliceable chunk of contiguous memory.
ReconnectState
Reconnection state tracker for managing connection attempts and backoff.
SocketOptions
Socket configuration options.

Enums§

ReconnectError
Error type for reconnection operations.
SocketType
ZeroMQ socket types.