↓Skip to main content

RabbitMQ Internals: A Substrate Decomposition

Table of Contents

The AMQP 0-9-1 protocol defines what a broker must do. RabbitMQ is one implementation of that contract — but the protocol says nothing about how the implementation is structured. Understanding how RabbitMQ actually works requires reading the source, not the spec.

This series decomposes RabbitMQ into six independent substrates, each with a clear boundary, its own Erlang process topology, and its own failure mode. The decomposition is grounded in the actual source code in deps/rabbit/src/ and deps/rabbit_common/src/.

The six substrates are not a conceptual model imposed from outside — they emerge directly from the module boundaries in the source tree:

SubstratePrimary modules
Transportrabbit_reader, rabbit_writer, rabbit_heartbeat, rabbit_binary_parser, rabbit_framing_amqp_0_9_1
Channel Multiplexerrabbit_channel, rabbit_confirms, rabbit_limiter, rabbit_channel_sup
Routingrabbit_exchange_type_{direct,fanout,topic,headers}, rabbit_db_topic_exchange, rabbit_binding
Classic Queue Storagerabbit_variable_queue, rabbit_classic_queue_index_v2, rabbit_classic_queue_store_v2, rabbit_msg_store
Quorum Queue Storagerabbit_quorum_queue, rabbit_fifo, rabbit_fifo_client (Ra / Raft)
Deliveryrabbit_queue_consumers, rabbit_limiter, rabbit_amqqueue_process
Cluster / Metadatarabbit_khepri, rabbit_db_*, rabbit_peer_discovery

Chapters #

Part 1: Client-Facing Substrates #

  1. The Six Substrates — A Map of the Broker — process topology, OTP supervision tree, how the substrates connect
  2. Transport Substrate — rabbit_reader and rabbit_writer — Ranch acceptors, recvloop/mainloop, frame parsing, backpressure throttle, heartbeat, connection.blocked
  3. Channel Multiplexer Substrate — rabbit_channel — gen_server2, channel state machine, publisher confirm tracking in rabbit_confirms, prefetch via rabbit_limiter

Part 2: Routing and Storage #

  1. Routing Substrate — Exchange Types and the Topic Trie — rabbit_exchange_type behaviour, direct/fanout/headers implementations, topic trie in rabbit_db_topic_exchange, Khepri projection
  2. Classic Queue Storage Substrate — rabbit_variable_queue — ram/disk duality, queue index v2, classic queue store v2, shared msg_store, seq_id ordering, pending acks
  3. Quorum Queue Storage Substrate — Ra and rabbit_fifo — Ra Raft machine, rabbit_fifo state machine, rabbit_fifo_client, enqueue/checkout/settle, delivery limit

Part 3: Delivery and Cluster #

  1. Delivery Substrate — rabbit_queue_consumers — consumer registry, limiter/prefetch enforcement, single-active-consumer, credit-based flow, requeue on disconnect
  2. Cluster and Metadata Substrate — Khepri and Mnesia — Khepri (Ra-based KV tree), Mnesia legacy, rabbit_db_* abstraction layer, topic trie Khepri projection, peer discovery, Mnesia→Khepri migration