- upload, metadata and download endpoints for PNG/JPEG attachments:
limits before reading and decompression, type by content,
structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
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
повторяться тем же телом и после замены реплик на версию с вложениями.
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], в истории одно такое сообщение
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