ruststream_lapin/lib.rs
1//! `RabbitMQ` / AMQP 0.9.1 broker for the
2//! [RustStream](https://github.com/powersemmi/ruststream) messaging framework, backed by
3//! [`lapin`].
4//!
5//! # Transport model
6//!
7//! A subscription consumes one queue; [`RabbitQueue`] describes the queue and its bindings, and
8//! the bare-string `#[subscriber("orders")]` form consumes the queue named `orders`. On the
9//! publish side [`OutgoingMessage::name`](ruststream::OutgoingMessage) is the routing key, sent
10//! to the publisher's exchange (the default exchange unless configured, where the routing key
11//! addresses the queue with that name).
12//!
13//! Settlement uses the protocol natively, with no republish tricks:
14//!
15//! - ack sends `basic.ack`
16//! - retry (`nack(true)`) sends `basic.nack` with requeue
17//! - drop (`nack(false)`) sends `basic.reject` without requeue, dead-lettering when the queue
18//! has a dead-letter exchange
19//!
20//! # The lifecycle ladder
21//!
22//! [`LapinBroker::new`] is synchronous and I/O-free, so a service composes with the synchronous
23//! `#[ruststream::app]` builder. The network work happens in the consuming `Broker::connect`,
24//! called once by the runtime at startup, which yields [`ConnectedLapinBroker`]: subscriptions,
25//! publishers, and requesters exist only from there, and `ConnectedBroker::shutdown` consumes it
26//! again into [`ClosedLapinBroker`]. Publishers are declared as policies ([`LapinPublish`],
27//! [`ConfirmsPublish`], [`ServerTxPublish`], [`LapinRequest`]) that hold no connection and pair
28//! into their live form against the connected broker.
29//!
30//! # Topology
31//!
32//! Descriptors describe the EXPECTED topology; nothing is created on the broker by default,
33//! because managing infrastructure is the user's job. Declaration is a per-broker opt-in:
34//! [`LapinBroker::declare_topology`].
35//!
36//! [`lapin`]: https://docs.rs/lapin
37
38#![forbid(unsafe_code)]
39
40mod broker;
41mod convert;
42mod delay;
43mod error;
44mod exchange;
45mod message;
46mod publish_policy;
47mod publisher;
48mod queue;
49mod reply;
50mod requester;
51mod subscriber;
52mod topology;
53mod transaction;
54
55pub mod context;
56#[cfg(feature = "testing")]
57pub mod testing;
58
59pub use broker::{ClosedLapinBroker, ConnectedLapinBroker, LapinBroker};
60pub use delay::Delay;
61pub use error::AmqpError;
62pub use exchange::RabbitExchange;
63pub use message::{LapinMessage, PARTITION_KEY_HEADER};
64pub use publish_policy::{ConfirmsPublish, LapinPublish, LapinPublishPolicy, ServerTxPublish};
65pub use publisher::{ConfirmsPublisher, LapinPublisher, ServerTxPublisher};
66pub use queue::{QueueType, RabbitQueue};
67pub use reply::DirectReplyTo;
68pub use requester::{LapinRequest, LapinRequester};
69pub use subscriber::LapinSubscriber;
70pub use transaction::ConfirmsTransaction;
71
72// Raw declaration-argument passthrough (`RabbitQueue::argument` / `arguments`).
73pub use lapin::types::{AMQPValue, FieldTable};