RabbitMQ Delayed Delivery

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.

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 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. By having 28 of these 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.

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.v2.delay-level-03 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.v2.delay-level-03 queue, where it will wait until the TTL expires (2^3 seconds) before being forwarded to the nsb.v2.delay-level-02 exchange.
• If the value is a 0, the exchange will route the message to the nsb.v2.delay-level-02 exchange.

Delivery

At the end of this process, the message is routed to the nsb.v2.delay-delivery 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 #.EndpointName 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.0.1.0.destination, and it is published to the Level 3 exchange:

This example can be visualized using the following

Backwards compatibility

Non-native to native

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.

Migrating timeouts to native delayed delivery

In order to migrate timeouts to the native-delay delivery implementation, the migration tool can be used.

v1 to v2

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.

Migrating delayed messages to v2

The delays migrate command provided by the command line tool can be used to migrate existing delayed messages.

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);