14 KiB
Отчёт — лабораторная 2
- Автор, группа: TODO (заполняет студент)
- Целевая оценка; выбранный трек 5, если нужен: 4 (уровень 3 + уровень 4); трек 5 не заявлен
- Commit/PR: TODO после публикации (ветка
solution/БВТ2301-Журавский) - Использованные источники, библиотеки и помощь ИИ: FastAPI 0.115.6, Pydantic 2.10.6, Uvicorn 0.34.0, psycopg 3.2.3 + psycopg-pool 3.2.4, argon2-cffi 23.1.0, redis-py 5.2.1 (клиент для Valkey);
openapi-spec-validatorи pytest только для проверок. Документация PostgreSQL (transactions, EXPLAIN), Valkey/Redis persistence, RFC 7617. Помощь ИИ: генерация каркаса и текста, проверено запуском тестов.
Запуск из чистого clone
Версии и prerequisites
| Компонент | Версия / образ |
|---|---|
| Runtime | Python 3.11.9 |
| API-образ | python:3.11.9-slim-bookworm (пин; digest sha256:8fb099…c317) |
| PostgreSQL | postgres:16.6-bookworm |
| Valkey | valkey/valkey:8.0.2-alpine |
| Docker / Compose | 26.1.4 / v2.27.1 |
| Python-зависимости | requirements.txt (пины: fastapi, pydantic, uvicorn, psycopg[binary], psycopg-pool, argon2-cffi, redis) |
| Стенд | Windows 10 Pro 10.0.19045, Ryzen 5 3600 (6C/12T), 15.9 GiB RAM; persistence-хук выполняется в WSL Ubuntu 22.04 (Python 3.12) и на Linux-раннере |
Prerequisites: Docker с Linux-контейнерами и плагином Compose. На Windows для scripts/restart.sh нужен POSIX-shell (WSL/Git Bash) либо Linux-раннер; публичный smoke и make check работают где угодно.
Создание локальных secrets (не коммитятся)
sh scripts/gen-secrets.sh
# создаёт ./secrets/database_password, ./secrets/database_url, ./secrets/cache_url
# либо: cp secrets.example/* secrets/ и вписать свой пароль
Запуск, миграции, проверка, остановка
docker compose --env-file .env config --quiet # 1. валидация конфигурации
docker compose --env-file .env up -d --build # 2. сборка и запуск API+PostgreSQL+Valkey
docker compose ps # 3. дождаться healthy у всех трёх
# Миграции применяются автоматически на старте API (идемпотентно, под advisory-lock);
# отдельно: docker compose exec -T api python -m src.migrate
python tests/smoke.py --base-url http://localhost:8080 # 4. публичный smoke
.venv\Scripts\python -m pytest student-tests -v # свои тесты (см. ниже)
# Сохранность: перезапуск API и всех хранилищ с сохранением volumes
make test-persistence ACTION_SCRIPT=scripts/restart.sh # выполнять в WSL/Linux
# Отказы и expiry
python scripts/check-degradation.py # Valkey/PG down -> 200/503, восстановление
sh scripts/check-expiry.sh # короткий TTL -> 401
# Безопасная остановка (данные сохраняются):
docker compose stop
# Намеренное удаление учебных данных (тома):
docker compose down -v
Оператору нужно: сгенерировать secrets, выполнить шаги 1–4. Повторная сборка — docker compose up -d --build. down -v удаляет данные PostgreSQL и Valkey; обычная остановка/down (без -v) их сохраняет.
Архитектура и решения
Схема: клиент → API (FastAPI/Uvicorn) → PostgreSQL (источник истины); Valkey — read-through кэш сессий.
- Источник истины — PostgreSQL. Таблицы
users(PK,UNIQUE(username),password_hash),chats,chat_members(FK, составной PK),messages(FK),sessions(token_hashPK,user_id,expires_at),schema_migrations. - Транзакционные границы. Создание чата — одна транзакция (вставить
chats+ всехchat_members); при невалидных участниках — rollback и400, частичный объект не остаётся. Регистрация полагается наUNIQUE(username); гонка даёт ровно одного победителя и409остальным. - Аутентификация lab2.
POST /api/v1/usersтребуетpassword(12–128 code points). Пароль хранится как Argon2id (argon2-cffi), не в открытом виде.POST /api/v1/auth/sessionsпринимает толькоAuthorization: Basic base64(username:password)и выдаёт opaque-токен (secrets.token_urlsafe(32), ≥256 бит). В БД хранится SHA-256 токена, не сам токен. Все бизнес-endpoint требуютBearer;X-User-Idигнорируется.DELETE /api/v1/auth/sessions/currentотзывает сессию и отдаёт204. - Сессии и кэш. Сессия валидна, пока
sessions.expires_at > now()(TTL =SESSION_TTL_SECONDS). Valkey кэшируетsession:{sha256(token)} → user_idс TTL до конца жизни сессии. Кэш не является источником истины:current_userвсегда затем читает пользователя из PostgreSQL. При недоступности Valkey кэш обходится (операция ограничена таймаутом 0.5 c + mini circuit breaker, т.к. DNS остановленного контейнера может блокироваться); при недоступности PostgreSQL — ограниченный503, анонимный пользователь не считается доверенным. - Индекс истории.
messages(chat_id, created_at, id)под keyset-запросWHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4; пагинация не сканирует всю историю. Подтверждено EXPLAIN на ≥10 000 сообщений. - Пул и таймауты.
psycopg_pool.ConnectionPoolограниченDB_POOL_MAX(default 10),DB_POOL_TIMEOUT(5 c); на соединенииstatement_timeout=DB_STATEMENT_TIMEOUT_MS(5000 мс). Все запросы параметризованы. - Перенос из lab1. Сохранён HTTP-каркас (маршруты, конверт ошибок,
X-Request-Id, keyset-cursor), но слой данных переписан на PostgreSQL, добавлены миграции, аутентификация заменена на password + Basic/Bearer.X-User-Idудалён. In-memorystore.pylab1 не переносился.
Соответствие .env.example
| Переменная | Роль в решении |
|---|---|
APP_HOST, APP_PORT |
адрес/порт Uvicorn (src/main.py); в compose 0.0.0.0:8080 |
APP_ENV |
метка в лог-строке запуска |
SESSION_TTL_SECONDS |
срок жизни сессии (sessions.expires_at) и TTL кэша |
SESSION_STORE |
valkey/redis — включить кэш Valkey; postgres — без кэша |
DATABASE_URL_FILE |
файл с DSN PostgreSQL (compose secret /run/secrets/database_url) |
CACHE_URL_FILE |
файл с URL Valkey (compose secret /run/secrets/cache_url) |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python tests/smoke.py --base-url http://localhost:8080 |
PASS: lab2 public API scenario |
evidence/lab2-smoke.txt |
| Persistence: данные и сессии переживают рестарт API и хранилищ без удаления volumes | make test-persistence ACTION_SCRIPT=scripts/restart.sh (WSL) |
PASS: persistence preserved confirmed data and existing session; контейнеры перезапущены, volumes на месте |
evidence/lab2-persistence.txt |
| Миграции запускаются с нуля и повторно без дублирования | docker compose exec -T api python -m src.migrate |
migrations up to date; в schema_migrations одна строка |
evidence/lab2-migrations.txt |
| PostgreSQL хранит users/chats/members/messages; PK/FK/UNIQUE; атомарное создание чата | схема + test_race.py, test_negative.py |
rollback при неизвестном участнике; 409 при дубликате username |
evidence/lab2-student-tests.txt |
Basic только на /auth/sessions; Bearer для остальных; TTL и отзыв; X-User-Id не даёт доступ; пароли — KDF |
test_auth.py |
401 Basic/Bearer с корректным challenge; logout → 401 | evidence/lab2-student-tests.txt |
| Уровень 4: Valkey реально используется с TTL, источник истины и политика описаны | check-degradation.py, check-expiry.sh |
cache bypass при отказе Valkey; expiry → 401 | evidence/lab2-degradation.txt, evidence/lab2-expiry.txt |
| Уровень 4: параметризованный SQL, ограниченный pool, таймауты; гонка регистрации и rollback | test_race.py |
один 201 и четыре 409; частичный чат не создан |
evidence/lab2-student-tests.txt |
| Уровень 4: индекс обоснован EXPLAIN на ≥10 000 сообщений, пагинация без full scan | EXPLAIN (ANALYZE, BUFFERS) |
Index Scan using messages_chat_created_id_idx, 0.113 мс, 52 буфера |
evidence/lab2-explain.txt |
| Уровень 4: expiry при коротком TTL, logout, неверный пароль, недоступность Valkey/БД | check-expiry.sh, test_auth.py, check-degradation.py |
expiry 401; logout 401; Valkey down → 200; PG down → 503 | evidence/lab2-expiry.txt, evidence/lab2-student-tests.txt, evidence/lab2-degradation.txt |
Безопасность: секреты вне Git, .env/volumes не коммитятся |
.gitignore, secrets.example/, scripts/gen-secrets.sh |
git status без .env/secrets/ |
описание в PR |
Эксперименты и отказы
Гипотеза: PostgreSQL — источник истины, поэтому рестарт API и хранилищ не теряет данные и активные сессии; Valkey можно потерять без остановки API; потеря PostgreSQL даёт ограниченный 503, а не обход аутентификации. Методика: реальный compose-стенд, синтетические данные, хуки в WSL.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
docker compose restart api postgres valkey |
данные и сессия сохранены | PASS: persistence preserved confirmed data and existing session |
рестарт ≈ секунды; потерь нет |
| Остановка Valkey | API продолжает работать, /health/ready=200 |
/users/me=200, /health/ready=200 (кэш обойдён) |
~0.5 c на операцию кэша, далее fast-path |
| Остановка PostgreSQL | /health/ready=503; аноним не доверяется |
/health/ready=503, /users/me=503, анонимным=503 |
восстановление после старта PG; сессия сохранилась |
| Гонка регистрации одинакового username (5 потоков) | ровно один победитель | 1×201, 4×409 |
n/a |
| Ошибка составной операции (неизвестный участник) | rollback, чат не создан | 400; число чатов не изменилось |
n/a |
Короткий SESSION_TTL_SECONDS=2 |
сессия истекает | before=200, after=401 |
~2 c |
Замеры: единичный стенд на одном Docker-host (Windows/WSL2); throughput-исследование не заявлено (трек 5 не выбран). Числа latency кэша/БД — из логов и EXPLAIN.
Ограничения и следующие шаги
- Выдерживается: перезапуск API и хранилищ с volumes, потеря Valkey (кэш), короткий отказ PostgreSQL с восстановлением, гонки и откат составных операций, некорректный ввод.
- Не выдерживается и не заявлено: отказ самого Docker-host, несколько API-реплик и балансировщик (lab3), вложения (lab4). Единственный инстанс PostgreSQL/Valkey не высокодоступен.
- Учебные упрощения: HTTP без TLS (допустимо для изолированного стенда lab1–6); нет rate limiting и лимитов памяти (трек 5); хук
restart.shперезапускает сервисы, а не выполняет rolling-обновление. - Подтверждено измерениями: сохранность после рестарта, использование индекса (EXPLAIN), отсутствие доверия кэшу/анониму. Гипотеза на будущее: поведение при росте числа реплик и кэш-согласованности — кандидат на трек 5 следующей лабы.