Files

12 KiB
Raw Permalink Blame History

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 и изменения пользовательских данных

Scenario: Принятие старой схемы вложений

  • WHEN процесс миграций запускается на схеме ЛР4 с журналом 0001–0004 и данными вложений
  • THEN он проверяет контрольные суммы и фактическую схему, принимает её без перезаписи данных, сохраняет связи сообщений и карантин, а повторный запуск ничего не меняет

Scenario: Неизвестная или повреждённая схема вложений

  • WHEN журнал или схема вложений отличается от поддерживаемой версии
  • THEN миграция завершается ошибкой до принятия версии и сохраняет данные

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