Messaging & Event Streaming

RabbitMQ and AMQP 0-9-1: Exchanges, Bindings, Queues and Routing

Intermediate9 min readUpdated

RabbitMQ routes every message through an exchange to zero or more queues according to bindings. This guide explains that model precisely — connections, channels, the four exchange types, routing and binding keys — then covers what makes RabbitMQ reliable in practice: durable quorum queues, publisher confirms, consumer acknowledgements, prefetch, TTL and dead-letter exchanges, with Java client examples for RabbitMQ 3.13 and 4.x.

What you will learn

  • Explain how a message travels from publisher through exchange and bindings to queues and consumers
  • Choose between direct, fanout, topic and headers exchanges and write correct binding patterns
  • Declare durable quorum queues and know when a classic queue or a stream fits better
  • Use publisher confirms and consumer acknowledgements to get at-least-once delivery
  • Control consumer load with prefetch and handle failures with dead-letter exchanges and TTL
  • Administer a broker with the management UI, rabbitmqctl and policies

RabbitMQ is the broker that implements AMQP 0-9-1 most faithfully, and nearly everything that confuses newcomers comes from not knowing that protocol's model. A producer never sends to a queue. It sends to an exchange, the exchange consults its bindings, and copies of the message land in zero, one or many queues, from which consumers take them. Once that picture is clear, RabbitMQ's flexibility — the same message going to a work queue, an audit log and a dashboard feed without the producer knowing — becomes something you design with rather than fight. This guide targets RabbitMQ 3.13 and 4.x with the official Java client.

The AMQP 0-9-1 model

Five nouns cover the protocol.

A connection is a long-lived TCP connection, usually with TLS, authenticated against a virtual host (vhost) — a namespace of exchanges, queues and permissions, so one broker can serve several applications in isolation. Inside a connection, applications open channels: cheap, multiplexed sessions on which all publishing and consuming happens. The rule is one connection per process and one channel per thread, because channels are not thread-safe and connections are expensive.

An exchange receives messages from publishers and routes them. It stores nothing. A queue stores messages and delivers them to consumers. A binding links an exchange to a queue and may carry a binding key (or, for headers exchanges, a set of headers). When a publisher sends a message, it names an exchange and supplies a routing key; the exchange type decides how the routing key is compared with the binding keys.

Everything above is programmable: applications declare exchanges, queues and bindings over the protocol, and declarations are idempotent as long as the arguments match. That is why a producer and a consumer can both declare the queue they share and start in any order.

publisher --(exchange, routing key)--> exchange --bindings--> queue(s) --> consumer(s)

The four exchange types

Direct

A direct exchange routes a message to every queue whose binding key equals the routing key exactly. It is the tool for point-to-point delivery and for sorting messages into a small fixed set of queues, such as one queue per log severity.

The default exchange is a pre-declared direct exchange with the empty string as its name. Every queue is automatically bound to it with the queue's own name as the binding key, so basicPublish("", "orders", ...) delivers to the queue named orders. It is convenient for tutorials and for reply queues, and a trap for everything else: producers end up hard-coding queue names, which is exactly the coupling exchanges exist to remove.

Fanout

A fanout exchange ignores the routing key and copies the message to every bound queue. It is the broadcast primitive: bind a queue per subscriber and each gets its own copy, at its own pace, with its own acknowledgements.

Topic

A topic exchange matches the routing key against binding patterns. Routing keys are dot-separated words, up to 255 bytes; in a binding key, * matches exactly one word and # matches zero or more words.

Routing keyBinding order.*.placedBinding order.#Binding #.failed
order.eu.placedmatchmatchno
order.placedno (* needs one word between)matchno
order.eu.payment.failednomatchmatch
shipment.failednonomatch

A topic exchange with a binding key of # behaves like a fanout, and one with a key containing no wildcards behaves like a direct exchange, which is why many teams use a single topic exchange per bounded context and express everything as routing-key conventions such as <entity>.<region>.<event>.

Headers

A headers exchange ignores the routing key and matches message headers against the binding's arguments; the x-match argument set to all requires every listed header to match and any requires at least one. It routes on multiple attributes at once, at the cost of being slower and less readable than topic keys. Most designs that reach for it are better served by encoding the attributes in a routing key.

Declaring the topology in Java

The official client is com.rabbitmq:amqp-client (5.x). This producer declares a durable topic exchange, a durable quorum queue, binds them and publishes one persistent message:

import com.rabbitmq.client.*;
import java.nio.charset.StandardCharsets;
import java.util.Map;

public class OrderPublisher {
  public static void main(String[] args) throws Exception {
    ConnectionFactory factory = new ConnectionFactory();
    factory.setUri("amqps://orders:[email protected]:5671/shop");  // vhost "shop"

    try (Connection connection = factory.newConnection("order-service");
         Channel channel = connection.createChannel()) {

      channel.exchangeDeclare("orders", BuiltinExchangeType.TOPIC, /* durable */ true);
      channel.queueDeclare("fulfilment", /* durable */ true, /* exclusive */ false,
          /* autoDelete */ false, Map.of("x-queue-type", "quorum"));
      channel.queueBind("fulfilment", "orders", "order.*.placed");

      channel.confirmSelect();                      // enable publisher confirms on this channel

      AMQP.BasicProperties props = new AMQP.BasicProperties.Builder()
          .contentType("application/json")
          .deliveryMode(2)                          // 2 = persistent: written to disk by durable queues
          .messageId("o-9911")
          .build();

      channel.basicPublish("orders", "order.eu.placed", /* mandatory */ true, props,
          "{\"orderId\":\"o-9911\",\"total\":149.90}".getBytes(StandardCharsets.UTF_8));

      channel.waitForConfirmsOrDie(5_000);          // throws if the broker did not confirm in 5 s
    }
  }
}

Three flags in that code decide durability, and all three are needed for a message to survive a broker restart: the exchange must be durable (or it disappears with its bindings), the queue must be durable, and the message must be published with delivery mode 2. Quorum queues are always durable and always persist messages; the delivery-mode flag still matters for classic queues.

Queue types

RabbitMQ has three kinds of queue, chosen with the x-queue-type argument at declaration time and immutable afterwards.

ClassicQuorumStream
ReplicationNone (mirroring removed in 4.0)Raft, majority of nodesReplicated log
DurabilityOptionalAlwaysAlways
ConsumptionDestructiveDestructiveNon-destructive, replayable by offset
Best forTransient, exclusive, reply and low-latency queuesAny queue whose messages matterLarge fan-out, replay, time-travel, very high throughput
Not supported—Exclusive, auto-delete, non-durablePriorities, per-message TTL

A quorum queue keeps its messages on a majority of a cluster's nodes and elects a leader through Raft; it survives the loss of a minority of nodes without losing acknowledged messages, which is the property that made it the recommended default. It also tracks how many times a message has been redelivered in the x-delivery-count header and can move messages to a dead-letter exchange after a configurable x-delivery-limit, which classic queues cannot do. The cost is more disk and memory per message and higher latency than a single-node classic queue.

A stream is an append-only log: consumers read from an offset, several consumers can read the same messages, and retention is set by size or age rather than by consumption. Streams speak AMQP 0-9-1 through the normal client, but the dedicated stream protocol and client are much faster. When you find yourself wanting Kafka-style replay inside RabbitMQ, streams are the answer.

RabbitMQ 4.0 also made AMQP 1.0 a core protocol alongside 0-9-1, so a Java application can use the Qpid JMS client or RabbitMQ's own AMQP 1.0 client against the same queues; the exchange-and-binding model described here is unchanged.

Consuming, acknowledging and prefetch

A consumer subscribes to a queue with basicConsume, and the broker pushes deliveries to it. What happens next depends on the acknowledgement mode you chose.

With autoAck = true, the broker forgets a message the moment it is written to the socket. A consumer crash loses everything in flight. With autoAck = false, the message stays in the queue, marked unacked, until the consumer sends basicAck; if the channel closes first, the broker requeues the message for another consumer. That is at-least-once delivery.

channel.basicQos(20);   // prefetch: at most 20 unacknowledged deliveries per consumer on this channel

channel.basicConsume("fulfilment", /* autoAck */ false, "fulfilment-worker-1",
    new DefaultConsumer(channel) {
      @Override
      public void handleDelivery(String tag, Envelope env, AMQP.BasicProperties props, byte[] body) throws IOException {
        long deliveryTag = env.getDeliveryTag();
        try {
          fulfil(new String(body, StandardCharsets.UTF_8));
          channel.basicAck(deliveryTag, /* multiple */ false);
        } catch (TransientFailure e) {
          channel.basicNack(deliveryTag, false, /* requeue */ true);    // try again, possibly elsewhere
        } catch (RuntimeException e) {
          channel.basicNack(deliveryTag, false, /* requeue */ false);   // dead-letter it, if a DLX is set
        }
      }
    });

basicQos sets the prefetch count: how many deliveries the broker may push to a consumer before it receives acknowledgements. Without it, the broker sends as fast as the socket allows, one consumer accumulates thousands of messages in memory while its peers idle, and a crash requeues them all. A prefetch between 10 and 100 suits most workloads; 1 gives perfect fairness at the cost of a round trip per message.

Two limits protect the broker from misbehaving consumers. Redelivery with requeue = true on a message that fails every time creates an infinite loop that burns CPU; check env.isRedeliver() or, on quorum queues, the x-delivery-count header, and stop requeueing after a few attempts. And a consumer that holds a delivery without acknowledging for longer than the consumer timeout (30 minutes by default) has its channel closed by the broker, which is a common surprise in batch-style consumers.

Publisher confirms

Acknowledgements protect the consumer side; publisher confirms protect the publisher. After confirmSelect, the broker sends basic.ack for each message once it has been routed and, for persistent messages in durable queues, written to disk, or basic.nack if it could not be handled. waitForConfirmsOrDie is the simple synchronous form; for throughput, publish in batches or register a ConfirmListener and track outstanding sequence numbers, republishing anything nacked. Together with mandatory = true and a ReturnListener, which hands back messages that matched no binding, confirms give you a publisher that knows what the broker accepted.

TTL, limits and dead-lettering

Queues accept optional arguments that control what happens to messages that are not consumed.

  • x-message-ttl — milliseconds a message may wait before it is discarded or dead-lettered. Per-message expiration on the properties does the same for one message.
  • x-expires — delete the queue itself after this many milliseconds without consumers or activity; useful for per-client reply queues.
  • x-max-length / x-max-length-bytes with x-overflow — cap the queue; drop-head discards the oldest messages, reject-publish makes new publishes nack under confirms so the producer sees the backpressure.
  • x-dead-letter-exchange and x-dead-letter-routing-key — where rejected, expired or overflowing messages go.

A dead-letter exchange (DLX) is an ordinary exchange; binding a queue to it gives you a place where failed messages accumulate with an x-death header describing why and how often. The combination of TTL and DLX is also how RabbitMQ implements delayed retry without a plugin: nack a failed message into a "wait" queue whose TTL is thirty seconds and whose dead-letter exchange routes back to the work queue.

Map<String, Object> args = Map.of(
    "x-queue-type", "quorum",
    "x-dead-letter-exchange", "orders.dlx",
    "x-delivery-limit", 5,               // quorum queues: dead-letter after 5 redeliveries
    "x-message-ttl", 86_400_000);        // one day
channel.queueDeclare("fulfilment", true, false, false, args);

Arguments set at declaration are frozen; changing them means deleting the queue. Prefer policies for anything that may change: rabbitmqctl set_policy dlx "^fulfilment$" '{"dead-letter-exchange":"orders.dlx"}' --apply-to queues applies the same setting without redeclaring, and can be updated live.

Administering the broker

The management plugin serves a web UI and an HTTP API on port 15672 (AMQP itself is on 5672, TLS on 5671, Prometheus metrics on 15692). It shows exchanges, bindings, queue depths, message rates, connections and channels, and lets you publish and get messages by hand for debugging. The default guest/guest account can only log in from localhost; create real users and grant them permissions per vhost before anything else connects:

rabbitmqctl add_vhost shop
rabbitmqctl add_user orders 'change-me'
rabbitmqctl set_permissions -p shop orders '^orders.*' '^orders$' '^(fulfilment|orders.*)$'
#                                          configure     write       read     (regular expressions on names)
rabbitmqctl list_queues -p shop name type messages messages_unacknowledged consumers
rabbitmq-diagnostics status

The three permission patterns are regular expressions over resource names for configure (declare and delete), write (publish to an exchange) and read (consume from a queue, bind a queue). The rabbitmqadmin command-line tool wraps the HTTP API for scripting declarations, and rabbitmq-diagnostics reports node health, alarms and cluster status. The first alarm you meet in practice is the memory or disk resource alarm: when a node exceeds its high watermark it blocks all publishing connections until consumers catch up, which looks to the publisher like a hang.

Common mistakes

  • Publishing to a queue name on a custom exchange. The routing key must match a binding; with no binding, the message is dropped and nothing is logged. Use mandatory plus a return listener while developing.
  • A connection per message, or a channel shared across threads. The first exhausts file descriptors and the broker; the second corrupts the protocol stream. One connection per process, one channel per thread.
  • Durable queue, transient message. Delivery mode 1 on a classic queue does not survive a restart even though the queue does. Use mode 2, or quorum queues which ignore the distinction.
  • No prefetch. One consumer takes everything, the rest idle, and a crash redelivers thousands. Always call basicQos.
  • Infinite requeue loops. A poison message nacked with requeue = true comes straight back. Cap redeliveries with x-delivery-limit or an x-death check and dead-letter it.
  • Baking mutable settings into queue arguments. TTLs, limits and DLX names change; queue arguments cannot. Use policies.

Key takeaways

  • Publishers send to exchanges with a routing key; bindings decide which queues receive copies; consumers read queues. Nothing else in RabbitMQ makes sense without this model.
  • Direct exchanges match keys exactly, fanout copies to everyone, topic matches * and # patterns, headers matches attributes; one topic exchange per context with a routing-key convention covers most designs.
  • Quorum queues are the default choice for durable work; classic queues serve transient and exclusive roles; streams add replayable logs.
  • At-least-once delivery needs durable exchange, durable queue, persistent message, publisher confirms and manual acknowledgements together.
  • basicQos prefetch keeps consumers fair and crashes cheap; consumer timeouts and delivery limits stop stuck or poisoned messages from taking the broker down.
  • Express TTLs, length limits and dead-letter routing as policies so they can change without redeclaring queues.

Sources and further reading

Frequently asked questions

Why does my message vanish when I publish it to a queue?
You never publish to a queue in AMQP 0-9-1; you publish to an exchange with a routing key. If no binding matches, the exchange drops the message silently. Publishing with an empty exchange name uses the default exchange, which routes to the queue whose name equals the routing key — that is what makes the tutorials look as if they publish to queues. Set the mandatory flag or configure an alternate exchange to catch unroutable messages.
Should new queues be classic or quorum?
Quorum for anything whose loss would matter and for anything that must survive a node failure: they replicate through Raft and are the type RabbitMQ recommends since classic mirrored queues were removed in 4.0. Classic queues remain right for transient, exclusive or short-lived queues such as reply queues, and for low-latency single-node use. Streams are a third type for large retained logs with replay.
What is the difference between a channel and a connection?
A connection is a TCP connection with TLS and authentication. A channel is a lightweight virtual connection multiplexed inside it, and almost every AMQP operation happens on a channel. Applications keep one long-lived connection per process and open a channel per thread; channels are not thread-safe, and opening a connection per message is the most expensive mistake you can make.
Does RabbitMQ preserve message order?
Within a single queue, messages are enqueued in publish order from one channel and delivered in that order to a single consumer. With several competing consumers, or after a redelivery, order is no longer guaranteed. Use one consumer, the single-active-consumer queue property, or consistent-hash partitioning into several queues when order matters.