Files
mtusi2026lab3/openspec/specs/api-conventions/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

186 lines
10 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`, 500 — `internal_error`, 503 — `unavailable`. Метод, не
поддерживаемый путём, SHALL давать 405 с `code` `invalid_request`.
#### Scenario: Неизвестный путь
- **WHEN** клиент запрашивает `GET /api/v1/unknown`
- **THEN** ответ 404 с `code` `not_found` в формате ошибки
#### Scenario: Неподдерживаемый метод
- **WHEN** клиент выполняет `DELETE /api/v1/users`
- **THEN** ответ 405 с `code` `invalid_request` в формате ошибки
### 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 в нижнем регистре