Updated dead-letter-exchange.txt

AlexanderSemenets authored
revision 455da205be48a439e1ff1a1808b171df1463b674
# Dead Letter Exchange

It is possible to form a cycle of message dead-lettering. For instance, this can happen when a queue dead-letters messages to the default exchange without specifiying a dead-letter routing key. Messages in such cycles (i.e. messages that reach the same queue twice) will be dropped if there was no rejections in the entire cycle.

Dead-lettering a message modifies its headers:

the exchange name is replaced with that of the latest dead-letter exchange,
the routing key may be replaced with that specified in a queue performing dead lettering,
if the above happens, the CC header will also be removed, and
the BCC header will be removed as per Sender-selected distribution.

The dead-lettering process adds an array to the header of each dead-lettered message named x-death. This array contains an entry for each dead lettering event, identified by a pair of {queue, reason}. Each such entry is a table that consists of several fields:

queue - the name of the queue the message was in before it was dead-lettered,
reason - see below,
time - the date and time the message was dead lettered as a 64-bit AMQP format timestamp,
exchange - the exchange the message was published to (note that this will be a dead letter exchange if the message is dead lettered multiple times),
routing-keys - the routing keys (including CC keys but excluding BCC ones) the message was published with,
count - how many times this message was dead-lettered in this queue for this reason, and
original-expiration (if the message was dead-letterered due to per-message TTL) - the original expiration property of the message. The expiration property is removed from the message on dead-lettering in order to prevent it from expiring again in any queues it is routed to.
New entries are prepended to the beginning of the x-death array. In case x-death already contains an entry with the same queue and dead lettering reason, its count field will be incremented and it will be moved to the beginning of the array.
The reason is a name describing why the message was dead-lettered and is one of the following:

rejected - the message was rejected with requeue=false,
expired - the TTL of the message expired; or
maxlen - the maximum allowed queue length was exceeded.