Files
mtusi2026lab2/REPORT.md
T
dykhanovaa 90f58162a6
Skeleton contracts / contracts (pull_request) Canceled after 0s
исправлен отчет
2026-10-22 17:20:36 +03:00

30 KiB
Raw Blame History

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

  • Автор: Алина Дыханова БВТ2301
  • Целевая оценка: 5. Трек 2: план запроса и восстановление. Выполнены также критерии уровней 3 и 4.
  • Commit/PR:
  • Библиотеки: Python 3.12.12, Flask 3.1.2, Gunicorn 23.0.0, psycopg 3.2.10, psycopg-pool 3.3.3, Redis client 6.4.0, argon2-cffi 25.1.0. Полный lock — requirements.lock.

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

Нужны Docker Desktop/Engine с Compose v2+ и Python 3.9+ на хосте. Порт 127.0.0.1:8080 должен быть свободен. Образы: python:3.12.12-slim, postgres:16.10-alpine, redis:7.4.6-alpine; Python-зависимости закреплены в lock. Первый build требует доступа к registry/PyPI.

python3 scripts/bootstrap.py
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
python3 scripts/experiments.py
python3 scripts/load_experiments.py
python3 scripts/contract_extra.py

Bootstrap идемпотентно создаёт локальные secrets/ с правами 0700, файлы 0600 и .env. Пароль генерируется криптографически, не выводится в терминал и не включается в Git. Уже существующие secrets не перезаписываются. Миграции автоматически выполняются перед Gunicorn; повторно:

docker compose exec -T api python -m app.migrate

--wait ожидает healthcheck. Проверить вручную: curl -f http://localhost:8080/health/ready. Изолированное имя проекта — mtusi_lab2_solution; создаются volumes mtusi_lab2_solution_pgdata и mtusi_lab2_solution_redisdata. Нельзя менять пароль файла после инициализации volume без согласованного изменения роли PostgreSQL.

Полная проверка схемы:

python3 -m venv .venv
.venv/bin/pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

Безопасная остановка: docker compose --profile research down — данные в именованных volumes остаются. Намеренное удаление учебных данных: docker compose --profile research down --volumes. Эта команда не входит в тесты перезапуска. Дамп исследования хранится внутри контейнера PostgreSQL в /tmp/research.dump; сценарий также сохраняет локальную копию backups/research.dump вне Git. Отдельная ручная команда копирования, например docker compose cp postgres:/tmp/research.dump /tmp/lab2-research.dump.

Оператор запускает сценарии последовательно: интеграционные проверки временно останавливают зависимости и пересоздают API с TTL=2, затем восстанавливают TTL=3600. Исследование пересоздаёт только выделенную базу research в основном PostgreSQL и схему research_restored в отдельном сервисе postgres_restore; оно не удаляет таблицы рабочей базы messenger. Не направлять сценарии на чужой/боевой PostgreSQL.

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

Клиент → 127.0.0.1:8080 → Gunicorn (2 workers × 4 threads) → PostgreSQL
                                                     ↘ Redis (кэш User)

PostgreSQL — источник истины для пользователей, чатов, участников, сообщений и сессий. Redis хранит только публичные неизменяемые профили по user:<UUID> на 60 секунд. Попадание в кэш экономит SELECT профиля, но не проверку сессии. На каждый защищённый запрос действительность сессии проверяется в PostgreSQL. Redis не критичен для readiness: ошибка кэша приводит к чтению профиля из БД; PostgreSQL критичен.

Подробный проект таблиц, ограничений, индексов и транзакционных границ — docs/schema.md, реализация — migrations/001_initial.sql. Есть PK/FK, UNIQUE username, CHECK обязательных строк и длин. Создание чата и всех участников — одна транзакция. Advisory lock сериализует миграции, журнал версий предотвращает повторное применение. SQL использует параметры, pool ограничен 8 соединениями на worker (16 на API); ожидание pool/connect — 3 s, statement — 3 s, lock — 2 s.

Минимум lab1 реализован заново в этом skeleton: регистрация, текущий пользователь, создание/чтение/список чатов, отправка и история сообщений, проверка членства и health. Исходников личной lab1 в репозитории не было. Объявленный переход lab2: password при регистрации, Basic только на создание сессии, Bearer для бизнес-запросов. X-User-Id не даёт доступ и не заменяет владельца токена. Вложения и Idempotency-Key относятся к следующим лабораторным и для lab2 не добавлялись.

Пароль: библиотечный Argon2id, m=19456 KiB, t=2, p=1, случайная соль библиотеки; UTF-8 не усекается. Неизвестный username также проходит проверку dummy hash. Opaque токен создаётся из 32 случайных байт (256 бит). В БД сохраняется только SHA-256 токена, пользователь и абсолютный expires_at. SHA-256 здесь применяется к случайному токену, а не к паролю. TTL не продлевается чтениями или перезапуском. Logout удаляет строку сессии. Истёкшие строки недействительны даже без физического удаления.

История не кэшируется. После COMMIT следующий SELECT из primary видит сообщение; поэтому Redis не может нарушить read-after-write. Неизменяемые профили не требуют инвалидации; при появлении редактирования нужно удаление/версионирование ключей. После FLUSHDB кэш наполняется из PostgreSQL. Redis имеет AOF everysec и volume, но потеря до секунды его содержимого не теряет сессии или сообщения.

Курсор — непрозрачная base64url-строка с ресурсом и парой (created_at,id). Чужой ресурс отвергается. Запрос использует WHERE chat_id = ... AND (created_at,id) > (...) ORDER BY created_at,id LIMIT ..., без OFFSET. Следующая страница определяется выборкой limit+1. Для неизменной истории нет повторов/пропусков. Между запросами общего snapshot нет: задержанный COMMIT или коррекция часов могут поместить конкурентную запись до уже пройденного курсора.

Переменная .env.example Реальная конфигурация
SESSION_TTL_SECONDS Compose передаёт API; по умолчанию 3600, тест expiry — 2
DATABASE_URL_FILE API читает DSN из /run/secrets/database_url
CACHE_URL_FILE API читает URL Redis из /run/secrets/cache_url
SESSION_STORE=postgres Декларация выбранной архитектуры; переключение на иное хранилище не поддерживается
APP_HOST, APP_PORT Документируют фиксированную привязку Gunicorn 0.0.0.0:8080 внутри контейнера; не являются переключателями
APP_ENV=lab Документирует учебный профиль; логика приложения от него не зависит

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke, минимум lab1 и переход lab2 make test PASS; Unicode, доступ, Bearer, logout, страницы smoke.txt
Неослабленный контракт/структура make check; make validate PYTHON=.venv/bin/python Обе проверки PASS check.txt, validation.txt
PostgreSQL, PK/FK, UNIQUE, миграции с нуля docker compose up -d --build --wait Чистые отдельные volumes; API готов после миграций build.txt, 001_initial.sql
Повтор миграций Два docker compose exec -T api python -m app.migrate Ошибок нет; версия 001_initial.sql ровно одна migrations.txt
Атомарность создания чата python3 scripts/experiments.py, rollback Тестовый trigger отклоняет INSERT участника после INSERT чата; чат отсутствует после отката experiments.json
Регистрация в гонке Тот же сценарий, 8 потоков 1×201, 7×409 experiments.json
KDF, entropy, срок и отзыв сессии Smoke + expiry, код регистрации/логина Неверный пароль, Basic на бизнес-API, X-User-Id и отозванный токен дают 401 smoke.txt, main.py
UTF-8 пароль 128 code points, двоеточие; malformed JSON и большой limit python3 scripts/contract_extra.py Логин 201, неверные запросы 400 contract-extra.txt
Короткий TTL Временный API с SESSION_TTL_SECONDS=2 После ожидания 2.2 s — 401; обычный TTL восстановлен experiments.json
Сохранность данных и прежнего токена make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS после restart API, PostgreSQL и Redis persistence.txt
Реальный полный restart, volumes сохранены Hook снимает docker inspect до/после StartedAt изменился у всех трёх; ID контейнеров и имена volumes сохранены restart-before.json, restart-after.json
Redis реально используется, TTL/инвалидация Прогрев /users/me, INFO stats, stop/start/FLUSHDB Cache hits +1; при отказе запрос успешен; после очистки профиль восстановлен experiments.json
Безопасный SQL, pool и таймауты Проверка конфигурации и отказа БД Параметризованные запросы; ограниченные pool/connect/statement/lock main.py, schema.md
Индекс истории, EXPLAIN ≥10000 сообщений Тот же интеграционный сценарий 120000 сообщений; составной индекс, keyset, нет полного обхода истории на страницу research.json
Отказы Redis и БД, anonymous fail closed stop/start соответствующего сервиса Redis: 200 с fallback; БД: ready/защищённый путь 503; анонимный 401 experiments.json
Строгий JSON, чужой курсор, read-after-write Собственные интеграционные проверки Лишнее поле/тип/пустая строка и чужой курсор — 400; запись видна участнику experiments.json
Трек 2: ≥100000, перекос, ≥2 индекса/запроса, стоимость записи python3 scripts/experiments.py → research.py 3 размера чатов, 2 индекса × 2 способа чтения; 5 повторов, INSERT 5000 research.json
Трек 2: backup → новое хранилище → сверка pg_dump -Fc; pg_restore в research_restored 120000 строк, общая контрольная сумма и 5 выбранных сообщений совпали experiments.json
Secrets и volumes вне Git .gitignore и .dockerignore; локальный bootstrap В Git подготовлены только исходники и очищенные summaries .gitignore, .dockerignore

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

Среда и методика

Хост: Apple M4, macOS-27.0.1-arm64-arm-64bit-Mach-O; Docker Engine 29.8.0, aarch64. Docker VM: 10 CPU, 7.75 GiB RAM, Docker Desktop. Compose 5.5.1. Дополнительные per-container CPU/RAM лимиты не установлены; сервисы делят ресурсы VM и хоста. На хосте могли работать другие приложения/старые учебные контейнеры. Поэтому это воспроизводимая локальная демонстрация, а не предел производительности сервера. Точные сведения — environment.json.

Трек 2: гипотеза и план запроса

Гипотеза: индекс только по chat_id оставляет фильтрацию/сортировку глубокой страницы; составной B-tree (chat_id,created_at,id) с keyset позволяет сразу перейти к границе. OFFSET даже с составным индексом обходит предшествующие записи. Составной индекс занимает больше места и может удорожать запись.

Скрипт scripts/research.py создаёт в отдельной БД ту же миграционную схему, что и API (UUID, FK, CHECK). Генерируются 120000 синтетических сообщений по 100 ASCII-символов: 100000 / 15000 / 5000 в трёх чатах. ID детерминированы для сравнения, времена разнесены на 1 ms; это синтетическая упорядоченная история. Каждая выборка возвращает до 50 полных Message. Позиции: 90000, 10000 и 4000 внутри соответствующих чатов.

Сравниваются индекс chat_only и composite; для каждого — keyset и OFFSET. После ANALYZE выполняются два прогревочных чтения и пять EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON). Concurrency=1; запросы подаются последовательно, arrival rate определяется временем выполнения. Ниже медиана Execution Time, ms; JSON содержит все пять времён и полный последний план каждой комбинации. Это время PostgreSQL с инструментированием, без HTTP/сети.

Чат / число сообщений chat_only + keyset composite + keyset chat_only + OFFSET composite + OFFSET
1 / 100,000 4.400 0.016 27.952 6.906
2 / 15,000 0.964 0.019 3.986 4.173
3 / 5,000 0.292 0.015 0.883 0.952

Для большого чата keyset ускорился примерно в 275.0 раза. На последнем прогоне число Shared Hit Blocks уменьшилось с 2806 до 5. План составного keyset: Limit → Index Scan с диапазоном по составному ключу. Планы baseline и OFFSET показывают дополнительную обработку строк. Проверяемая причина улучшения — количество просмотренных строк/буферов, а не только малое абсолютное время.

Стоимость записи

Для каждого индекса выполнено пять INSERT по 5000 строк с сохранёнными FK/PK. Измеряется время выполнения INSERT клиентом внутри транзакции, без времени COMMIT. Затем тестовые строки удаляются в той же транзакции. Пакеты выполняются последовательно, concurrency=1, отдельного прогрева записи нет. Показаны медианы:

Индекс Размер индекса до INSERT, bytes INSERT 5000, ms
chat_only 860160 68.960
composite 7094272 73.526

Оба варианта сохраняют PK и проверки FK. Это не WAL-байты, не latency отдельного COMMIT и не изолированная стоимость обслуживания индекса. Порядок вариантов фиксирован, повторные INSERT/DELETE оставляют dead tuples; cold-cache, рандомизация порядка и доверительные интервалы не исследовались. Поэтому большой выигрыш чтения подтверждён планом, а небольшая разница записи не доказывает устойчивую регрессию. Размер составного индекса показывает реальный расход памяти/диска.

Backup и восстановление

После исследования остаются ровно 120000 сообщений. Состояния двух контейнеров и разные имена volumes зафиксированы в restore-storage.json. pg_dump -Fc research создаёт custom-format backup; pg_restore --exit-on-error восстанавливает его в БД research_restored другого контейнера postgres_restore с отдельным volume restoredata, не поверх источника. Сервис запускается через профиль research. Это новый экземпляр PostgreSQL и отдельный volume; перенос на другой физический host/диск не проверялся.

Backup занял 0.271 s, restore — 0.395 s (включая запуск команды через Compose, без запуска нового контейнера и последующей сверки). Перенос dump через хост занял 0.156 s. Восстановились схема, индексы и строки; число строк сверено также для users/chats/members/sessions. Количество и контрольная сумма отсортированного содержимого:

source:   120000|8875a7ede51a3769bf6725a3d57afda0
restored: 120000|8875a7ede51a3769bf6725a3d57afda0

Дополнительно побайтно сравнены поля пяти выбранных сообщений с исходными номерами 1, 50000, 100000, 110000, 120000. MD5 здесь — удобная проверка случайного расхождения учебных данных; это не криптографическая защита backup. Выбранные записи сохранены в research.json.

Дамп соответствует согласованному snapshot; все изменения после его начала могут отсутствовать при восстановлении. В эксперименте конкурентных записей во время backup не было, потеря строк — 0. Без WAL-архива и PITR RPO определяется возрастом последнего backup, а не обещанием нулевой потери. Измеренные 0.395 s — время маленького локального restore, не production RTO: оно не включает поиск/передачу копии, создание сервера, secrets, DNS и переключение клиентов.

HTTP-нагрузка

python3 scripts/load_experiments.py: три независимых прогона tests/load.py, каждый по 10 s, 4 клиента, closed-loop POST сообщений, без retries, без искусственной паузы между запросами. Каждый прогон создаёт отдельный чат; размер истории растёт. Инициализация пользователей вне измеряемого цикла; отдельного HTTP-прогрева нет. Arrival rate не фиксирован. RPS — число успешных HTTP-подтверждений / elapsed, квантили только успешных ответов.

Повтор Успешные запросы RPS Ошибки p50, ms p95, ms p99, ms
1 13898 1381.482 0 2.509 4.806 8.953
2 15141 1504.304 0 2.377 4.288 6.102
3 15682 1558.333 0 2.296 4.081 6.06

Сырые summaries без токенов: load-1.json, load-2.json, load-3.json. CPU/RAM снимались docker compose stats --no-stream во время нагрузки; ниже максимум наблюдаемого CPU и RAM в том же снимке, а не гарантированный непрерывный пик:

Сервис Максимум CPU из samples RAM в этом sample / лимит VM
api 119.79% 116.4MiB / 7.748GiB
postgres 48.81% 41.66MiB / 7.748GiB
redis 1.97% 10.14MiB / 7.748GiB

Все samples — load-resources.json. Генератор ограничен клиентом и имеет coordinated omission; результаты не устанавливают максимальную ёмкость, не моделируют open-loop arrival и не заменяют длительный soak-test. CPU может превышать 100% при использовании нескольких ядер. Измерения SQL и HTTP сделаны раздельно, нагрузка HTTP не сравнивает варианты индекса.

Матрица отказов

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
restart API + PostgreSQL + Redis, volumes сохранены Старый токен и данные работают Публичный persistence PASS; StartedAt всех трёх изменился После readiness данные доступны; подтверждённые тестовые данные не потеряны; точное RTO hook отдельно не измерялось
Недоступен Redis Fallback в БД, анонимный не доверяется /users/me 200; POST сообщения 201; anonymous 401 Fallback-запрос 16.47 ms; после start + FLUSHDB повторное наполнение; потеря обязательных данных 0
Недоступен PostgreSQL live 200, ready/бизнес-путь 503 Ожидаемые статусы, anonymous 401 Проверки заняли 0.009 s на уже оборванных соединениях; готовность после start за 0.561 s; прежняя сессия работает
TTL=2, ожидание 2.2 s Истёкший токен отвергается 401 Ожидаемое истечение; API возвращён к TTL=3600
Logout Отзыв немедленно действует Повторный /me и logout — 401 Сессия удалена транзакционно
Ошибка INSERT участника Откат всего нового чата Ответ 503, в БД 0 чатов с тестовым title После удаления тестового trigger работа продолжается
8 одновременных регистраций Ровно один username 1×201, 7×409 Дубликатов нет
Backup → отдельная БД Схема и данные совпадают 120000 строк, checksum и 5 сообщений совпали Restore 0.395 s; в статическом наборе потерь 0

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

Подтверждены полный управляемый restart с volumes, безопасный отказ кэша, fail-closed БД, expiry/logout, гонка уникальности, rollback и восстановление из логической копии. Управляемый restart не моделирует потерю питания, повреждение диска, partition или failover primary. PostgreSQL использует штатные fsync/synchronous_commit/full_page_writes; COMMIT подтверждает запись WAL в рамках гарантий локального диска/VM, а не репликацию на другой узел.

Стенд имеет одну БД, один Redis и один API-контейнер с двумя worker, без HA. Учебная роль БД создана штатным POSTGRES_USER и обладает избыточными полномочиями; следующий шаг — отдельные роли мигратора и runtime. HTTP/Basic допустимы только на изолированном localhost с синтетическими данными; внешняя демонстрация требует TLS. Rate limiting, очистка истёкших сессий и повторное хеширование при изменении параметров KDF не реализованы.

Redis в этом решении ускоряет неизменяемый профиль, а не историю; его полезность подтверждена попаданием в кэш, но отдельный throughput-выигрыш /me не исследовался. Трек согласованности кэша не заявляется. Значительный выигрыш keyset подтверждён для данной перекошенной синтетической истории и тёплых буферов; другие распределения, холодный диск и масштаб больше RAM требуют отдельных опытов. Backup на том же физическом хосте не защищает от потери хоста; нужны внешнее хранение, расписание backup, WAL-архив и регулярные restore drill.

При первой финальной пересборке PyPI дал сетевой read timeout; повторная сборка использует увеличенный timeout и retries.

Перед сдачей необходимо вписать номер группы и после публикации добавить ссылку на собственный commit/PR. Оценку выставляет преподаватель по запуску и защите; прохождение smoke само по себе её не гарантирует.

Источники: контракт курса, PostgreSQL 16: составные индексы, PostgreSQL 16: backup/restore, PostgreSQL EXPLAIN, argon2-cffi: password hashing, Redis persistence, RFC 7617.