21 KiB
Отчёт — лабораторная 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; для выбора индекса под иным распределением данных опыт надо повторить.