feat(consumer): one-call dead-letter queue setup

[KARTIKrocks]

Add ConsumerConfig.WithDeadLetterQueue (with DeadLetterConfig and DefaultDeadLetterConfig): it declares the dead-letter exchange, the dead-letter queue, the binding between them, and wires the work queue's x-dead-letter-exchange — replacing four hand-written declarations. Like the rest of the consumer topology, it is re-applied in applyTopology on every channel setup, so it survives reconnects and broker restarts.

Add Consumer.DeadLetterQueueName() so a second consumer can read the DLQ without re-deriving the name.

Pairs with the v0.6.0 reject-by-default behaviour: a failed handler now dead-letters into the configured DLQ instead of discarding.

Summary

Motivation

Fixes #

Changes

Checklist

• fmt, vet, lint, test, build passes (make all)
• New code has tests where appropriate
• Breaking changes are documented

Summary by CodeRabbit

• New Features

  • Added one-call dead-letter queue setup for consumers.
  • Messages can now be routed to a dedicated queue when processing fails, with support for retrieving the dead-letter queue name.

• Bug Fixes

  • Dead-letter routing is now restored automatically after reconnects and restarts, helping prevent message loss.

• Documentation

  • Updated the changelog and README with setup guidance and usage examples for dead-letter queues.

[coderabbitai]

Warning

Review limit reached

@KARTIKrocks, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3da87844-4a07-4140-8dcc-a4d376588770

📥 Commits

Reviewing files that changed from the base of the PR and between 54c309f and 910d54e.

📒 Files selected for processing (2)

• consumer.go
• consumer_test.go

Walkthrough

This PR adds one-call dead-letter queue (DLQ) support to the consumer API: a new DeadLetterConfig type with builders and defaults, ConsumerConfig.WithDeadLetterQueue, topology declaration via applyDeadLetter, a DeadLetterQueueName() accessor, plus unit tests, integration tests, and documentation.

Changes

Dead-Letter Queue Feature

Layer / File(s)	Summary
DeadLetterConfig type and ConsumerConfig wiring consumer.go	Adds DeadLetterConfig struct, DefaultDeadLetterConfig, fluent setters, buildArgs(), ConsumerConfig.DeadLetter field, and WithDeadLetterQueue which synthesizes or updates QueueConfig with DLX routing args.
Topology declaration and accessor consumer.go	applyTopology now calls new applyDeadLetter to idempotently declare DLX/DLQ/binding before the work queue; adds DeadLetterQueueName() accessor.
Unit tests consumer_test.go	Tests for defaults, builder chaining, buildArgs, QueueConfig synthesis/preservation, and copy semantics of the stored config.
Integration tests integration_test.go	Verifies end-to-end DLQ delivery and confirms topology is restored after a forced reconnect.
Documentation CHANGELOG.md, README.md	Adds 0.7.0 changelog entry and a README "Dead-Letter Queues" section with example; reformats Built-in Middleware table.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Publisher
  participant WorkQueue
  participant Consumer
  participant DLX
  participant DLQConsumer
  Publisher->>WorkQueue: publish message
  WorkQueue->>Consumer: deliver message
  Consumer->>Consumer: handler fails, reject
  Consumer->>DLX: message dead-lettered
  DLX->>DLQConsumer: deliver to DLQ
  Note over Consumer: connection dropped/reconnected
  Consumer->>Consumer: applyTopology re-declares DLX/DLQ/bind
  Publisher->>WorkQueue: publish message again
  WorkQueue->>Consumer: deliver, handler fails
  Consumer->>DLX: message dead-lettered
  DLX->>DLQConsumer: deliver to DLQ

Loading

Poem

A rabbit hops, a message fails,
Rejected once, but never derails —
To DLX and DLQ it flees,
Reconnects too? Rebuilt with ease. 🐰📬
Hop, bind, declare — resilience prevails.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description only partially fills the template and leaves Summary, Motivation, Changes, and Checklist mostly as placeholders.	Rewrite it using the repo template: add a real Summary, Motivation with issue link, concrete Changes bullets, and a completed checklist.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: one-call dead-letter queue setup.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/consumer-dlq-helper

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov-commenter]

Codecov Report

❌ Patch coverage is 68.05556% with 23 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
consumer.go	68.05%	23 Missing ⚠️

📢 Thoughts on this report? Let us know!

[KARTIKrocks]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@consumer.go`:
- Around line 183-210: The issue is that WithDeadLetterQueue forces a
QueueConfig even when ConsumerConfig.Queue is empty, which breaks the
server-named queue path and can orphan queues on reconnect. Update
WithDeadLetterQueue to guard against anonymous work queues by failing fast when
c.Queue is empty and c.QueueConfig is nil, or preserve the existing server-named
behavior instead of synthesizing a QueueConfig; keep the fix centered in
ConsumerConfig.WithDeadLetterQueue and the topology setup flow it feeds.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3b7706b8-fa40-471f-a83a-f3cab215f307

📥 Commits

Reviewing files that changed from the base of the PR and between 4c3e2b9 and 54c309f.

📒 Files selected for processing (5)

• CHANGELOG.md
• README.md
• consumer.go
• consumer_test.go
• integration_test.go