- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
8.8 KiB
Markdown
146 lines
8.8 KiB
Markdown
# 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`.
|
||
|
||
Пул SHALL держать постоянный набор соединений. Соединение, возвращённое
|
||
в пул после запроса, SHALL оставаться открытым и обслуживать следующие
|
||
запросы. При настройках по умолчанию соединений сверх размера пула
|
||
сервис MUST NOT открывать. Запрос, которому не хватило свободного
|
||
соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания,
|
||
а не открывать новое соединение с PostgreSQL. Новое соединение сервис
|
||
открывает, только пока пул не набрал своего размера, и взамен
|
||
соединения, закрытого после обрыва или отказа.
|
||
|
||
#### Scenario: Соединения исчерпаны
|
||
|
||
- **WHEN** все соединения пула заняты дольше таймаута ожидания
|
||
- **THEN** новый запрос получает 503 `unavailable` не позже этого
|
||
таймаута, а не ждёт бесконечно
|
||
|
||
#### Scenario: Соединения пула не переоткрываются
|
||
|
||
- **WHEN** пул прогрет, и сервису раз за разом приходят пачки
|
||
одновременных запросов, которых больше, чем соединений в пуле
|
||
- **THEN** все запросы пачек обслуживаются успешно
|
||
- **AND** PostgreSQL за время пачек не принимает от сервиса ни одного
|
||
нового соединения
|