Files
mtusi2026lab2/REPORT.md

21 KiB
Raw Permalink Blame History

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

  • Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
  • Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Уровни 3 и 4 и выбранный трек 5 проверены на локальном стенде.
  • Ветка: solution/bpi2302-samohvalov; commit/PR указываются после публикации.
  • Источники: README.md, COURSE.md, contracts/README.md, contracts/openapi.json, публичные тесты и примеры этого репозитория; FastAPI, psycopg, PostgreSQL и Argon2id. Код и инструкции подготовлены с помощью ИИ Codex и проверяются запуском команд ниже.

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

Нужны Docker с Compose, Python 3.9+ и make. Стенд рассчитан на учебный localhost. API собирается из исходников в python:3.12.12-slim-bookworm; БД — postgres:17.6-bookworm, кэш — valkey/valkey:8.0.2-alpine. Python-зависимости закреплены в requirements.txt; кэш использует короткий RESP-клиент стандартной библиотеки. Порт API опубликован только на 127.0.0.1:8080; PostgreSQL и Valkey наружу не публикуются. На моей macOS с Colima команды make test и make test-persistence выполнялись на хосте с разрешённым доступом к Docker socket и loopback. В ограниченном sandbox 127.0.0.1:8080 был недоступен; проверка не запускалась внутри VM и SSH-туннель не требовался.

После чистого clone создать локальные файлы, которые исключены из Git:

cp .env.example .env
mkdir -p secrets
python3 - <<'PY'
from pathlib import Path
from secrets import token_urlsafe

password = token_urlsafe(32)
Path('secrets/postgres_password').write_text(password)
Path('secrets/database_url').write_text(
    f'postgresql://messenger:{password}@postgres:5432/messenger'
)
PY
chmod 600 .env secrets/*
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-level4
docker compose --env-file .env exec -T api python - < scripts/track2_experiment.py > evidence/query-comparison.csv 2> evidence/query-plans.txt
bash scripts/backup_restore.sh > evidence/restore-check.txt

На каждом старте API выполняет scripts/migrate.py под advisory lock: миграции 001 и 002 применяются только один раз и завершаются до приёма запросов. docker compose --env-file .env exec -T api python scripts/migrate.py безопасно повторить вручную. GET /health/ready требует доступную БД. docker compose --env-file .env down останавливает стенд с сохранением именованного volume. Только для намеренного уничтожения учебных данных: docker compose --env-file .env down -v.

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

Клиент → FastAPI (api) → PostgreSQL (postgres) и необязательный Valkey (valkey); postgres_data сохраняет состояние между перезапусками. PostgreSQL — источник истины для users, chats, memberships, messages и sessions. Создание чата с участниками выполняется одной транзакцией. Пароль хранится как Argon2id hash, непрозрачный токен выдаётся только клиенту, в БД лежит его SHA-256 и абсолютный срок действия. Из lab1 сохранены чаты, членство, сообщения и keyset-пагинация; X-User-Id заменён входом по Basic и запросами по Bearer. .env.example задаёт опубликованный APP_PORT и SESSION_TTL_SECONDS; DATABASE_URL_FILE, VALKEY_URL, APP_HOST и порт внутри контейнера установлены Compose. Pool ограничен восемью соединениями и SQL timeout 5 секунд.

Каждый Bearer-запрос проверяет hash, срок и отзыв сессии в PostgreSQL. После этого публичная проекция User читается по UUID из Valkey с TTL 60 секунд; на промахе или отказе кэша читается PostgreSQL. После регистрации создаётся новый UUID; endpoint изменения/удаления пользователя в lab2 нет, поэтому инвалидация при записи не требуется. Потеря Valkey очищает лишь ускоритель, не сессии или подтверждённые данные. У кэша нет именованного volume, и приложение не полагается на сохранность его данных. При потере PostgreSQL авторизация не использует даже заполненный кэш и возвращает 503; /health/ready зависит от БД, но не от кэша.

Роль Образ/версия Проверка Хранилище/секрет
API Собственный build на Python 3.12.12 /health/ready Без volume; database_url через Docker secret
PostgreSQL postgres:17.6-bookworm pg_isready postgres_data; postgres_password через Docker secret
Valkey valkey/valkey:8.0.2-alpine valkey-cli ping Временный кэш User; без именованного volume и внешнего порта

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test BASE_URL=http://127.0.0.1:8080 PASS, lab2 public API scenario evidence/restart-2026-10-02.txt
Стенд и миграции уровня 3 docker compose --env-file .env up -d --build --wait; повторный scripts/migrate.py API и БД healthy, повторная миграция завершилась без ошибки evidence/restart-2026-10-02.txt
Сохранность уровня 3 make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: прежние данные и сессия после рестарта обоих сервисов evidence/restart-2026-10-02.txt
Отказ обязательной БД Остановить postgres, запросить readiness и защищённый endpoint Оба HTTP 503; затем БД восстановлена, сервисы healthy evidence/restart-2026-10-02.txt
Кэш и отказы уровня 4 docker compose exec -T api python - < student-tests/test_cache_failures.py; отказ Valkey/БД Два интеграционных теста PASS; SQL 2/1/2 на miss/hit/reload; Valkey hit/miss 1/2; smoke проходит без кэша; при отказе БД 503, отозванный токен после рестарта кэша 401 evidence/cache-2026-10-02.txt
Негативные, конкурентные проверки уровня 4 make test-level4 10 тестов PASS: короткий TTL 2 с и неизменный expiry после рестарта API, logout/повторный logout, одинаковая ошибка неверных credentials, гонка username 201/409, откат чата после ошибки второй membership, обход отказавшего Valkey, ограниченный 503 при отказе БД и 401 после перезапуска Valkey. Оба списка отвечают 400 на limit из 4301 цифры evidence/level4-tests.txt
Индекс истории уровня 4 docker compose --env-file .env exec -T api python - --count 10000 --deep-offset 8000 < scripts/seed_history.py 10 000 сообщений в одном чате; первая и глубокая страницы по 51 строке, порядок и отсутствие повторов проверены. Обе страницы используют messages_history_idx evidence/history-explain.txt
Трек 5: ≥100 000 сообщений и два индекса scripts/track2_experiment.py в API-контейнере Чаты 80 000/15 000/5 000; по пять измерений первой и глубокой страниц и вставки 500 строк; индекс приложения восстановлен после опыта evidence/query-comparison.csv, evidence/query-plans.txt
Трек 5: backup/restore bash scripts/backup_restore.sh Дамп 3 441 039 байт восстановлен в новый volume; все пять таблиц совпали по count и SHA-256 строк; при остановленной исходной БД восстановленный API вернул 200 с действующим токеном и 401 с истёкшим evidence/restore-check.txt

У api, postgres и valkey изменились времена StartedAt при сохранении именованного volume; точные значения приведены в evidence. Это подтверждает фактический перезапуск трёх контейнеров. Проверка make validate локально пока не завершена: DNS до files.pythonhosted.org не позволил установить openapi-spec-validator==0.7.2; отдельный CI workflow устанавливает зависимости из requirements-dev.txt для проверки контракта.

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

Стенд — Colima на arm64 macOS с Docker/Compose, 2 CPU и 2 054 840 320 байт памяти. make test-level4 запускает тесты БД, auth, кэша внутри API-контейнера и отдельный HTTP-сценарий, который последовательно останавливает/восстанавливает Valkey и PostgreSQL. Он работает только на учебном стенде с локальным .env, не удаляет volumes и не публикует токены. Отказ второй вставки участника инъецируется после записи чата и первой membership: отсутствие нового чата и membership после исключения доказывает rollback, в отличие от одной предварительной проверки входных данных.

Для SQL-плана scripts/seed_history.py создаёт отдельный синтетический чат с 10 000 сообщениями, выполняет ANALYZE messages и проверяет 51 упорядоченную строку на первой и странице после курсора 8000-й записи. Команда и полный EXPLAIN (ANALYZE, BUFFERS) сохранены в evidence/history-explain.txt. PostgreSQL 17.6 выбрал Index Scan using messages_history_idx с условием chat_id для первой страницы и (chat_id, (created_at,id) > cursor) для глубокой. Обе прочли лишь 3 и 4 буфера из cache, выполнились за 0,010 и 0,014 мс в этом прогоне; это время SQL на прогретых страницах, не HTTP latency и не прогноз для других размеров истории. В запросах приложения также используется keyset (created_at,id) с индексом (chat_id,created_at,id), поэтому глубокая страница не пропускает заново первые 8000 строк.

Трек 5: план запроса и стоимость записи

Гипотеза. Покрывающий индекс (chat_id,created_at,id) INCLUDE (sender_id,text) уберёт обращения к heap на прогретых страницах истории, но займёт больше места и не обязан дать выигрыш по времени при короткой странице. Сохраняемый индекс приложения — (chat_id,created_at,id); эксперимент временно заменяет его на покрывающий и в finally восстанавливает исходный.

Метод. На исходном commit e50ba0f и Colima-стенде (arm64, 2 CPU, 2 054 840 320 байт RAM; PostgreSQL 17.6) скрипт создаёт три синтетических чата 80 000/15 000/5 000 сообщений с равномерным временем внутри каждого чата. VACUUM (ANALYZE) выполнен перед каждым вариантом. Для каждого индекса одна и та же проекция из пяти полей читается первой страницей и по keyset-курсору после 72 000-й записи горячего чата; размер ответа — 51 строка. Три прогрева и пять повторов EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) дают время SQL, план и cache buffers. Отдельно пять раз вставляются и подтверждаются по 500 синтетических строк в четвёртый чат под каждым индексом; измерено время клиента на INSERT ... SELECT вместе с COMMIT. Итоговая БД содержит ещё 5 000 строк этого теста, поэтому фактический размер при backup — 115 026 сообщений с учётом данных прежних проверок. Значения CSV содержат каждый повтор; запросы и DDL — в scripts/track2_experiment.py.

Вариант Первая страница: медиана SQL, shared hit Глубокая: медиана SQL, shared hit INSERT 500 + COMMIT: медиана / диапазон Размер индекса после опыта
A: обычный btree 0,009 мс, 6 0,011 мс, 6 2,632 мс / 2,467–3,997 6 799 360 байт
B: covering btree 0,011 мс, 5 0,010 мс, 4 2,638 мс / 2,382–12,557 11 935 744 байт

Вариант B дал Index Only Scan и ноль Heap Fetches в сохранённых планах; A дал Index Scan. Во всех повторениях shared_read=0: измерялся тёплый cache. Разница медиан SQL в пределах тысячных долей миллисекунды и не доказывает ускорение B. Медленная вставка B в одном повторе показывает нестабильность, но пяти повторов недостаточно, чтобы приписать её именно индексу. Размер B больше примерно на 76%; поэтому оставлен исходный A. Сравнение последовательное A→B, записи второго варианта идут после записей первого, и опыт не включает параллельную нагрузку, холодный cache, HTTP и долговременную запись WAL. Команда из чистого clone требует поднятого Compose и локальных .env/secrets по разделу запуска; эксперимент добавляет синтетические строки только в учебную БД.

Трек 5: восстановление

scripts/backup_restore.sh создаёт private pg_dump -Fc в системном временном каталоге, поднимает второй postgres:17.6-bookworm с новым именованным volume, применяет pg_restore --exit-on-error, запускает отдельный API с URL второй БД, затем останавливает исходный PostgreSQL на время проверки. Он не копирует исходный volume. Источник после проверки снова запущен; временные контейнеры и файлы с URL/токенами удалены, успешный новый volume оставлен для проверки. Сценарий не объявляет успех, если dump, restore, сверка или HTTP-сценарий завершились ошибкой.

При замере 2026-10-02 09:51 UTC новый volume mtusi2026lab2_restore_20261002125101_21469 содержал 110 users, 26 chats, 41 memberships, 115 026 messages и 49 sessions. Для каждой таблицы совпали количество и SHA-256 потока всех строк в порядке ключа; у трёх выбранных сообщений совпали ID и SHA-256 текста. Через восстановленный API при недоступном источнике действующий токен прочитал первую страницу (200), а токен, истёкший ещё до backup, получил 401. Полный путь «старт нового PostgreSQL → restore → API ready» занял 10 с по секундным отметкам; отдельные dump/restore уложились в разрешение 1 с этой грубой шкалы. evidence/restore-check.txt содержит результат без токенов и raw dump.

Граница восстановления — согласованный снимок pg_dump: подтверждённые записи после момента снимка этим резервным файлом не возвращаются. Архивации WAL и непрерывного PITR здесь нет, поэтому RPO зависит от частоты backup, а измеренные 10 с не включают поиск и передачу файла с другой машины. Тест выполнялся без внешних писателей между подготовкой fingerprint и dump. Для реальной эксплуатации потребуются расписание backup и регулярная проверка restore.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Полный restart API и PostgreSQL Тот же действующий токен читает сообщение Публичный persistence PASS Подтверждённая запись сохранена; время восстановления в пределах лимита hook
Остановка PostgreSQL Readiness и защищённый запрос дают ограниченный отказ Оба HTTP 503; после запуска БД healthy Без принятия анонимного запроса
Остановка Valkey Запросы идут через PostgreSQL Публичный smoke PASS при остановленном кэше; затем Valkey healthy Данные и сессии не зависят от кэша
Остановка PostgreSQL при заполненном User-кэше Кэш не авторизует без БД Readiness и защищённый запрос 503; после восстановления действующий токен 200 HTTP-клиенту нужен timeout больше 5-секундного ожидания pool
Отзыв токена и рестарт Valkey Старый токен остаётся недействительным После restart кэша прежний токен 401 Отзыв хранится в PostgreSQL

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

Подтверждён рестарт одного API, одного PostgreSQL и Valkey с сохранением volume БД и отдельное восстановление во второй PostgreSQL. Это не высокая доступность: отказ рабочей БД временно делает API недоступным, а заполненный кэш не может заменить проверку сессии. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Результаты трека 5 описывают один локальный стенд и тёплый cache; для выбора индекса под иным распределением данных опыт надо повторить.