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

14 KiB
Raw Blame History

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