Files
mtusi2026lab6/openspec/specs/api-conventions/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

265 lines
15 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.
# api-conventions Specification
## Purpose
Общие правила HTTP API мессенджера: кодировка и формат JSON, единый
формат ошибок, заголовок `X-Request-Id`, представление времени и
идентификаторов. На них опираются все эндпоинты и клиенты, включая
публичный smoke.
## Requirements
### Requirement: JSON в UTF-8 без искажений
Ответы с телом SHALL иметь `Content-Type: application/json` в
кодировке UTF-8. Строки SHALL возвращаться клиенту в том виде, в каком
были приняты, включая кириллицу и emoji. Длины строк SHALL считаться в
Unicode code points.
#### Scenario: Unicode сохраняется
- **WHEN** клиент отправляет строковое поле `"Привет, мир 👋"`
- **THEN** в ответе и при последующем чтении это поле равно
`"Привет, мир 👋"` байт в байт после декодирования UTF-8
#### Scenario: Длина в code points
- **WHEN** клиент отправляет поле с ограничением 100 символов,
состоящее из 100 emoji
- **THEN** запрос принимается, хотя в UTF-8 это больше 100 байт
### Requirement: X-Request-Id на каждом ответе
Каждый ответ API SHALL содержать непустой заголовок `X-Request-Id`,
уникальный для запроса: успешный, с ошибкой, health, ответ на
неизвестный путь и ответ на непредвиденное исключение.
#### Scenario: Успешный ответ
- **WHEN** клиент выполняет любой успешный запрос
- **THEN** ответ содержит непустой `X-Request-Id`
#### Scenario: Ответ 500
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ 500 тоже содержит непустой `X-Request-Id`
#### Scenario: Разные запросы
- **WHEN** клиент выполняет два запроса подряд
- **THEN** значения `X-Request-Id` в ответах различаются
### Requirement: X-Instance-Id на каждом ответе
Каждый ответ, созданный API, SHALL содержать непустой заголовок
`X-Instance-Id` — идентификатор процесса, который обслужил запрос.
Это касается успешных ответов, ошибок, health, ответа на неизвестный
путь и неподдерживаемый метод, ответа на непредвиденное исключение.
Значение SHALL быть одним для всех ответов процесса, пока он работает,
и различаться у одновременно работающих процессов. Значение SHALL
состоять из ASCII-символов `A–Z`, `a–z`, `0–9`, `.`, `_`, `-`.
Требование не распространяется на ответы, которые создал не API, а
балансировщик при недоступности реплик.
#### Scenario: Instance id в успешном ответе и ошибке
- **WHEN** клиент получает ответы 200 и 201 и ответы с ошибками 400,
401, 404 и 409
- **THEN** каждый ответ содержит непустой `X-Instance-Id` допустимого
формата
#### Scenario: Instance id в health и служебных ответах
- **WHEN** клиент запрашивает `/health/live`, `/health/ready`,
`GET /api/v1/unknown` и `DELETE /api/v1/users`
- **THEN** каждый ответ содержит непустой `X-Instance-Id`
#### Scenario: Instance id в ответе 500
- **WHEN** обработка запроса завершается непредвиденным исключением
- **THEN** ответ 500 тоже содержит `X-Instance-Id` того же процесса
#### Scenario: Одно значение на процесс
- **WHEN** клиент дважды подряд выполняет одну и ту же серию разных
запросов — к одному процессу API или через балансировщик к
нескольким репликам
- **THEN** против одного процесса все ответы содержат одно значение
`X-Instance-Id`; через балансировщик каждое значение встречается
больше чем в одном ответе, а во второй серии нет значений, которых не
было в первой
### Requirement: Единый формат ошибки
Любой ответ со статусом ≥ 400 SHALL иметь тело
`{"error": {"code": ..., "message": ..., "request_id": ...}}` без
других полей. `request_id` MUST совпадать с заголовком `X-Request-Id`.
`message` MUST быть непустым и MUST NOT раскрывать stack trace, пути к
файлам, имена внутренних классов, запросы к хранилищу или сам факт
существования недоступного объекта.
#### Scenario: Ошибка содержит request_id заголовка
- **WHEN** клиент получает любой ответ с ошибкой
- **THEN** тело соответствует формату, а `error.request_id` равен
значению заголовка `X-Request-Id`
#### Scenario: Нет тела FastAPI по умолчанию
- **WHEN** клиент получает ошибку валидации или 404
- **THEN** в теле нет ключа `detail`, есть только `error`
### Requirement: Соответствие статусов и кодов ошибок
Сервис SHALL использовать пары статус — `code`: 400 —
`invalid_request`, 401 — `unauthorized`, 404 — `not_found`, 409 —
`conflict`, 413 — `payload_too_large`, 415 — `unsupported_media_type`,
429 — `rate_limited`, 500 — `internal_error`, 503 — `unavailable`.
Метод, не поддерживаемый путём, SHALL давать 405 с `code`
`invalid_request`. Ответ 429 SHALL содержать заголовок `Retry-After` —
положительное целое число секунд.
#### Scenario: Неизвестный путь
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
#### Scenario: Неподдерживаемый метод
- **WHEN** клиент выполняет `DELETE /api/v1/users`
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
#### Scenario: Лимит и тип вложения
- **WHEN** участник загружает вложение больше 10 MiB, а затем текст с
`Content-Type: image/png`
- **THEN** ответы 413 с `code` `payload_too_large` и 415 с `code`
`unsupported_media_type` в формате ошибки
#### Scenario: Лимит одновременных загрузок
- **WHEN** все места загрузки процесса заняты и очередь ожидания полна
(`attachments`, «Одновременные загрузки реплики»), и участник
загружает вложение
- **THEN** ответ 429 с `code` `rate_limited` в формате ошибки, с
непустыми `X-Request-Id` и `X-Instance-Id` и с `Retry-After` —
положительным целым числом
### Requirement: Невалидный запрос даёт 400
Сервис SHALL отвечать 400 `invalid_request`, а не 422, когда тело не
является корректным JSON; когда JSON не объект там, где ожидается
объект; когда в теле есть поля, не описанные в контракте; когда тип
значения не совпадает с контрактом. Значения MUST NOT приводиться к
нужному типу неявно. Обязательные строковые поля, состоящие только из
пробельных символов, SHALL считаться невалидными.
#### Scenario: Битый JSON
- **WHEN** клиент отправляет тело `{bad` с `Content-Type: application/json`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Лишнее поле
- **WHEN** тело запроса содержит поле, которого нет в схеме контракта
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Неверный тип без приведения
- **WHEN** строковое поле передано числом `123`
- **THEN** ответ 400, значение не превращается в строку `"123"`
#### Scenario: Строка из пробелов
- **WHEN** обязательное строковое поле равно `" "`
- **THEN** ответ 400 с `code` `invalid_request`
### Requirement: Непредвиденная ошибка без деталей
Непредвиденное исключение SHALL давать ответ 500 с `code`
`internal_error` и общим сообщением. Детали ошибки MUST попадать только
в лог сервиса.
#### Scenario: Исключение внутри обработки
- **WHEN** при обработке запроса возникает непредвиденное исключение
- **THEN** клиент получает 500 `internal_error` без stack trace, а в
логе есть запись уровня `error` с traceback и тем же `request_id`
### Requirement: Представление времени и идентификаторов
Идентификаторы и время SHALL назначаться сервером. Идентификаторы SHALL
быть UUID в виде строки в нижнем регистре. Время SHALL передаваться в
формате RFC 3339 в UTC с суффиксом `Z` и точностью до микросекунд,
одинаковой при хранении и выдаче.
#### Scenario: Формат created_at
- **WHEN** клиент получает любой объект с `created_at`
- **THEN** значение оканчивается на `Z` и разбирается как RFC 3339 UTC
#### Scenario: Формат id
- **WHEN** клиент получает любой объект с `id`
- **THEN** значение — UUID в нижнем регистре
### Requirement: UUID на входе
Идентификатор, который передаёт клиент, SHALL приниматься только как
строка UUID в записи 8-4-4-4-12 (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`),
как `format: uuid` контракта. Это `chat_id` и с лабы 4
`attachment_id` в пути, элементы `member_ids` и с лабы 4 элементы
`attachment_ids` в теле. Шестнадцатеричные цифры SHALL приниматься в
любом регистре: UUID в верхнем регистре обозначает тот же
идентификатор, что в нижнем. В ответах идентификаторы остаются в нижнем
регистре (требование «Представление времени и идентификаторов»).
Значение другого типа (массив, объект, число, логическое значение, null)
и строка в другой записи (без дефисов, с префиксом `urn:uuid:`, в
фигурных скобках, с пробелами) SHALL давать 400 `invalid_request`, а не
500 и не успешный ответ. Такой запрос MUST NOT создавать объектов.
#### Scenario: UUID другого типа в теле
- **WHEN** Алиса создаёт чат, где `member_ids` содержит её id и ещё один
элемент — `[]`, `{}`, `123` или `false`
- **THEN** ответ 400 с `code` `invalid_request`, чат не появился в
списке чатов Алисы
#### Scenario: Не UUID в пути
- **WHEN** пользователь с действующей сессией запрашивает чат, историю
чата или отправляет сообщение с верным `Idempotency-Key`, а `chat_id`
в пути равен `123`, `false`, `[]` или `{}`
- **THEN** ответ 400 с `code` `invalid_request`
#### Scenario: Другая запись UUID
- **WHEN** участник передаёт id своего чата в пути или Алиса передаёт id
Боба в `member_ids`, записанный без дефисов, с префиксом `urn:uuid:`
или в фигурных скобках
- **THEN** ответ 400 с `code` `invalid_request`; ни чата, ни сообщения
не создано
#### Scenario: UUID в верхнем регистре в пути
- **WHEN** участник запрашивает свой чат, его историю и отправляет в
него сообщение, записав `chat_id` в верхнем регистре
- **THEN** ответы те же, что для `chat_id` в нижнем регистре, а
`id` и `chat_id` в них — в нижнем регистре
#### Scenario: Идентификаторы вложений в другой записи
- **WHEN** участник запрашивает метаданные и байты вложения, записав
`attachment_id` без дефисов, с префиксом `urn:uuid:` или в фигурных
скобках, и отправляет сообщение с таким элементом в `attachment_ids`
- **THEN** каждый ответ 400 с `code` `invalid_request`, сообщение не
создано
#### Scenario: Идентификаторы вложений в верхнем регистре
- **WHEN** участник запрашивает метаданные и байты вложения и
отправляет сообщение с ним, записав id вложения в верхнем регистре
- **THEN** ответы те же, что для id в нижнем регистре, а `id` и
`attachment_ids` в них — в нижнем регистре