Allow custom headers when messages are dead-lettered via BasicNack/BasicReject

[fuatozerr]

Is your feature request related to a problem? Please describe.

When a message is dead-lettered via basic.nack or basic.reject with requeue=false,
there is no way to attach custom headers to the dead-lettered message.

Currently, RabbitMQ only adds the x-death header automatically, which contains:

• queue: Original queue name
• exchange: Original exchange name
• reason: rejected, expired, maxlen, or delivery_limit
• count: Number of times dead-lettered
• time: Timestamp
• routing-keys: Original routing keys

Application-level context about why the message failed:

• Exception message (e.g., "Connection timeout to database")
• Exception type (e.g., System.TimeoutException)
• Stack trace (truncated)
• Retry count before failure
• Custom application metadata

Describe the solution you'd like

Introduce a new method like basic.dead-letter: like a
await channel.BasicNackAsync(
deliveryTag: ea.DeliveryTag,
multiple: false,
requeue: false,
headers: new Dictionary<string, object?> // NEW PARAMETER
{
["x-error-reason"] = "Connection timeout",
["x-error-type"] = "System.TimeoutException"
});
or

await channel.BasicRejectWithAnnotationsAsync(
deliveryTag: ea.DeliveryTag,
annotations: new Dictionary<string, object?>
{
["x-error-reason"] = "Validation failed",
["x-validation-errors"] = "['Field X is required', 'Field Y is invalid']"
});

Describe alternatives you've considered

No response

Additional context

No response

[michaelklishin]

@fuatozerr while we can extend the protocol with new methods, the bar for doing that is very high.
And this issue does not clear it.

If your applications need to provide more context to other applications, they can use the request-response (tutorial 6) approach and make the "server" part send an extra message before negatively acknowledging the delivery.

Logging more context, tracing and metrics also help with observability.

The x-death already contains a fair amount of context that applications cannot get any other way.
For application-specific details, send additional messages to the apps that need that context.

Conclusion: we won't introduce a new protocol method for passing stack traces around in basic.nack, basic.reject-like negative consumer acknowledgements.

[fuatozerr]

thank you

[kjnilsson]

@fuatozerr RabbitMQ already supports this but you have to use the AMQP (1.0) protocol and "modified" outcome. See: https://www.rabbitmq.com/blog/2024/10/11/modified-outcome

[fuatozerr]

thank you