In versions 4.3 and above, the RabbitMQ transport no longer relies on the timeout manager to implement delayed delivery. Instead, the transport creates infrastructure inside the broker which can delay messages using native RabbitMQ features.
When an endpoint is started, the transport declares a set of topic exchanges, queues, and bindings that work together to provide the necessary infrastructure to support delayed messages. Exchanges and queues are grouped to provide 28 delay levels. There is one final delivery exchange in addition to the delay-level exchanges. When a message needs to be delayed, the value of the desired delay is first converted to seconds. The binary representation of this value is used as part of the routing key when the message is sent to the delay-level exchanges. The full routing key has the following format:
N is either
1, representing the delay value in binary, and
destination is the name of endpoint the delayed message will be sent to.
As an example, a delay of 10 seconds (
1010 in binary) on a message bound for the
destination queue is encoded with a routing key of:
Each exchange/queue pair that makes up a level represents one bit of the total delay value. By having 28 of these levels, corresponding to
2^0, the delay infrastructure can delay a message for any value that can be represented by a 28-bit number.
A delay level is created by declaring a topic exchange that is bound to a queue with a routing key of
1, and to the exchange corresponding to
level - 1 with a routing key of
0. The queue for the delay level is declared with an
x-message-ttl value corresponding to
2^level seconds. The queue is also declared with an
x-dead-letter-exchange value corresponding to the
level - 1 exchange, so that when a message in the queue expires, it will be routed to the
level - 1 exchange.
The delay levels are connected in this manner, from highest (27) to lowest (0). Each delay level's routing key adds wildcards as needed so that each routing key is looking at the portion of the message's routing key that corresponds to its delay level.
The following diagram illustrates the relationships between the exchanges and queues in the delay infrastructure, which are connected by bindings and
x-dead-letter-exchange values. It's important to note the wildcard rules for RabbitMQ binding expressions, where word describes a dot-delimited segment:
*substitutes for exactly one word
#substitutes for 0 or more words
To avoid unnecessary traversal through the delay infrastructure, the message is published to the first applicable exchange by identifying the first level that will route to a queue, or in other words, the first
1 in the routing key. In the 10-second example (binary
1010), the message would first be published to the
nsb. exchange, and all of that exchange's bindings are evaluated. Only two bindings exist for the exchange, so:
- If the value is a
1, the exchange will route the message to the
nsb.queue, where it will wait until the TTL expires (2^3 seconds) before being forwarded to the
- If the value is a
0, the exchange will route the message to the
At the end of this process, the message is routed to the
nsb. exchange. It is at this final step where the message destination is evaluated to determine where the message should be routed to.
Every endpoint that can receive delayed messages will create bindings like
#. to this exchange to control final routing. The exact process depends upon the routing topology in use. These bindings match any combination of delay values, but only the binding for the correct destination endpoint will match, resulting in the message being delivered only to the correct endpoint.
This example illustrates the delay mentioned above, showing a message sent with a delay of 10 seconds to an endpoint called
destination. For brevity, the number of delay levels has been reduced to 4, so the routing key for this message is
1., and it is published to the Level 3 exchange:
|Routing Key Segment
|Delay in Queue
|Level 03 Queue
|Level 02 Exchange
|Level 01 Exchange
|Level 01 Queue
|Level 00 Exchange
This example can be visualized using the following
It is safe to operate a combination of native-delay and non-native-delay endpoints at the same time. Native endpoints can send delayed messages to endpoints that are not yet aware of the native delay infrastructure. Native endpoints can continue to receive delayed messages from non-native endpoints as well.
In order to migrate timeouts to the native-delay delivery implementation, the migration tool can be used.
The v1 and v2 infrastructure can exist side-by-side in the broker, so delayed messages will continue to work regardless of what version of the infrastructure an endpoint is using.
delays migrate command provided by the command line tool can be used to migrate existing delayed messages.