Files
mtusi2026lab4/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 5d5d8f9d2a chore: carry lab 3 over
- 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>
2026-10-20 17:32:33 +03:00

146 lines
8.8 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`.
Пул SHALL держать постоянный набор соединений. Соединение, возвращённое
в пул после запроса, SHALL оставаться открытым и обслуживать следующие
запросы. При настройках по умолчанию соединений сверх размера пула
сервис MUST NOT открывать. Запрос, которому не хватило свободного
соединения, SHALL ждать его в очереди пула не дольше таймаута ожидания,
а не открывать новое соединение с PostgreSQL. Новое соединение сервис
открывает, только пока пул не набрал своего размера, и взамен
соединения, закрытого после обрыва или отказа.
#### Scenario: Соединения исчерпаны
- **WHEN** все соединения пула заняты дольше таймаута ожидания
- **THEN** новый запрос получает 503 `unavailable` не позже этого
таймаута, а не ждёт бесконечно
#### Scenario: Соединения пула не переоткрываются
- **WHEN** пул прогрет, и сервису раз за разом приходят пачки
одновременных запросов, которых больше, чем соединений в пуле
- **THEN** все запросы пачек обслуживаются успешно
- **AND** PostgreSQL за время пачек не принимает от сервиса ни одного
нового соединения