Idempotency + Dead Letter Queue: защита от дублей и ям
Idempotency + Dead Letter Queue: защита от дублей и ям
Повторная доставка сообщений - не баг, а нормальное явление. Consumer упал после обработки, но до ack (как именно работают ack, nack и prefetch)? Сообщение доставится снова. Значит, обработчики обязаны быть идемпотентными - см. идемпотентность в event-driven.
Exactly-once vs At-least-once
Гарантия доставки Реальность
────────────────── ─────────────────────────────────────
At-most-once Сообщение может потеряться (auto-ack)
At-least-once Сообщение может прийти дважды (manual ack) ← обычно выбираем
Exactly-once RabbitMQ такого режима не даёт
Формулировка «exactly-once невозможен» ходит по статьям, но она неточная - и из неё делают неверный вывод, будто транзакции Kafka маркетинг. Точнее так:
End-to-end exactly-once для произвольных внешних эффектов нельзя получить одной транспортной гарантией. Kafka даёт exactly-once в границах своей транзакции - чтение из топика, запись в топик и коммит offset атомарны (как это выглядит в коде). RabbitMQ подобного механизма не предоставляет вовсе. Но как только эффект уходит за пределы брокера - запись в PostgreSQL, письмо, чужой HTTP-API, - гарантия заканчивается, и «ровно один раз» обеспечивает уже идемпотентность обработчика.
Для RabbitMQ это значит: берём at-least-once + idempotency и получаем «effectively once»:
At-least-once delivery + Idempotent handler = Effectively-once processing
Idempotency: inbox-таблица
Самый надёжный способ - сохранять event_id обработанных сообщений. Но здесь
есть ловушка, из-за которой защита от дублей превращается в потерю данных,
поэтому начнём с неправильного варианта.
Как делать нельзя
НЕПРАВИЛЬНО - разбор ниже
1. INSERT INTO inbox (event_id, handler) ... ON CONFLICT DO NOTHING
2. если вставки не было → «уже обработано», выходим
3. вызываем handler ← а если здесь ошибка?
Отметка «обработано» ставится до самой обработки. Между этими двумя
строками есть окно: если handler упадёт - сеть, паника, OOM killer,
перезапуск пода, - в базе останется запись, что событие обработано,
а бизнес-операции не будет.
RabbitMQ честно доставит сообщение снова. Consumer посмотрит в inbox, увидит
0 affected rows и скажет «дубль, пропускаю». Событие потеряно навсегда,
и никакой алерт об этом не сработает: с точки зрения брокера всё в порядке,
сообщение подтверждено.
Ирония в том, что такой код выглядит как защита от потерь, а сам их создаёт.
Как правильно
Отметка и бизнес-операция должны быть в одной транзакции базы - тогда при ошибке откатятся вместе.
CREATE TABLE inbox (
event_id TEXT NOT NULL,
handler TEXT NOT NULL, -- какой обработчик выполнил
processed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-- Ключ составной, и это принципиально: одно событие обрабатывают
-- несколько подписчиков. При PRIMARY KEY (event_id) второй обработчик
-- увидел бы конфликт и решил, что это дубль первого - хотя свою работу
-- ещё не делал.
PRIMARY KEY (event_id, handler)
);
// Handler получает транзакцию, а не открывает своё соединение.
//
// Это не украшение сигнатуры, а условие корректности: обработчик со своим
// соединением коммитится отдельно от отметки в inbox, и «одна транзакция»
// становится неправдой при живом `BeginTx` в коде рядом.
type Handler func(ctx context.Context, tx *sql.Tx, event []byte) error
// IdempotentHandler отмечает событие обработанным и выполняет работу
// в одной транзакции.
type IdempotentHandler struct {
db *sql.DB
name string // имя обработчика: часть ключа дедупликации
handle Handler
log *slog.Logger
}
func New(db *sql.DB, name string, handle Handler, log *slog.Logger) *IdempotentHandler {
return &IdempotentHandler{db: db, name: name, handle: handle, log: log}
}
// Handle обрабатывает событие ровно один раз на обработчика.
//
// Порядок шагов важен: сначала транзакция, потом отметка, потом работа.
// Отметка служит и проверкой - отдельный SELECT перед INSERT прошли бы
// два воркера одновременно, оба увидев «не обработано».
func (h *IdempotentHandler) Handle(ctx context.Context, eventID string, body []byte) error {
tx, err := h.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
// После успешного Commit это no-op, а при любом раннем return
// транзакция откатится - вместе с отметкой в inbox.
defer tx.Rollback()
res, err := tx.ExecContext(ctx,
`INSERT INTO inbox (event_id, handler)
VALUES ($1, $2)
ON CONFLICT (event_id, handler) DO NOTHING`,
eventID, h.name,
)
if err != nil {
return fmt.Errorf("inbox insert: %w", err)
}
rows, err := res.RowsAffected()
if err != nil {
return fmt.Errorf("rows affected: %w", err)
}
if rows == 0 {
// Этот обработчик событие уже проводил - подтверждаем и уходим.
h.log.Info("duplicate event, skipping",
slog.String("event_id", eventID),
slog.String("handler", h.name),
)
return nil
}
// Бизнес-операция в той же транзакции. Ошибка здесь откатит и отметку.
if err := h.handle(ctx, tx, body); err != nil {
return fmt.Errorf("handler: %w", err)
}
return tx.Commit()
}
<?php
declare(strict_types=1);
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
final class IdempotentHandler
{
/** @param callable(Connection $tx, string $body): void $handler */
public function __construct(
private readonly Connection $db,
private readonly LoggerInterface $logger,
private readonly string $name,
private readonly Closure $handler,
) {}
public function handle(string $eventId, string $body): void
{
// transactional откатит всё при исключении - и отметку, и работу
// обработчика. Ключ в том, что обработчик пишет через тот же $tx.
$this->db->transactional(function (Connection $tx) use ($eventId, $body): void {
$inserted = $tx->executeStatement(
'INSERT INTO inbox (event_id, handler) VALUES (:id, :name)
ON CONFLICT (event_id, handler) DO NOTHING',
['id' => $eventId, 'name' => $this->name],
);
if ($inserted === 0) {
$this->logger->info('duplicate event {id} for {handler}, skipping', [
'id' => $eventId,
'handler' => $this->name,
]);
return;
}
($this->handler)($tx, $body);
});
}
}
import logging
from typing import Callable
import psycopg
from psycopg_pool import ConnectionPool
# Handler получает соединение с открытой транзакцией, а не берёт своё из пула.
#
# Это не украшение сигнатуры, а условие корректности: обработчик со своим
# соединением коммитится отдельно от отметки в inbox, и «одна транзакция»
# становится неправдой при живом pool.connection() в коде рядом.
Handler = Callable[[psycopg.Connection, bytes], None]
class IdempotentHandler:
"""Отмечает событие обработанным и выполняет работу
в одной транзакции.
"""
def __init__(self, pool: ConnectionPool, name: str, handle: Handler, log: logging.Logger) -> None:
self._pool = pool
self._name = name # имя обработчика: часть ключа дедупликации
self._handle = handle
self._log = log
# handle обрабатывает событие ровно один раз на обработчика.
#
# Порядок шагов важен: сначала транзакция, потом отметка, потом работа.
# Отметка служит и проверкой - отдельный SELECT перед INSERT прошли бы
# два воркера одновременно, оба увидев «не обработано».
def handle(self, event_id: str, body: bytes) -> None:
# Аналог defer tx.Rollback() + tx.Commit(): выход из with без исключения -
# commit, любое исключение - rollback вместе с отметкой в inbox.
with self._pool.connection() as conn, conn.transaction():
cur = conn.execute(
"""INSERT INTO inbox (event_id, handler)
VALUES (%s, %s)
ON CONFLICT (event_id, handler) DO NOTHING""",
(event_id, self._name),
)
if cur.rowcount == 0:
# Этот обработчик событие уже проводил - подтверждаем и уходим.
self._log.info(
"duplicate event, skipping",
extra={"event_id": event_id, "handler": self._name},
)
return
# Бизнес-операция в той же транзакции. Исключение здесь откатит и отметку.
self._handle(conn, body)
⚠️ Транзакция работает только если в неё пишут
Обработчик принимает транзакцию, а не пул соединений, и это не стилистика. Если внутри он возьмёт соединение сам - через глобальный пул, другой репозиторий или отдельный
db.Exec- его запись окажется вне транзакции с отметкой, и мы вернёмся к тому же окну отказа, только менее заметному.Правило простое: отметка и всё, что она защищает, пишутся одним и тем же
tx. Если бизнес-операция физически не может быть в этой транзакции - например, это отправка письма или вызов чужого API - inbox не поможет, нужен outbox и повторная попытка на стороне получателя.
ℹ️ Inbox в той же базе, что бизнес-данные
Из того же правила: inbox лежит в базе, куда пишет обработчик. Отдельная «база под идемпотентность» ломает всю схему - две базы нельзя изменить атомарно без распределённых транзакций, которые здесь никто не разворачивает.
Idempotency через бизнес-логику
Иногда inbox не нужен - операция сама по себе идемпотентна:
// Идемпотентно: UPSERT не создаст дубль
func MarkLessonCompleted(ctx context.Context, db *sql.DB, userID, lessonID int64) error {
_, err := db.ExecContext(ctx,
`INSERT INTO progress (user_id, lesson_id, completed, completed_at)
VALUES ($1, $2, true, now())
ON CONFLICT (user_id, lesson_id)
DO UPDATE SET completed = true, completed_at = COALESCE(progress.completed_at, now())`,
userID, lessonID,
)
return err
}
// НЕ идемпотентно: каждый вызов добавляет запись
func AddPoints(ctx context.Context, db *sql.DB, userID int64, points int) error {
_, err := db.ExecContext(ctx,
`UPDATE users SET points = points + $1 WHERE id = $2`,
points, userID,
)
return err // повторный вызов удвоит очки!
}
<?php
declare(strict_types=1);
use Doctrine\DBAL\Connection;
final class ProgressService
{
public function __construct(
private readonly Connection $db,
) {}
// Идемпотентно: UPSERT не создаст дубль
public function markLessonCompleted(int $userId, int $lessonId): void
{
$this->db->executeStatement(
'INSERT INTO progress (user_id, lesson_id, completed, completed_at)
VALUES (:uid, :lid, TRUE, NOW())
ON CONFLICT (user_id, lesson_id)
DO UPDATE SET completed = TRUE,
completed_at = COALESCE(progress.completed_at, NOW())',
['uid' => $userId, 'lid' => $lessonId],
);
}
// НЕ идемпотентно: каждый вызов прибавит очки
public function addPoints(int $userId, int $points): void
{
$this->db->executeStatement(
'UPDATE users SET points = points + :p WHERE id = :id',
['p' => $points, 'id' => $userId],
);
// повторный вызов удвоит очки!
}
}
from psycopg_pool import ConnectionPool
# Идемпотентно: UPSERT не создаст дубль
def mark_lesson_completed(pool: ConnectionPool, user_id: int, lesson_id: int) -> None:
with pool.connection() as conn:
conn.execute(
"""INSERT INTO progress (user_id, lesson_id, completed, completed_at)
VALUES (%s, %s, true, now())
ON CONFLICT (user_id, lesson_id)
DO UPDATE SET completed = true, completed_at = COALESCE(progress.completed_at, now())""",
(user_id, lesson_id),
)
# НЕ идемпотентно: каждый вызов добавляет запись
def add_points(pool: ConnectionPool, user_id: int, points: int) -> None:
with pool.connection() as conn:
conn.execute(
"UPDATE users SET points = points + %s WHERE id = %s",
(points, user_id),
)
# повторный вызов удвоит очки!
Если операция не идемпотентна по природе - используй inbox.
Dead Letter Queue (DLQ)
DLQ - карантин для сообщений, которые не удалось обработать. Это не мусорка - это место для анализа и повторной обработки.
Настройка DLQ в RabbitMQ
// 1. Создаём DLQ exchange и queue
ch.ExchangeDeclare("dlx", "topic", true, false, false, false, nil)
ch.QueueDeclare("dlq.progress", true, false, false, false, nil)
ch.QueueBind("dlq.progress", "#", "dlx", false, nil)
// 2. Основная очередь с DLQ настройкой
ch.QueueDeclare("progress-worker", true, false, false, false, amqp.Table{
"x-dead-letter-exchange": "dlx", // куда отправлять отклонённые
"x-dead-letter-routing-key": "progress.dead", // routing key в DLX
})
<?php
declare(strict_types=1);
use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Wire\AMQPTable;
final class DlqTopology
{
public function __construct(
private readonly AMQPChannel $ch,
) {}
public function declare(): void
{
// 1. Создаём DLQ exchange и queue
$this->ch->exchange_declare('dlx', 'topic', false, true, false);
$this->ch->queue_declare('dlq.progress', false, true, false, false);
$this->ch->queue_bind('dlq.progress', 'dlx', '#');
// 2. Основная очередь с DLQ настройкой
$this->ch->queue_declare(
queue: 'progress-worker',
durable: true,
auto_delete: false,
arguments: new AMQPTable([
'x-dead-letter-exchange' => 'dlx', // куда отправлять отклонённые
'x-dead-letter-routing-key' => 'progress.dead', // routing key в DLX
]),
);
}
}
# 1. Создаём DLQ exchange и queue
ch.exchange_declare(exchange="dlx", exchange_type="topic", durable=True)
ch.queue_declare(queue="dlq.progress", durable=True)
ch.queue_bind(queue="dlq.progress", exchange="dlx", routing_key="#")
# 2. Основная очередь с DLQ настройкой - аргументы обычным dict
ch.queue_declare(
queue="progress-worker",
durable=True,
arguments={
"x-dead-letter-exchange": "dlx", # куда отправлять отклонённые
"x-dead-letter-routing-key": "progress.dead", # routing key в DLX
},
)
Теперь msg.Nack(false, false) (без requeue) отправит сообщение в DLQ вместо удаления.
⚠️ Не ставь TTL на рабочую очередь
x-message-ttlна рабочей очереди отправит в DLQ любое сообщение, которое пролежало в ней дольше TTL, даже если его ни разу не пытались обработать: достаточно, чтобы consumer-ы отстали в пиковую нагрузку. DLQ заполнится валидными сообщениями сreason: expired. TTL нужен на retry-очереди, где задержка и есть цель, - об этом ниже.
ack
Consumer ◄──── Queue ◄──── Exchange
│ │
│ error │ nack(requeue=false)
│ ▼
└────────► DLQ Queue ◄──── DLX Exchange
Что должно быть в DLQ-сообщении
RabbitMQ добавляет заголовок x-death при dead-lettering - то есть когда
сообщение отвергнуто без requeue, протухло по TTL или вытеснено по длине
очереди:
x-death: [
{
count: 3 # сколько раз через эту очередь с этой причиной
reason: rejected # rejected | expired | maxlen | delivery_limit
queue: progress-worker # из какой очереди выпало
time: 2026-05-05 12:00:00
exchange: events
routing-keys: [lesson.completed]
},
{ count: 3, reason: expired, queue: retry.progress, ... }
]
⚠️ x-death - массив, а не счётчик
Записи группируются по паре очередь + причина, поэтому в retry-цикле их будет несколько: одна про
rejectedиз рабочей очереди, другая проexpiredиз retry-очереди. Читатьx-death[0].countи считать это «числом попыток» - ошибка, которая проявится при первом же усложнении топологии.Нужную запись ищут по имени очереди и причине - как в
retryCountиз раздела про poison messages ниже.И главное:
x-deathпоявляется только при dead-lettering. Если отвергать сообщение сrequeue=true, оно вернётся в очередь напрямую, минуя DLX, - и счётчик не изменится никогда. Про эту ловушку - в разделе про poison messages ниже.
Retry с DLQ
Паттерн «retry через DLQ» с задержкой:
1. Сообщение не обработано → nack(requeue=false) → через DLX в retry-очередь
2. Retry-очередь имеет TTL → через N секунд сообщение «протухает»
3. Retry-очередь имеет свой DLX → «протухшее» сообщение возвращается
только в progress-worker (через default exchange, а не в общий exchange)
4. Consumer пробует снова
5. После N попыток consumer сам публикует сообщение в финальную DLQ
Это другая схема, чем простая DLQ выше: у очереди только один DLX, и здесь он ведёт не в dlq.progress, а в retry-очередь. Аргументы существующей очереди поменять нельзя (RabbitMQ ответит PRECONDITION_FAILED), поэтому при переходе на retry-схему очередь progress-worker пересоздают.
Почему возврат идёт через default exchange (""), а не в events с ключом lesson.completed: сообщение из events попало бы во все очереди с подходящим binding (analytics-worker, email-worker...), и каждый ретрай одного consumer-а давал бы дубли у остальных. Default exchange кладёт сообщение ровно в очередь, имя которой совпадает с routing key.
// Retry-очередь с TTL: сообщение отлёживается 30 секунд и возвращается
// через default exchange ("") только в progress-worker
ch.QueueDeclare("retry.progress", true, false, false, false, amqp.Table{
"x-dead-letter-exchange": "", // default exchange: ключ = имя очереди
"x-dead-letter-routing-key": "progress-worker",
"x-message-ttl": int32(30000), // 30 секунд задержка
})
// Основная очередь: отказы (nack без requeue) уходят в retry.progress
ch.QueueDeclare("progress-worker", true, false, false, false, amqp.Table{
"x-dead-letter-exchange": "",
"x-dead-letter-routing-key": "retry.progress",
})
ch.QueueBind("progress-worker", "lesson.*", "events", false, nil)
// Финальная DLQ - её наполняет сам consumer после исчерпания ретраев
ch.QueueDeclare("dlq.progress.final", true, false, false, false, nil)
<?php
declare(strict_types=1);
use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Wire\AMQPTable;
final class RetryTopology
{
public function __construct(
private readonly AMQPChannel $ch,
) {}
public function declare(): void
{
// Retry-очередь с TTL: через 30 секунд сообщение вернётся
// через default exchange ('') только в progress-worker.
// auto_delete: false обязательно - в php-amqplib по умолчанию true.
$this->ch->queue_declare(
queue: 'retry.progress',
durable: true,
auto_delete: false,
arguments: new AMQPTable([
'x-dead-letter-exchange' => '', // default exchange
'x-dead-letter-routing-key' => 'progress-worker',
'x-message-ttl' => 30000, // 30 секунд задержка
]),
);
// Основная очередь: отказы уходят в retry.progress
$this->ch->queue_declare(
queue: 'progress-worker',
durable: true,
auto_delete: false,
arguments: new AMQPTable([
'x-dead-letter-exchange' => '',
'x-dead-letter-routing-key' => 'retry.progress',
]),
);
$this->ch->queue_bind('progress-worker', 'events', 'lesson.*');
// Финальная DLQ - её наполняет сам consumer после исчерпания ретраев
$this->ch->queue_declare('dlq.progress.final', durable: true, auto_delete: false);
}
}
# Retry-очередь с TTL: через 30 секунд сообщение вернётся
# через default exchange ("") только в progress-worker
ch.queue_declare(
queue="retry.progress",
durable=True,
arguments={
"x-dead-letter-exchange": "", # default exchange
"x-dead-letter-routing-key": "progress-worker",
"x-message-ttl": 30000, # 30 секунд задержка
},
)
# Основная очередь: отказы уходят в retry.progress
ch.queue_declare(
queue="progress-worker",
durable=True,
arguments={
"x-dead-letter-exchange": "",
"x-dead-letter-routing-key": "retry.progress",
},
)
ch.queue_bind(queue="progress-worker", exchange="events", routing_key="lesson.*")
# Финальная DLQ - её наполняет сам consumer после исчерпания ретраев
ch.queue_declare(queue="dlq.progress.final", durable=True)
Poison Messages
Poison message - сообщение, которое всегда вызывает ошибку: невалидный JSON, неизвестный тип события, баг в обработчике. Его нельзя ни обработать, ни бесконечно возвращать в очередь.
Ловушка: requeue=true не считается попыткой
Естественное желание - «не получилось, вернём в очередь и попробуем ещё»:
НЕПРАВИЛЬНО - разбор ниже
handler вернул ошибку:
если retryCount(msg) >= 3 ← счётчик читается из x-death
nack(requeue=false) → сдаёмся, в DLQ
иначе
nack(requeue=true) → «попробуем ещё»
Этот код не работает, и ломается он тихо. requeue=true возвращает сообщение
в ту же очередь напрямую, не через dead-letter exchange. Значит x-death
не появляется и retryCount навсегда остаётся нулём:
handler → ошибка → nack(requeue=true) → та же очередь
→ handler → ошибка → retryCount = 0 → nack(requeue=true)
→ ... и так пока кто-нибудь не заметит
Вместо трёх попыток получается бесконечный цикл, который жжёт CPU и забивает логи одним и тем же сообщением. Причём consumer выглядит живым и работающим.
Как правильно: только dead-lettering
Отвергаем всегда без requeue, а задержку и повторы обеспечивает retry-очередь с TTL - та самая топология из раздела выше. Разница лишь в том, куда сообщение уйдёт: в retry-очередь или в финальную DLQ.
const maxRetries = 3
func (c *Consumer) handleSafely(ctx context.Context, msg amqp.Delivery, handler func(context.Context, []byte) error) {
// Паника обработчика - тот же случай, что ошибка: сообщение
// отправляем на разбор, а не роняем consumer.
defer func() {
if r := recover(); r != nil {
log.Printf("panic on message %s: %v", msg.MessageId, r)
c.reject(ctx, msg, fmt.Errorf("panic: %v", r))
}
}()
if len(msg.Body) == 0 {
// Пустое тело не станет валидным от повторов - сразу в финальную DLQ,
// без круга по retry-очереди.
log.Printf("empty body, straight to final DLQ")
c.moveToFinalDLQ(ctx, msg, "empty body")
return
}
if err := handler(ctx, msg.Body); err != nil {
c.reject(ctx, msg, err)
return
}
msg.Ack(false)
}
// retryCount ищет запись x-death по очереди и причине. Брать первую нельзя:
// в retry-цикле их несколько - rejected из рабочей очереди и expired
// из retry-очереди.
func retryCount(msg amqp.Delivery, queue, reason string) int32 {
deaths, ok := msg.Headers["x-death"].([]interface{})
if !ok {
return 0
}
for _, d := range deaths {
entry, ok := d.(amqp.Table)
if !ok {
continue
}
if entry["queue"] == queue && entry["reason"] == reason {
if count, ok := entry["count"].(int64); ok {
return int32(count)
}
}
}
return 0
}
// reject решает, куда отправить сообщение: на очередной круг retry
// или в финальную DLQ. Счётчик берётся из x-death именно той очереди
// и той причины, которые нас интересуют.
func (c *Consumer) reject(ctx context.Context, msg amqp.Delivery, cause error) {
attempts := retryCount(msg, c.queue, "rejected")
if attempts >= maxRetries {
log.Printf("message %s failed %d times, final DLQ: %v", msg.MessageId, attempts, cause)
// Публикуем в финальную DLQ сами: так к сообщению можно приложить
// причину последней ошибки - при dead-lettering её негде взять.
c.moveToFinalDLQ(ctx, msg, cause.Error())
return
}
log.Printf("message %s attempt %d failed, retry later: %v", msg.MessageId, attempts+1, cause)
// Без requeue: сообщение уходит через DLX в retry-очередь,
// отлёживается там TTL и возвращается обратно. Именно этот проход
// увеличивает x-death.
msg.Nack(false, false)
}
// moveToFinalDLQ подтверждает исходное сообщение только после того,
// как копия надёжно легла в финальную DLQ. Иначе сбой публикации
// (закрытый канал, nack брокера) означал бы тихую потерю.
func (c *Consumer) moveToFinalDLQ(ctx context.Context, msg amqp.Delivery, reason string) {
if err := c.publishToFinalDLQ(ctx, msg, reason); err != nil {
log.Printf("final DLQ publish failed for %s: %v", msg.MessageId, err)
msg.Nack(false, false) // не теряем: уйдёт по DLX на ещё один круг
return
}
msg.Ack(false)
}
// publishToFinalDLQ публикует копию с причиной в заголовке и ждёт
// publisher confirm. Для этого Consumer из урока про consumer дополнен
// полем pubCh *amqp.Channel - отдельный канал в confirm-режиме
// (pubCh.Confirm(false)): смешивать confirm и consume на одном канале неудобно.
func (c *Consumer) publishToFinalDLQ(ctx context.Context, msg amqp.Delivery, reason string) error {
headers := amqp.Table{}
for k, v := range msg.Headers {
headers[k] = v
}
headers["x-final-reason"] = reason
conf, err := c.pubCh.PublishWithDeferredConfirmWithContext(ctx,
"", "dlq.progress.final", false, false, amqp.Publishing{
ContentType: msg.ContentType,
DeliveryMode: amqp.Persistent,
MessageId: msg.MessageId,
Headers: headers,
Body: msg.Body,
})
if err != nil {
return fmt.Errorf("publish: %w", err)
}
ok, err := conf.WaitContext(ctx)
if err != nil {
return fmt.Errorf("wait confirm: %w", err)
}
if !ok {
return fmt.Errorf("final DLQ publish nacked by broker")
}
return nil
}
<?php
declare(strict_types=1);
use PhpAmqpLib\Message\AMQPMessage;
use Psr\Log\LoggerInterface;
final class PoisonSafeConsumer
{
private const MAX_RETRIES = 3;
public function __construct(
private readonly LoggerInterface $logger,
private readonly FinalDlqPublisher $finalDlq,
private readonly string $queue,
) {}
/** @param callable(string): void $handler */
public function handleSafely(AMQPMessage $msg, callable $handler): void
{
if ($msg->getBody() === '') {
// Повторы не сделают пустое тело валидным.
$this->logger->warning('empty body, straight to final DLQ');
$this->finalDlq->publish($msg, 'empty body');
$msg->ack();
return;
}
try {
$handler($msg->getBody());
$msg->ack();
} catch (Throwable $e) {
$this->reject($msg, $e);
}
}
private function reject(AMQPMessage $msg, Throwable $cause): void
{
$attempts = $this->retryCount($msg, $this->queue, 'rejected');
if ($attempts >= self::MAX_RETRIES) {
$this->logger->error('message {id} failed {n} times, final DLQ: {err}', [
'id' => $msg->get_properties()['message_id'] ?? '',
'n' => $attempts,
'err' => $cause->getMessage(),
]);
$this->finalDlq->publish($msg, $cause->getMessage());
$msg->ack();
return;
}
// requeue: false - обязательно. Только так сообщение пройдёт через DLX
// в retry-очередь, и только так вырастет x-death.
$msg->nack(requeue: false);
}
/** Ищем запись x-death по очереди и причине, а не берём первую. */
private function retryCount(AMQPMessage $msg, string $queue, string $reason): int
{
$headers = $msg->get_properties()['application_headers'] ?? null;
$deaths = $headers?->getNativeData()['x-death'] ?? [];
foreach ($deaths as $entry) {
if (($entry['queue'] ?? null) === $queue && ($entry['reason'] ?? null) === $reason) {
return (int) ($entry['count'] ?? 0);
}
}
return 0;
}
}
import logging
from pika.adapters.blocking_connection import BlockingChannel
from pika.spec import Basic, BasicProperties
log = logging.getLogger(__name__)
MAX_RETRIES = 3
class Consumer: # продолжение класса из урока про consumer
def handle_safely(
self,
ch: BlockingChannel,
method: Basic.Deliver,
props: BasicProperties,
body: bytes,
handler: Handler,
) -> None:
if not body:
# Пустое тело не станет валидным от повторов - сразу в финальную DLQ,
# без круга по retry-очереди.
log.warning("empty body, straight to final DLQ")
self._publish_to_final_dlq(props, body, "empty body")
ch.basic_ack(delivery_tag=method.delivery_tag)
return
# Отдельного recover() не нужно: и ошибка, и «паника» обработчика
# здесь одно и то же исключение. Сообщение отправляем на разбор,
# а не роняем consumer.
try:
handler(body)
except Exception as e:
self._reject(ch, method, props, body, e)
return
ch.basic_ack(delivery_tag=method.delivery_tag)
def _reject(
self,
ch: BlockingChannel,
method: Basic.Deliver,
props: BasicProperties,
body: bytes,
cause: Exception,
) -> None:
"""Решает, куда отправить сообщение: на очередной круг retry
или в финальную DLQ. Счётчик берётся из x-death именно той очереди
и той причины, которые нас интересуют.
"""
attempts = retry_count(props, self._queue, "rejected")
if attempts >= MAX_RETRIES:
log.error("message %s failed %d times, final DLQ: %s", props.message_id, attempts, cause)
# Публикуем в финальную DLQ сами: так к сообщению можно приложить
# причину последней ошибки - при dead-lettering её негде взять.
self._publish_to_final_dlq(props, body, str(cause))
ch.basic_ack(delivery_tag=method.delivery_tag)
return
log.warning("message %s attempt %d failed, retry later: %s", props.message_id, attempts + 1, cause)
# Без requeue: сообщение уходит через DLX в retry-очередь,
# отлёживается там TTL и возвращается обратно. Именно этот проход
# увеличивает x-death.
ch.basic_nack(delivery_tag=method.delivery_tag, requeue=False)
def retry_count(props: BasicProperties, queue: str, reason: str) -> int:
"""Ищет запись x-death по очереди и причине. Брать первую нельзя:
в retry-цикле их несколько - rejected из рабочей очереди и expired
из retry-очереди.
"""
deaths = (props.headers or {}).get("x-death")
if not isinstance(deaths, list):
return 0
for entry in deaths:
if not isinstance(entry, dict):
continue
if entry.get("queue") == queue and entry.get("reason") == reason:
return int(entry.get("count", 0))
return 0
ℹ️ Когда requeue=true всё-таки уместен
Запрет не абсолютный.
requeue=trueподходит там, где ошибка заведомо не связана с самим сообщением и пройдёт сама: например, consumer потерял соединение с базой и знает, что переподключение уже идёт. Тогда возврат в очередь - это «сейчас не я, пусть возьмёт другой».Но такой возврат не считается попыткой и не имеет задержки, поэтому ограничивать его надо своим счётчиком в памяти consumer-а, а не
x-death. Для повторов бизнес-ошибок остаётся схема с retry-очередью.
Мониторинг DLQ
Алерт на сам факт «в DLQ что-то есть» будит дежурного на каждом случайном сбое. Смотреть надо на rate попаданий и на возраст старейшего сообщения; полный набор сигналов и порогов для event-driven системы - в уроке наблюдаемость.
// Проверяем размер DLQ через Management API.
// Любая ошибка (нет доступа, 401, битый JSON) должна вернуться наверх:
// «0, nil» на сбое мониторинга читается как «DLQ пуста», и алерт молчит.
func CheckDLQSize(ctx context.Context, mgmtURL, user, pass, queue string) (int, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet,
fmt.Sprintf("%s/api/queues/%%2F/%s", mgmtURL, url.PathEscape(queue)), nil)
if err != nil {
return 0, err
}
req.SetBasicAuth(user, pass) // Management API без авторизации отвечает 401
resp, err := http.DefaultClient.Do(req)
if err != nil {
return 0, err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return 0, fmt.Errorf("management api: %s", resp.Status)
}
var q struct {
Messages int `json:"messages"`
}
if err := json.NewDecoder(resp.Body).Decode(&q); err != nil {
return 0, fmt.Errorf("decode queue info: %w", err)
}
return q.Messages, nil
}
<?php
declare(strict_types=1);
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class DlqMonitor
{
public function __construct(
private readonly HttpClientInterface $http,
private readonly string $mgmtUrl, // например: http://rabbitmq:15672
private readonly string $user,
private readonly string $pass,
) {}
// Проверяем размер DLQ через Management API
public function size(string $queue): int
{
$vhost = rawurlencode('/');
$response = $this->http->request('GET', "{$this->mgmtUrl}/api/queues/{$vhost}/{$queue}", [
'auth_basic' => [$this->user, $this->pass],
]);
$data = $response->toArray();
return (int) ($data['messages'] ?? 0);
}
}
import base64
import json
import urllib.parse
import urllib.request
# Проверяем размер DLQ через Management API
def check_dlq_size(mgmt_url: str, user: str, password: str, queue: str) -> int:
# Стандартный urllib вместо http.Get; в сервисе это обычно httpx или requests.
# Ошибки (401, недоступность, битый JSON) urllib и json отдают исключениями -
# их нельзя глушить, иначе мониторинг решит, что DLQ пуста.
vhost = urllib.parse.quote("/", safe="") # "/" -> "%2F"
req = urllib.request.Request(f"{mgmt_url}/api/queues/{vhost}/{urllib.parse.quote(queue, safe='')}")
token = base64.b64encode(f"{user}:{password}".encode()).decode()
req.add_header("Authorization", f"Basic {token}")
with urllib.request.urlopen(req, timeout=5) as resp:
data = json.load(resp)
return int(data["messages"])
Как это проверено
Оба утверждения этого урока - «отметка и бизнес-операция применяются
атомарно» и «после N неудачных попыток сообщение уходит в очередь разбора» -
проверяются прогоном, а не чтением: examples/reliability/.
Стенд собран так, чтобы проверять именно их, а не работу моков:
- inbox гоняет код из этого урока на настоящих
BeginTx,CommitиRollback- под ними драйверdatabase/sqlв памяти, умеющий вернуть ошибку на любой по счёту операции. Тест перебирает все точки отказа (вставка отметки, бизнес-операция,Commit) и после каждой проверяет, что состояние согласовано: либо отметка и эффект вместе, либо ни того, ни другого. Состояние «отметка есть, эффекта нет» запрещено - именно оно означает потерю события навсегда; - retry моделирует ту часть RabbitMQ, которая здесь и решает: очереди,
dead-letter exchange, TTL и
x-deathкак массив записей по паре (очередь, причина). Тест доводит сообщение до очереди разбора и сверяет число доставок с числом разрешённых попыток.
Рядом с каждой рабочей версией лежит сломанная - та, что была в этом уроке до правок. Без неё тесты ничего не доказывали бы: проверка имеет смысл только если известно, что она способна упасть. Сломанный inbox теряет событие при сбое в окне, сломанный consumer крутит сообщение бесконечно, и оба факта зафиксированы тестами.
ℹ️ Почему стенд, а не «прочитать внимательно»
Утверждение «в одной транзакции» держалось в этом уроке на том, что рядом стоит
BeginTx. Обработчик при этом писал в своё соединение - и код, и текст выглядели правильными по отдельности. Такую ошибку не видно чтением: её видно только прогоном, в котором сбой случается между двумя побочными эффектами.
Мини-задание
- Создай таблицу
inboxи оберни свой handler вIdempotentHandler - Отправь одно и то же сообщение дважды - убедись, что обработка произошла один раз
- Настрой DLQ для своей очереди через
x-dead-letter-exchange - Сделай handler, который всегда возвращает ошибку, и убедись, что после 3 ретраев сообщение попало в DLQ