Skip to main content

Crate ruststream_lapin

Crate ruststream_lapin 

Source
Expand description

RabbitMQ over AMQP 0.9.1 for RustStream services, backed by the lapin client.

A subscription consumes one queue, and a publish is one message on an exchange under a routing key. A queue is destructive storage: an acknowledged delivery leaves it. Acknowledgements, requeues and dead-letter routes are protocol frames, so the framework settles a message on the server and keeps no copy in the service.

§A service

A handler is an async fn over the decoded payload, mounted on a broker inside the application object, and the attribute writes the main:

use ruststream_lapin::prelude::*;
use serde::Deserialize;

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

#[subscriber("orders")]
async fn handle(order: &Order) -> HandlerOutcome {
    tracing::info!(order.id, "accepted");
    HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(
        LapinBroker::new("amqp://localhost:5672").prefetch(nonzero!(64)),
        |b| {
            b.include(handle);
        },
    )
}

cargo run -- run starts it. LapinBroker::new only records the configuration; the runtime connects the broker at startup and shuts it down when the service stops. The queue orders has to exist, or the broker declares it under declare_topology(true).

§Where things are

The guides take a RabbitMQ service from installation to production, in this order: getting started, work queues, exchanges and routing, topology, acknowledgements, retries and dead letters, reliable publishing, request and reply, testing and running in production. The architecture pages show how the crate sits between lapin 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

§Subscriptions

§Exchanges

§Settlement

§Context

§Publishing

§Transactions

§Request and reply

§Tooling

§Cargo features

asyncapi contributes the AMQP bindings to the generated document, and testing adds the in-process mode TestApp::start connects the broker through. tls-native-tls, tls-rustls and tls-rustls-ring map onto lapin’s own TLS backends. plugin-consistent-hash and plugin-dme add the typed forms of two server plugins, which must be enabled on the server.

Re-exports§

pub use queue::QueueDescriptor;
pub use queue::RabbitQueue;
pub use queue::RabbitQuorumQueue;

Modules§

context
Per-delivery context fields exposed to handlers.
prelude
The imports a service on RabbitMQ writes every time, in one glob.

Structs§

ClosedLapinBroker
The terminal witness returned by shutting down a ConnectedLapinBroker.
ConfirmsPublish
The confirm-transactional publish policy: same options as LapinPublish, pairing into ConfirmsPublisher.
ConfirmsPublisher
The live publisher that awaits broker confirms for every message.
ConfirmsTransaction
An owned confirm-transaction, opened by transaction on a ConfirmsPublisher.
ConnectedLapinBroker
The typed witness that Broker::connect succeeded: holds the live connection.
DirectReplyTo
Redirects each reply of a #[subscriber(.., reply(..))] handler to the requester’s private reply-to address, echoing its correlation id.
FieldTable
A Map<String, AMQPValue>
LapinBroker
A RabbitMQ broker backed by lapin: configuration captured, no I/O performed yet.
LapinMessage
One AMQP delivery, settled with the protocol’s native acknowledgement frames.
LapinPublish
The fire-and-forget publish policy: pure declaration, constructible anywhere.
LapinPublishOptions
The AMQP basic properties one publish may differ from the next in.
LapinPublisher
The live fire-and-forget publisher, on the connection’s shared publish channel. Cheap to clone.
LapinRequest
The request/reply policy: pure declaration, constructible anywhere, pairing into LapinRequester.
LapinRequester
The live request/reply client over RabbitMQ direct reply-to.
LapinSubscriber
A consumer on one queue, yielding LapinMessage deliveries.
RabbitExchange
Describes the exchange side of a RabbitQueue binding.
RabbitQueue
Describes one classic-queue subscription: the queue, its expected settings, and its bindings.
RabbitQuorumQueue
Describes one quorum-queue subscription: the queue, its expected settings, and its bindings.
ServerTxPublish
The server-transactional publish policy: same options as LapinPublish, pairing into ServerTxPublisher.
ServerTxPublisher
The live publisher backed by AMQP server transactions (tx.select / tx.commit / tx.rollback).

Enums§

AMQPValue
Enumeration referencing the possible AMQP values depending on the types
AmqpError
Errors returned by LapinBroker and the types it hands out.
Delay
How a subscription handles retry_after / nack_after delays.

Constants§

EXPIRATION_HEADER
Header carrying the AMQP per-message expiration property of a DELIVERY: whole milliseconds, as decimal digits, which is how AMQP spells a TTL.
PARTITION_KEY_HEADER
Header carrying a message’s partition key, read by Partitioned for keyed worker lanes.
PRIORITY_HEADER
Header carrying the AMQP priority property of a DELIVERY.

Traits§

LapinPublishPolicy
A publish policy that pairs with a connected RabbitMQ broker without opening a channel.
LapinPublishSteps
The AMQP basic properties, as steps on the publish builder.
QueueDescriptor
The queue a subscription consumes: RabbitQueue or RabbitQuorumQueue.