Files
mtusi2026lab2/openspec/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 ae4154eaf5 feat: add password login and bearer sessions
- Argon2id password hashes, KDF in a thread with its own limit
- POST /auth/sessions with Basic, DELETE /auth/sessions/current
- Bearer sessions in PostgreSQL, X-User-Id ignored
- migration drops lab 1 data without passwords
- student-tests on tokens, sessions spec and synced specs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-01 18:50:42 +03:00

6.7 KiB
Raw Blame History

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 не позже этого таймаута, а не ждёт бесконечно