23 KiB
Отчёт — лабораторная 2
- Автор, группа: Бабиченко Максим, БВТ2303
- Целевая оценка; 4
- Commit/PR: mtusi2026/mtusi2026lab2#26
- Использованные источники, библиотеки и помощь ИИ: FastAPI, Uvicorn, Pydantic, psycopg 3 и psycopg-pool, argon2-cffi, redis-py (точные версии в requirements.txt); образы python:3.11.13-slim, postgres:17.11-alpine, redis:7.4.11-alpine; документация PostgreSQL (транзакции, индексы, EXPLAIN), документация Redis (persistence, AOF), RFC 7617 (Basic). Помощь ИИ: использовался как консультант по git и PowerShell, для разбора ошибок Docker (монтирование секретов, пароль PostgreSQL в старом volume)
Запуск из чистого clone
Проверял на Windows 11, все команды в PowerShell. Версии: Docker 28.1.1 (Docker Compose v2.35.1-desktop.1), Python <<python --version>> (Python нужен только для тестов, приложение работает в контейнере).
git clone https://gitea.privcloud.tech/Kalibr/mtusi2026lab2.git
cd mtusi2026lab2
git checkout solution/bvt2303-babichenko
Copy-Item .env.example .env
python scripts/init_secrets.py # случайные пароли в secrets/ (папка в .gitignore)
docker compose up -d --build --wait # api, postgres, redis; ждём статус healthy
docker compose ps
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.cmd --base-url http://127.0.0.1:8080
python student-tests/test_api.py
python student-tests/test_race.py
python student-tests/test_db.py
python student-tests/test_expiry.py
python student-tests/test_failures.py
python student-tests/redis_info.py
python student-tests/explain.py # пишет evidence/explain-history.txt
Это те же проверки, что в Makefile, только без make (на моём Windows его нет): make check = python scripts/check_contract.py, make test = python tests/smoke.py ..., make test-persistence ACTION_SCRIPT=... = python tests/resilience.py --mode persistence .... Где 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. Адрес 127.0.0.1 вместо localhost: на Windows localhost сначала пробует IPv6 и отвечает медленнее.
На Linux/macOS вместо scripts/restart.cmd указывается scripts/restart.sh. Restart-скриптов два, потому что тест запускает hook напрямую, без shell, а Python на Windows не умеет запускать .sh (ошибка WinError 193). Команда в обоих одна: docker compose restart.
Миграции применяет само приложение при старте, отдельной команды нет. Секреты создаются один раз скриптом scripts/init_secrets.py, значения на экран не выводятся.
Остановка без потери данных: docker compose down (контейнеры удаляются, volumes pgdata и redisdata остаются, следующий docker compose up -d --wait поднимает те же данные). Намеренное удаление учебных данных: docker compose down -v, затем удалить папку secrets и снова запустить python scripts/init_secrets.py.
Архитектура и решения
Клиент --HTTP--> api (FastAPI, порт 8080 только на 127.0.0.1)
|--> postgres пользователи, чаты, участники, сообщения (volume pgdata)
|--> redis сессии: session:<SHA-256 токена> -> id пользователя (AOF, volume redisdata)
PostgreSQL и Redis наружу не опубликованы, к ним ходит только API внутри сети Compose.
| Роль | Сервис Compose | Версия | Health / готовность | Volume | Сеть / порт | Credentials |
|---|---|---|---|---|---|---|
| API | api (собирается из Dockerfile) |
python:3.11.13-slim | /health/ready (Docker HEALTHCHECK) |
нет | 127.0.0.1:8080 на хосте |
читает /run/secrets/database_url и /run/secrets/cache_url |
| База данных | postgres |
postgres:17.11-alpine | pg_isready |
pgdata |
только сеть Compose, 5432 | POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password |
| Сессии | redis |
redis:7.4.11-alpine | redis-cli ping с паролем |
redisdata (AOF) |
только сеть Compose, 6379 | include /run/secrets/redis_auth (requirepass) |
Bootstrap: секреты — python scripts/init_secrets.py (повторный запуск ничего не меняет), схема — миграции при старте API (повторный старт ничего не применяет). Redis подготовки не требует.
Что перенесено из lab1 и что изменилось:
main.pyостался главным файлом: модели Pydantic, формат ошибок, X-Request-Id, курсоры и маршруты из lab1. Вместо словарейusers,chats,messagesмаршруты вызывают функции изdb.py.- Новые файлы:
db.py(пул соединений, миграции, SQL-запросы),auth.py(Argon2id, разбор Basic/Bearer, сессии в Redis),settings.py(настройки из окружения и секретов),errors.py(ошибка API с кодом),migrations/001_init.sql,compose.yaml,infra/redis.conf, скрипты вscripts/. - Вход: регистрация с
password,POST /api/v1/auth/sessionsтолько с Basic, дальше толькоAuthorization: Bearer.X-User-Idбольше ничего не значит. Токен проверяется в middleware до разбора тела, поэтому без токена всегда 401, а не 400 или 404. - Свои тесты lab1 лежали в
tests/test_lab1.py. По CONTRIBUTING публичную папкуtests/переносить нельзя, поэтому свои тесты теперь вstudent-tests/и переведены на пароль и Bearer. - Контейнер теперь запускается командой
python main.py: хост и порт берутся из окружения, при SIGTERM uvicorn ждёт начатые запросы не дольше 5 с.
Схема БД (migrations/001_init.sql):
users: PKid, UNIQUEusername, CHECK формата username и длины display_name,password_hash.chats;chat_membersс PK (chat_id, user_id) и FK наchatsиusers; индекс поuser_idдля списка чатов.messages: FK (chat_id, sender_id) ->chat_members, то есть база сама не даст записать сообщение от того, кто не в чате. Индекс(chat_id, created_at, id)под историю.
Транзакции:
- регистрация: один INSERT. Повтор username ловит уникальный индекс (ответ 409), без проверки «есть ли такой» в коде, которая пропустила бы две одновременные регистрации;
- создание чата: одна транзакция, сначала INSERT чата, потом всех участников. Если участника нет, FK падает, транзакция откатывается целиком, ответ 400;
- сообщение: один INSERT; если отправитель не в чате, срабатывает FK и ответ 404.
Миграции: файлы migrations/*.sql применяются при старте API по порядку. Применённые записываются в schema_migrations, повторный старт ничего не применяет. Файл и запись о нём в одной транзакции. pg_advisory_lock не даёт двум API применять миграции одновременно.
Сессии и роль Redis:
- источник истины для сессий — Redis, это единственное хранилище сессий (README допускает такой вариант при включённой persistence). Ключ
session:<SHA-256 токена>, значение — id пользователя. Сам токен нигде не хранится; - истечение: у ключа абсолютное время истечения (
SET ... PXAT), равноеexpires_atиз ответа. Redis удаляет ключ сам, рестарт срок не продлевает; - сброс: logout удаляет ключ (
DEL).FLUSHALLили удаление volumeredisdataудалят все сессии, всем придётся войти заново; пользователи и сообщения в PostgreSQL при этом не пострадают; - сохранность: раз Redis — единственное хранилище сессий, одного TTL мало, включён AOF с
appendfsync always: Redis отвечает «OK» только после записи на диск. Поэтому после рестарта Redis действующие токены работают, и даже после аварийногоdocker compose kill redis; maxmemory-policy noeviction: при нехватке памяти Redis откажет во входе (503), но не удалит молча чужие сессии;- Redis закрыт паролем (
requirepassиз секретаsecrets/redis_auth).
Пароли и токены: пароль хешируется Argon2id (m=12 МиБ, t=3, p=1, один из вариантов OWASP) с солью. Токен — 32 случайных байта (256 бит). Для ключа в Redis используется быстрый SHA-256: токен случайный, подбирать его бессмысленно. Неверный пароль и несуществующий пользователь дают одинаковый 401, и для несуществующего пароль тоже проверяется, чтобы время ответа было одинаковым.
Пул и таймауты: PostgreSQL — пул psycopg от 1 до 10 соединений, ожидание соединения 3 с, подключение 3 с, statement_timeout 5 с, соединение проверяется перед выдачей. Redis — пул до 20 соединений, таймауты 500 мс, без повторов. Все SQL-запросы параметризованные (%s).
Health: /health/live — процесс жив. /health/ready — отвечают и PostgreSQL, и Redis: без любого из них обычный запрос обслужить нельзя. Docker healthcheck API проверяет /health/ready.
Durability: PostgreSQL с fsync=on и synchronous_commit=on (значения по умолчанию, в compose.yaml записаны явно). 201 отдаётся после COMMIT, а COMMIT — после записи WAL на диск. Данные в именованном volume pgdata.
Соответствие .env.example:
| Переменная | Что делает в этом решении |
|---|---|
| APP_HOST, APP_PORT, APP_ENV | где слушает API (0.0.0.0:8080), APP_ENV пишется в лог при старте |
| SESSION_TTL_SECONDS | срок жизни сессии, 3600 с; тест истечения временно запускает API с 2 с |
| DATABASE_URL_FILE | путь к секрету с адресом PostgreSQL (/run/secrets/database_url) |
| SESSION_STORE=redis | сессии хранятся в Redis (другие значения не поддерживаются) |
| CACHE_URL_FILE | путь к секрету с адресом Redis (/run/secrets/cache_url) |
| DB_, REDIS_ | дополнительные: размеры пулов и таймауты |
Секреты передаются файлами через secrets: в Compose (/run/secrets/...), а не значениями переменных, поэтому их нет в docker inspect. .env и secrets/ в .gitignore.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python tests/smoke.py --base-url http://127.0.0.1:8080 |
PASS | evidence/smoke.txt |
| Skeleton и контракт не изменены | python scripts/check_contract.py |
PASS | evidence/check.txt |
| 3: минимум lab1 сохранён, переход на новую аутентификацию | smoke; python student-tests/test_api.py (тесты lab1 переведены на пароль и Bearer) |
smoke PASS; 18 passed, 0 failed | evidence/smoke.txt, evidence/student-tests.txt |
| 3: данные и сессии переживают рестарт API и хранилищ без удаления volumes | docker compose ps; resilience.py с scripts/restart.cmd; docker compose ps |
PASS; ID контейнеров те же, время Up у api, postgres и redis сбросилось | evidence/persistence.txt |
| 3: PostgreSQL: users, chats, members, messages; PK/FK; уникальный username | migrations/001_init.sql; python student-tests/test_db.py |
UNIQUE (username); прямой INSERT сообщения от не-участника отклонён по FK | evidence/db.txt |
| 3: миграции с нуля | docker compose up на пустом volume, docker compose logs api |
«Migrations applied: 001_init.sql» | evidence/stack.txt |
| 3: повторный запуск миграций без дублирования | test_db.py (рестарт api) | «Migrations applied: none», в schema_migrations одна запись | evidence/db.txt |
| 3: создание чата атомарно | test_db.py (test_create_chat_rolls_back) | 400; строки чата нет, хотя счётчик вставок в chats вырос: вставка была и откатилась | evidence/db.txt |
| 3: Basic только на POST /auth/sessions | test_api.py (test_bearer_required) | Basic на /users/me -> 401 с WWW-Authenticate: Bearer | evidence/student-tests.txt |
| 3: остальные endpoint требуют Bearer, X-User-Id не даёт доступ | test_api.py (test_bearer_required, test_x_user_id_ignored) | только X-User-Id -> 401; X-User-Id рядом с токеном не меняет пользователя | evidence/student-tests.txt |
| 3: срок жизни сессии и logout | python student-tests/test_expiry.py; test_api.py (test_logout) |
после TTL 2 с -> 401 и ключа в Redis нет; после logout -> 401, вторая сессия работает | evidence/expiry.txt, evidence/student-tests.txt |
| 3: пароль хешируется password KDF | test_db.py (test_password_is_argon2id) | $argon2id$v=19$m=12288,t=3,p=1$... |
evidence/db.txt |
| 3: secrets и volumes не попадают в Git | git check-ignore -v .env secrets/database_url |
оба файла игнорируются | evidence/stack.txt |
| 4: Redis реально используется (источник истины, expiry, сброс описаны выше) | docker compose exec redis ...: число ключей session:*, TTL ключа, настройки AOF |
ключи session:* есть, TTL около 3600 с, appendonly yes, appendfsync always | evidence/redis.txt |
| 4: параметризованные запросы | db.py |
все значения через %s, SQL не склеивается со вводом |
код |
| 4: ограниченный пул и таймауты | db.py, auth.py, settings.py |
PostgreSQL: пул 1–10, 3 с / 3 с / 5 с; Redis: пул 20, 500 мс | код |
| 4: гонка регистрации одного username | python student-tests/test_race.py |
20 параллельных запросов: 201 x1, 409 x19 | evidence/race.txt |
| 4: rollback составной операции | test_db.py | см. строку «создание чата атомарно» | evidence/db.txt |
| 4: индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | python student-tests/explain.py (20 000 сообщений, большой чат 15 000) |
Index Scan по messages_history, 51 строка, 4 буфера | evidence/explain-history.txt |
| 4: пагинация без полного scan истории | explain.py, запросы 2–4 | keyset после 10 000-го сообщения: 6 буферов; OFFSET 10000: 10 051 строка и 257 буферов; без индекса: Seq Scan по всей таблице и Sort, 255 буферов | evidence/explain-history.txt |
| 4: автопроверка expiry при коротком SESSION_TTL_SECONDS | test_expiry.py (API пересоздаётся с TTL=2) | до истечения 200, после 401 | evidence/expiry.txt |
| 4: автопроверка logout | test_api.py (test_logout) | 204, потом 401, повторный logout 401 | evidence/student-tests.txt |
| 4: автопроверка неверного пароля | test_api.py (test_wrong_password) | одинаковый 401 для неверного пароля и неизвестного пользователя | evidence/student-tests.txt |
| 4: недоступность Redis | python student-tests/test_failures.py redis |
ready 503; с токеном 503; с чужим токеном 503, а не 200; без токена 401; регистрация 201 | evidence/failures.txt |
| 4: persistence Redis выдерживает проверяемый рестарт | resilience.py (restart всего стенда); test_failures.py redis (test_redis_crash: docker compose kill redis, затем start) |
прежний токен работает и после обычного рестарта, и после аварийной остановки | evidence/persistence.txt, evidence/failures.txt |
| 4: недоступность БД, аноним не становится доверенным | python student-tests/test_failures.py postgres |
ready 503; бизнес-запросы 503 без подробностей; без токена и с чужим токеном 401; после старта БД прежний токен работает | evidence/failures.txt |
| Выбранный трек 5 | не выбран |
Эксперименты и отказы
Компьютер: <<процессор, память>>, Windows 11, Docker Desktop без отдельных лимитов. Дата прогона: 9 октября 2026. Нагрузочных экспериментов нет, трек 5 не выбран. Ниже проверки отказов уровня 4.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
restart hook: docker compose restart (api, postgres, redis), volumes на месте |
данные и токен живы | тот же токен читает то же сообщение | около 3,6 с (real 00:03.587); потерь нет |
docker compose stop redis |
без проверки сессии никого не пускаем | ready 503, запросы с токеном 503, без токена 401, регистрация 201 | после start redis прежний токен работает сразу; сессии не потеряны (AOF) |
docker compose kill redis (SIGKILL, без корректной остановки) |
сессии не теряются | сессия, выданная до сбоя, работает после start redis |
потерь нет: каждая запись в AOF на диске до ответа «OK» |
docker compose stop postgres |
ограниченная ошибка, анонимов не пускаем | ready 503, бизнес-запросы 503, без токена и с чужим токеном 401 | после start postgres токен и сообщения на месте; запросы во время отказа не сохранены (получили 503) |
| 20 одновременных регистраций одного username | один победитель | 201 x1, 409 x19 | дублей нет |
| 10 клиентов x 10 сообщений одновременно | ровно 100 сообщений | 100, все id уникальны | потерь нет |
Ограничения и следующие шаги
- Одна PostgreSQL и один Redis, без реплик и бэкапов. Упал любой из них — API отвечает 503.
- Если Redis недоступен, не работает никто из вошедших: сессии хранятся только там. Цена — простая схема: один источник истины для сессий.
- Если потерять volume
redisdataили выполнитьFLUSHALL, все пользователи разлогинятся (данные в PostgreSQL останутся). - Время сообщения — время начала транзакции. При одновременных вставках сообщение, закоммиченное позже, может получить более раннее время, и клиент, уже пролиставший историю дальше, его не увидит. Это ограничение keyset-пагинации по времени.
- API подключается к PostgreSQL владельцем базы. Отдельная роль с минимальными правами — в lab7.
- Basic по HTTP передаёт пароль открыто (base64 — не шифрование). Допустимо только на локальном стенде, TLS — в lab7.