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

8.8 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 недоступен, отказывает в новом подключении из-за предела соединений (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 за время пачек не принимает от сервиса ни одного нового соединения