10 KiB
lab2-persistent-storage Specification
Purpose
Определяет постоянное хранение лабы 2: схему PostgreSQL с ограничениями, версионируемые миграции, атомарность составных операций, сохранность данных и сессий при рестарте и воспроизводимый стенд из репозитория без секретов в Git.
Requirements
Requirement: Схема с ограничениями целостности
PostgreSQL SHALL хранить пользователей, сессии, чаты, участников и сообщения в отдельных таблицах с первичными ключами. Уникальность username SHALL обеспечиваться ограничением БД. Участник чата SHALL ссылаться на существующего пользователя и существующий чат, сообщение SHALL ссылаться на участника своего чата, сессия — на пользователя. Схема SHALL дублировать правила контракта проверками CHECK (формат username, длины строк).
Scenario: Ограничения видны в схеме
- WHEN оператор выполняет
\d+по таблицамusers,chat_members,messages - THEN видны
PRIMARY KEY,UNIQUE (username)и внешние ключиchat_members → users, chats,messages → chat_members
Scenario: Сообщение от постороннего не записывается даже в обход API
- WHEN в
messagesвставляется строка, отправитель которой не состоит в чате - THEN вставка отклоняется нарушением внешнего ключа
Requirement: Версионируемые миграции
Схема SHALL создаваться только миграциями Alembic: упорядоченными файлами ревизий, каждая из которых применяется в своей транзакции и записывается в журнал alembic_version. Миграции SHALL применяться одним одноразовым процессом (alembic upgrade head) до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться advisory lock. Повторный запуск SHALL NOT менять схему и данные. Журнал SHALL ссылаться на существующие ревизии каталога миграций; ссылка на отсутствующую ревизию SHALL останавливать запуск с ошибкой. Итоговая схема SHALL совпадать со схемой прежнего мигратора: те же таблицы, ограничения и индексы. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
Scenario: Миграции с пустого volume
- WHEN стенд поднимается на пустом volume PostgreSQL
- THEN one-shot сервис
migrateприменяет все ревизии по порядку и завершается кодом 0, после чего стартуют реплики API
Scenario: Повторный запуск
- WHEN процесс миграций запускается повторно на той же БД
- THEN он завершается кодом 0, таблица
alembic_versionи число строк во всех таблицах не меняются
Scenario: Схема идентична прежней
- WHEN миграции применены на чистой БД
- THEN
\d+показывает те же таблицы (users,sessions,chats,chat_members,messages,idempotency_keys), те же первичные ключи,UNIQUE (username), внешние ключи,CHECKи индексы, что и до перевода на Alembic
Scenario: Изменённая миграция
- WHEN ревизия, записанная в
alembic_version, отсутствует в каталоге миграций, и процесс миграций запущен - THEN он завершается ненулевым кодом, не применяя других ревизий
Scenario: Реплики не мигрируют схему
- WHEN стартует или перезапускается реплика API
- THEN она не применяет миграции; таблицу
alembic_versionменяет только one-shot сервисmigrate
Scenario: Одновременный запуск сериализуется
- WHEN два процесса миграций запускаются одновременно на одной БД
- THEN advisory lock пропускает их по одному, и журнал содержит каждую ревизию один раз
Scenario: Принятие существующей схемы
- WHEN БД содержит схему прежнего SQL-мигратора и известный непрерывный журнал
schema_migrations - THEN переход сверяет контрольные суммы и фактическую схему с указанными ревизиями, сохраняет все строки и старый журнал, устанавливает проверенную ревизию Alembic и применяет только недостающие ревизии
Scenario: Несогласованная старая схема
- WHEN старый журнал неизвестен, изменён или неполон либо фактическая схема расходится с ним
- THEN процесс завершается ошибкой без установки версии Alembic и изменения пользовательских данных
Requirement: Атомарное создание чата
Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся.
Scenario: Неизвестный участник откатывает чат
- WHEN
POST /api/v1/chatsсодержит вmember_idsUUID несуществующего пользователя - THEN ответ
400с кодомinvalid_request - AND в БД нет ни чата с этим
title, ни его участников
Requirement: Данные и сессии переживают рестарт
Пользователи, чаты, участники, сообщения, ключи идемпотентности и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего expires_at, а подтверждённое сообщение SHALL читаться побайтно тем же.
Scenario: Полный рестарт стенда
- WHEN выполняется
make test-persistence ACTION_SCRIPT=scripts/restart.sh - THEN hook перезапускает балансировщик, API и хранилища за ≤90 с с кодом 0, а тест печатает
PASS: persistence preserved confirmed data and existing session
Scenario: Логаут после рестарта
- WHEN после рестарта пользователь отзывает прежний токен
- THEN ответ
204, а следующий запрос с этим токеном получает401
Requirement: Воспроизводимый стенд из репозитория
Стенд SHALL подниматься из чистого clone командами репозитория: образы сторонних сервисов закреплены версией и digest, API собирается из исходников. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на 127.0.0.1 (порт HTTP и порт статистики); PostgreSQL, Valkey и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны, и SHALL NOT появляться в Git, образе и журнале.
Scenario: Подъём из чистого clone
- WHEN в чистом clone выполняются
make secretsиmake up - THEN все сервисы становятся
healthyили завершаются кодом 0, аGET /health/readyчерез балансировщик отвечает200
Scenario: Опубликован только балансировщик
- WHEN выполняется
docker compose ps --format '{{.Service}} {{.Ports}}' - THEN опубликованные порты есть только у сервиса
lbи все они привязаны к127.0.0.1
Scenario: Секреты и volumes вне Git
- WHEN выполняются
git ls-files secrets .envиgit check-ignore secrets/database_url .env - THEN первая команда ничего не выводит, вторая подтверждает, что пути игнорируются