13 KiB
Отчёт — лабораторная 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.