Files
mtusi2026lab2/REPORT.md
T
R0flyan e33d1298ba
Skeleton contracts / contracts (pull_request) Canceled after 0s
update REPORT.md
2026-10-16 15:27:03 +03:00

19 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Максим Ситосенко, БВТ2303.
  • Целевая оценка: 5, трек 2 — план запроса и восстановление.
  • Commit/PR: ветка solution/bvt2303-sitosenko; основа skeleton: 65003b6.
  • Источники: PostgreSQL, Valkey AOF, Argon2id, pg_dump / pg_restore. Библиотеки: pgx/v5 5.7.6, go-redis/v9 9.12.1, x/crypto 0.43.0; полный lock — go.sum. Codex использован для переноса реализации, тестов, проверки стенда и отчёта.

Запуск из чистого clone

Нужны Git, Docker с Linux-контейнерами и Compose v2+, Python 3.9+, GNU make. Сборка: Go 1.26.0; PostgreSQL 17.6; Valkey 8.1.3. Образы закреплены digest, runtime API — scratch, UID 65532. Локальный Go нужен только для Go-тестов. Команды ниже рассчитаны на fork после публикации файлов решения.

git clone https://gitea.privcloud.tech/Roflyan/mtusi2026lab2-fork.git
cd mtusi2026lab2-fork
python3 -X utf8 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
curl -f http://127.0.0.1:8080/health/ready
make check
make test BASE_URL=http://127.0.0.1:8080
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
make test-own BASE_URL=http://127.0.0.1:8080
make test-infra BASE_URL=http://127.0.0.1:8080
make explain
make research

Bootstrap создаёт .env и случайные секреты в secrets/, существующие значения сохраняет. Миграции применяются API при старте; повтор вручную: docker compose run --rm --no-deps api migrate. Не удалять секреты при сохранённых volumes: пароль БД и ключ курсора должны оставаться прежними.

Windows: использовать python -X utf8 вместо python3; перед make задать $env:PYTHONUTF8="1". Без локального make/GCC:

docker build -f Dockerfile.tests -t mtusi-messenger:lab2-tests .
python -X utf8 scripts/linux_tests.py check
python -X utf8 scripts/linux_tests.py test
python -X utf8 scripts/linux_tests.py test-persistence
python -X utf8 scripts/linux_tests.py test-own
python -X utf8 scripts/linux_tests.py test-race
python -X utf8 student-tests/infrastructure.py
python -X utf8 student-tests/explain.py
python -X utf8 student-tests/research.py

Linux-runner выполняет исходные make targets; для persistence получает Docker socket и запускает тот же scripts/restart.sh. Инфраструктурные тесты выполнять последовательно, без параллельных пользователей стенда. Порты 8080 и 18082 свободны. Research запускается отдельно, ему нужен только Docker: два временных PostgreSQL без сети, каждый с новым volume, 2 CPU и 512 MiB. После проверки они удаляются, dump остаётся в игнорируемой папке backups/.

Безопасная остановка: docker compose down — volumes остаются. Повторный запуск: docker compose up -d --build --wait. Намеренное удаление всех учебных данных и сессий: docker compose down -v. Локальные секреты эта команда не удаляет. Команды ручной диагностики, полной валидации OpenAPI и сохранения вывода — в памятке проверок.

Архитектура и решения

Клиент → Go API → PostgreSQL (пользователи, чаты, участники, сообщения) и Valkey (единственный источник сессий). Из lab1 перенесены API, Unicode-валидация, проверка членства, подписанный cursor и graceful shutdown. Память процесса заменена PostgreSQL; X-User-Id игнорируется, бизнес-запросы требуют Bearer. Схема, выбранная до реализации запросов, сведена сюда: users — PK id, UNIQUE username; chats — PK id; chat_members — PK (chat_id, user_id) и FK на чат/пользователя; messages — PK id, FK на чат и составной FK (chat_id, sender_id) на членство. Индексы списка чатов: chat_members(user_id, chat_id), chats(created_at, id). Миграции встроены в бинарник: версия и checksum в schema_migrations, advisory lock от параллельного запуска, каждый файл — отдельная транзакция. Свободные строки хранятся в UTF-8 bytea: это сохраняет в том числе U+0000, который PostgreSQL text не принимает; длину в code points проверяет API.

Регистрация защищена UNIQUE username, создание чата и участников — общей транзакцией и FK. Сообщение подтверждается после COMMIT; чтения идут в PostgreSQL без кэша, Read Committed, synchronous_commit=on. Индекс (chat_id, created_at, id) обслуживает keyset-пагинацию с LIMIT limit+1. SQL параметризован, пул БД ограничен 8 соединениями; timeout запроса 5с, SQL 3с. При SIGTERM API прекращает приём и завершает запросы до 8с.

Пароли: Argon2id, случайная соль, 64 MiB / 3 прохода / 1 поток. Basic используется только для входа. Bearer — случайные 256 бит; Valkey хранит SHA256 токена, владельца и абсолютный expiry. TTL не продлевается чтением или restart; logout удаляет ключ. AOF appendfsync always, volume и noeviction сохраняют сессии. Отказ любой зависимости даёт 503; без сессии — 401. Readiness зависит от обоих хранилищ, liveness — только от API. Логи не содержат тела, пароли или токены.

.env.example: APP_HOST — bind API; APP_PORT — опубликованный порт (в контейнере 8080); APP_ENV — метка логов; SESSION_STORE допускает valkey; SESSION_TTL_SECONDS — TTL; DB_POOL_MAX / MAX_INFLIGHT — лимиты; *_FILE — пути смонтированных secrets. Максимум два одновременных KDF, тело запроса ограничено 128 KiB. Дополнительные ответы: 413 при большом теле, 503 при перегрузке или недоступности зависимости, с общим форматом ошибки.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Неизменность skeleton git diff --exit-code 65003b6 -- contracts tests (полная команда в памятке) 17 обязательных файлов совпадают; публичные make targets сохранены source-check.txt, хеши
Offline и публичный API make check, make test PASS check.txt, smoke.txt
Перенос lab1 make test-own JSON, Unicode, членство, пагинация; 100/100 уникальных сообщений own.txt
PostgreSQL, миграции с нуля clone → bootstrap → docker compose up -d --build --wait → make test Первичная сборка отдельного локального clone на новых volumes прошла clean-build.txt
Данные и сессии переживают restart make test-persistence ACTION_SCRIPT=scripts/restart.sh Старый токен читает прежнее сообщение persistence, до, после
Миграции повторяемы, чат атомарен make test-infra Два повтора без изменения данных; FK-ошибка не оставляет чат/участников infrastructure.json
KDF, Basic/Bearer, logout make test-own Неверный пароль и X-User-Id не дают доступ; logout → 401 own.txt
Valkey TTL и persistence make test-infra, persistence TTL=2с → 401; отозванная сессия не оживает после restart infrastructure.json
SQL, пул, гонка регистрации make test-own; ревью store.go/main.go Параметры отдельно от SQL; пул 8; 1×201 и 9×409 own.txt
Индекс на ≥10 000 сообщениях make explain Index Scan, 51 строка; нет Seq Scan/Sort explain.txt
Отказ PostgreSQL/Valkey make test-infra Ограниченные 503; anonymous 401; восстановление без потери infrastructure.json
Конкурентность и завершение make test-race, make test-infra Race detector пройден; SIGTERM завершился с кодом 0 race.txt, infrastructure.json
Контейнер и секреты docker inspect, git check-ignore (команды в памятке) UID 65532, readonly, healthy; фактический AOF always; секреты исключены audit.json
Трек 5: индексы и стоимость записи make research 100 000 сообщений, 3 размера чатов, два индекса, 3 повтора исходные замеры, планы
Трек 5: backup/restore make research Новый volume: совпали счётчики, 11 сообщений и SHA-256 всей истории research.json

clean-build.txt, audit.json и source-manifest.json — результаты первичной проверки. Служебные генераторы этих доказательств удалены при упрощении проекта; повторять проверки можно обычными командами из отчёта и памятки.

Эксперименты и отказы

Гипотеза трека 2: индекс (chat_id, created_at, id) сокращает чтение страницы большого чата по сравнению с (chat_id), но занимает больше места и требует дополнительной работы при записи. Методика: python -X utf8 student-tests/research.py.

Стенд: PostgreSQL 17.6, Docker Desktop 4.66.0 / Engine 29.3.0, Linux/amd64, 12 доступных CPU и 3.68 GiB RAM. Данные синтетические: 100 000 сообщений в чатах 80 000 / 15 000 / 5 000, включая Unicode и байт U+0000. Источнику и восстановленной БД выделены отдельные новые volumes, по 2 CPU / 512 MiB, сеть отключена. Основной Compose-стенд не участвует в эксперименте.

Сравниваются два индекса при неизменных PK/FK и запросе API: фильтр по чату и (created_at,id), сортировка по этой паре, LIMIT 51. Три повтора с порядком AB / BA / AB; перед каждой вставкой таблица очищается, индекс создаётся заново. После INSERT 100 000 строк выполняется ANALYZE. Чтение: 3 прогрева и 20 замеров на случай в каждом повторе; один клиент, тёплый кэш, без parallel query и JIT. EXPLAIN фиксирует исполнение, buffers и WAL; выбор индекса не форсируется.

Метрика (chat_id) (chat_id, created_at, id)
Большой чат, первая страница: p50 / p95 / p99, мс 25.392 / 27.725 / 31.140 0.036 / 0.069 / 0.087
Большой чат, после 70 000: p50 / p95 / p99, мс 8.729 / 9.807 / 14.786 0.035 / 0.072 / 0.084
Малый чат, после 4 000: p50 / p95 / p99, мс 0.651 / 0.755 / 0.945 0.379 / 0.665 / 0.971
INSERT 100 000: медиана исполнения, мс 1071.7 1166.0
Размер исследуемого индекса, MiB 0.63 6.54
WAL при вставке: медиана, MiB 39.96 43.61
Shared buffers глубокой страницы: медиана 2856 6

В большом чате простой индекс приводит к Seq Scan + Sort, составной — к Index Scan с чтением 51 строки. Для малого чата планировщик выбирает Bitmap Scan + Sort: выигрыш меньше, p99 в этом прогоне немного выше. Составной индекс занимает в 10.3 раза больше места; медиана записи выше на 8.8%, WAL — на 9.1%. Разброс трёх вставок перекрывается: устойчивый размер надбавки не доказан. Для API сохранён составной индекс, уже реализованный в миграции 001.

Восстановление: pg_dump -Fc создаёт согласованный backup, pg_restore восстанавливает его во второй контейнер с новым пустым volume (до restore — 0 public-таблиц). Совпали: users=1, chats=3, members=3, messages=100 000, migrations=2, размеры чатов, 11 выбранных сообщений и SHA-256 потока всей истории в порядке id. Dump: 2.89 MiB, создание 0.58с; pg_restore — 1.16с; от старта новой БД до завершения проверки — 6.65с. Старт API в это время не входит.

После dump в источнике отдельно зафиксирована ещё одна запись: там 100 001 строка, после восстановления — 100 000, новой записи нет. Backup сохраняет состояние снимка; последующие COMMIT без WAL-архива/PITR не восстановятся. Фиксированный RPO не заявлен, расписание backup не реализовано. Сессии Valkey в этот dump не входят.

Raw: research.csv; сводка/сверка: research.json; планы: research-plans.txt. Это SQL-эксперимент: Execution Time не включает planning, Docker и COMMIT; полное время вставки с COMMIT/Docker отдельно записано в CSV. HTTP RPS и CPU/RSS не измерялись. Для чтений по 60 замеров; p99 близок к максимуму и не является SLA. Планы получены с конкретными параметрами; generic plans подготовленных запросов pgx могут отличаться. Данные умещаются в RAM, холодный диск не исследовался.

Проверки уровня 4 сохранены отдельно в student-tests/infrastructure.py:

Воздействие Ожидание Наблюдение Восстановление / потеря данных
Restart API+БД+Valkey Старый токен и сообщение сохранены Публичный persistence PASS В пределах 90с теста / потерь проверяемых данных нет
Остановка PostgreSQL Ограниченный 503, anonymous 401 503 за 5.00–5.03с Готовность после start ≈1.53с / сообщение сохранено
Остановка Valkey 503 без обхода авторизации 503 за 1.02–1.03с Готовность после start ≈0.25с / токен сохранён
TTL=2с; logout + restart Недействительный токен → 401 Оба сценария прошли Переписка сохранена
Ошибка участника Полный rollback Счётчики до/после равны Частичных данных нет

Ограничения и следующие шаги

Одна БД и один Valkey, без HA. Backup/restore проверен локально на синтетической БД; автоматического расписания, внешнего хранения backup и PITR нет. Потеря volumes уничтожает данные, не попавшие в backup; восстановление Valkey отдельно не исследовалось. HTTP предназначен для локального стенда; удалённому нужен TLS. Cursor не даёт snapshot между страницами: поздняя вставка или коррекция часов может поместить запись перед пройденной границей. Эксперимент с тёплым кэшем и одним клиентом не доказывает устойчивость под длительной конкурентной нагрузкой.