Files
mtusi2026lab2/REPORT.md
T
killoq 396d149849
Skeleton contracts / contracts (pull_request) Canceled after 0s
fix and report update
2026-10-23 15:41:18 +03:00

33 KiB
Raw Blame History

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

  • Автор, группа: Журавлев Алексей, БПИ2301
  • Целевая оценка: 5; трек 2 — план запроса и восстановление**
  • Commit/PR: выполнен
  • Использованные источники, библиотеки и помощь ИИ: материалы lab1 и skeleton lab2; официальные материалы PostgreSQL по EXPLAIN, pg_dump/pg_restore; документация Redis по AOF. Python-библиотеки: argon2-cffi==23.1.0, psycopg[binary,pool]==3.2.9, redis==5.2.1; для полной валидации OpenAPI — openapi-spec-validator==0.7.2. Использовалась помощь ИИ при диагностике тестов, подготовке эксперимента и текста отчёта; результаты экспериментов проверялись командами проекта.

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

Требования и версии

  • Windows 10/11 с PowerShell, Docker Desktop и Docker Compose v2.
  • Python Launcher (py -3); тесты используют Python 3.9+ и стандартную библиотеку. В текущей среде тесты запускались на Python 3.14.6.
  • GNU Make — только для команд make; прямые команды py -3 работают без Make.
  • Dockerfile задаёт python:3.12.11-slim-bookworm; PostgreSQL — postgres:16.8-alpine; Redis — redis:7.4.2-alpine.
  • В requirements.txt версии библиотек зафиксированы. Полная OpenAPI-валидация дополнительно использует requirements-dev.txt.
  • Для обычного запуска нужны свободные порты 8080 (API) и 5432 (PostgreSQL); для backup/restore — также 5433.

Конфигурация, .env и secrets

Для локального учебного стенда отдельные secrets-файлы создавать не нужно: compose.yaml задаёт тестовые учётные данные и URL зависимостей непосредственно в конфигурации сервиса. Это упрощение только для локальной лабораторной, не production-конфигурация. Не используйте тестовые учётные данные в реальной среде и не публикуйте реальные секреты.

.env.example — справочный файл интерфейса переменных, но Compose не подключает его через env_file. Compose автоматически читает .env, однако в текущем compose.yaml через подстановку из него реально используются только APP_PORT (публикуемый порт API) и SESSION_TTL_SECONDS (TTL сессии). DATABASE_URL и CACHE_URL заданы в Compose; APP_ENV в приложении не используется. DATABASE_URL_FILE и CACHE_URL_FILE поддерживаются кодом, но Compose не монтирует секретные файлы и не задаёт эти переменные.

Для стандартного запуска можно не создавать ни .env, ни secrets. Если нужно изменить только порт/TTL локально, создайте .env в корне с собственными значениями, например:

@'
APP_PORT=8080
SESSION_TTL_SECONDS=3600
'@ | Set-Content -Encoding ascii .env

Не добавляйте .env с реальными секретами в Git. Для настоящего secret management требуется отдельно настроить Compose secrets/монтирование файлов и соответствующие переменные; такой production bootstrap в этой лабораторной не реализован.

Сборка, запуск и проверки

В PowerShell:

Set-Location 'C:\VMD2\mtusi2026lab2'
py -3 --version
docker compose version
docker compose config --quiet
docker compose up -d --build
docker compose ps

Приложение ждёт, пока healthcheck PostgreSQL и Redis станут успешными; затем при запуске API применяет новые миграции. Проверить готовность:

Invoke-RestMethod http://localhost:8080/health/live
Invoke-RestMethod http://localhost:8080/health/ready

Ожидаемый ответ обоих маршрутов при исправных зависимостях: status: ok. Если API не готов, посмотреть диагностику:

docker compose ps
docker compose logs --tail 100 api
docker compose logs --tail 100 postgres
docker compose logs --tail 100 redis

Затем выполнить базовый набор:

make check
make test
make student-test

Прямые эквиваленты, если Make недоступен:

py -3 scripts/check_contract.py
py -3 tests/smoke.py --base-url http://localhost:8080
py -3 -m unittest discover -s student-tests -p 'test_*.py'

Скрипт smoke создаёт синтетические данные, которые автоматически не удаляются. Дополнительные проверки persistence, отказов, expiry и трека 2 приведены ниже в разделе доказательств.

Полная проверка OpenAPI необязательна:

py -3 -m pip install -r requirements-dev.txt
make validate

Открыть документацию API можно по адресу http://localhost:8080/docs, контракт — http://localhost:8080/openapi.json.

Безопасная остановка и сброс данных

Обычная остановка сохраняет именованные volumes:

docker compose down

Намеренно удалить все учебные данные основного Compose-проекта (PostgreSQL и Redis), когда контейнеры больше не нужны:

docker compose down -v

Это необратимо удалит пользователей, чаты, сообщения и сессии в volumes. Не выполнять, если данные нужны для демонстрации. Отдельный сервис восстановления postgres_restore управляется другим Compose-файлом и имеет собственный volume postgres_restore_data; его остановка/удаление выполняется отдельно:

docker compose -f compose.track2-restore.yaml down

Чтобы удалить и его учебный volume намеренно:

docker compose -f compose.track2-restore.yaml down -v

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

HTTP-клиент
    │ Basic Auth при входе / Bearer при защищённых запросах
    ▼
Python HTTP API
    ├── PostgreSQL: users, chats, chat_members, messages
    └── Redis: sess:<token> → user_id с TTL
  • app.py реализует HTTP-маршруты и валидацию; auth.py — Argon2-хеширование, Basic/Bearer и выпуск токена; sessions.py — Redis-операции сессий; db.py — PostgreSQL и миграции.
  • Основной источник истины для пользователей, чатов, членства и сообщений — PostgreSQL. Redis является единственным хранилищем активных сессий приложения. Сессия создаётся в Redis через SETEX, имеет срок SESSION_TTL_SECONDS (по умолчанию 3600 секунд), удаляется при logout. Redis запущен с AOF и appendfsync everysec.
  • PostgreSQL использует параметризованные запросы и psycopg_pool.ConnectionPool (min 1, max 10 соединений, timeout 5 секунд). Миграции версионированы файлами migrations/*.sql, применяются при старте и регистрируются в schema_migrations.
  • Создание чата и строк участников выполняется в одной транзакции после проверки существования участников; при неизвестном участнике изменения откатываются. Создание сообщения проверяет членство и вставляет строку транзакционно.
  • История сообщений упорядочивается по (created_at, id), курсор содержит этот ключ и идентификатор ресурса. Индекс messages_chat_history_idx (chat_id, created_at, id) соответствует выборке истории. Ограничение размера страницы — 1–100.
  • Пароли сохраняются как Argon2-хеши; пользовательские ответы не содержат пароль или хеш. Вход использует Basic только для POST /api/v1/auth/sessions; защищённые маршруты требуют Bearer. X-User-Id не устанавливает личность. Logout отзывает ключ в Redis.
  • Compose использует именованные volumes PostgreSQL и Redis. Порты и локальные dev credentials в Compose предназначены только для учебного локального стенда.

Перенос из lab1: сохранена предметная модель мессенджера — пользователи, чаты, члены чата, сообщения, чтение истории и отправка сообщений. Состояние вынесено из минимального стенда в PostgreSQL. Учебная идентификация через X-User-Id заменена на регистрацию с паролем, Basic-вход и Bearer-сессии в Redis. Текущая лабораторная не добавляет функциональность вложений или несколько API-реплик.

Переменные конфигурации: APP_HOST/APP_PORT читаются приложением; Compose задаёт APP_HOST=0.0.0.0, контейнерный порт 8080 и публикацию ${APP_PORT:-8080}:8080. SESSION_STORE=redis проверяется приложением; SESSION_TTL_SECONDS передаётся в API. DATABASE_URL и CACHE_URL заданы в compose.yaml. Код также умеет читать DATABASE_URL_FILE и CACHE_URL_FILE, но в текущем Compose они не активированы. APP_ENV из .env.example на поведение не влияет.

Границы транзакций: регистрация пользователя — одна вставка; составное создание чата (чат + участники) — одна транзакция; создание сообщения — транзакция с проверкой доступа и вставкой; каждый файл миграции применяется и отмечается как применённый транзакционно. Внешней общей транзакции между PostgreSQL и Redis нет; для этих операций она и не требуется.

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

Публичный smoke и уровень 3

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Статическая структура и синтаксис py -3 scripts/check_contract.py PASS: проверены структура, локальные ссылки и Python syntax. Скрипт сам подчёркивает, что не тестирует работающий API. Вывод команды; scripts/check_contract.py
Публичный smoke py -3 tests/smoke.py --base-url http://localhost:8080 PASS: lab2 public API scenario; регистрация, auth, создание чата, сообщения, пагинация, авторизация и logout. Вывод команды; tests/smoke.py; contracts/openapi.json
PostgreSQL схема и миграции docker compose up -d --build; затем docker compose exec postgres psql -U messenger -d messenger -c "\dt" и docker compose exec postgres psql -U messenger -d messenger -c "SELECT version FROM schema_migrations" API применяет миграции при запуске. Миграция создаёт users/chats/chat_members/messages; уникальность username и FK/PK заданы в SQL. migrations/001_schema.sql; реализация db.py
Создание чата атомарно py -3 -m unittest student-tests.test_lab2.Lab2Grade4Tests.test_chat_creation_rollback_unknown_member PASS в запуске student suite: при неизвестном участнике API отвечает 400, неуспешный чат не появляется в списках. student-tests/test_lab2.py; db.py
Argon2, Basic/Bearer, logout, отказ от X-User-Id py -3 tests/smoke.py --base-url http://localhost:8080; py -3 -m unittest student-tests.test_lab2.Lab2Grade4Tests.test_wrong_password_rejected student-tests.test_lab2.Lab2Grade4Tests.test_logout_revokes_session Smoke PASS; в student suite неверный пароль и logout прошли; logout отзывается и прежний токен получает 401; X-User-Id не переопределяет Bearer. auth.py, sessions.py, app.py, tests/smoke.py, student-tests/test_lab2.py
Полный restart с сохранением подтверждённых данных и прежней сессии py -3 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080 PASS: persistence preserved confirmed data and existing session. Hook scripts/restart.bat выполняет docker compose restart api postgres redis; volumes не удаляются. Hook подтверждает перезапуск этих трёх Compose-сервисов, не удаление/создание контейнеров и не внешний backup. Вывод команды; tests/resilience.py; scripts/restart.bat; compose.yaml

Уровень 4

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Redis используется для сессий с TTL и persistence docker compose up -d; проверить docker compose exec redis redis-cli INFO persistence; тест expiry см. ниже Сессии хранятся под sess:<token> через SETEX; Compose включает AOF и appendfsync everysec; expiry-тест ниже прошёл. sessions.py, auth.py, compose.yaml, compose.ttl.yaml
Параметризованный доступ, пул, гонка регистрации и rollback py -3 -m unittest discover -s student-tests -p 'test_*.py' Последний локальный запуск: 10 тестов, OK, 5 пропущено по умолчанию. Тест гонки проверяет ровно один 201 из 8 параллельных регистраций; rollback проверяет отсутствие чата после ошибки. Вывод unittest; db.py; student-tests/test_lab2.py
Проверка expiry короткой сессии Сначала docker compose -f compose.yaml -f compose.ttl.yaml up -d --build, дождаться /health/ready; затем $env:RUN_EXPIRY_TEST='1'; py -3 -m unittest student-tests.test_lab2.Lab2Grade4Tests.test_session_expiry 1 тест OK: после TTL=2 секунд защищённый запрос со старым токеном получает 401. После проверки обычная конфигурация восстановлена. Вывод unittest; compose.ttl.yaml; student-tests/test_lab2.py; evidence/ (отдельный JSON не создаётся)
Недоступность Redis/PostgreSQL $env:RUN_INFRA_TEST='1'; py -3 -m unittest discover -s student-tests -p 'test_dependencies.py' 2 теста OK: при остановке Redis readiness и Bearer-запрос дают 503; при остановке PostgreSQL readiness даёт 503. Teardown запускает зависимости обратно. Вывод unittest; student-tests/test_dependencies.py; app.py
Индекс и планы на ≥100 000 записей py -3 scripts/track2_run.py; изучить evidence/track2/benchmark.json В текущем артефакте датасет seeded минимумом 100 000 skewed-сообщений; EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) показывает Index Only Scan на messages_chat_history_idx. Текущий замер keyset-style первой страницы 0.061 ms против OFFSET 6.117 ms. evidence/track2/benchmark.json; scripts/track2_seed.py; scripts/track2_benchmark.py
Все обязательные пункты уровня 4 Совокупность smoke, persistence, race/rollback, expiry, dependency failure и track2 команд выше На текущем стенде подтверждены отдельными запусками. HTTP нагрузочный тест не запускался и не является доказательством этих пунктов. Таблицы выше и перечисленные исходники/выводы

Выбранный трек 2 для оценки 5

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Повторяемый skewed dataset ≥100 000 сообщений py -3 scripts/track2_run.py Seed создаёт 100 000 сообщений: 70% в hot-чате, оставшаяся доля в пяти medium- и 50 small-чатах. Seed пропускается, если track2_hot уже есть; последующий объём БД включает пользовательские/benchmark-вставки. scripts/track2_seed.py; evidence/track2/benchmark.json
Сравнение запросов/индексов и стоимости записи В составе py -3 scripts/track2_run.py Текущий benchmark: keyset-style LIMIT 50 0.061 ms, OFFSET 50 000 — 6.117 ms; с дополнительным (chat_id) индексом keyset — 0.052 ms, тот же план. Вставки 500 записей: 23 192.1 msg/s с дополнительным индексом против 38 756.3 msg/s только на production-индексах (один прогон). evidence/track2/benchmark.json; scripts/track2_benchmark.py
Backup → отдельное хранилище → сверка counts и выбранных строк В составе py -3 scripts/track2_run.py Текущий артефакт: 116 022 сообщений и 88 пользователей до/после; counts_match=true, sample_match=true для пяти строк; dump 3 024 158 bytes; end-to-end 3.75 s. Сценарий завершался PASS: restore verification. evidence/track2/restore_report.json; scripts/track2_backup_restore.py; compose.track2-restore.yaml
Автоматическая проверка артефактов трека $env:RUN_TRACK2_VERIFY='1'; py -3 -m unittest student-tests.test_track2 Последний запуск: 2 теста OK; проверены keyset быстрее offset, выбран индекс, совпадение counts/sample и не менее 100 000 сообщений. Вывод unittest; student-tests/test_track2.py; JSON-файлы выше

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

Методика, стенд и результаты трека 2

  • Гипотеза: индекс (chat_id, created_at, id) обслуживает сортированную историю; запрос LIMIT 50 дешевле большого OFFSET; дополнительный индекс только (chat_id) не улучшит план keyset, но добавит стоимость вставки. Логический pg_dump восстанавливается в отдельный PostgreSQL с теми же counts и контрольными строками.
  • Стенд: Docker Desktop на Windows, один локальный host; версии контейнеров указаны в разделе запуска. PostgreSQL работает без заданных CPU/RAM limits. Точная модель CPU, объём RAM и метрики использования CPU/RAM во время эксперимента не записывались.
  • Данные: seed задаёт 100 000 сообщений, из них 70 000 в hot-чате, по 5 000 в пяти medium-чатах и суммарно 5 000 в 50 small-чатах. Остальные строки в текущем общем count — пользовательские smoke/student записи и дополнительные benchmark вставки; например, последний restore snapshot содержит 116 022 сообщения.
  • Профиль запросов: три одиночных EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) замера — первый ORDER BY created_at, id LIMIT 50, запрос того же порядка с OFFSET 50000 LIMIT 50, затем первый запрос после создания дополнительного (chat_id) индекса. Важно: данный benchmark измеряет первую страницу без cursor-предиката; пагинация API использует keyset cursor, но именно продолжение страницы с (created_at,id) > (...) здесь отдельно не замерялось.
  • Профиль записей: два последовательных batch-вставочных замера по 500 коротких сообщений одним соединением/клиентом с commit; сначала дополнительный индекс включён, затем он удалён. Это последовательный микробенчмарк, concurrency=1, без специально заданного arrival rate, прогрева, повторов или статистической агрегации.
  • Последний сохранённый read result: keyset-style 0.061 ms; OFFSET 6.117 ms; keyset с лишним индексом 0.052 ms. Во всех трёх выбран Index Only Scan на messages_chat_history_idx.
  • Последний сохранённый write result: 23 192.1 msg/s с лишним индексом против 38 756.3 msg/s без него (примерно −40.2% относительно production-index-only в этом одном прогоне). Выборка не повторялась, поэтому это наблюдение, а не стабильная оценка эффекта индекса.
  • Backup/restore: pg_dump -Fc → копирование dump в отдельный postgres_restore → pg_restore в отдельную БД → сравнение общего числа messages/users и пяти последних строк по стабильной сортировке created_at DESC, id DESC. В последнем артефакте: 3.75 s end-to-end, 3 024 158 bytes, 116 022 messages, 88 users, counts и sample совпали.
  • Повторение: py -3 scripts/track2_run.py; проверка JSON: $env:RUN_TRACK2_VERIFY='1'; py -3 -m unittest student-tests.test_track2. Seed намеренно не добавляет второй набор, если уже есть track2_hot; benchmark добавляет 1 000 строк на прогон и тестовые данные также накапливаются. Для чистого повтора нужен осознанный новый учебный volume, что удаляет его данные.

RPS, ошибки, p50/p95/p99, CPU/RAM: в треке 2 HTTP load generator не использовался; успешные HTTP RPS, error ratio, p50/p95/p99 и ресурсы хоста не измерялись, поэтому значения не заявляются. Отдельный tests/load.py — closed-loop HTTP-тест сообщений, но его summary в этот отчёт не включён, так как в подтверждённом прогоне он не запускался. Трек 2 сохраняет query/write/restore summary без токенов в evidence/track2/benchmark.json и evidence/track2/restore_report.json.

Отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Restart API + PostgreSQL + Redis через scripts/restart.bat Контейнеры перезапущены без удаления volumes; данные и ещё действующая Redis-сессия доступны после восстановления tests/resilience.py --mode persistence ...: PASS, тот же токен использован после restart, проверены подтверждённые данные Время в артефакт не записывается; подтверждённые данные не потеряны в этом тесте. Тест не доказывает crash-consistency при потере питания
Остановить Redis readiness 503; защищённый запрос не должен стать анонимно разрешённым test_redis_down_ready_and_auth прошёл; readiness и /users/me вернули 503 Время восстановления отдельной метрикой не фиксируется; тестовый teardown запускает Redis обратно. При фактической потере Redis-содержимого активные сессии могут стать недействительными
Остановить PostgreSQL readiness 503, API не объявляет сервис готовым test_postgres_down_ready прошёл Время восстановления отдельно не фиксируется; тест запускает PostgreSQL обратно. Потеря данных при повреждении volume не тестировалась
Истечение TTL после TTL токен невалиден expiry test при TTL=2 s прошёл: старый токен получил 401 Наблюдение около 3 s ожидания теста; потери PostgreSQL-данных нет
Логический backup/restore в новый PostgreSQL counts и контрольные строки совпадают counts_match=true, sample_match=true 3.75 s end-to-end в последнем артефакте. Записи после момента dump не гарантированы в копии

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

  • Это локальная учебная конфигурация. PostgreSQL использует фиксированные dev credentials в Compose, порты открыты на host, TLS и production secret manager не настроены. Тестовые пароли и переменные не предназначены для production.
  • .env.example не является полностью подключённым конфигурационным контрактом: Compose использует из .env только APP_PORT и SESSION_TTL_SECONDS; file-based secrets в Compose не смонтированы. Следующее улучшение — согласовать шаблон переменных с Compose и подключить локальные secret files без хранения секретов в Git.
  • Redis является единственным хранилищем активных сессий. AOF с appendfsync everysec уменьшает риск потери при рестарте, но не даёт нулевого RPO при внезапном отказе; отказ/потеря Redis может инвалидировать сессии. Репликация/HA Redis не настроены.
  • PostgreSQL backup логический; WAL archiving, PITR и автоматическая ротация/проверка расписания backup не реализованы. Потеря/повреждение основного volume не покрыта тестом restore из автоматического расписания.
  • Persistence hook перезапускает API и оба хранилища, сохраняя Docker volumes. Он проверяет прикладную доступность и сессию прежним токеном, но не имитирует внезапное отключение питания и не проверяет failover на другую API-реплику. API работает одной Compose-репликой.
  • Benchmark однопроходный, без повторов, статистики, прогрева и ресурсного профиля. Значения в ms и msg/s подвержены шуму. Тест не подтверждает latency на cursor continuation, а только сравнивает первую страницу/offset и стоимость batch insert.
  • Исторические времена, RPS/percentiles, CPU и RAM нельзя вывести из тестов, которые их не измеряли. Для более сильного результата нужно повторить каждый профиль несколько раз на зафиксированных ресурсах, записывать raw summary, median/percentiles и ресурсы системы.
  • Сообщения benchmark синтетические и короткие; 500 INSERT — небольшой последовательный batch, а не реалистичная конкурентная нагрузка.
  • Следующие шаги: согласовать .env/secrets с Compose; добавить регулярный backup и WAL/PITR с тестированием RPO/RTO; повторить benchmark с прогревом и несколькими прогонами; измерить HTTP load отдельным генератором; при необходимости добавить HA API/Redis/PostgreSQL.

Проверки, выполненные в текущей среде

Дата фиксации результатов: 2026-10-23. Повторно выполнены:

Команда Фактический итог
py -3 scripts/check_contract.py PASS
py -3 tests/smoke.py --base-url http://localhost:8080 PASS
py -3 -m unittest discover -s student-tests -p 'test_*.py' 10 тестов, OK, 5 skipped
py -3 -m unittest student-tests.test_track2 при RUN_TRACK2_VERIFY=1 2 теста, OK
py -3 tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080 PASS: данные и существующая сессия пережили restart hook
py -3 -m unittest discover -s student-tests -p 'test_dependencies.py' при RUN_INFRA_TEST=1 2 теста, OK
py -3 -m unittest student-tests.test_lab2.Lab2Grade4Tests.test_session_expiry при TTL=2 и RUN_EXPIRY_TEST=1 1 тест, OK; обычная Compose-конфигурация после теста восстановлена
py -3 scripts/track2_run.py PASS: restore counts/sample совпали; summary в evidence/track2/

Все проверки используют localhost и синтетические данные. При повторной сдаче выполнять команды на стенде заново и показывать фактический вывод: JSON benchmark и размер БД могут измениться из-за новых тестовых данных и разной нагрузки.