Files
mtusi2026lab2/REPORT.md

13 KiB
Raw Permalink Blame History

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

Автор: Мартинес Анастасия, БПИ2303. Целевая оценка: 4; трек 5 не заявлен. Ветка: solution/bpi2303-martines. Публикация PR ожидает доступа к fork.

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

Нужны Git, Python 3.9+ и работающий Docker Engine с Compose v2. На Windows — Docker Desktop в режиме Linux containers. Все команды выполняются из корня этого репозитория; соседние лабы и внешняя БД не нужны.

python scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
python -X utf8 scripts/verify.py

Bootstrap генерирует локальные случайные credentials и создаёт игнорируемые secrets/db_password, secrets/database_url, .env. Повторный запуск их не перезаписывает. Не коммитить эти файлы. API: http://127.0.0.1:8080, готовность: /health/ready. Библиотеки на хост для этих проверок не нужны. Стенд использует только синтетические тестовые данные.

Версии: Python 3.12.8 slim-bookworm, PostgreSQL 16.6 bookworm, Redis 7.4.1 bookworm. Все Python-зависимости закреплены в requirements.txt. Gunicorn: 2 worker × 4 thread. Миграции выполняются до запуска API.

Отдельные проверки:

python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python student-tests/acceptance.py
docker compose exec -T api python scripts/explain.py

В Windows для persistence использовать scripts/restart.cmd; verify.py выбирает hook автоматически. restart.sh хранится с executable bit. GNU Make запускает те же проверки: make check, make test BASE_URL=http://127.0.0.1:8080, make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080. Полная OpenAPI-валидация: установить requirements-dev.txt в отдельный venv, затем python scripts/validate_openapi.py.

Остановка с сохранением данных: docker compose down. Намеренное удаление всех учебных данных этой лабы: docker compose down -v. Hook перезапуска volumes не удаляет. Новый запуск после удаления volume создаёт пустую схему; прежние пользователи и токены не восстанавливаются.

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

Клиент → Flask/Gunicorn → PostgreSQL; Redis кэширует публичный профиль. Схема, ограничения, индексы и границы транзакций: docs/design.md.

Реализованы текстовые endpoint lab1 с переходом lab2 на password/Basic/Bearer. Отдельный исходный проект lab1 не предоставлялся: код написан с нуля по контракту lab2, чужие студенческие решения не переносились. Контракт и публичные tests остались без изменений.

PostgreSQL — источник истины для пользователей, чатов, членства, сообщений, сессий; данные сохраняются в именованном pgdata. Пароли — Argon2id (19 MiB, 2 прохода, parallelism=1), opaque-токены — 32 случайных байта, в БД только SHA-256. SESSION_TTL_SECONDS задаёт абсолютный expiry, по умолчанию 3600. Logout удаляет текущую сессию; рестарт не продлевает её срок.

Redis хранит неизменяемый публичный профиль profile:v1:<uuid> на 60 с. Редактирования профиля в API нет: инвалидация по TTL и версии ключа; при добавлении редактирования понадобится отдельная стратегия. Сессии и история не кэшируются. Каждый защищённый запрос проверяет PostgreSQL, поэтому тёплый кэш не отменяет logout/expiry. Подтверждённые сообщения сразу видны новому чтению истории. Redis persistence не нужен: потеря кэша вызывает чтение из PostgreSQL.

Пул: максимум 8 соединений на worker, суммарно 16; очередь до 32 на worker. Pool/connect/statement timeout 3 с, lock timeout 2 с. Redis socket timeout 0.2 с; wall timeout операции 0.25 с также ограничивает ожидание DNS. Фоновых операций кэша максимум две на worker, очереди нет; при исчерпании слотов кэш пропускается. SQL параметризован. Составные операции выполняются в транзакциях, 201 — после COMMIT.

Сопоставление .env.example: DATABASE_URL_FILE используется напрямую; CACHE_URL_FILE поддерживается загрузчиком, Compose задаёт несекретный CACHE_URL; SESSION_STORE=postgres фиксирован архитектурой. APP_HOST/APP_PORT заменены явным bind Gunicorn 0.0.0.0:8080; хостовый порт только 127.0.0.1. APP_ENV не влияет на поведение. Секреты и volumes исключены из Git и build context.

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

Общий воспроизводимый запуск: python -X utf8 scripts/verify.py. PASS учитывается только после завершения соответствующей команды; сырые результаты сохраняются в evidence/.

Критерий Сценарий Доказательство
Контракт и текстовый API Публичный smoke evidence/smoke.txt
Сохранность данных и прежнего токена Публичный persistence, restart api/db/redis evidence/persistence.txt, evidence/restart.json
PK/FK/UNIQUE и атомарность FK-ошибка второго участника; число чатов/участников не меняется migrations/001_initial.sql, evidence/student-tests.json
Гонка регистрации 8 одновременных запросов: один 201, семь 409 evidence/student-tests.json
Повторяемые миграции Повторное применение; число пользователей/версий не меняется evidence/student-tests.json
KDF, expiry, logout Unicode/двоеточие в пароле, неверный пароль, TTL=2, тёплый кэш src/app.py, evidence/student-tests.json
Реальное использование Redis TTL профиля ≤60, остановка и восстановление evidence/student-tests.json
Пул/таймауты/отказы Остановка БД: ограниченный 503, live=200, затем прежняя сессия src/db.py, evidence/student-tests.json
Индекс на ≥10 000 сообщений EXPLAIN ANALYZE BUFFERS на 12 000 сообщений evidence/query-plan.json
Keyset и доступ Изменение limit, чужой cursor, совпадение timestamp, чужой чат evidence/student-tests.json
Структура skeleton check_contract.py evidence/contract.txt

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

Гипотеза: индекс (chat_id,created_at,id) позволяет читать позднюю страницу без сканирования всей истории. scripts/explain.py создаёт 12 000 сообщений, делает ANALYZE, выбирает pivot после 10 000 строк и выполняет реальный запрос API с LIMIT 51. OFFSET используется только при выборе экспериментального pivot, в API его нет. Фикстуры откатываются после измерения. JSON содержит actual rows/time и buffers; это эксперимент уровня 4, сравнение индексов и backup/restore уровня 5 не заявлены.

Наблюдение: Index Scan по messages_history, actual rows=51, shared hit blocks=4, shared read blocks=0, Execution Time=0.278 мс. Прогретые страницы находились в памяти; время не характеризует холодный диск. Полного Seq Scan/Sort в плане нет.

Нагрузка: один closed-loop запуск, 30 с, concurrency=4, POST сообщений, без прозрачных retry и без отдельного фиксированного прогрева. Стенд перед замером уже выполнял functional tests; история нагрузочного чата растёт. evidence/load.json содержит successes/errors, RPS, p50/p95/p99. CPU/RAM снимаются во время нагрузки в evidence/resources.json.

Результат 19.11.2026: 6843 успешных запроса за 30.141 с, ошибок 0, 227.033 успешных RPS; p50=16 мс, p95=32 мс, p99=47 мс. По семи выборкам Docker stats: API до 129.85% CPU и 198.5 MiB RAM, PostgreSQL до 36.85% CPU и 39.2 MiB, Redis до 0.49% CPU и 8.312 MiB. 100% в Docker stats соответствует одному логическому CPU; выборки не являются непрерывным измерением пиков. В нагрузочном чате создано 6843 сообщения.

Хост: Windows, около 15.75 GiB доступной ОС физической RAM (16 GiB номинально); CPU/ОС — evidence/environment.json. Docker Engine 26.1.4, Compose 2.27.1. Лимиты: API 2 CPU/512 MiB, PostgreSQL 1 CPU/512 MiB, Redis 0.5 CPU/128 MiB.

Воздействие Ожидание Проверка
Перезапуск API, БД, Redis Прежний токен читает прежнее сообщение persistence и StartedAt всех трёх контейнеров
Остановка Redis Fallback в БД, ready=200, анонимный запрос не получает профиль acceptance, затем start redis
Остановка PostgreSQL 503 для me/ready, live=200; восстановление с прежним токеном acceptance, затем start db
TTL=2 После ожидания 401 даже с тёплым кэшем Отдельный временный API на 8081

В первом прогоне отказ Redis выявил, что socket timeout не ограничивает разрешение Docker DNS. Добавлен wall timeout с ограниченным executor; окончательные evidence соответствуют успешному повторному прогону исправления. Один нагрузочный повтор на ноутбуке не измеряет максимум производительности: closed-loop страдает coordinated omission, latency учитывает успешные запросы.

Ограничения и источники

Один host и один PostgreSQL не обеспечивают HA. Проверяется перезапуск с сохранением диска, а не потеря узла/volume. Нет backup, TLS, rate limiting, автоматической очистки истёкших сессий и ротации секретов. Cursor не фиксирует snapshot между запросами: поздний COMMIT с ранним timestamp может оказаться позади cursor; детали — docs/design.md.

Источники: контракт/публичные проверки skeleton; Flask, Gunicorn, Psycopg, Redis-py, argon2-cffi; материалы по PostgreSQL и Redis из README задания. Помощь ИИ: Codex подготовил код, инфраструктуру, собственные тесты, выполнение проверок и отчёт. Автору необходимо понимать решение для защиты; памятка: docs/defense.md.