Files
mtusi2026lab2/REPORT.md
2026-10-09 15:19:03 +03:00

23 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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: PK id, UNIQUE username, 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 или удаление volume redisdata удалят все сессии, всем придётся войти заново; пользователи и сообщения в 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.