- 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>
233 lines
13 KiB
Markdown
233 lines
13 KiB
Markdown
# 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
|