Files
mtusi2026lab2/openspec/specs/lab2-persistent-storage/spec.md
T
ArtyomandClaude Opus 5.5 e4253eb076 Archive the image attachments change
Grade 3 of lab 4 is closed. RustFS with a private bucket runs in the
stand, metadata lives in PostgreSQL and the bytes only in the bucket,
uploads answer 201 ready after the object write and the commit, and
the original is served byte for byte to chat members only. The smoke
test passes from a fresh clone; limits of 10 MiB and 40 MP, content
type by content and dangerous names are covered by 325 own tests; an
upload survives the stop of the replica that took it, both replicas
fail over under writes in under 3.1 s, a full restart keeps metadata
and bytes, and with S3 stopped uploads and downloads answer 503 within
2.6 s while texts, metadata and readiness keep working. 22 checks show
the bucket is private outside the API and the API key is limited.

For the defence: upload the fixture, send it in a message, download it
as the second member and compare SHA-256, get 404 as a stranger and
403 for an anonymous GET in S3, then run persistence, failover and the
upload failover scenario.

The lab4-attachments and lab4-object-storage specs are added, and
message sending, history, idempotent replay, the restart hook and stand
persistence are updated in the main specs.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-28 22:20:38 +03:00

8.8 KiB
Raw 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 создаваться только миграциями: упорядоченными 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 первая команда ничего не выводит, вторая подтверждает, что пути игнорируются