Files
mtusi2026lab3/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 af4bca08c9 feat: carry lab 2 over and add X-Instance-Id and idempotency keys
- carry the lab 2 solution over and plan lab 3 (PLAN.md, OpenSpec
  change instance-id-idempotency)
- rename the compose project to mtusi-lab3 and the image to :lab3
- add X-Instance-Id to every response and instance_id to every log
  record ([app] instance_id, hostname by default)
- require Idempotency-Key on POST messages: keys table in Postgres,
  key and message in one transaction, replay returns the same 201,
  another body gets 409, TTL from [idempotency] ttl_seconds
- send the key from student-tests, k6 scenarios and the skill driver;
  add idempotency, X-Instance-Id, key race and fault tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-08 19:42:36 +03:00

118 lines
6.7 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 недоступен или не ответил за отведённое время,
запрос SHALL завершаться ответом 503 с `code` `unavailable` в формате
ошибки, а не 500 и не зависанием. Частично выполненная операция MUST
NOT фиксироваться. Когда PostgreSQL снова доступен, сервис SHALL
обслуживать запросы без перезапуска.
#### Scenario: БД остановлена
- **WHEN** PostgreSQL остановлен, и клиент отправляет сообщение
- **THEN** ответ 503 `unavailable` без деталей в `message`
#### Scenario: БД вернулась
- **WHEN** PostgreSQL остановлен, затем снова запущен, а сервис не
перезапускался
- **THEN** следующие запросы после готовности БД обслуживаются штатно
### Requirement: Ограниченный пул соединений и таймауты
Число соединений сервиса с PostgreSQL SHALL быть ограничено настройкой.
Ожидание свободного соединения, подключение и выполнение запроса SHALL
иметь таймауты из настроек. Истёкший таймаут SHALL давать 503
`unavailable`.
#### Scenario: Соединения исчерпаны
- **WHEN** все соединения пула заняты дольше таймаута ожидания
- **THEN** новый запрос получает 503 `unavailable` не позже этого
таймаута, а не ждёт бесконечно