Crate rustzmq2 

Native async Rust implementation of ZeroMQ.

The ZeroMQ guide is the canonical reference for the messaging patterns below; this crate’s API mirrors libzmq’s so chapters of the guide apply directly.

Wire protocol: ZMTP 3.1.

Quick start

[dependencies]
rustzmq2 = "0.1"
tokio = { version = "1", features = ["full"] }

use rustzmq2::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut rep = rustzmq2::RepSocket::new();
    rep.bind("tcp://127.0.0.1:5555").await?;
    let msg: String = rep.recv().await?.try_into()?;
    rep.send(format!("{msg} world")).await?;
    Ok(())
}

Socket types

Pattern	Types
Request / Reply	ReqSocket, RepSocket, DealerSocket, RouterSocket
Publish / Subscribe	PubSocket, SubSocket, XPubSocket, XSubSocket
Pipeline	PushSocket, PullSocket
Peer-to-peer	PairSocket
Scatter / Gather	ScatterSocket, GatherSocket
Channel	ChannelSocket

All socket types implement Socket (for bind / connect) and either SocketSend, SocketRecv, or both. Import them via prelude:

use rustzmq2::prelude::*;

Configuration

Use SocketBuilder (via SocketType::builder()) to configure security, heartbeats, and peer identity before creating a socket:

use rustzmq2::{RepSocket, Socket};

let mut rep = RepSocket::builder()
    .plain_server()
    .zap_domain("myapp")
    .build();

Security

The full ZMTP security stack is supported: NULL (default), PLAIN, CURVE, and ZAP. See SocketBuilder for configuration methods and set_zap_handler / clear_zap_handler for ZAP.

Modules

family

Sealed role-marker traits that gate kind-specific builder methods. Used only in trait bounds; you should never need to name these directly. Sealed role markers that gate kind-specific builder methods at the type level.

prelude

Convenience re-exports. use rustzmq2::prelude::*; brings in the traits and types needed for nearly every program.

Structs

ChannelSocket

Channel socket (CHANNEL). Bidirectional point-to-point channel.

DealerRecvHalf

Recv half of a DealerSocket produced by DealerSocket::split.

DealerSendHalf

Send half of a DealerSocket produced by DealerSocket::split.

DealerSocket

Dealer socket (DEALER). Async request socket without the strict send/recv alternation of REQ.

GatherSocket

Gather socket (GATHER). Receives messages fair-queued from connected SCATTER peers.

PairSocket

Pair socket (PAIR). Exclusive one-to-one bidirectional channel.

PeerIdentity

Per-peer identity (up to 255 bytes). Equivalent to libzmq’s ZMQ_ROUTING_ID — used to address a specific peer through a ROUTER socket and surfaced in SocketEvents.

PubSocket

Publish socket (PUB). Broadcasts every message to all matching subscribers.

PullSocket

Pull socket (PULL). Receives messages from any connected PUSH peer, fair-queued.

PushSocket

Push socket (PUSH). Distributes messages round-robin to connected PULL peers.

ReconnectStop

Conditions under which the reconnect task gives up rather than retrying. Mirrors libzmq’s ZMQ_RECONNECT_STOP flag set.

RepSocket

Reply socket (REP). Receives a request, then must send exactly one reply.

ReqSocket

Request socket (REQ). Sends one message and waits for a reply before sending again.

RouterEnvelope

A message received from a RouterSocket: the originating peer’s identity plus its payload, with the envelope already split apart.

RouterRecvHalf

The recv half of a RouterSocket produced by RouterSocket::split.

RouterSendHalf

The send half of a RouterSocket produced by RouterSocket::split.

RouterSocket

Router socket (ROUTER). Async reply socket that tracks each peer’s identity so replies can be addressed by identity.

ScatterSocket

Scatter socket (SCATTER). Distributes messages round-robin to connected GATHER peers.

SocketBuilder

Fluent builder for any socket type.

SocketOptions

Per-socket configuration passed to Socket::with_options.

SubSocket

Subscribe socket (SUB). Receives messages from publishers matching subscribed prefixes.

XPubSocket

Extended publish socket (XPUB). Like PUB, but surfaces subscribe/unsubscribe events via recv.

XSubSocket

Extended subscribe socket (XSUB). Raw counterpart of SubSocket.

ZapRequest

A request sent to the ZAP handler for authentication.

ZapResponse

Response from the ZAP handler.

ZmqEmptyMessageError

Error returned when attempting to construct a ZmqMessage with no frames.

ZmqMessage

A multi-frame ZMQ message.

Enums

CodecError

Represents an error when encoding/decoding raw byte buffers and frames

Endpoint

Represents a ZMQ Endpoint.

EndpointError

Represents an error when parsing an crate::Endpoint

Host

Represents a host address. Does not include the port, and may be either an ip address or a domain name

JoinError

The error type returned by awaiting a [crate::async_rt::task::JoinHandle].

MessageConversionError

Error returned when converting a ZmqMessage into a single-frame representation (Vec<u8> / String / Bytes) fails.

SocketEvent

Event emitted by the socket monitor channel (see Socket::monitor).

SocketType

Identifies the ZMQ socket pattern. Used internally and in SocketEvents.

TaskError

Transport

The type of transport used by a given endpoint

XPubEvent

A subscription event surfaced by XPubSocket::recv_event: a subscriber is asking for a topic to be added or removed.

ZmqError

Traits

CaptureSocket

Marker trait expressing the fact that only certain types of sockets may be used in the proxy function as a capture parameter.

MultiPeerBackend

Backend trait for sockets that manage multiple peer connections.

Socket

Core trait implemented by every ZMQ socket type.

SocketBackend

Low-level interface implemented by every socket backend.

SocketRecv

Receive half of a ZMQ socket.

SocketSend

Send half of a ZMQ socket.

Functions

clear_zap_handler

Remove the global ZAP handler. After this call, all connections are permitted without authentication (permissive default).

proxy

Bidirectional proxy between a frontend and backend socket.

proxy_with_capture

Bidirectional proxy that also forwards every message to a capture socket before relaying — useful for monitoring or logging traffic.

set_zap_handler

Register a ZAP authentication handler for all connections.

Type Aliases

ZmqResult