The RabbitMQ transport implements delayed delivery by creating infrastructure inside the broker that delays messages using native RabbitMQ features.
How it works
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.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.N.destination
Where N is either 0 or 1, representing the delay value in binary, and destination is the name of the 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:
0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.0.1.0.destination
Delay levels
Each exchange/queue pair that makes up a level represents one bit of the total delay value. With 28 levels, corresponding to 2^27 through 2^0, the delay infrastructure can delay a message for any value that can be represented by a 28-bit number.
With 28 total levels, the maximum delay value is 268,435,455 seconds, or about 8.5 years.
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 thensb.queue, where it will wait until the TTL expires (2^3 seconds) before being forwarded to thev2. delay-level-03 nsb.exchange.v2. delay-level-02 - If the value is a
0, the exchange will route the message to thensb.exchange.v2. delay-level-02
Delivery
At the end of this process, the message is routed to the nsb. exchange. At this final step, 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.
Example
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:
| Exchange | Routing Key Segment | Routing Value | Routed To | Delay in Queue | Dead-letter To |
|---|---|---|---|---|---|
| Level 03 | 1.0.1.0.destination | 1 | Level 03 Queue | 8 seconds | Level 02 Exchange |
| Level 02 | 1.0.1.0.destination | 0 | Level 01 Exchange | - | - |
| Level 01 | 1.0.1.0.destination | 1 | Level 01 Queue | 2 seconds | Level 00 Exchange |
| Level 00 | 1.0.1.0.destination | 0 | Delivery Exchange | - | - |
| Delivery Exchange | 1.0.1.0.destination | destination | destination | - | - |
The following diagram visualizes this example:
Disabling delayed delivery
From version 9.1 and higher it is possible to disable the creation of the delayed delivery infrastructure. This can be useful in integration scenarios where the creation of the delayed delivery infrastructure is undesirable.
var rabbitMqTransport = new RabbitMQTransport(
routingTopology: RoutingTopology.Conventional(QueueType.Classic),
connectionString: "host=localhost;username=rabbitmq;password=rabbitmq",
enableDelayedDelivery: false
);
endpointConfiguration.UseTransport(rabbitMqTransport);
Saga timeouts and delayed retries depend on delayed delivery.
RabbitMQ upgrade
When upgrading the RabbitMQ cluster, it is recommended to use the rolling (in-place) method.
Upgrading RabbitMQ by using blue-green deployments is more complicated because standard tools, such as the shovel, are not aware of how the delay infrastructure is implemented and cannot move delayed messages.
Contact Particular support for details on moving delayed messages from one broker to another.