Files
mtusi2026lab6/openspec/changes/archive/2026-10-01-postgres-storage/specs/data-storage/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

7.1 KiB
Raw Blame History

Spec Delta

ADDED Requirements

Requirement: Хранение в PostgreSQL

Пользователи, чаты, участники чатов и сообщения SHALL храниться в PostgreSQL, он — источник истины. Сервис MUST NOT хранить эти данные в памяти процесса, файлах или SQLite. Подтверждённая запись (ответ 201) SHALL быть зафиксирована в БД до ответа и видна следующему чтению.

Scenario: Созданное видно сразу

  • WHEN клиент создал пользователя и следующим запросом использует его id в X-User-Id
  • THEN пользователь найден

Requirement: Данные переживают рестарт

После перезапуска сервиса и PostgreSQL с сохранённым volume все ранее подтверждённые пользователи, чаты, участники и сообщения SHALL быть доступны в прежнем виде.

Scenario: Прежний пользователь после рестарта

  • WHEN стенд перезапущен scripts/restart.sh, и клиент использует X-User-Id, созданный до рестарта
  • THEN ответ 200, а история чата этого пользователя содержит те же сообщения в том же порядке

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

MODIFIED Requirements

Requirement: Параллельные запросы не повреждают состояние

Параллельные запросы MUST NOT терять, дублировать или повреждать записи. Уникальность username SHALL обеспечиваться ограничением БД, а не проверкой перед вставкой, поэтому одновременная регистрация одного имени создаёт ровно одного пользователя.

Scenario: 100 сообщений от 10 клиентов

  • WHEN 10 клиентов одновременно отправляют по 10 сообщений в один чат
  • THEN получено 100 ответов 201, а полный обход истории возвращает ровно 100 сообщений с уникальными id

Scenario: Гонка за username

  • WHEN несколько клиентов одновременно регистрируют одинаковый username
  • THEN создан ровно один пользователь

REMOVED Requirements

Requirement: Состояние только в памяти одного процесса

Reason: лаба 2 требует PostgreSQL как источник истины; память процесса больше не хранит данные. Migration: требование «Хранение в PostgreSQL». Сценарий «Созданное видно сразу» перенесён туда без изменений.

Requirement: Потеря состояния при рестарте

Reason: на лабе 2 подтверждённые данные обязаны переживать рестарт; пустое состояние после рестарта теперь дефект. Migration: требование «Данные переживают рестарт», сценарий «Прежний пользователь после рестарта» теперь ждёт 200.