Files
mtusi2026lab3/openspec/specs/idempotency/spec.md
T
ricoromaandClaude Opus 5.5 ab71c3b51e feat: put API replicas behind HAProxy
HAProxy 3.4 is the only published entry point; api runs as
API_REPLICAS replicas without ports, found through Docker DNS and
checked on /health/ready. Retries only on connection failure, LB errors
in the contract error format, resource limits and per-service secrets.
Adds scripts/stop-one.sh, LB-aware restart.sh, make replicas /
instances / lb_stats and replica tests driven by EXPECT_REPLICAS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 18:05:05 +03:00

233 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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