# 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 создаваться версионируемыми миграциями, каждая в своей транзакции. Одноразовый процесс `migrate` SHALL завершаться до старта API; одновременные запуски SHALL сериализоваться. Повторный запуск SHALL NOT менять данные. При переходе со старого SQL-журнала процесс SHALL проверить контрольные суммы и фактическую схему до принятия версии. Неизвестная или изменённая история SHALL останавливать запуск без изменения пользовательских данных. Аддитивные изменения SHALL сохранять совместимость с предыдущей версией приложения. Основание: обязательное постоянное хранение и сохранение lab1–lab4 в README. #### Scenario: Миграции с пустого volume - **WHEN** стенд запускается с пустой PostgreSQL - **THEN** все миграции применяются по порядку, migrate завершается кодом 0 и запускается API #### Scenario: Повторный запуск - **WHEN** migrate повторно запускается на той же БД - **THEN** он завершается кодом 0 без изменения пользовательских строк #### Scenario: Переход старого стенда ЛР5 - **WHEN** БД содержит проверенный SQL-журнал ЛР5, вложения, задания, outbox и варианты - **THEN** переход сохраняет строки, ограничения, состояния и ссылки на объекты #### Scenario: Изменённая миграция - **WHEN** контрольная сумма SQL-журнала или фактическая схема не совпадает с ожидаемой - **THEN** принятие истории завершается ошибкой без изменения данных и отметки версии #### Scenario: Реплики не мигрируют схему - **WHEN** стартует реплика API, relay или worker - **THEN** только отдельный процесс migrate изменяет журнал миграций ### Requirement: Атомарное создание чата Создание чата SHALL записывать чат и всех его участников в одной транзакции. Если хотя бы одна запись нарушает ограничение, транзакция SHALL откатываться целиком: ни строки чата, ни строк участников не остаётся. #### Scenario: Неизвестный участник откатывает чат - **WHEN** `POST /api/v1/chats` содержит в `member_ids` UUID несуществующего пользователя - **THEN** ответ `400` с кодом `invalid_request` - **AND** в БД нет ни чата с этим `title`, ни его участников ### Requirement: Данные и сессии переживают рестарт Пользователи, чаты, участники, сообщения со ссылками на вложения, ключи идемпотентности, метаданные вложений, их байты в bucket и ещё действующие сессии SHALL сохраняться при перезапуске балансировщика, всех реплик API и всех хранилищ, включая S3, с сохранёнными volumes. После рестарта прежний токен SHALL работать до своего прежнего `expires_at`, подтверждённое сообщение SHALL читаться побайтно тем же, а загруженное вложение 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 собирается из исходников, bucket и доступ к нему создаёт одноразовый bootstrap. Процессы сервисов SHALL работать не от root, у каждого долгоживущего сервиса SHALL быть healthcheck и лимиты CPU и памяти. Наружу SHALL публиковаться только балансировщик на `127.0.0.1` (порт HTTP и порт статистики); PostgreSQL, Valkey, S3 и реплики API SHALL NOT публиковать порты. Учётные данные SHALL передаваться файлами compose secrets из каталога, исключённого из Git, только тем сервисам, которым они нужны (root-ключи S3 — только S3-сервисам), и SHALL NOT появляться в Git, образе и журнале. #### Scenario: Подъём из чистого clone - **WHEN** в чистом clone выполняются `make secrets` и `make up` - **THEN** все сервисы становятся `healthy` или завершаются кодом 0 (`migrate`, `s3-init`), а `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 secrets/s3_root_password .env` - **THEN** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются