Files
mtusi2026lab3/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 68edc66742 fix: answer 503 when PostgreSQL refuses connections with too many clients
SQLSTATE 53300 (too_many_connections) joins UNAVAILABLE_SQLSTATES, so a
refused pool connection gives 503 unavailable instead of 500. New fault
check fills max_connections through the failure stand hook and expects
503 in the contract format.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 07:26:36 +03:00

129 lines
7.4 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.
# data-storage Specification
## Purpose
Где живут данные мессенджера с лабы 2 и какие гарантии они дают:
PostgreSQL как источник истины, сохранность после рестарта, целостность
и транзакции на стороне БД, поведение при недоступности БД и
ограниченные ресурсы подключения.
## Requirements
### Requirement: Хранение в PostgreSQL
Пользователи, чаты, участники чатов, сообщения и сессии SHALL храниться
в PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные
в памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201
или 204) SHALL быть зафиксирована в БД до ответа и видна следующему
запросу.
#### Scenario: Созданное видно сразу
- **WHEN** клиент зарегистрировался и следующим запросом входит с теми
же username и паролем
- **THEN** вход успешен, и `GET /api/v1/users/me` с выданным токеном
возвращает этого пользователя
### Requirement: Данные переживают рестарт
После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее
подтверждённые пользователи, чаты, участники и сообщения SHALL быть
доступны в прежнем виде.
#### Scenario: Прежний пользователь после рестарта
- **WHEN** стенд перезапущен `scripts/restart.sh`, и клиент использует
токен, полученный до рестарта
- **THEN** ответ 200, а история чата этого пользователя содержит те же
сообщения в том же порядке
### Requirement: Параллельные запросы не повреждают состояние
Параллельные запросы MUST NOT терять, дублировать или повреждать
записи. Уникальность `username` SHALL обеспечиваться ограничением БД,
а не проверкой перед вставкой, поэтому одновременная регистрация
одного имени создаёт ровно одного пользователя.
#### Scenario: 100 сообщений от 10 клиентов
- **WHEN** 10 клиентов одновременно отправляют по 10 сообщений в один
чат
- **THEN** получено 100 ответов 201, а полный обход истории возвращает
ровно 100 сообщений с уникальными `id`
#### Scenario: Гонка за username
- **WHEN** несколько клиентов одновременно регистрируют одинаковый
`username`
- **THEN** создан ровно один пользователь
### Requirement: Целостность данных в БД
Ограничения SHALL проверяться самой БД, а не только сервисом:
уникальность `username`, существование пользователей и чатов, на
которые ссылаются участники и сообщения, уникальность участника в
чате, членство отправителя в чате сообщения. Порядок `member_ids`,
заданный при создании чата, SHALL сохраняться.
#### Scenario: Порядок участников
- **WHEN** чат создан с `member_ids` в порядке `[bob, alice]`
- **THEN** `GET` этого чата и список чатов возвращают `member_ids` в
том же порядке, в том числе после рестарта стенда
### Requirement: Составная операция в одной транзакции
Создание чата вместе с участниками SHALL выполняться одной
транзакцией: при ошибке на любом шаге в БД MUST NOT остаться ни чата,
ни части его участников.
#### Scenario: Сбой при добавлении участников
- **WHEN** чат уже записан в транзакции, а запись участников
завершается ошибкой
- **THEN** транзакция откатывается, чата нет ни в `GET` по его `id`, ни
в списках чатов участников
### Requirement: Недоступность PostgreSQL
Если PostgreSQL недоступен, отказывает в новом подключении из-за
предела соединений (`max_connections`) или не ответил за отведённое
время, запрос SHALL завершаться ответом 503 с `code` `unavailable` в
формате ошибки, а не 500 и не зависанием. Частично выполненная операция
MUST NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
обслуживать запросы без перезапуска.
#### Scenario: БД остановлена
- **WHEN** PostgreSQL остановлен, и клиент отправляет сообщение
- **THEN** ответ 503 `unavailable` без деталей в `message`
#### Scenario: БД вернулась
- **WHEN** PostgreSQL остановлен, затем снова запущен, а сервис не
перезапускался
- **THEN** следующие запросы после готовности БД обслуживаются штатно
#### Scenario: Предел соединений PostgreSQL исчерпан
- **WHEN** все слоты `max_connections` PostgreSQL заняты, и пулу
сервиса для запроса нужно новое соединение
- **THEN** PostgreSQL отказывает в подключении («too many clients»,
SQLSTATE `53300`), а клиент получает 503 `unavailable` без деталей в
`message`, а не 500
- **AND** после освобождения слотов запросы обслуживаются без
перезапуска сервиса
### Requirement: Ограниченный пул соединений и таймауты
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
Ожидание свободного соединения, подключение и выполнение запроса SHALL
иметь таймауты из настроек. Истёкший таймаут SHALL давать 503
`unavailable`.
#### Scenario: Соединения исчерпаны
- **WHEN** все соединения пула заняты дольше таймаута ожидания
- **THEN** новый запрос получает 503 `unavailable` не позже этого
таймаута, а не ждёт бесконечно