Files
mtusi2026lab5/openspec/specs/idempotency/spec.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

15 KiB
Raw Blame History

idempotency Specification

Purpose

Повторная отправка сообщения с Idempotency-Key. Клиент, который не получил ответа, повторяет запрос с тем же ключом. Он получает тот же результат без дубля, через любой процесс API и при одновременных повторах.

Requirements

Requirement: Обязательный ключ отправки сообщения

POST /api/v1/chats/{chat_id}/messages SHALL требовать заголовок Idempotency-Key: от 1 до 128 символов ASCII из набора A–Z, a–z, 0–9, ., _, :, -. Если ключа нет, он пустой, длиннее 128 символов или содержит другой символ, ответ SHALL быть 400 invalid_request. Сообщение при этом MUST NOT создаваться, а значение ключа MUST NOT попадать в ответ. Остальные эндпоинты ключ не требуют, и его наличие их поведение MUST NOT менять.

Scenario: Нет ключа

  • WHEN участник отправляет валидное тело без Idempotency-Key
  • THEN ответ 400 invalid_request, в истории чата нового сообщения нет

Scenario: Неверный ключ

  • WHEN участник отправляет валидное тело с пустым ключом, с ключом из 129 символов, с ключом с пробелом, / или кириллицей
  • THEN каждый ответ 400 invalid_request, значение ключа не встречается в теле ответа, история чата не меняется

Scenario: Граница длины ключа

  • WHEN участник отправляет сообщение с ключом из 128 допустимых символов, включая ., _, : и -
  • THEN ответ 201

Scenario: Ключ у других запросов

  • WHEN Алиса дважды создаёт чат одним и тем же телом и одним и тем же Idempotency-Key
  • THEN оба ответа 201, и это два разных чата

Requirement: Повтор возвращает исходный результат

Повтор от того же пользователя в тот же чат с тем же ключом и тем же телом в пределах срока ключа SHALL возвращать 201 и тот же Message: тот же id, text, attachment_ids и created_at до микросекунды. Новое сообщение MUST NOT создаваться. Тела SHALL сравниваться по смыслу, после разбора JSON. На результат не влияют:

  • запись пробелов и экранирование символов;
  • порядок полей объекта;
  • отсутствующий attachment_ids вместо [];
  • регистр букв в идентификаторах вложений.

Порядок элементов attachment_ids значим: это порядок вложений в сообщении. Ключ, сохранённый версией сервиса без вложений, SHALL повторяться тем же телом и после замены реплик на версию с вложениями.

Повтор MUST NOT зависеть от текущего состояния вложений сообщения: вложение, ставшее failed после отправки, не меняет ответ на повтор.

Scenario: Повтор того же тела

  • WHEN Алиса отправляет текст T с ключом K и повторяет тот же запрос
  • THEN оба ответа 201 с одинаковым JSON, а в истории чата одно сообщение с текстом T

Scenario: Тот же JSON в другой записи

  • WHEN повтор с ключом K несёт то же тело в другой записи: с другими пробелами и с текстом в экранировании \uXXXX
  • THEN ответ 201 с тем же Message, новое сообщение не создано

Scenario: Вложения по умолчанию

  • WHEN Алиса отправила {"text": T} с ключом K и повторяет с K тело {"attachment_ids": [], "text": T}
  • THEN ответ 201 с тем же Message, новое сообщение не создано

Scenario: Повтор сообщения с вложениями

  • WHEN Алиса отправила текст с attachment_ids [A, B] и ключом K, затем повторяет с K то же тело, а потом то же тело с A и B в верхнем регистре
  • THEN оба ответа 201 с тем же Message и attachment_ids [A, B], в истории одно такое сообщение

Scenario: Повтор после failed вложения

  • WHEN Алиса отправила с ключом K сообщение с вложением в queued, вложение стало failed, и она повторяет с K то же тело, а затем с другим ключом
  • THEN повтор с K — 201 с тем же Message, отправка с другим ключом — 409 conflict, а в истории одно такое сообщение

Requirement: Другое тело с тем же ключом

Если ключ в своей области уже использован с другим телом и срок не истёк, сервис SHALL отвечать 409 conflict. Новое сообщение MUST NOT создаваться, сохранённый результат ключа MUST NOT меняться. Другие вложения или их другой порядок — другое тело.

Scenario: Другой текст

  • WHEN Алиса отправила T1 с ключом K, затем отправляет T2 с тем же ключом в тот же чат
  • THEN второй ответ 409 conflict, в истории только T1, а повтор T1 с K по-прежнему возвращает исходный Message

Scenario: Другие вложения

  • WHEN Алиса отправила текст с attachment_ids [A, B] и ключом K, затем шлёт с K тот же текст с [B, A], а потом без вложений
  • THEN оба ответа 409 conflict, в истории одно сообщение с [A, B]

Requirement: Область ключа

Ключ SHALL быть уникален в пределах пользователя и чата: метод и путь для него однозначны, ключ принимает одна ручка. Тот же ключ у другого пользователя или в другом чате SHALL обрабатываться как новый.

Scenario: Другой пользователь

  • WHEN Алиса и Боб отправляют в общий чат сообщения с одинаковым ключом K и разными текстами
  • THEN оба ответа 201, в истории два разных сообщения

Scenario: Другой чат

  • WHEN Алиса отправляет одно и то же тело с ключом K в чат A и в чат B
  • THEN оба ответа 201 с разными id, по одному сообщению в каждом чате

Requirement: Повтор проверяет сессию и доступ

Повтор SHALL проходить ту же аутентификацию и проверку членства, что и первый запрос. Без них сохранённый результат MUST NOT выдаваться. Ключ принадлежит пользователю, а не сессии: новая сессия того же пользователя SHALL получать сохранённый результат.

Scenario: Отозванный токен

  • WHEN Алиса отправила сообщение с ключом K, вышла и повторяет запрос тем же токеном
  • THEN ответ 401 unauthorized с WWW-Authenticate: Bearer

Scenario: Новая сессия того же пользователя

  • WHEN Алиса отправила сообщение с ключом K, вошла заново и повторяет запрос новым токеном
  • THEN ответ 201 с тем же Message

Scenario: Посторонний с чужим ключом

  • WHEN Ева повторяет в чат Алисы и Боба запрос Алисы с её ключом K и тем же телом
  • THEN ответ 404 not_found, а повтор Алисы с K по-прежнему возвращает исходный Message

Requirement: Порядок проверок

Если у запроса сразу несколько ошибок, ответ SHALL определяться порядком 401 (сессия) → 400 (ключ и тело) → 404 (не участник) → 409 (другое тело). Исключение — битый JSON: он даёт 400 раньше проверки сессии (расхождение FastAPI, согласованное с преподавателем).

Scenario: Без сессии и без ключа

  • WHEN запрос без Authorization и без Idempotency-Key с валидным телом
  • THEN ответ 401 unauthorized

Scenario: Посторонний без ключа

  • WHEN Ева отправляет валидное тело без ключа в чат Алисы и Боба
  • THEN ответ 400 invalid_request

Scenario: Невалидное тело с занятым ключом

  • WHEN Алиса отправила T1 с ключом K, затем отправляет с K тело {"text": ""}
  • THEN ответ 400 invalid_request, а не 409

Requirement: Одновременные повторы

Одновременные запросы с одним ключом и одним телом, в том числе через разные процессы API, SHALL создавать ровно одно сообщение. Все ответы SHALL быть 201 с одним и тем же Message.

Scenario: Гонка одного ключа

  • WHEN 10 клиентов по отдельным соединениям одновременно отправляют одно тело с одним ключом
  • THEN все ответы 201 с одинаковым id, а в истории чата ровно одно такое сообщение

Scenario: Гонка одного ключа через реплики

  • WHEN 10 клиентов по отдельным соединениям одновременно отправляют одно тело с одним ключом через балансировщик, и среди ответов есть два пересекающихся по времени запроса, которые обслужили реплики с разными X-Instance-Id
  • THEN все ответы 201 с одинаковым Message, а в истории чата ровно одно такое сообщение

Requirement: Ключ фиксируется только вместе с сообщением

Ключ SHALL сохраняться только вместе с сообщением, в одной транзакции. Запрос, завершившийся ошибкой (400, 401, 404, 5xx, отказ хранилища), MUST NOT занимать ключ: повтор с тем же ключом SHALL выполняться заново. Ответ 201 SHALL означать, что сохранены и сообщение, и ключ.

Scenario: Невалидный запрос не занимает ключ

  • WHEN с ключом K пришло тело {"text": ""} (ответ 400), затем с тем же K — валидное тело
  • THEN второй ответ 201, сообщение создано

Scenario: Сбой при записи сообщения

  • WHEN ключ уже записан в транзакции, а вставка сообщения завершается ошибкой
  • THEN ответ 5xx; после устранения сбоя повтор с тем же ключом и телом даёт 201, и в истории ровно одно такое сообщение

Scenario: Отказ БД при отправке

  • WHEN PostgreSQL остановлен во время отправки с ключом K, а после его возврата клиент повторяет запрос с K и тем же телом
  • THEN первый ответ 503 unavailable, повтор — 201, в истории ровно одно такое сообщение

Requirement: Срок ключа

Ключ SHALL храниться не меньше срока [idempotency] ttl_seconds с момента успешной отправки (по умолчанию 86400 с, 24 ч по контракту). После срока ключ SHALL считаться свободным: запрос с ним выполняется как новый, в том числе с другим телом.

Scenario: Ключ после срока

  • WHEN срок ключа — 2 с, Алиса отправила T1 с ключом K, и прошло больше 2 с
  • THEN отправка T2 с тем же K — 201 и новое сообщение, а не 409

Requirement: Ключ хранится вне процесса API

Ключи и их результаты SHALL храниться в PostgreSQL вместе с сообщениями. Они SHALL переживать рестарт API и хранилищ с сохранёнными volumes. Повтор через другой процесс API SHALL давать тот же результат, что и через исходный.

Scenario: Повтор после рестарта API

  • WHEN сообщение отправлено с ключом K, и процесс API перезапущен
  • THEN повтор с K и тем же телом даёт 201 с тем же Message

Scenario: Повтор через другую реплику

  • WHEN сообщение отправлено с ключом K через балансировщик, а повтор с K и тем же телом обслужила реплика с другим X-Instance-Id
  • THEN повтор даёт 201 с тем же Message, а другое тело с K на любой реплике — 409