Crate ruststream_zeromq 

ZeroMQ broker for the RustStream messaging framework, over the pure-Rust zeromq client on tcp:// and ipc://.

Two processes talk directly, with a documented frame layout between them, so the peer on the other side may be written in any language. A service picks one broker per socket pattern: ZmqQueue (PUSH/PULL), ZmqFanout (PUB/SUB) or ZmqRpc (DEALER/ROUTER), each on a ZmqEndpoint that says whether this process binds or connects. A subscription is a name, and the name is frame 0 of every message. Delivery is at most once: ack reports AckError::Unsupported, and a retry is a copy the service publishes.

A service

A worker on the PUSH/PULL queue, with the pattern’s own prelude as its one import:

use ruststream_zeromq::queue::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct Job {
    id: u64,
}

#[subscriber("jobs")]
async fn handle(job: &Job) -> HandlerOutcome {
    tracing::info!(job.id, "working on the job");
    HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> impl App {
    RustStream::new(AppInfo::new("worker", "0.1.0")).with_broker(
        ZmqQueue::new(ZmqEndpoint::bind("tcp://0.0.0.0:5555")),
        |b| {
            b.include(handle);
        },
    )
}

cargo run -- run starts it, and any peer that sends the three frames pushes work into it. ZmqQueue::new only records the endpoint; the runtime connects the broker at startup and shuts it down when the service stops.

Where things are

The guides take a ZeroMQ service from a first worker to production, in this order: getting started, pipelines with PUSH/PULL, broadcast with PUB/SUB, request and reply, retries and dead letters, peers in other languages, testing and running in production. The architecture pages show how the sockets work and where the crate sits between them and the runtime, and the benchmarks what it costs.

Each topic below links to its component page on the site, which shows it in a service; the item’s own documentation keeps the detail.

Broker

• Broker: the three brokers, each connected into its own form (ConnectedZmqQueue, ConnectedZmqFanout, ConnectedZmqRpc).
• ZmqQueue: ZmqQueue, PUSH/PULL, competing consumers; module queue.
• ZmqFanout: ZmqFanout, PUB/SUB, broadcast filtered by name prefix; module fanout.
• ZmqRpc: ZmqRpc, DEALER/ROUTER, request and reply; module rpc.
• ZmqEndpoint: ZmqEndpoint, an address on tcp:// or ipc:// and the side this process takes.
• bind: ZmqEndpoint::bind, one subscription per bound endpoint, and port zero resolved by ConnectedZmqQueue::bound_address and its twins.
• connect: ZmqEndpoint::connect, subscriptions that dial a sending peer.
• EndpointRole: EndpointRole, the side as a type, Bind or Connect.
• Startup: the endpoint check at connect, and a socket per subscription as it opens.
• Shutdown: ZmqError::NotConnected for a publisher used afterwards.
• Prelude: queue::prelude, fanout::prelude and rpc::prelude for a routes file on one pattern, prelude for one that mounts several.
• Errors: ZmqError, the one error type of the crate.

Subscriptions

• Subscriptions: a name in #[subscriber("jobs")], delivered as a ZmqMessage.
• Prefixes: the name as a prefix filter on ZmqFanout.
• Batches: slice handlers over ZmqSubscriber batches, assembled on the client; ZmqRpcSubscriber takes none.
• read_ahead: ZmqQueue::read_ahead and its twins, how far a subscription reads ahead of its handler.

Acknowledgement

• Acknowledgement: what ack, nack and each handler outcome do on a transport that settles nothing.
• Retries: retry_after copies and the max_attempts cap.
• out_retry: where the copies go, by the pattern and the side.
• Dead letters: dead_letter, a publisher on another endpoint.

Publishing

• Publishing: ZmqQueuePublish, ZmqFanoutPublish and ZmqRpcPublish, and their live ZmqQueuePublisher, ZmqFanoutPublisher and ZmqRpcPublisher.
• Replies: a queue worker’s replies through a queue on an endpoint of its own.
• Cancellation: which publishes are cancel-safe.

Request-reply

• Request-reply: RequestReply on ZmqRpcPublisher, a DEALER per request matched by correlation-id.
• Responders: an answer at the reply-to address each request carries.

Wire format

• Wire format: the three frames, name, headers and payload.
• Headers: the name: value lines of the header frame.
• Envelope: the identity frame a ROUTER puts in front of a request and its answer.

The generated document

• AsyncAPI: the x-ruststream-zeromq extension of the generated document (feature asyncapi).
• Server: the coordinate, the transport and the side of each endpoint.
• Channels: the socket pair and the name frame of each channel.
• Reply address: a responder’s answers, addressed by reply-to.

Testing

• Testing: the in-process transport TestApp connects each broker to (feature testing).
• Live: TestApp::start_live, the same test over loopback sockets.

Cargo features

default is empty. testing adds the in-process mode TestApp::start connects the brokers through, and a service enables it in its [dev-dependencies]. asyncapi contributes the server and channel facts of the generated document. The codecs are the core’s: a service enables json, msgpack or cbor on ruststream itself.

Re-exports

pub use fanout::ConnectedZmqFanout;

pub use fanout::ZmqFanout;

pub use fanout::ZmqFanoutPublish;

pub use fanout::ZmqFanoutPublisher;

pub use queue::ConnectedZmqQueue;

pub use queue::ZmqQueue;

pub use queue::ZmqQueuePublish;

pub use queue::ZmqQueuePublisher;

pub use queue::ZmqSubscriber;

pub use rpc::ConnectedZmqRpc;

pub use rpc::ZmqRpc;

pub use rpc::ZmqRpcPublish;

pub use rpc::ZmqRpcPublisher;

pub use rpc::ZmqRpcSubscriber;

Modules

fanout

ZmqFanout: the PUB/SUB pattern, broadcast filtered by name prefix.

prelude

The imports a routes file that mounts more than one ZeroMQ form writes, in one glob.

queue

ZmqQueue: the PUSH/PULL pattern, competing consumers served in turn.

rpc

ZmqRpc: the DEALER/ROUTER pattern, request and reply.

Structs

Bind

This process listens on the endpoint: the side ZmqEndpoint::bind takes.

Connect

This process dials the endpoint: the side ZmqEndpoint::connect takes.

ZmqEndpoint

An address (tcp://... or ipc://...) and the side of it this process takes, fixed by the constructor and carried in the type.

ZmqMessage

A message delivered by one of the transport’s subscribers.

Enums

ZmqError

Errors returned by the ZeroMQ transport.

Traits

EndpointRole

Which side of an endpoint this process takes: Bind or Connect.