Гарантии доставки: at-most-once / at-least-once / exactly-once

Гарантии доставки: at-most-once / at-least-once / exactly-once

Когда событие путешествует от publisher к subscriber через сеть, что-то может пойти не так. Сеть может оборваться, consumer может упасть в середине обработки, broker может потерять сообщение. Гарантии доставки - это ответ на вопрос: что произойдёт при сбое?

Этот вопрос критически важен для продакшна. Представь: subscriber начисляет бонусные баллы за пройденный урок. Если событие потеряется - пользователь не получит бонус. Если событие обработается дважды - получит двойной. Выбор гарантии доставки определяет, какой из этих сценариев возможен.

Три уровня гарантий

Три гарантии: at-most-once с потерями, at-least-once с дубликатами, exactly-once = at-least-once + idempotent

At-most-once: отправил и забыл

Producer публикует событие и не ждёт подтверждения. Если broker не получил сообщение или consumer упал - событие потеряно навсегда.

// At-most-once publisher: отправка без подтверждения
type FireAndForgetPublisher struct {
    conn net.Conn
}

func (p *FireAndForgetPublisher) Publish(ctx context.Context, event Event) error {
    data, err := json.Marshal(event)
    if err != nil {
        return fmt.Errorf("marshal event: %w", err)
    }

    // Отправляем и не проверяем, получил ли broker
    _, _ = p.conn.Write(data)
    return nil
}
<?php
// src/Infrastructure/Messaging/FireAndForgetPublisher.php
declare(strict_types=1);

namespace App\Infrastructure\Messaging;

use App\Domain\Event\Event;
use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Message\AMQPMessage;

// At-most-once publisher: отправка без подтверждения
final class FireAndForgetPublisher
{
    public function __construct(
        private readonly AMQPChannel $channel,
        private readonly string $exchange,
    ) {}

    public function publish(Event $event): void
    {
        $data = json_encode($event, JSON_THROW_ON_ERROR);
        $msg = new AMQPMessage($data);

        // Отправляем без publisher confirms - ack от брокера не ждём
        // (mandatory=false, immediate=false: даже если очередь не привязана, broker молча отбросит)
        $this->channel->basic_publish($msg, $this->exchange);
    }
}
# infrastructure/messaging/fire_and_forget.py
import json
from dataclasses import asdict

from pika.channel import Channel  # pip install pika (RabbitMQ)

from events.base import Event


# At-most-once publisher: отправка без подтверждения
class FireAndForgetPublisher:
    def __init__(self, channel: Channel, exchange: str) -> None:
        self._channel = channel
        self._exchange = exchange

    def publish(self, event: Event) -> None:
        data = json.dumps(asdict(event), default=str)

        # Отправляем без publisher confirms (channel.confirm_delivery() не вызывали) -
        # ack от брокера не ждём; mandatory=False: если очередь не привязана, broker молча отбросит
        self._channel.basic_publish(exchange=self._exchange, routing_key="", body=data)

Когда допустимо: метрики, аналитика, логирование - ситуации, где потеря одного события не приводит к бизнес-проблеме. Если потерялся один клик из миллиона - статистика не пострадает.

Когда не подходит: email-уведомления, начисление бонусов, обновление баланса - всё, где потеря имеет последствия для пользователя.

At-least-once: гарантия доставки через retry

Producer отправляет событие и ждёт подтверждения (ACK) от broker. Если ACK не пришёл - повторяет отправку. Consumer обрабатывает событие и отправляет ACK broker-у. Если consumer упал до ACK - broker доставит событие повторно.

// At-least-once publisher с retry и exponential backoff
type ReliablePublisher struct {
    writer     *kafka.Writer
    maxRetries int
    logger     *slog.Logger
}

func NewReliablePublisher(brokers []string, logger *slog.Logger) *ReliablePublisher {
    w := &kafka.Writer{
        Addr:         kafka.TCP(brokers...),
        RequiredAcks: kafka.RequireAll, // ждём подтверждения от всех реплик
        MaxAttempts:  1,                // retry делаем сами (для контроля backoff)
    }
    return &ReliablePublisher{
        writer:     w,
        maxRetries: 5,
        logger:     logger,
    }
}

func (p *ReliablePublisher) Publish(ctx context.Context, topic string, event Event) error {
    data, err := json.Marshal(event)
    if err != nil {
        return fmt.Errorf("marshal event: %w", err)
    }

    msg := kafka.Message{
        Topic: topic,
        Key:   []byte(event.AggregateID), // partition key для ordering
        Value: data,
    }

    var lastErr error
    for attempt := 0; attempt <= p.maxRetries; attempt++ {
        if attempt > 0 {
            delay := backoff(attempt)
            p.logger.Warn("retrying publish",
                slog.String("topic", topic),
                slog.String("event_id", event.ID),
                slog.Int("attempt", attempt),
                slog.Duration("delay", delay),
            )
            select {
            case <-time.After(delay):
            case <-ctx.Done():
                return ctx.Err()
            }
        }

        lastErr = p.writer.WriteMessages(ctx, msg)
        if lastErr == nil {
            return nil // ACK получен - событие доставлено
        }
    }

    return fmt.Errorf("publish failed after %d retries: %w", p.maxRetries, lastErr)
}

// backoff возвращает задержку с экспоненциальным ростом
// 100ms, 200ms, 400ms, 800ms, 1600ms
func backoff(attempt int) time.Duration {
    base := 100 * time.Millisecond
    return base * time.Duration(1<<uint(attempt-1))
}
<?php
// src/Infrastructure/Messaging/ReliablePublisher.php
declare(strict_types=1);

namespace App\Infrastructure\Messaging;

use App\Domain\Event\Event;
use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Message\AMQPMessage;
use Psr\Log\LoggerInterface;
use RuntimeException;
use Throwable;

// At-least-once publisher с retry и exponential backoff
final class ReliablePublisher
{
    public function __construct(
        private readonly AMQPChannel $channel,
        private readonly LoggerInterface $logger,
        private readonly int $maxRetries = 5,
    ) {
        // Включаем publisher confirms - broker отправит basic.ack/basic.nack
        $this->channel->confirm_select();
    }

    public function publish(string $exchange, string $routingKey, Event $event): void
    {
        $data = json_encode($event, JSON_THROW_ON_ERROR);

        $msg = new AMQPMessage($data, [
            'delivery_mode' => AMQPMessage::DELIVERY_MODE_PERSISTENT,
            'message_id' => $event->id,
        ]);

        $lastErr = null;
        for ($attempt = 0; $attempt <= $this->maxRetries; $attempt++) {
            if ($attempt > 0) {
                $delayMs = self::backoffMs($attempt);
                $this->logger->warning('retrying publish', [
                    'exchange' => $exchange,
                    'event_id' => $event->id,
                    'attempt' => $attempt,
                    'delay_ms' => $delayMs,
                ]);
                usleep($delayMs * 1000);
            }

            try {
                $this->channel->basic_publish($msg, $exchange, $routingKey);
                // Блокируемся, пока broker не подтвердит публикацию (publisher confirms)
                $this->channel->wait_for_pending_acks(timeout: 5.0);

                return; // ACK получен - событие доставлено
            } catch (Throwable $e) {
                $lastErr = $e;
            }
        }

        throw new RuntimeException(
            sprintf('publish failed after %d retries: %s', $this->maxRetries, $lastErr?->getMessage() ?? ''),
            previous: $lastErr,
        );
    }

    // backoffMs возвращает задержку в миллисекундах с экспоненциальным ростом
    // 100, 200, 400, 800, 1600
    private static function backoffMs(int $attempt): int
    {
        return 100 * (1 << ($attempt - 1));
    }
}

В Symfony Messenger retry-логика конфигурируется на уровне транспорта (retry_strategy.max_retries, multiplier, delay). Встроенного Kafka-транспорта у Symfony нет: используют сторонние (например, на базе ext-rdkafka), где acks=all задаётся в конфигурации producer.

# infrastructure/messaging/reliable_publisher.py
import json
import logging
import time
from dataclasses import asdict

from kafka import KafkaProducer  # pip install kafka-python; в aiokafka API тот же, но async
from kafka.errors import KafkaError

from events.base import Event


class PublishError(Exception):
    """Публикация не удалась после всех повторов."""


# At-least-once publisher с retry и exponential backoff
class ReliablePublisher:
    def __init__(self, brokers: list[str], logger: logging.Logger) -> None:
        self._producer = KafkaProducer(
            bootstrap_servers=brokers,
            acks="all",  # ждём подтверждения от всех реплик
            retries=0,   # retry делаем сами (для контроля backoff)
        )
        self._max_retries = 5
        self._logger = logger

    def publish(self, topic: str, event: Event) -> None:
        data = json.dumps(asdict(event), default=str).encode()

        last_err: Exception | None = None
        for attempt in range(self._max_retries + 1):
            if attempt > 0:
                delay = backoff(attempt)
                self._logger.warning(
                    "retrying publish",
                    extra={
                        "topic": topic,
                        "event_id": event.event_id,
                        "attempt": attempt,
                        "delay": delay,
                    },
                )
                time.sleep(delay)

            try:
                future = self._producer.send(
                    topic,
                    key=event.aggregate_id.encode(),  # partition key для ordering
                    value=data,
                )
                future.get(timeout=10)
                return  # ACK получен - событие доставлено
            except KafkaError as err:
                last_err = err

        raise PublishError(f"publish failed after {self._max_retries} retries") from last_err


def backoff(attempt: int) -> float:
    """Возвращает задержку в секундах с экспоненциальным ростом
    0.1, 0.2, 0.4, 0.8, 1.6.
    """
    base = 0.1
    return base * (1 << (attempt - 1))

Побочный эффект at-least-once: дубликаты. Если consumer обработал событие, но упал до отправки ACK, broker не знает, что обработка завершена, и доставит событие повторно. Consumer обработает его второй раз.

Сценарии сбоев

Разберём, что происходит при падении consumer-а на разных этапах:

Сценарий 1: Consumer упал ДО обработки
─────────────────────────────────────────
Broker ──▶ Consumer (crash!)
Broker: "ACK не получен, доставлю повторно"
Broker ──▶ Consumer (перезапущен) ──▶ обрабатывает ──▶ ACK
Результат: событие обработано 1 раз ✅

Сценарий 2: Consumer упал ПОСЛЕ обработки, но ДО ACK
─────────────────────────────────────────
Broker ──▶ Consumer ──▶ обработал ──▶ (crash before ACK!)
Broker: "ACK не получен, доставлю повторно"
Broker ──▶ Consumer (перезапущен) ──▶ обработал СНОВА ──▶ ACK
Результат: событие обработано 2 раза ⚠️ ДУБЛИКАТ

Сценарий 2 - это именно тот случай, когда нужна идемпотентность consumer-а.

Kafka: auto-commit vs manual commit

В Kafka consumer читает сообщения из partition и коммитит offset (позицию). Offset указывает, до какого сообщения consumer дочитал.

// Auto-commit: offset коммитится автоматически через заданный интервал
// Проблема: если consumer упал между auto-commit и обработкой - сообщение потеряно
reader := kafka.NewReader(kafka.ReaderConfig{
    Brokers:        []string{"localhost:9092"},
    Topic:          "progress.lesson.completed",
    GroupID:        "email-sender",
    CommitInterval: 1 * time.Second, // коммит каждую секунду - рискованно
})

const maxAttempts = 5

// Manual commit: offset коммитится только после того, как сообщение обработано
// или надёжно отложено в DLQ.
//
// В Kafka offset - позиция в партиции, а не ack отдельного сообщения. Пропустить
// упавшее сообщение через continue нельзя: следующий коммит «перепрыгнет» его,
// и оно будет потеряно. Поэтому ретраим здесь, после лимита - в DLQ-топик, затем коммит.
func consumeManual(ctx context.Context, reader *kafka.Reader, dlq *kafka.Writer) error {
    for {
        // FetchMessage НЕ коммитит offset
        msg, err := reader.FetchMessage(ctx)
        if err != nil {
            return fmt.Errorf("fetch: %w", err)
        }

        if err := processWithRetry(ctx, msg); err != nil {
            slog.Error("process failed after retries, sending to DLQ",
                slog.String("err", err.Error()),
                slog.Int64("offset", msg.Offset),
            )
            dead := kafka.Message{Key: msg.Key, Value: msg.Value, Headers: msg.Headers}
            if err := dlq.WriteMessages(ctx, dead); err != nil {
                // Не коммитим и выходим: после рестарта читаем с последнего коммита,
                // сообщение придёт снова.
                return fmt.Errorf("send to dlq: %w", err)
            }
        }

        // Коммитим offset: сообщение обработано или лежит в DLQ
        if err := reader.CommitMessages(ctx, msg); err != nil {
            return fmt.Errorf("commit: %w", err)
        }
    }
}

// processWithRetry повторяет обработку одного и того же сообщения с паузой
func processWithRetry(ctx context.Context, msg kafka.Message) error {
    var err error
    for attempt := 1; attempt <= maxAttempts; attempt++ {
        if err = processMessage(ctx, msg); err == nil {
            return nil
        }
        if attempt == maxAttempts {
            break
        }
        select {
        case <-time.After(time.Duration(attempt) * 200 * time.Millisecond):
        case <-ctx.Done():
            return ctx.Err()
        }
    }
    return err
}
<?php
// src/Infrastructure/Messaging/KafkaManualCommitConsumer.php
declare(strict_types=1);

namespace App\Infrastructure\Messaging;

use Psr\Log\LoggerInterface;
use RdKafka\Conf;
use RdKafka\KafkaConsumer;
use RdKafka\Message;
use Throwable;

// Manual commit: offset коммитится только после того, как сообщение обработано
// или надёжно отложено в DLQ. Auto-commit (enable.auto.commit=true) рискован:
// коммит по таймеру не связан с моментом обработки.
//
// В Kafka offset - позиция, а не ack отдельного сообщения: пропустить упавшее
// сообщение через continue нельзя, следующий коммит «перепрыгнет» его.
final class KafkaManualCommitConsumer
{
    private const MAX_ATTEMPTS = 5;

    private readonly KafkaConsumer $consumer;

    public function __construct(
        string $brokers,
        string $groupId,
        private readonly MessageProcessor $processor,
        private readonly DeadLetterPublisher $dlq, // пишет сообщение в DLQ-топик
        private readonly LoggerInterface $logger,
    ) {
        $conf = new Conf();
        $conf->set('group.id', $groupId);
        $conf->set('bootstrap.servers', $brokers);
        $conf->set('enable.auto.commit', 'false'); // ОТКЛЮЧАЕМ авто-коммит
        $conf->set('auto.offset.reset', 'earliest');

        $this->consumer = new KafkaConsumer($conf);
    }

    public function run(string $topic): void
    {
        $this->consumer->subscribe([$topic]);

        while (true) {
            $msg = $this->consumer->consume(timeoutMs: 10_000);
            if ($msg === null || $msg->err !== RD_KAFKA_RESP_ERR_NO_ERROR) {
                continue;
            }

            try {
                $this->processWithRetry($msg);
            } catch (Throwable $e) {
                $this->logger->error('process failed after retries, sending to DLQ', [
                    'err' => $e->getMessage(),
                    'offset' => $msg->offset,
                ]);
                // Если запись в DLQ упадёт, исключение остановит воркер без коммита:
                // после рестарта сообщение придёт снова.
                $this->dlq->publish($msg, $e);
            }

            // Коммитим offset: сообщение обработано или лежит в DLQ (синхронный commit)
            $this->consumer->commit($msg);
        }
    }

    private function processWithRetry(Message $msg): void
    {
        for ($attempt = 1; ; $attempt++) {
            try {
                $this->processor->process($msg);

                return;
            } catch (Throwable $e) {
                if ($attempt >= self::MAX_ATTEMPTS) {
                    throw $e;
                }
                usleep($attempt * 200_000); // 200, 400, 600... мс
            }
        }
    }
}

Встроенного Kafka-транспорта в Symfony Messenger нет. В сторонних транспортах на базе ext-rdkafka то же поведение задаётся опцией enable.auto.commit в их конфигурации, а ручной цикл consume() прячется внутри worker-а messenger:consume.

# infrastructure/messaging/kafka_consumer.py
import logging
import time

from kafka import KafkaConsumer, KafkaProducer  # pip install kafka-python

log = logging.getLogger(__name__)

# Auto-commit: offset коммитится автоматически через заданный интервал
# Проблема: если consumer упал между auto-commit и обработкой - сообщение потеряно
auto_consumer = KafkaConsumer(
    "progress.lesson.completed",
    bootstrap_servers=["localhost:9092"],
    group_id="email-sender",
    enable_auto_commit=True,
    auto_commit_interval_ms=1000,  # коммит каждую секунду - рискованно
)


MAX_ATTEMPTS = 5


# Manual commit: offset коммитится только после того, как сообщение обработано
# или надёжно отложено в DLQ.
#
# В Kafka offset - позиция, а не ack отдельного сообщения: пропустить упавшее
# сообщение через continue нельзя, следующий commit() «перепрыгнет» его.
def consume_manual(consumer: KafkaConsumer, dlq: KafkaProducer) -> None:
    # consumer создан с enable_auto_commit=False: итерация НЕ коммитит offset
    for msg in consumer:
        try:
            process_with_retry(msg)
        except Exception as err:
            log.error(
                "process failed after retries, sending to DLQ",
                extra={"err": str(err), "offset": msg.offset},
            )
            # .get() ждёт подтверждения брокера; если запись в DLQ упадёт,
            # исключение остановит воркер без коммита, и сообщение придёт снова.
            dlq.send("progress.lesson.completed.dlq", key=msg.key, value=msg.value).get(timeout=10)

        # Коммитим offset: сообщение обработано или лежит в DLQ (синхронный commit)
        consumer.commit()


def process_with_retry(msg) -> None:
    for attempt in range(1, MAX_ATTEMPTS + 1):
        try:
            process_message(msg)
            return
        except Exception:
            if attempt == MAX_ATTEMPTS:
                raise
            time.sleep(attempt * 0.2)  # 200, 400, 600... мс

Manual commit даёт at-least-once: если consumer упал после обработки, но до коммита, сообщение будет доставлено повторно. Auto-commit не даёт ни одной чистой гарантии: коммит по таймеру не связан с моментом обработки, а что именно он коммитит, зависит от клиента. Упал после коммита, но до обработки - сообщение потеряно; упал после обработки, но до очередного коммита - получишь дубль. Поэтому для бизнес-событий используй manual commit после обработки плюс идемпотентный consumer. (Некоторые клиенты, например franz-go, по умолчанию коммитят только записи предыдущих poll-ов, и при синхронной обработке это даёт at-least-once; подробности - в Message Brokers: Kafka consumer. Но полагаться на такие тонкости рискованно.)

RabbitMQ: ack, nack, reject

В RabbitMQ подтверждение работает на уровне отдельных сообщений. Как это выглядит в живом воркере - с prefetch, пулом горутин и graceful shutdown по сигналу - смотри в уроке про consumer на RabbitMQ:

ack - "обработал успешно, удали из очереди"
nack - "не смог обработать": с requeue вернётся в очередь, без requeue уйдёт в DLQ
       (только если у очереди настроен dead-letter-exchange, иначе удаляется)
reject - то же для одного сообщения (с requeue или без); nack - расширение
         RabbitMQ, которое дополнительно умеет multiple=true
// RabbitMQ consumer с manual ack
func consumeRabbit(ch *amqp.Channel, queueName string) error {
    msgs, err := ch.Consume(
        queueName,
        "",    // consumer tag
        false, // auto-ack = false (manual ack!)
        false, // exclusive
        false, // no-local
        false, // no-wait
        nil,
    )
    if err != nil {
        return fmt.Errorf("consume: %w", err)
    }

    for msg := range msgs {
        err := processMessage(msg.Body)
        if err != nil {
            slog.Error("processing failed",
                slog.String("err", err.Error()),
            )
            // requeue=false: при настроенном dead-letter-exchange сообщение уйдёт в DLQ.
            // Мгновенный requeue=true вернул бы его в голову очереди, и при постоянной
            // ошибке (битый payload) получился бы бесконечный цикл со 100% CPU.
            // Повтор с задержкой делают через DLX + TTL, а не мгновенным requeue.
            _ = msg.Nack(false, false) // multiple=false, requeue=false
            continue
        }

        // Подтверждаем успешную обработку
        _ = msg.Ack(false) // multiple=false
    }
    return nil
}
<?php
// src/Infrastructure/Messaging/RabbitConsumer.php
declare(strict_types=1);

namespace App\Infrastructure\Messaging;

use PhpAmqpLib\Channel\AMQPChannel;
use PhpAmqpLib\Message\AMQPMessage;
use Psr\Log\LoggerInterface;
use Throwable;

// RabbitMQ consumer с manual ack
final class RabbitConsumer
{
    public function __construct(
        private readonly AMQPChannel $channel,
        private readonly MessageProcessor $processor,
        private readonly LoggerInterface $logger,
    ) {}

    public function consume(string $queueName): void
    {
        $callback = function (AMQPMessage $msg): void {
            try {
                $this->processor->process($msg->getBody());
            } catch (Throwable $e) {
                $this->logger->error('processing failed', ['err' => $e->getMessage()]);
                // requeue=false: при настроенном dead-letter-exchange уйдёт в DLQ.
                // Мгновенный requeue при постоянной ошибке даёт бесконечный цикл.
                $msg->nack(requeue: false); // multiple=false (по умолчанию)

                return;
            }

            // Подтверждаем успешную обработку
            $msg->ack(); // multiple=false
        };

        $this->channel->basic_consume(
            queue: $queueName,
            consumer_tag: '',
            no_local: false,
            no_ack: false, // manual ack!
            exclusive: false,
            nowait: false,
            callback: $callback,
        );

        while ($this->channel->is_consuming()) {
            $this->channel->wait();
        }
    }
}
# infrastructure/messaging/rabbit_consumer.py
import logging

from pika.channel import Channel  # pip install pika
from pika.spec import Basic, BasicProperties

log = logging.getLogger(__name__)


# RabbitMQ consumer с manual ack
def consume_rabbit(ch: Channel, queue_name: str) -> None:
    def on_message(
        channel: Channel, method: Basic.Deliver, _props: BasicProperties, body: bytes,
    ) -> None:
        try:
            process_message(body)
        except Exception as err:
            log.error("processing failed", extra={"err": str(err)})
            # requeue=False: при настроенном dead-letter-exchange уйдёт в DLQ.
            # Мгновенный requeue при постоянной ошибке даёт бесконечный цикл.
            channel.basic_nack(method.delivery_tag, multiple=False, requeue=False)
            return

        # Подтверждаем успешную обработку
        channel.basic_ack(method.delivery_tag, multiple=False)

    ch.basic_consume(
        queue=queue_name,
        on_message_callback=on_message,
        auto_ack=False,  # manual ack!
        exclusive=False,
    )
    ch.start_consuming()  # блокирующий цикл; ошибка соединения - исключение pika.exceptions.AMQPError

Exactly-once: где именно проходит граница

«Exactly-once невозможен» - расхожая формулировка, и она сбивает с толку: из неё делают вывод, что транзакции Kafka маркетинг. Точная версия длиннее на одно уточнение:

End-to-end exactly-once для произвольных внешних эффектов нельзя получить одной транспортной гарантией.

Разложим по участкам:

УчастокЧто достижимо
Producer → брокердубли отсекает idempotent producer (sequence number)
Топик → топик + offsetexactly-once: транзакция Kafka покрывает все три операции: чтение, запись в выходной топик и коммит offset
Брокер → внешний эффект (БД, письмо, чужой API)только at-least-once; «ровно один раз» даёт идемпотентность обработчика

Последняя строка и есть причина, по которой exactly-once «не бывает»: подтверждение теряется уже после того, как эффект случился (теорема о двух генералах), и брокер присылает сообщение снова. Транзакция Kafka об этом эффекте не знает - она живёт внутри Kafka. RabbitMQ не даёт и этого: там транзакционного механизма для пары «чтение + запись + подтверждение» нет вовсе.

Практический подход - at-least-once + идемпотентный consumer:

// IdempotentConsumer проверяет, обработано ли уже событие
type IdempotentConsumer struct {
    db      *sql.DB
    name    string // имя обработчика: часть ключа дедупликации
    handler func(ctx context.Context, tx *sql.Tx, event Event) error
    logger  *slog.Logger
}

func (c *IdempotentConsumer) Handle(ctx context.Context, event Event) error {
    // Транзакция открывается первой: и отметка, и бизнес-логика пишут в неё.
    tx, err := c.db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    // Проверка и отметка - одна операция. Отдельный SELECT перед INSERT
    // не нужен: два воркера прошли бы его одновременно, оба увидев "нет".
    res, err := tx.ExecContext(ctx,
        `INSERT INTO processed_events (event_id, handler)
         VALUES ($1, $2)
         ON CONFLICT (event_id, handler) DO NOTHING`,
        event.ID, c.name,
    )
    if err != nil {
        return fmt.Errorf("mark processed: %w", err)
    }

    rows, err := res.RowsAffected()
    if err != nil {
        return fmt.Errorf("rows affected: %w", err)
    }
    if rows == 0 {
        c.logger.Info("event already processed, skipping",
            slog.String("event_id", event.ID),
            slog.String("handler", c.name),
        )
        return nil // идемпотентность: повторная обработка - просто skip
    }

    // Обработчик пишет в ту же транзакцию - иначе "атомарно" остаётся словом.
    if err := c.handler(ctx, tx, event); err != nil {
        return fmt.Errorf("handle event: %w", err)
    }

    return tx.Commit()
}
<?php
// src/Infrastructure/Messaging/IdempotentConsumer.php
declare(strict_types=1);

namespace App\Infrastructure\Messaging;

use App\Domain\Event\Event;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;

// IdempotentConsumer проверяет, обработано ли уже событие
final class IdempotentConsumer
{
    /**
     * @param  callable(Connection, Event): void  $handler
     */
    public function __construct(
        private readonly Connection $db,
        private readonly LoggerInterface $logger,
        private readonly string $name, // имя обработчика: часть ключа дедупликации
        private $handler,
    ) {}

    public function handle(Event $event): void
    {
        // transactional() коммитит на выходе и откатывает на исключении.
        $this->db->transactional(function (Connection $tx) use ($event): void {
            // Проверка и отметка - одна операция: отдельный SELECT прошли бы
            // два воркера одновременно, оба увидев «не обработано».
            $inserted = $tx->executeStatement(
                'INSERT INTO processed_events (event_id, handler)
                 VALUES (:id, :handler)
                 ON CONFLICT (event_id, handler) DO NOTHING',
                ['id' => $event->id, 'handler' => $this->name],
            );

            if ($inserted === 0) {
                $this->logger->info('event already processed, skipping', [
                    'event_id' => $event->id,
                    'handler' => $this->name,
                ]);

                return; // идемпотентность: повторная обработка - просто skip
            }

            // Обработчик пишет в ту же транзакцию - иначе «атомарно» остаётся словом.
            ($this->handler)($tx, $event);
        });
    }
}
# infrastructure/messaging/idempotent_consumer.py
import logging
from typing import Callable

from psycopg import Connection  # pip install psycopg

from events.base import Event


class IdempotentConsumer:
    """Проверяет, обработано ли уже событие."""

    def __init__(
        self,
        db: Connection,
        name: str,  # имя обработчика: часть ключа дедупликации
        handler: Callable[[Connection, Event], None],
        logger: logging.Logger,
    ) -> None:
        self._db = db
        self._name = name
        self._handler = handler
        self._logger = logger

    def handle(self, event: Event) -> None:
        # Транзакция открывается первой: и отметка, и бизнес-логика пишут в неё.
        # Контекстный менеджер коммитит на выходе и откатывает на исключении.
        with self._db.transaction():
            # Проверка и отметка - одна операция. Отдельный SELECT перед INSERT
            # не нужен: два воркера прошли бы его одновременно, оба увидев "нет".
            cur = self._db.execute(
                """INSERT INTO processed_events (event_id, handler)
                   VALUES (%s, %s)
                   ON CONFLICT (event_id, handler) DO NOTHING""",
                (event.event_id, self._name),
            )

            if cur.rowcount == 0:
                self._logger.info(
                    "event already processed, skipping",
                    extra={"event_id": event.event_id, "handler": self._name},
                )
                return  # идемпотентность: повторная обработка - просто skip

            # Обработчик пишет в ту же транзакцию - иначе "атомарно" остаётся словом.
            self._handler(self._db, event)

Таблица processed_events - это deduplication store, а ключ дедупликации составной: (event_id, handler). Одно событие обрабатывают несколько подписчиков, и при ключе из одного event_id первый успевший занял бы его, а остальные сочли бы работу сделанной.

Два обязательных свойства кода выше, и оба легко потерять:

  1. Обработчик получает транзакцию. Если он открывает своё соединение, его коммит происходит отдельно от отметки - и «атомарно» перестаёт быть правдой, хотя BeginTx в коде есть.
  2. Проверка и отметка - одна операция. SELECT EXISTS перед INSERT два воркера пройдут одновременно, оба получив «не обработано». Работает только INSERT ... ON CONFLICT DO NOTHING с проверкой числа затронутых строк.

Подробный разбор - в уроке про идемпотентность.

ℹ️ В продакшне выбирай at-least-once + idempotency

Это золотой стандарт для 95% систем. At-most-once теряет события. Транзакции Kafka дороги и покрывают только путь топик → топик, а деньги и письма живут за пределами брокера. At-least-once + идемпотентный consumer даёт надёжность без чрезмерной сложности. Правило простое: каждый subscriber должен корректно обработать повторное получение одного и того же события.

🚫 Auto-commit в Kafka не гарантирует at-least-once

Если consumer падает между auto-commit и обработкой сообщения - сообщение потеряно; если между обработкой и очередным auto-commit - придёт дубль. В продакшне используй manual commit: FetchMessage → process → CommitMessages. Только так момент фиксации offset под твоим контролем, и at-least-once гарантирован при любом клиенте.

Сводная таблица

ГарантияПотеря событийДубликатыСложностьКогда использовать
At-most-onceДаНетНизкаяМетрики, аналитика, логи
At-least-onceНетДаСредняяEmail, бонусы (+ идемпотентность)
Exactly-once внутри KafkaНетНетВысокаяПотоковая обработка: топик → топик

Типичные ошибки

  • Auto-commit + долгая обработка - Kafka закоммитил offset до того, как ты успел сделать работу; consumer крашится → событие потеряно. Manual commit после успешной обработки (либо после записи в БД с idempotency).

  • Manual ack/commit перед обработкой - «сначала ack, потом работа» = at-most-once в одежде at-least-once. Acknowledgement - после успешного действия. Если упал перед ack - broker повторит.

  • «Exactly-once на уровне брокера, мне не нужна идемпотентность» - у Kafka Exactly-Once-Semantics работает только внутри Kafka-pipeline (Kafka→Kafka). Как только пишешь во внешнюю БД или дёргаешь HTTP - у тебя at-least-once, нужен idempotency-store.

  • Дедупликация по event.Type + aggregate_id - у двух событий одного типа на один aggregate один и тот же ключ → второе событие считается дублем и теряется. Дедуп по уникальному event_id (вместе с именем обработчика, если подписчиков несколько).

  • processed_events без cleanup - таблица растёт безгранично, через год запросы тормозят. TTL/партиционирование/архив (для большинства задач достаточно 7-30 дней - повторы за гранью ретеншна брокера невозможны).

  • Бесконечный retry без exponential backoff - consumer падает, broker сразу redeliver, consumer снова падает - retry storm загружает 100% CPU. Exponential backoff (100ms, 500ms, 2s, 10s...) + max retries + DLQ. Сама DLQ без присмотра бесполезна: заводи на неё алерт по rate и возрасту старейшего сообщения - как это делается, в уроке про наблюдаемость event-driven.

  • Записал в БД, и в defer отправляешь событие - defer сработает даже если транзакция откатилась. Событие уйдёт без реальных данных в БД. Публикация - после tx.Commit() или через Outbox.

  • Python - Kafka с aiokafka: idempotent producer, exactly-once - практическая реализация гарантий доставки в aiokafka: транзакции, consumer commit

Мини-задание

  • Реализуй publisher с retry и exponential backoff (3 попытки, начальная задержка 100ms)
  • Напиши consumer с manual commit: FetchMessage → process → CommitMessages
  • Создай таблицу processed_events и оберни subscriber в IdempotentConsumer
  • Для каждого subscriber в своём проекте определи: какая гарантия доставки нужна и почему
  • Смоделируй сценарий: consumer упал после обработки, но до ACK - что произойдёт?

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.