Files
mtusi2026lab4/openspec/specs/lab2-persistent-storage/spec.md
T

117 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются