Files
mtusi2026lab2/REPORT.md
T
koichakaev 5b47c579cc
Skeleton contracts / contracts (pull_request) Canceled after 0s
Skeleton contracts / application (pull_request) Canceled after 0s
ЛР 2: PostgreSQL, сессии, Valkey и исследование восстановления
2026-10-30 21:03:37 +03:00

12 KiB
Raw Blame History

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

  • Автор, группа: Койчакаев Багавдин, БВТ2301.
  • Целевая оценка: 5; трек: 2 — план запроса и восстановление.
  • Ветка решения: solution/bvt2301-koichakaev, от master skeleton (65003b61195361aac238f19c9bff0027ca58e09e).
  • Fork: https://gitea.privcloud.tech/koichakaev/mtusi2026lab2; ссылка на PR добавляется после его создания.
  • Использованные источники, библиотеки и помощь ИИ: контракт и материалы курса; Python 3.12.8, psycopg 3.2.3, argon2-cffi 23.1.0, redis-py 5.2.1; при подготовке использовался Codex.

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

Требуются Docker Compose v2 и свободный локальный порт 8080. Скопировать .env.example в .env, заменить локальный POSTGRES_PASSWORD, затем:

cp .env.example .env
# Заменить POSTGRES_PASSWORD в .env на локальный пароль.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 180
docker compose --env-file .env ps
make check
make test BASE_URL=http://127.0.0.1:8080
make track2
make quality BASE_URL=http://127.0.0.1:8080
make test-dependencies BASE_URL=http://127.0.0.1:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080

Схема накатывается при старте API и отмечается в schema_migrations; повторный запуск не пересоздаёт таблицы. Стек использует python:3.12.8-slim-bookworm с digest, PostgreSQL 16.4-bookworm и Valkey 8.0.1-alpine; все Python-зависимости закреплены в requirements.txt. Остановка без удаления данных: docker compose --env-file .env stop. Для короткого TTL временно установить SESSION_TTL_SECONDS=2, пересоздать API (docker compose --env-file .env up -d --force-recreate api) и выполнить make test-ttl; после проверки вернуть TTL не менее 300 секунд. Удаление учебных данных выполняется только отдельной явной командой docker compose --env-file .env down -v.

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

Из собственной lab1 сохранены HTTP API пользователей, чатов и сообщений, проверки входных данных, членства, пагинация и health endpoints. Хранилище заменено на PostgreSQL; вместо X-User-Id используется объявленный в lab2 переход на Basic/Bearer. Собственные дополнительные проверки находятся в student-tests/, исходные tests/, contracts/, README.md и COURSE.md сохранены без изменений. Файл .github/workflows/contracts.yml дополнен отдельным application job для сборки Compose, ожидания готовности и публичного smoke на одноразовом GitHub-hosted runner; локальные результаты приведены независимо от наличия CI на Gitea.

Схема: HTTP API → PostgreSQL; API также использует Valkey для TTL-кэша сессий. Источник истины для пользователей, чатов, membership, сообщений и сессий — PostgreSQL. Valkey хранит только короткоживущую связь хеша opaque-токена с user ID. PostgreSQL проверяет сессию при каждом запросе, поэтому logout отзывается и при недоступном Valkey; при отказе Valkey используется путь через PostgreSQL.

Пароли хешируются Argon2id через argon2-cffi; клиент получает случайный Bearer-токен с энтропией 256 бит, в PostgreSQL хранится только SHA-256 токена. Истёкшие токены отвергаются по expires_at. Бизнес-запросы принимают только Bearer; X-User-Id игнорируется. Пользователь, чат и его membership создаются транзакционно. История использует параметризованный keyset SQL по (created_at,id) и составной индекс messages_history_keyset; pool ограничен DB_POOL_MAX, ожидание соединения ограничено 3 секундами.

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

Критерий Команда Наблюдаемый результат
Структура и контракт make check; docker compose --env-file .env config --quiet PASS
Публичный smoke make test BASE_URL=http://127.0.0.1:8080 PASS: lab2 public API scenario
Сохранность make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080 PASS: подтверждённые данные и сессия пережили рестарт API, PostgreSQL и Valkey с сохранёнными volumes
Гонки и транзакции make quality BASE_URL=http://127.0.0.1:8080 PASS: 1×201 и 11×409 при 12 одинаковых регистрациях; невалидное создание чата не оставило строку
План истории make quality после make track2 PASS: Index Only Scan using messages_history_keyset, 50 строк, 0,046 ms на таблице с 100k+ сообщений
Истечение и logout make test; make test-ttl при TTL=2 PASS: неверный пароль и logout проверены smoke; токен отвергнут после 2,2 s
Отказы зависимостей make test-dependencies BASE_URL=http://127.0.0.1:8080 PASS: Valkey outage использовал PostgreSQL; PostgreSQL outage вернул 503 и восстановился с той же сессией
Трек 2 make track2 PASS: 100k skewed сообщений, два индекса, три парных write trials и restore в отдельный PostgreSQL с отдельным volume; подробности в evidence/track2-results.json

Эксперимент: план запроса и восстановление

Гипотеза: индекс A (chat_id,created_at,id) будет компактнее; вариант B (chat_id,created_at DESC,id DESC) INCLUDE(sender_id) может снизить чтение страниц. B меняет направление сортировки двух ключей и добавляет sender_id: сравнение относится к двум вариантам в целом, а не к изолированному эффекту INCLUDE. Seed создаёт 100 000 синтетических сообщений: 80 000 в одном чате и 20 000 в 200 малых чатах, по 100 в каждом. Длина текста меняется от 40 до 199 символов. Детерминированные UUID и ON CONFLICT делают повторный запуск seed безопасным.

Для каждого индекса запускается одинаковый keyset-запрос на 50 строк с границей внутри большого чата. Затем проводятся три парных записи по 10 000 строк: каждый замер начинается с копии той же 100k таблицы, порядок A/B чередуется, построение индекса исключено из времени. PostgreSQL EXPLAIN ANALYZE измеряет исполнение вставки на стороне сервера. После этого pg_dump -Fc восстанавливается в отдельный PostgreSQL service с отдельным persistent volume restore_data; проверяются количества строк и первые десять выбранных benchmark-сообщений.

Среда: Docker Desktop 29.8.2, ARM64; Docker VM выделены 8 CPU и 4 106 604 544 байт RAM (около 3,82 GiB), отдельные container CPU/RAM limits не заданы. Runtime: Python 3.12.8, PostgreSQL 16.4, Valkey 8.0.1. План каждого индекса измерен один раз после seed и ANALYZE, без отдельного прогрева, поэтому различия в десятках микросекунд не считаются устойчивым выигрышем. Для write cost приведена медиана трёх парных повторов.

Результаты финального запуска, записанные в evidence/track2-results.json (для чтения указано Actual Total Time узла Limit; для записи — Execution Time):

  • A выбрал Index Scan Forward: 0,04 ms, shared hit=3, read=3; размер 5776 kB.
  • B выбрал Index Scan Backward: 0,029 ms, shared hit=4, read=4; размер 7544 kB (+30,6%). Запрос выбирает text, поэтому INCLUDE(sender_id) не устраняет heap access и не даёт index-only scan. Единичные измерения не доказывают устойчивый выигрыш чтения.
  • Медиана вставки 10k: A — 25,63 ms; B — 22,507 ms (-12.2%). На этих данных B увеличил размер индекса; трёх повторов недостаточно, чтобы отделить влияние индекса на время записи от шума среды. Для данного запроса выбран компактный индекс A.
  • Backup занял 0,556 s и 6,882,247 bytes; restore — 0,608 s. В обеих БД совпали количества: 53 users, 214 chats, 227 chat_members, 100015 messages, 42 sessions. Первые десять выбранных synthetic messages совпали.

Ограничения

Стенд использует HTTP и предназначен для loopback и синтетических данных. Репликация и failover не заявлены. Backup восстановлен в отдельный контейнер и volume того же Docker Desktop host; отказ всего host не моделировался, поэтому результаты не задают disaster recovery RPO/RTO. Плановые timings единичные, write trials — три; значения зависят от диска, CPU, RAM и прогрева PostgreSQL.

pg_dump фиксирует согласованный снимок БД: подтверждённые изменения после момента снимка в эту копию не попадут. Без архивирования WAL/PITR восстановление возможно только на момент последнего сохранённого backup; потенциальная потеря данных равна интервалу между его снимком и отказом. В эксперименте параллельная запись во время backup не выполнялась, поэтому сверка относится к неподвижному набору данных. Измеренные 0,608 s включают исполнение pg_restore, но не обнаружение аварии, передачу backup и подготовку нового сервера. Для отказа всего host копию нужно хранить отдельно от Docker Desktop.

Сводка полного прогона: evidence/lab2-run.txt. Исходные планы и измерения: evidence/track2-results.json. Вывод финальной проверки перед публикацией: evidence/submission-checks.txt.