33 KiB
Отчёт — лабораторная 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 и размер БД могут измениться из-за новых тестовых данных и разной нагрузки.