- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 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 и created_at до микросекунды. Новое сообщение
MUST NOT создаваться. Тела SHALL сравниваться по смыслу, после разбора
JSON: запись пробелов, экранирование символов и порядок полей на
результат не влияют.
Scenario: Повтор того же тела
- WHEN Алиса отправляет текст T с ключом K и повторяет тот же запрос
- THEN оба ответа 201 с одинаковым JSON, а в истории чата одно сообщение с текстом T
Scenario: Тот же JSON в другой записи
- WHEN повтор с ключом K несёт то же тело в другой записи: с
другими пробелами и с текстом в экранировании
\uXXXX - THEN ответ 201 с тем же
Message, новое сообщение не создано
Requirement: Другое тело с тем же ключом
Если ключ в своей области уже использован с другим телом и срок не
истёк, сервис SHALL отвечать 409 conflict. Новое сообщение MUST NOT
создаваться, сохранённый результат ключа MUST NOT меняться.
Scenario: Другой текст
- WHEN Алиса отправила T1 с ключом K, затем отправляет T2 с тем же ключом в тот же чат
- THEN второй ответ 409
conflict, в истории только T1, а повтор T1 с K по-прежнему возвращает исходныйMessage
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