# 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