Idempotency: как не выполнить одно и то же дважды

Idempotency: как не выполнить одно и то же дважды

В мире событий доставка работает по принципу at-least-once: брокер гарантирует, что сообщение дойдёт хотя бы один раз, но может доставить его дважды, трижды или десять раз. Сеть моргнула, consumer перезапустился, offset не закоммитился - и событие приходит повторно. Если обработчик не готов к этому, пользователь получит два списания, две ачивки или два письма.

Idempotency - это свойство операции: повторный вызов с теми же входными данными не меняет результат. f(x) = f(f(x)). Для event-driven архитектуры это не оптимизация и не nice-to-have, а обязательное требование к каждому подписчику.

⚠️ Идемпотентная операция и дедуплицированная обработка - разные вещи

Их постоянно смешивают, в том числе в статьях: «поставил inbox-таблицу - обработчик стал идемпотентным». Это неверно, и различие практическое.

Идемпотентная операция безопасна к повтору сама по себе, без внешней памяти:

-- идемпотентно: сколько раз ни выполни, состояние одно
UPDATE users SET status = 'active' WHERE id = 42;
INSERT INTO badges (user_id, badge) VALUES (42, 'first-lesson')
    ON CONFLICT (user_id, badge) DO NOTHING;

Неидемпотентная операция остаётся неидемпотентной, что бы ни лежало рядом:

-- не идемпотентно: каждый вызов меняет результат
UPDATE users SET balance = balance + 100 WHERE id = 42;

Inbox-таблица не превращает вторую операцию в первую. Она делает другое: дедуплицирует обработку - гарантирует, что по конкретной паре (event_id, handler) тело обработчика выполнится один раз согласно записи в нашей базе. Это протокол вокруг операции, а не свойство операции.

Почему различие важно на практике:

  • дедупликация работает только там, где есть её запись. Потеряли inbox (восстановили базу из бэкапа, сменили ключ дедупа, поменяли имя handler-а) - и защита исчезла. Идемпотентная операция переживает всё это без последствий;
  • дедупликация не помогает против повторов вне канала. Оператор дёрнул тот же endpoint руками, retry прошёл под другим event_id, событие пересобрали при миграции - для inbox это новое событие;
  • дедупликация ничего не говорит про частичное применение. Если внутри обработчика два внешних вызова, а между ними сбой, запись в inbox либо откатится вместе с ними (тогда всё хорошо), либо нет - и тогда «уже обработано» соврёт.

Поэтому порядок предпочтений такой: сначала сделать операцию идемпотентной по природе (UPSERT вместо инкремента, целевое состояние вместо дельты, ключ операции на стороне внешнего API), и только для того, что так переписать нельзя, добавлять дедупликацию через inbox.

Почему at-least-once - это норма

End-to-end exactly-once для произвольных внешних эффектов нельзя получить одной транспортной гарантией: подтверждение может потеряться уже после обработки (Two Generals' Problem), и брокер пришлёт сообщение снова. Kafka даёт exactly-once в границах своей транзакции - топик → топик вместе с коммитом offset (разбор); RabbitMQ такого механизма не даёт, а NATS JetStream даёт похожую гарантию (дедупликация публикаций по заголовку Nats-Msg-Id плюс двойной ack) тоже только внутри брокера. Но за пределами брокера - запись в базу, письмо, чужой API - гарантия заканчивается: там «ровно один раз» обеспечивает идемпотентная обработка на уровне приложения. И требование это шире, чем подписчики: шаги и компенсации саги повторяются при retry по тем же причинам, поэтому каждый шаг тоже обязан выдерживать повторный вызов.

Ситуации, когда событие приходит повторно:

  • Consumer упал после обработки, но до коммита offset
  • Сетевой таймаут между consumer и брокером
  • Rebalancing партиций в Kafka
  • Ручной replay событий при инциденте

Idempotency Key: event ID как натуральный ключ

Каждое событие несёт уникальный event_id (UUID или ULID) - он попадает в конверт в момент создания факта, в домене, а не в consumer-е (см. структуру доменного события). Этот идентификатор - ключ дедупликации. Перед обработкой проверяем: видели ли мы это событие раньше? Если да - пропускаем. Если нет - обрабатываем и запоминаем. Обрати внимание: «idempotency key» его называют по традиции, но идемпотентной операцию он не делает - см. врезку выше.

Inbox-таблица: дедупликация обработки

Для дедупликации нужна таблица в базе данных:

CREATE TABLE processed_events (
    event_id    VARCHAR(64) NOT NULL,
    event_type  VARCHAR(128) NOT NULL,
    handler     VARCHAR(128) NOT NULL,
    processed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (event_id, handler)
);

-- Индекс для очистки старых записей
CREATE INDEX idx_processed_events_processed_at
    ON processed_events (processed_at);

Ключ здесь составной, и это не педантичность. Одно и то же событие обрабатывают несколько подписчиков: achievement-сервис и analytics-сервис - разные обработчики, каждый должен выполнить свою работу ровно один раз. При PRIMARY KEY (event_id) первый успевший обработчик занимает ключ, а второй видит «уже обработано» и молча пропускает свою часть - то есть ровно та потеря, от которой таблица защищает.

⚠️ «Пока обработчик один» - не аргумент

Соблазн взять PRIMARY KEY (event_id) «для простоты, у нас один подписчик» велик, но второй подписчик появляется позже и без миграции. Сбой при этом не громкий: ошибок нет, событие считается обработанным, просто чья-то работа не сделана. Составной ключ ничего не усложняет - он такой же индекс, только из двух колонок.

Check-Process-Mark: паттерн обработки

Первый приём: check inbox not found → process → mark; повторный: check found → skip

Основной паттерн: проверить - обработать - отметить.

// ProcessedEventsRepo отвечает за дедупликацию событий.
type ProcessedEventsRepo struct {
    db *sql.DB
}

// AlreadyProcessed проверяет, было ли событие обработано.
func (r *ProcessedEventsRepo) AlreadyProcessed(ctx context.Context, eventID, handler string) (bool, error) {
    var exists bool
    err := r.db.QueryRowContext(ctx,
        `SELECT EXISTS(SELECT 1 FROM processed_events WHERE event_id = $1 AND handler = $2)`,
        eventID, handler,
    ).Scan(&exists)
    return exists, err
}

// MarkProcessed отмечает событие как обработанное.
func (r *ProcessedEventsRepo) MarkProcessed(ctx context.Context, eventID, handler, eventType string) error {
    _, err := r.db.ExecContext(ctx,
        `INSERT INTO processed_events (event_id, event_type, handler)
         VALUES ($1, $2, $3)
         ON CONFLICT (event_id, handler) DO NOTHING`,
        eventID, eventType, handler,
    )
    return err
}
<?php
// src/Infrastructure/Inbox/ProcessedEventsRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Inbox;

use App\Application\Port\ProcessedEventsRepository as ProcessedEventsRepositoryPort;
use Doctrine\DBAL\Connection;

// Doctrine DBAL - тонкая прослойка над PDO. Симметрична database/sql из Go.
final class ProcessedEventsRepository implements ProcessedEventsRepositoryPort
{
    public function __construct(
        private readonly Connection $connection,
    ) {}

    public function alreadyProcessed(string $eventId, string $handler): bool
    {
        $row = $this->connection->fetchOne(
            'SELECT EXISTS(SELECT 1 FROM processed_events WHERE event_id = :eid AND handler = :h)',
            ['eid' => $eventId, 'h' => $handler],
        );
        return (bool) $row;
    }

    public function markProcessed(string $eventId, string $handler, string $eventType): void
    {
        // ON CONFLICT DO NOTHING - Postgres-specific.
        // На MySQL: INSERT IGNORE INTO ...
        $this->connection->executeStatement(
            'INSERT INTO processed_events (event_id, event_type, handler)
             VALUES (:eid, :etype, :h)
             ON CONFLICT (event_id, handler) DO NOTHING',
            ['eid' => $eventId, 'etype' => $eventType, 'h' => $handler],
        );
    }
}
# infrastructure/inbox/processed_events_repo.py
from psycopg import Connection


class ProcessedEventsRepo:
    """Отвечает за дедупликацию событий.

    psycopg (v3) - тонкая прослойка над libpq. Симметричен database/sql из Go.
    """

    def __init__(self, conn: Connection) -> None:
        self._conn = conn

    def already_processed(self, event_id: str, handler: str) -> bool:
        """Проверяет, было ли событие обработано."""
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                "SELECT EXISTS(SELECT 1 FROM processed_events WHERE event_id = %s AND handler = %s)",
                (event_id, handler),
            )
            row = cur.fetchone()
        return bool(row and row[0])

    def mark_processed(self, event_id: str, handler: str, event_type: str) -> None:
        """Отмечает событие как обработанное."""
        # ON CONFLICT DO NOTHING - Postgres-specific.
        # Явная транзакция: выход из with без исключения - COMMIT, с исключением - ROLLBACK.
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                """INSERT INTO processed_events (event_id, event_type, handler)
                   VALUES (%s, %s, %s)
                   ON CONFLICT (event_id, handler) DO NOTHING""",
                (event_id, event_type, handler),
            )

Обработчик события использует этот репозиторий:

// HandleLessonCompleted обрабатывает событие завершения урока.
// Защищает от повтора, только если обработка и отметка не разорваны сбоем:
// упадём между шагами 2 и 3 - при повторе логика выполнится снова.
// Надёжный вариант - HandleAtomically ниже.
func (h *AchievementHandler) HandleLessonCompleted(ctx context.Context, evt LessonCompleted) error {
    const handlerName = "achievement_checker"

    // 1. Check: уже обработано?
    seen, err := h.inbox.AlreadyProcessed(ctx, evt.EventID, handlerName)
    if err != nil {
        return fmt.Errorf("inbox check: %w", err)
    }
    if seen {
        slog.InfoContext(ctx, "event already processed, skipping",
            slog.String("event_id", evt.EventID),
            slog.String("handler", handlerName),
        )
        return nil
    }

    // 2. Process: выполняем бизнес-логику
    if err := h.checkAndGrantAchievements(ctx, evt.UserID, evt.LessonID); err != nil {
        return fmt.Errorf("grant achievements: %w", err)
    }

    // 3. Mark: запоминаем
    if err := h.inbox.MarkProcessed(ctx, evt.EventID, handlerName, evt.Type); err != nil {
        return fmt.Errorf("inbox mark: %w", err)
    }

    return nil
}
<?php
// src/Application/Subscriber/AchievementSubscriber.php
declare(strict_types=1);

namespace App\Application\Subscriber;

use App\Application\Port\ProcessedEventsRepository;
use App\Domain\Event\LessonCompleted;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class AchievementSubscriber
{
    private const HANDLER_NAME = 'achievement_checker';

    public function __construct(
        private readonly ProcessedEventsRepository $inbox,
        private readonly AchievementGranter $granter,
        private readonly LoggerInterface $logger,
    ) {}

    public function __invoke(LessonCompleted $event): void
    {
        // 1. Check: уже обработано?
        if ($this->inbox->alreadyProcessed($event->id, self::HANDLER_NAME)) {
            $this->logger->info('event already processed, skipping', [
                'event_id' => $event->id,
                'handler' => self::HANDLER_NAME,
            ]);
            return;
        }

        // 2. Process: выполняем бизнес-логику
        $this->granter->grantAchievements($event->userId, $event->lessonId);

        // 3. Mark: запоминаем
        $this->inbox->markProcessed($event->id, self::HANDLER_NAME, $event->eventType());
    }
}
# application/subscriber/achievement_handler.py
import logging

log = logging.getLogger(__name__)


class AchievementHandler:
    HANDLER_NAME = "achievement_checker"

    def __init__(self, inbox: ProcessedEventsRepo, granter: AchievementGranter) -> None:
        self._inbox = inbox
        self._granter = granter

    def handle_lesson_completed(self, evt: LessonCompleted) -> None:
        """Обрабатывает событие завершения урока.

        Защищает от повтора, только если обработка и отметка не разорваны сбоем:
        упадём между шагами 2 и 3 - при повторе логика выполнится снова.
        Надёжный вариант - handle_atomically ниже.
        Ошибки не возвращаются, а летят исключениями из inbox и granter - вызывающий
        (consumer) по ним решает, делать ли nack/retry.
        """
        # 1. Check: уже обработано?
        if self._inbox.already_processed(evt.event_id, self.HANDLER_NAME):
            log.info(
                "event already processed, skipping",
                extra={"event_id": evt.event_id, "handler": self.HANDLER_NAME},
            )
            return

        # 2. Process: выполняем бизнес-логику
        self._granter.check_and_grant_achievements(evt.user_id, evt.lesson_id)

        # 3. Mark: запоминаем
        self._inbox.mark_processed(evt.event_id, self.HANDLER_NAME, evt.event_type)

Атомарная отметка: INSERT ON CONFLICT DO NOTHING

Обратите внимание на ON CONFLICT DO NOTHING в MarkProcessed. Это критически важно. Если два воркера одновременно получили одно и то же событие, оба пройдут проверку AlreadyProcessed (оба получат false) и оба начнут обработку. ON CONFLICT DO NOTHING гарантирует, что вставка пройдёт только у первого. Но бизнес-логика всё равно выполнится дважды.

Для полной защиты от гонки нужна транзакция с блокировкой:

// HandleAtomically обрабатывает событие в одной транзакции с отметкой.
func (h *AchievementHandler) HandleAtomically(ctx context.Context, evt LessonCompleted) error {
    tx, err := h.db.BeginTx(ctx, nil)
    if err != nil {
        return fmt.Errorf("begin tx: %w", err)
    }
    defer tx.Rollback()

    // Пытаемся вставить - если уже есть, rows == 0
    res, err := tx.ExecContext(ctx,
        `INSERT INTO processed_events (event_id, event_type, handler)
         VALUES ($1, $2, $3)
         ON CONFLICT (event_id, handler) DO NOTHING`,
        evt.EventID, evt.Type, "achievement_checker",
    )
    if err != nil {
        return fmt.Errorf("inbox insert: %w", err)
    }

    rows, _ := res.RowsAffected()
    if rows == 0 {
        // Событие уже обработано другим воркером
        return nil
    }

    // Бизнес-логика внутри той же транзакции
    if err := h.grantAchievementsInTx(ctx, tx, evt.UserID, evt.LessonID); err != nil {
        return fmt.Errorf("grant: %w", err)
    }

    return tx.Commit()
}
<?php
// src/Application/Subscriber/AchievementHandlerAtomic.php
declare(strict_types=1);

namespace App\Application\Subscriber;

use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler]
final class AchievementHandlerAtomic
{
    private const HANDLER_NAME = 'achievement_checker';

    public function __construct(
        private readonly Connection $connection,
        private readonly AchievementGranter $granter,
    ) {}

    public function __invoke(LessonCompleted $event): void
    {
        $this->connection->transactional(function (Connection $tx) use ($event): void {
            // Пытаемся вставить - если уже есть, affectedRows == 0
            $affected = $tx->executeStatement(
                'INSERT INTO processed_events (event_id, event_type, handler)
                 VALUES (:eid, :etype, :h)
                 ON CONFLICT (event_id, handler) DO NOTHING',
                ['eid' => $event->id, 'etype' => $event->eventType(), 'h' => self::HANDLER_NAME],
            );

            if ($affected === 0) {
                // Событие уже обработано другим воркером
                return;
            }

            // Бизнес-логика внутри той же транзакции
            $this->granter->grantInTransaction($tx, $event->userId, $event->lessonId);
        });
    }
}
# application/subscriber/achievement_handler_atomic.py
from psycopg import Connection


class AchievementHandlerAtomic:
    HANDLER_NAME = "achievement_checker"

    def __init__(self, conn: Connection, granter: AchievementGranter) -> None:
        self._conn = conn
        self._granter = granter

    def handle_atomically(self, evt: LessonCompleted) -> None:
        """Обрабатывает событие в одной транзакции с отметкой."""
        # Явная транзакция: выход из with без исключения - COMMIT,
        # с исключением - ROLLBACK (откатятся и отметка, и бизнес-логика).
        with self._conn.transaction(), self._conn.cursor() as cur:
            # Пытаемся вставить - если уже есть, rowcount == 0
            cur.execute(
                """INSERT INTO processed_events (event_id, event_type, handler)
                   VALUES (%s, %s, %s)
                   ON CONFLICT (event_id, handler) DO NOTHING""",
                (evt.event_id, evt.event_type, self.HANDLER_NAME),
            )
            if cur.rowcount == 0:
                # Событие уже обработано другим воркером
                return

            # Бизнес-логика внутри той же транзакции - через тот же курсор
            self._granter.grant_in_tx(cur, evt.user_id, evt.lesson_id)

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

Естественная идемпотентность

Не все операции требуют inbox-таблицы, и это предпочтительный случай: если операция безопасна к повтору сама по себе, дедупликация не нужна вовсе - а значит нет и таблицы, которую можно потерять, и ключа, который можно подобрать неверно.

UPSERT вместо INSERT. Если подписчик записывает результат в таблицу, используйте INSERT ... ON CONFLICT DO UPDATE:

// RecordLessonCompletion записывает факт завершения урока.
// completedAt берём из события (evt.OccurredAt()), а не now(): тогда повтор
// пишет то же значение. Идемпотентна: повтор не меняет ни количество строк,
// ни completed_at.
func (r *AnalyticsRepo) RecordLessonCompletion(ctx context.Context, userID, lessonID int64, completedAt time.Time) error {
    _, err := r.db.ExecContext(ctx,
        `INSERT INTO lesson_completions (user_id, lesson_id, completed_at)
         VALUES ($1, $2, $3)
         ON CONFLICT (user_id, lesson_id)
         DO UPDATE SET completed_at = EXCLUDED.completed_at`,
        userID, lessonID, completedAt,
    )
    return err
}
<?php
// src/Infrastructure/Analytics/AnalyticsRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Analytics;

use Doctrine\DBAL\Connection;
use DateTimeImmutable;

final class AnalyticsRepository
{
    public function __construct(
        private readonly Connection $connection,
    ) {}

    // $completedAt берём из события ($event->occurredAt), а не now(): тогда повтор
    // пишет то же значение. Идемпотентна: повтор не меняет ни количество строк,
    // ни completed_at.
    public function recordLessonCompletion(int $userId, int $lessonId, DateTimeImmutable $completedAt): void
    {
        $this->connection->executeStatement(
            'INSERT INTO lesson_completions (user_id, lesson_id, completed_at)
             VALUES (:uid, :lid, :at)
             ON CONFLICT (user_id, lesson_id)
             DO UPDATE SET completed_at = EXCLUDED.completed_at',
            ['uid' => $userId, 'lid' => $lessonId, 'at' => $completedAt->format(DATE_ATOM)],
        );
    }
}
# infrastructure/analytics/analytics_repo.py
from datetime import datetime

from psycopg import Connection


class AnalyticsRepo:
    def __init__(self, conn: Connection) -> None:
        self._conn = conn

    def record_lesson_completion(self, user_id: int, lesson_id: int, completed_at: datetime) -> None:
        """Записывает факт завершения урока.

        completed_at берём из события (evt.occurred_at), а не now(): тогда повтор
        пишет то же значение. Идемпотентна: повтор не меняет ни количество строк,
        ни completed_at.
        """
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                """INSERT INTO lesson_completions (user_id, lesson_id, completed_at)
                   VALUES (%s, %s, %s)
                   ON CONFLICT (user_id, lesson_id)
                   DO UPDATE SET completed_at = EXCLUDED.completed_at""",
                (user_id, lesson_id, completed_at),
            )

State machine transitions. Если статус может двигаться только вперёд (pending -> paid -> shipped), повторная попытка перевести из pending в paid ничего не сломает, а попытка перевести из shipped в paid просто не пройдёт:

// AdvanceOrderStatus переводит заказ на следующий статус.
// Идемпотентна: WHERE clause гарантирует, что переход произойдёт только один раз.
func (r *OrderRepo) AdvanceOrderStatus(ctx context.Context, orderID int64, from, to string) error {
    res, err := r.db.ExecContext(ctx,
        `UPDATE orders SET status = $1, updated_at = now()
         WHERE id = $2 AND status = $3`,
        to, orderID, from,
    )
    if err != nil {
        return err
    }
    rows, _ := res.RowsAffected()
    if rows == 0 {
        slog.InfoContext(ctx, "order already advanced past this status",
            slog.Int64("order_id", orderID),
            slog.String("expected_from", from),
        )
    }
    return nil
}
<?php
// src/Infrastructure/Order/OrderRepository.php
declare(strict_types=1);

namespace App\Infrastructure\Order;

use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;

final class OrderRepository
{
    public function __construct(
        private readonly Connection $connection,
        private readonly LoggerInterface $logger,
    ) {}

    // Идемпотентна: WHERE clause гарантирует, что переход произойдёт только один раз.
    public function advanceStatus(int $orderId, string $from, string $to): void
    {
        $affected = $this->connection->executeStatement(
            'UPDATE orders SET status = :to, updated_at = now()
             WHERE id = :oid AND status = :from',
            ['to' => $to, 'oid' => $orderId, 'from' => $from],
        );

        if ($affected === 0) {
            $this->logger->info('order already advanced past this status', [
                'order_id' => $orderId,
                'expected_from' => $from,
            ]);
        }
    }
}
# infrastructure/order/order_repo.py
import logging

from psycopg import Connection

log = logging.getLogger(__name__)


class OrderRepo:
    def __init__(self, conn: Connection) -> None:
        self._conn = conn

    def advance_order_status(self, order_id: int, from_status: str, to_status: str) -> None:
        """Переводит заказ на следующий статус.

        Идемпотентна: WHERE clause гарантирует, что переход произойдёт только один раз.
        """
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                """UPDATE orders SET status = %s, updated_at = now()
                   WHERE id = %s AND status = %s""",
                (to_status, order_id, from_status),
            )
            affected = cur.rowcount

        if affected == 0:
            log.info(
                "order already advanced past this status",
                extra={"order_id": order_id, "expected_from": from_status},
            )

TTL для processed_events

Таблица processed_events растёт бесконечно. События старше определённого возраста можно безопасно удалять - вероятность получить событие двухнедельной давности стремится к нулю:

// CleanupOldEvents удаляет записи старше ttl.
// Запускайте по cron раз в сутки.
func (r *ProcessedEventsRepo) CleanupOldEvents(ctx context.Context, ttl time.Duration) (int64, error) {
    res, err := r.db.ExecContext(ctx,
        `DELETE FROM processed_events WHERE processed_at < $1`,
        time.Now().Add(-ttl),
    )
    if err != nil {
        return 0, err
    }
    return res.RowsAffected()
}
<?php
// src/Application/Cron/CleanupProcessedEventsCommand.php
declare(strict_types=1);

namespace App\Application\Cron;

use Doctrine\DBAL\Connection;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use DateTimeImmutable;

// Запускается из cron: `bin/console app:cleanup-processed-events --ttl-days=14`.
// В Symfony альтернатива - Scheduler component (symfony/scheduler).
#[AsCommand(name: 'app:cleanup-processed-events')]
final class CleanupProcessedEventsCommand extends Command
{
    public function __construct(
        private readonly Connection $connection,
    ) {
        parent::__construct();
    }

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $ttlDays = 14;
        $threshold = (new DateTimeImmutable())->modify(sprintf('-%d days', $ttlDays));

        $affected = $this->connection->executeStatement(
            'DELETE FROM processed_events WHERE processed_at < :threshold',
            ['threshold' => $threshold->format('Y-m-d H:i:s')],
        );

        $output->writeln(sprintf('deleted %d rows', $affected));
        return Command::SUCCESS;
    }
}
# application/cron/cleanup_processed_events.py
from datetime import datetime, timedelta, timezone

from psycopg import Connection


class ProcessedEventsRepo:
    def __init__(self, conn: Connection) -> None:
        self._conn = conn

    def cleanup_old_events(self, ttl: timedelta) -> int:
        """Удаляет записи старше ttl и возвращает число удалённых.

        Запускайте по cron раз в сутки (или из Celery beat / APScheduler).
        """
        threshold = datetime.now(timezone.utc) - ttl
        with self._conn.transaction(), self._conn.cursor() as cur:
            cur.execute(
                "DELETE FROM processed_events WHERE processed_at < %s",
                (threshold,),
            )
            return cur.rowcount

Разумный TTL - от 7 до 30 дней, в зависимости от того, как далеко назад вы можете replay-ить события.

HTTP API: заголовок Idempotency-Key

Idempotency нужна не только внутри event-driven системы. HTTP-клиенты тоже могут повторять запросы (таймаут, retry). Stripe популяризировал паттерн с заголовком Idempotency-Key:

// CachedResponse - сохранённый ответ: статус, заголовки и тело.
type CachedResponse struct {
    StatusCode int
    Header     http.Header
    Body       []byte
}

// IdempotencyRepo хранит ключи в таблице
// idempotency_keys(key PRIMARY KEY, status, status_code, headers, body, created_at).
type IdempotencyRepo interface {
    // Reserve атомарно занимает ключ:
    //   INSERT INTO idempotency_keys (key, status) VALUES ($1, 'in_progress')
    //   ON CONFLICT (key) DO NOTHING
    // reserved=true - ключ наш. Иначе cached - сохранённый ответ
    // или nil, если первый запрос с этим ключом ещё выполняется.
    Reserve(ctx context.Context, key string) (reserved bool, cached *CachedResponse, err error)
    // Complete сохраняет ответ и переводит ключ в статус done.
    Complete(ctx context.Context, key string, resp CachedResponse) error
    // Release удаляет бронь, чтобы повтор мог выполниться заново.
    Release(ctx context.Context, key string) error
}

// IdempotencyMiddleware проверяет заголовок Idempotency-Key.
// Если запрос с таким ключом уже обработан - возвращает сохранённый ответ.
func IdempotencyMiddleware(repo IdempotencyRepo) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            key := r.Header.Get("Idempotency-Key")
            if key == "" {
                next.ServeHTTP(w, r)
                return
            }

            // 1. Занимаем ключ ДО вызова handler-а. Просто проверить кэш мало:
            // клиент обычно повторяет запрос по таймауту, пока первый ещё
            // выполняется, и оба прошли бы проверку - двойное списание.
            reserved, cached, err := repo.Reserve(r.Context(), key)
            if err != nil {
                http.Error(w, "idempotency store unavailable", http.StatusServiceUnavailable)
                return
            }
            if !reserved {
                if cached == nil {
                    // Первый запрос с этим ключом ещё в работе
                    http.Error(w, "request with this Idempotency-Key is in progress", http.StatusConflict)
                    return
                }
                // 2. Повтор: отдаём сохранённый ответ целиком, вместе с заголовками
                for k, v := range cached.Header {
                    w.Header()[k] = v
                }
                w.WriteHeader(cached.StatusCode)
                _, _ = w.Write(cached.Body)
                return
            }

            // 3. Ключ наш: выполняем запрос и записываем ответ
            rec := &responseRecorder{ResponseWriter: w, statusCode: http.StatusOK}
            next.ServeHTTP(rec, r)

            // 5xx не сохраняем: снимаем бронь, чтобы повтор мог выполниться
            if rec.statusCode >= http.StatusInternalServerError {
                _ = repo.Release(r.Context(), key)
                return
            }
            // Если запись упадёт, ключ останется in_progress: такие брони чистит TTL
            _ = repo.Complete(r.Context(), key, CachedResponse{
                StatusCode: rec.statusCode,
                Header:     w.Header().Clone(),
                Body:       rec.body.Bytes(),
            })
        })
    }
}

// responseRecorder пропускает ответ клиенту и параллельно копит его для сохранения
type responseRecorder struct {
    http.ResponseWriter
    statusCode int
    body       bytes.Buffer
}

func (r *responseRecorder) WriteHeader(code int) {
    r.statusCode = code
    r.ResponseWriter.WriteHeader(code)
}

func (r *responseRecorder) Write(b []byte) (int, error) {
    r.body.Write(b)
    return r.ResponseWriter.Write(b)
}
<?php
// src/Infrastructure/Http/IdempotencyListener.php
declare(strict_types=1);

namespace App\Infrastructure\Http;

use App\Application\Port\IdempotencyRepository;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\Event\ResponseEvent;

// В Symfony роль HTTP-middleware из Go играют kernel-listener'ы.
// onRequest занимает ключ (или отдаёт сохранённый ответ), onResponse сохраняет ответ.
//
// IdempotencyRepository:
//   reserve(key): bool - INSERT INTO idempotency_keys (key, status)
//                        VALUES (:key, 'in_progress') ON CONFLICT (key) DO NOTHING
//   getCachedResponse(key): ?CachedResponse - null, пока первый запрос выполняется
//   complete(key, status, headers, body), release(key)
final class IdempotencyListener
{
    private const RESERVED_ATTR = '_idempotency_reserved';

    public function __construct(
        private readonly IdempotencyRepository $repo,
    ) {}

    #[AsEventListener(event: RequestEvent::class)]
    public function onRequest(RequestEvent $event): void
    {
        $request = $event->getRequest();
        $key = $request->headers->get('Idempotency-Key');
        if ($key === null) {
            return;
        }

        // Занимаем ключ ДО контроллера: повтор по таймауту приходит,
        // пока первый запрос ещё выполняется
        if ($this->repo->reserve($key)) {
            $request->attributes->set(self::RESERVED_ATTR, true);

            return;
        }

        $cached = $this->repo->getCachedResponse($key);
        if ($cached === null) {
            // Первый запрос с этим ключом ещё в работе
            $event->setResponse(new Response('request with this Idempotency-Key is in progress', 409));

            return;
        }

        // Повтор: отдаём сохранённый ответ вместе с заголовками - дальше kernel не идёт
        $event->setResponse(new Response($cached->body, $cached->statusCode, $cached->headers));
    }

    #[AsEventListener(event: ResponseEvent::class)]
    public function onResponse(ResponseEvent $event): void
    {
        $request = $event->getRequest();
        $key = $request->headers->get('Idempotency-Key');
        // Сохраняем только ответ запроса, который сам занял ключ
        if ($key === null || $request->attributes->get(self::RESERVED_ATTR) !== true) {
            return;
        }

        $response = $event->getResponse();
        if ($response->getStatusCode() >= 500) {
            // 5xx не сохраняем: снимаем бронь, чтобы повтор мог выполниться
            $this->repo->release($key);

            return;
        }

        $this->repo->complete(
            $key,
            $response->getStatusCode(),
            $response->headers->all(),
            (string) $response->getContent(),
        );
    }
}
# infrastructure/http/idempotency_middleware.py
from dataclasses import dataclass
from http import HTTPStatus
from typing import Callable, Iterable, Protocol

WSGIApp = Callable[[dict, Callable], Iterable[bytes]]


@dataclass(frozen=True, slots=True)
class CachedResponse:
    status_code: int
    headers: list[tuple[str, str]]
    body: bytes


class IdempotencyRepo(Protocol):
    # INSERT INTO idempotency_keys (key, status) VALUES (%s, 'in_progress')
    # ON CONFLICT (key) DO NOTHING; True - ключ занят нами
    def reserve(self, key: str) -> bool: ...
    # None, пока первый запрос с этим ключом выполняется
    def get_cached_response(self, key: str) -> CachedResponse | None: ...
    def complete(self, key: str, response: CachedResponse) -> None: ...
    def release(self, key: str) -> None: ...


class IdempotencyMiddleware:
    """Проверяет заголовок Idempotency-Key.

    Если запрос с таким ключом уже обработан - возвращает сохранённый ответ.
    Фреймворк-независимый WSGI-вариант: в FastAPI/Starlette это BaseHTTPMiddleware,
    в Django - класс middleware с __call__(request).
    """

    def __init__(self, app: WSGIApp, repo: IdempotencyRepo) -> None:
        self._app = app
        self._repo = repo

    def __call__(self, environ: dict, start_response: Callable) -> Iterable[bytes]:
        # WSGI кладёт заголовки в environ как HTTP_<ИМЯ>
        key = environ.get("HTTP_IDEMPOTENCY_KEY", "")
        if not key:
            return self._app(environ, start_response)

        # Занимаем ключ ДО вызова приложения: повтор по таймауту приходит,
        # пока первый запрос ещё выполняется
        if not self._repo.reserve(key):
            cached = self._repo.get_cached_response(key)
            if cached is None:
                start_response("409 Conflict", [("Content-Type", "text/plain")])
                return [b"request with this Idempotency-Key is in progress"]
            # Повтор: отдаём сохранённый ответ вместе с заголовками
            phrase = HTTPStatus(cached.status_code).phrase
            start_response(f"{cached.status_code} {phrase}", cached.headers)
            return [cached.body]

        # Оборачиваем start_response для захвата статуса и заголовков ответа
        captured: dict = {}

        def recording_start_response(status: str, headers: list, exc_info=None):
            captured["status"] = status
            captured["headers"] = list(headers)
            return start_response(status, headers, exc_info)

        try:
            body = b"".join(self._app(environ, recording_start_response))
        except Exception:
            self._repo.release(key)  # упали - повтор должен выполниться заново
            raise

        status_code = int(captured.get("status", "200 OK").split()[0])
        if status_code >= 500:
            self._repo.release(key)  # 5xx не сохраняем
        else:
            self._repo.complete(key, CachedResponse(status_code, captured.get("headers", []), body))
        return [body]

🚫 Устойчивость к повтору - не оптимизация, а обязательное требование

В at-least-once системе каждый подписчик обязан корректно переживать повторную доставку. Без этого повторы дадут дубли данных, двойные списания и повреждённое состояние.

Достигается это двумя способами, и они не равноценны: идемпотентная операция безопасна к повтору сама (UPSERT, установка целевого состояния, ключ операции на стороне внешнего API), дедупликация через inbox делает безопасной обработку конкретного события по записи в базе. Первое надёжнее, потому что не зависит от сохранности этой записи; второе - способ прикрыть то, что переписать нельзя.

Проектировать это стоит с самого начала: добавлять потом значительно дороже, особенно если операции уже написаны через инкременты.

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

  • Проверка «не обработано ли» отдельно от обработки - две reads + два writes без транзакции. Между check и mark два инстанса видят «не обработано», оба делают работу. Атомарность через INSERT ... ON CONFLICT DO NOTHING + RETURNING в одной транзакции с бизнес-логикой.
  • Idempotency-key = таймстамп клиента - два разных POST от одного юзера в одну миллисекунду дают одинаковый ключ; одно из действий теряется. Используй UUID, генерируемый клиентом до запроса.
  • Idempotency-store разделён с бизнес-БД - отметка о processing идёт в Redis, бизнес-данные в PostgreSQL. Redis перезагрузился без AOF → дубли. Idempotency живёт в той же БД, что и бизнес-операция; одна транзакция.
  • Различные subscriber-ы пишут в одну processed_events без поля handler - subscriber A обработал, отметил; subscriber B видит «уже обработано» и пропускает свою работу. Ключ дедупа = (event_id, handler_name), не только event_id.
  • UPSERT вместо «начислить +10 бонусов» - повторное событие → бонусы перезаписываются тем же значением (это корректно). Но если бы было UPDATE balance = balance + 10 - двойное начисление. Понимай: идемпотентность через UPSERT работает для установки значения, не для инкремента.
  • Idempotency только в HTTP-слое - клиент шлёт повторный POST с тем же Idempotency-Key, HTTP-middleware возвращает кэшированный ответ. Но внутреннее событие тоже опубликовано дважды - а subscriber не имеет своей дедупликации. Дедуп нужен на каждом узле at-least-once-цепочки.
  • Сравнение processed_at для «свежести» - «не обработать события старше 1 часа». При replay из брокера старые события массово пропускаются и не обновляют read-модели. Не путай идемпотентность с фильтрацией.

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

  • Создай таблицу processed_events с полями event_id, handler, event_type, processed_at
  • Реализуй атомарный check-process-mark паттерн с INSERT ON CONFLICT DO NOTHING внутри транзакции
  • Перепиши один из своих обработчиков, чтобы он использовал естественную идемпотентность (UPSERT или state machine)
  • Добавь горутину очистки записей старше 14 дней
  • Напиши unit-тест: вызови обработчик дважды с одним event_id и убедись, что бизнес-логика выполнилась один раз

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