Files
mtusi2026lab4/openspec/specs/idempotency/spec.md
T
ricoromaandClaude Opus 5.5 116d8d3bf0 feat: add image attachments to messages
- 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>
2026-10-21 01:08:56 +03:00

262 lines
14 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`, `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