10 KiB
Отчёт — лабораторная 2
- Автор, группа: Бадрадин Али, БВТ-2302
- Целевая оценка: 4; трек 5 не заявлен
- Commit/PR: черновик PR #84 — mtusi2026/mtusi2026lab2#84
- Источники и помощь: контракт этого репозитория; документация FastAPI, SQLAlchemy, PostgreSQL, Redis и Argon2. ИИ использован для реализации и ревью.
Запуск из чистого clone
Версии закреплены в requirements.txt и compose.yaml: Python 3.12.6, FastAPI 0.115.0, SQLAlchemy 2.0.36, Psycopg 3.2.3, Redis client 5.2.0, Argon2-cffi 23.1.0, PostgreSQL 16.4 и Redis 7.4.1. Docker Compose v2 собирает API и запускает DB, Redis и одноразовую миграцию.
Copy-Item .env.example .env
./scripts/create-secrets.ps1
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
python tests/smoke.py --base-url http://localhost:8080
Оператор создаёт secrets локально; их значения не добавляются в Git. docker compose stop или docker compose down сохраняют именованные volumes. Удаление учебной БД и Redis выполняется отдельно через docker compose down --volumes.
Архитектура и решения
- PostgreSQL — источник истины для пользователей, хэшей паролей, чатов, членства и сообщений. Все SQL-операции параметризованы через SQLAlchemy. Миграция
001_initial.sqlвыполняется в транзакции с advisory lock и записывает версию вschema_migrations. - Чат и членство создаются атомарно. FK
(chat_id, sender_id)не позволяет записать сообщение от неучастника. Уникальность username обеспечивается PostgreSQL, а не предварительной проверкой приложения. - История читается по keyset
(created_at, id)черезmessages_history_idx(chat_id, created_at, id); полная история не загружается на каждую страницу. - Argon2id хэширует пароли. Basic используется только для входа; Bearer-токены генерируются с 256 битами случайности. В Redis сохраняется SHA-256-ключ, идентификатор пользователя и абсолютное время истечения. Logout удаляет текущую запись.
- Redis — источник истины для сессий.
appendonly yes,appendfsync everysec, периодический RDB snapshot и именованный volume сохраняют записи при штатном рестарте. При аварии возможна потеря последних записей примерно за одну секунду. - Пул PostgreSQL ограничен 5 соединениями + 5 overflow; connect timeout 3 с, pool timeout 3 с, statement timeout 5 с. При отказе Redis/PostgreSQL аутентификация не деградирует в доверие к
X-User-Id: запросы возвращают503 unavailable, readiness становится 503. - Для сообщений кэш отсутствует: успешная запись и последующее чтение используют PostgreSQL, поэтому stale read от кэша невозможен.
Проверки и доказательства
Таблица ниже фиксирует фактически выполненное в этой рабочей сессии. Не отмечайте подготовленный сценарий как пройденный до запуска с работающим Docker Engine.
| Критерий | Команда/сценарий | Результат | Доказательство |
|---|---|---|---|
| Структура API и локальные ссылки | python scripts/check_contract.py |
PASS | Вывод: PASS: offline skeleton structure, local refs and Python syntax |
| Цели Makefile | make check; make test |
PASS | evidence/check-output.txt; evidence/test-output.txt |
| Синтаксис Python | python -m compileall -q src tests scripts |
PASS | exit code 0 |
| Конфигурация Compose и secrets | docker compose config --quiet |
PASS; secrets и .env созданы локально и игнорируются Git |
exit code 0 |
| In-process HTTP, ошибки и базовые проверки | fastapi.testclient.TestClient с нерабочими локальными адресами хранилищ |
PASS: health, request ID, игнорирование X-User-Id, пустое тело сессии, ошибки валидации/malformed JSON, Argon2id, Basic parsing и cursor codec |
вывод PASS в терминале |
| Недоступная PostgreSQL | GET /health/ready при закрытом localhost-порту |
PASS: контролируемый 503 unavailable, request ID совпадает |
вывод PASS в терминале |
| README задания | README.md сохранён из исходного репозитория задания |
PASS | README.md; инструкция запуска решения находится в этом отчёте |
| Публичный smoke | python tests/smoke.py --base-url http://localhost:8080 |
PASS | evidence/test-output.txt; вывод пользователя от 2026-10-23 |
| Пароль, expiry, logout, гонка регистрации, rollback чата | $env:SESSION_TTL_SECONDS='10'; python tests/grade4.py --base-url http://localhost:8080 |
PASS: все 8 сценариев | вывод пользователя от 2026-10-22; tests/grade4.py |
| Отказ Redis и PostgreSQL | часть tests/grade4.py |
PASS: оба отказа возвращают ограниченный 503; API и хранилища восстановлены |
вывод пользователя от 2026-10-22 |
| Полный перезапуск сессии и данных | python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080 |
PASS: сохранены подтверждённые данные и действующая сессия после перезапуска | вывод пользователя от 2026-10-23; hook: scripts/restart.sh (без удаления volumes) |
| История ≥10 000 сообщений | docker compose --env-file .env exec -T api python -m src.app.explain_history |
PASS: Index Scan использует messages_history_idx; Execution Time 0,108 мс |
evidence/query-plan.json; 3 shared hit blocks в узле Index Scan |
| Повторное применение миграций | docker compose --env-file .env run --rm migrate |
PASS: одноразовый migrate-контейнер завершился без ошибки | вывод пользователя от 2026-10-23 |
Локальный HTTP-прогон использовал установленное в рабочей среде FastAPI 0.139.0, Pydantic 2.13.4, SQLAlchemy 2.0.51 и Redis client 8.0.1; контейнер фиксирует версии из requirements.txt. Публичный smoke и полная suite grade4 подтверждены пользователем на Docker Compose 2026-10-22 и 2026-10-23; перезапуск с сохранением данных/сессии и повторное применение миграции также прошли 2026-10-23. План запроса истории снят в Docker: Index Scan по messages_history_idx, 0,108 мс на синтетическом наборе.
Транзакции и план запроса
Регистрация делает один INSERT; конкурентный конфликт определяется ограничением UNIQUE(username) и возвращает одинаковый 409. Создание чата проверяет существование участников и затем вставляет чат и все связи в одном Session.begin(). Ошибка до commit откатывает всю транзакцию. История использует сравнение строки (created_at, id) и LIMIT, согласованное с индексом messages_history_idx.
src/app/explain_history.py создаёт 10 000 синтетических сообщений в транзакции, запускает ANALYZE и EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON), проверяет план и откатывает данные. Сохранённый evidence/query-plan.json показывает Index Scan через messages_history_idx, 3 shared hit blocks и время 0,108 мс. Это замер одного локального запуска, не универсальная оценка производительности.
Ограничения
Это локальный учебный стенд, не HA: один API, одна PostgreSQL и один Redis на одном Docker host. Перезапуск host/потеря диска не покрываются. AOF everysec не обещает сохранение каждой последней записи при внезапном обесточивании. TLS, лимиты скорости и защита от перебора паролей не входят в обязательный контракт Lab 2. Приложение не выдаёт производственный уровень безопасности.