forked from mtusi2026/mtusi2026lab5
Bring the Claude Code settings, the lint hook, the opsx commands and skills, the architecture notes, the lab 1 to lab 4 specs and the archived lab 1 to lab 4 changes into the lab 5 skeleton, so lab 5 continues the same spec history instead of starting from scratch. The files come from the lab 4 solution commit d2744bc. Rewrite AGENTS.md and the openspec context and rules for lab 5: upload answers 202 queued after the original is in a private staging prefix and the attachment, the job and the outbox row are committed in one transaction, a separate relay publishes the outbox to RabbitMQ with publisher confirms, a separate worker built from the same image consumes the queue through FastStream with a manual ack after the result commit, PostgreSQL stays the source of truth for job states, Out of scope moves to labs 6-7, track 1 and broker HA, and the rules add the failure windows between PostgreSQL and the broker, the effect key and the lease to specs and designs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
87 lines
8.8 KiB
Markdown
87 lines
8.8 KiB
Markdown
# 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 создаваться только миграциями: упорядоченными SQL-файлами, каждый из которых применяется в своей транзакции и записывается в журнал применённых версий. Миграции SHALL применяться одним одноразовым процессом до старта реплик API, а не каждой репликой; одновременный запуск двух процессов SHALL сериализоваться. Повторный запуск SHALL NOT менять схему и данные. Изменение текста уже применённой миграции SHALL останавливать запуск с ошибкой. Новая миграция SHALL быть аддитивной: работающая предыдущая версия API SHALL продолжать работать на схеме после неё.
|
||
|
||
#### Scenario: Миграции с пустого volume
|
||
|
||
- **WHEN** стенд поднимается на пустом volume PostgreSQL
|
||
- **THEN** процесс миграций применяет все версии по порядку и завершается кодом 0, после чего стартуют реплики API
|
||
|
||
#### Scenario: Повторный запуск
|
||
|
||
- **WHEN** процесс миграций запускается повторно на той же БД
|
||
- **THEN** он завершается кодом 0, журнал версий и число строк во всех таблицах не меняются
|
||
|
||
#### Scenario: Изменённая миграция
|
||
|
||
- **WHEN** текст применённой миграции изменён и процесс миграций запущен
|
||
- **THEN** процесс завершается ненулевым кодом и схему не трогает
|
||
|
||
#### Scenario: Реплики не мигрируют схему
|
||
|
||
- **WHEN** стартует или перезапускается реплика API
|
||
- **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** первая команда ничего не выводит, вторая подтверждает, что пути игнорируются
|
||
|