24 KiB
Отчёт — лабораторная 2
- Автор, группа: Боцоев Арсен, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR:
- Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, psycopg 3 + psycopg-pool, argon2-cffi, valkey-py (версии в requirements.txt); образы postgres:17.10-bookworm и valkey/valkey:8.1.9; документация PostgreSQL (транзакции, EXPLAIN), Valkey (ACL, persistence), RFC 7617. ИИ использовался для оценки качества решения, написания комментариев к коду и помощи в составлении отчета.
Запуск из чистого clone
Проверял на Windows 10 в Git Bash. Версии: Docker 29.4.2 , Docker Compose v5.1.3, Python 3.11.9 (команда python, нужен только для тестов). GNU Make в Git Bash и в PATH нет, поэтому ниже те же действия, что в Makefile, вызваны напрямую. В контейнерах: python:3.12.8-slim-bookworm (API), postgres:17.10-bookworm, valkey/valkey:8.1.9.
git clone https://gitea.privcloud.tech/pepega/mtusi2026lab2Fork.git && cd mtusi2026lab2Fork
cp .env.example .env
sed -i 's/\r$//' .env # только Windows: убрать \r из .env
sh scripts/init-secrets.sh # создаёт secrets/ со случайными паролями (каталог в .gitignore)
docker compose up -d --build --wait # сборка API, запуск PostgreSQL и Valkey, ожидание healthy
# localhost на этой Windows резолвится очень медленно, поэтому тесты ходят на 127.0.0.1.
export BASE_URL=http://127.0.0.1:8080
export BASE_URL_TTL=http://127.0.0.1:8081
docker compose ps -a --format "table {{.Service}}\t{{.ID}}\t{{.Status}}" # api, postgres, valkey: running (healthy)
python scripts/check_contract.py
python tests/smoke.py --base-url "$BASE_URL"
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url "$BASE_URL" # Linux/macOS: scripts/restart.sh
python -m unittest discover -s student-tests -p "test_*.py" -v
python student-tests/race.py
docker compose --profile tools run --rm db-test
docker compose --profile ttl up -d --wait api-short-ttl
python student-tests/expiry.py
python student-tests/dependency_failure.py valkey
python student-tests/dependency_failure.py postgres
docker compose exec -T postgres psql -X -q -U messenger -d messenger -v ON_ERROR_STOP=1 < infra/sql/explain_history.sql > evidence/explain-history.txt
По умолчанию публичный клиент ходит на http://localhost:8080. В блоке выше задан BASE_URL=http://127.0.0.1:8080: на Windows localhost резолвится очень медленно.
Миграции применяет само приложение при старте (см. «Архитектура»), отдельной команды не нужно. Оператору нужно только один раз создать секреты (sh scripts/init-secrets.sh). Пароли там случайные, на экран не выводятся, в Git не попадают.
Безопасная остановка: docker compose --profile ttl --profile tools down (контейнеры удаляются, volume с данными остаётся; следующий docker compose up -d --wait поднимет те же данные). Намеренное удаление учебных данных: docker compose down -v (удаляет volume pgdata), после этого rm -rf secrets и заново sh scripts/init-secrets.sh.
В persistence-тесте перезапускаются api, postgres и valkey. Сервис api-short-ttl (второй API с TTL 2 с) нужен только для python student-tests/expiry.py и в этом тесте не участвует.
Почему два restart-скрипта: тест вызывает hook напрямую, без shell. Python на Windows не может запустить .sh (ошибка WinError 193), поэтому для Windows есть scripts/restart.cmd с теми же командами. scripts/restart.sh — то же самое для Linux/macOS.
Архитектура и решения
клиент ──HTTP──> api (FastAPI, :8080 только на 127.0.0.1)
├──> postgres (источник истины: users, chats, chat_members, messages, sessions; volume pgdata)
└──> valkey (кэш «hash токена -> пользователь», без persistence)
PostgreSQL и Valkey наружу не опубликованы, доступны только из сети стенда backend.
Что перенесено из lab1 и что изменилось:
api.py,errors.py,cursor.py,config.py, Dockerfile, свои тесты перенесены. Маршруты, проверка входных данных, формат ошибок, X-Request-Id, логи без текстов остались как были.store.py: вместо словарей в памяти иthreading.Lockтеперь PostgreSQL. Методы те же, поэтомуapi.pyпочти не изменился. Согласованность теперь держат транзакции и ограничения БД.- Новое:
db.py(пул соединений, таймауты, миграции),security.py(Argon2id, токены, разбор Basic/Bearer),sessions.py(сессии и кэш в Valkey),migrations/*.sql,compose.yaml, скрипты. - Аутентификация: регистрация с
password, входPOST /auth/sessionsтолько с Basic, дальше толькоAuthorization: Bearer.X-User-Idбольше ничего не значит. Проверка токена выполняется в middleware до разбора тела запроса, поэтому всегда сначала 401, потом 404/400.
Схема БД (migrations/001_core.sql, 002_sessions.sql):
users: PK id, UNIQUE username, CHECK формата username и длины display_name,password_hash(Argon2id).chatsиchat_members: PK (chat_id, user_id), FK на chats и users, индекс (user_id, chat_id) для списка чатов пользователя.messages: FK (chat_id, sender_id) -> chat_members, то есть сама база не даст записать сообщение от не-участника. Индекс (chat_id, created_at, id) под историю.sessions: PK = SHA-256 токена (сам токен не хранится), user_id, expires_at, revoked_at.
Транзакционные границы:
- регистрация — один INSERT; дубль username ловит уникальный индекс (409), а не проверка «есть ли такой» в коде (она уязвима к гонке);
- создание чата — одна транзакция: проверка участников, INSERT чата, INSERT всех участников. Ошибка на любом шаге = ROLLBACK, чата нет;
- отправка сообщения — один INSERT ... SELECT, вставляет строку только если отправитель состоит в чате;
- вход — одна транзакция: удаление старых истёкших/отозванных сессий пользователя и INSERT новой.
Миграции: файлы migrations/NNN_*.sql применяются при старте API по порядку. Каждый файл и запись о нём в schema_migrations идут в одной транзакции. Повторный запуск применяет только новые файлы. Если стартуют сразу два API (основной и api-short-ttl), pg_advisory_lock пускает к миграциям только один процесс.
Сессии и роль Valkey:
- источник истины — таблица
sessionsв PostgreSQL. Она переживает рестарт, срокexpires_atабсолютный, рестарт его не продлевает; - Valkey — кэш, чтобы не делать SQL-запрос при каждой проверке токена. Ключ
sess:<sha256 токена>, значение — пользователь и expires_at; - expiry в кэше: TTL ключа = min(30 с, остаток жизни сессии); кроме того, expires_at проверяется при чтении, поэтому кэш никогда не продлевает сессию;
- инвалидация: logout сначала ставит revoked_at в PostgreSQL, затем запоминает hash токена в процессе и удаляет ключ из кэша. Если DEL не дошёл, hash всё равно остаётся в памяти процесса: после восстановления Valkey старая запись не принимается. Записи кэша помечены эпохой процесса; при сбое эпоха меняется, и ключи, записанные до него, читаются заново из PostgreSQL;
- persistence у Valkey выключена: кэш после рестарта пустой, данные снова берутся из PostgreSQL;
- если Valkey недоступен, API его обходит и работает напрямую с PostgreSQL. После первой ошибки запросы перестают обращаться к кэшу, а фоновый поток раз в 5 с делает PING и, когда Valkey вернулся, снова включает кэш. Так ожидание подключения к пропавшему Valkey не попадает в запросы пользователей;
- у Valkey ACL: пользователь
defaultвыключен,messenger(пароль из secrets) может только get/set/del/ping и только по ключамsess:*,health(без пароля) — только ping/info/dbsize.
Пароли и токены: пароль хешируется Argon2id (m=19 МиБ, t=2, p=1 — минимум по OWASP), это медленная функция с солью против перебора. Токен — 32 случайных байта (256 бит), в БД и кэше лежит только его SHA-256: быстрый hash подходит, потому что токен случайный и перебирать его бессмысленно. Неверный пароль и несуществующий пользователь дают одинаковый 401 за одинаковое время (для несуществующего пользователя тоже выполняется проверка Argon2).
Пул и таймауты: PostgreSQL — пул psycopg от 1 до 10 соединений, ожидание соединения 3 с, connect_timeout 3 с, statement_timeout 5 с, idle_in_transaction_session_timeout 10 с; соединение проверяется перед выдачей (после рестарта БД «мёртвые» соединения заменяются). Valkey — пул до 20 соединений, таймаут 300 мс. Все SQL-запросы параметризованные (%s), текст запроса никогда не склеивается с вводом пользователя.
Health: /health/live — процесс жив. /health/ready — PostgreSQL отвечает (таймаут 1 с). Критична только PostgreSQL; без Valkey API готов (работает медленнее). Docker healthcheck API опрашивает /health/ready.
Durability: PostgreSQL с fsync=on, synchronous_commit=on, full_page_writes=on (значения по умолчанию, выписаны явно в compose.yaml). Ответ 201 отдаётся после COMMIT, а COMMIT — после записи WAL на диск, поэтому подтверждённое сообщение переживает рестарт и падение процесса БД. Данные лежат в именованном volume pgdata.
Соответствие .env.example:
| Переменная | Что делает в этом решении |
|---|---|
| APP_HOST, APP_PORT, APP_ENV | где слушает uvicorn (0.0.0.0:8080), APP_ENV пишется в лог |
| SESSION_TTL_SECONDS | срок жизни сессии (3600; у api-short-ttl в compose.yaml — 2) |
| DATABASE_URL_FILE | путь к секрету с адресом PostgreSQL (/run/secrets/database_url) |
| SESSION_STORE=postgres | источник истины сессий — PostgreSQL (другие значения не поддерживаются) |
| CACHE_URL_FILE | путь к секрету с адресом Valkey; пусто = работать без кэша |
| SESSION_CACHE_TTL_SECONDS, DB_, CACHE_ | дополнительные: TTL записи в кэше, размер пула и таймауты |
Секреты передаются файлами через secrets: в Compose (/run/secrets/...), а не значениями переменных, поэтому не видны в docker inspect. .env и secrets/ в .gitignore.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python tests/smoke.py --base-url "$BASE_URL" | PASS: lab2 public API scenario | evidence/test.txt |
| Структура skeleton и контракт не изменены | python scripts/check_contract.py | PASS: offline skeleton structure | evidence/check.txt |
| 3: минимум lab1 сохранён, переход на новую аутентификацию | smoke и python -m unittest discover -s student-tests -p "test_*.py" -v (тесты lab1 переведены на пароль и Bearer) | smoke PASS; Ran 21 tests, OK | evidence/test.txt, evidence/student-test.txt |
| 3: данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | docker compose ps; python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url "$BASE_URL"; docker compose ps | PASS: persistence preserved confirmed data and existing session; ID контейнеров те же, время Up у api, postgres, valkey сбросилось | evidence/persistence.txt |
| 3: в PostgreSQL пользователи, чаты, участники, сообщения; PK/FK; уникальный username | migrations/001_core.sql; docker compose --profile tools run --rm db-test | FK не даёт записать сообщение от не-участника (ForeignKeyViolation); дубль username — 409 | migrations/, evidence/db-test.txt |
| 3: миграции с нуля | docker compose up на пустом volume, docker compose logs api | «Миграции применены: 001_core, 002_sessions» | evidence/stack.txt |
| 3: повторный запуск миграций без дублирования | db-test; логи api после рестарта | повторный migrate() ничего не применил; «Миграции: новых нет» | evidence/db-test.txt, evidence/persistence.txt |
| 3: создание чата атомарно | db-test (test_create_chat_rolls_back_when_failing_midway) | ошибка посреди транзакции, строк chats/chat_members не осталось | evidence/db-test.txt |
| 3: Basic только на POST /auth/sessions | student-tests (test_bearer_required_on_business_endpoints) | Basic на /users/me -> 401 с WWW-Authenticate: Bearer | evidence/student-test.txt |
| 3: остальные endpoint требуют Bearer, X-User-Id не даёт доступ | smoke и student-tests | только X-User-Id -> 401; X-User-Id рядом с Bearer не меняет пользователя | evidence/test.txt, evidence/student-test.txt |
| 3: срок жизни сессии и отзыв | python student-tests/expiry.py; student-tests (test_logout_*) | после TTL 2 с -> 401; после logout -> 401, другая сессия работает | evidence/expiry.txt, evidence/student-test.txt |
| 3: пароли хешируются password KDF | docker compose exec postgres psql ... SELECT left(password_hash, 30) | $argon2id$v=19$m=19456,t=2,p=1 | evidence/stack.txt |
| 3: secrets и volumes не попадают в Git | git check-ignore -v .env secrets/database_url | оба файла игнорируются правилами .gitignore | evidence/stack.txt |
| 4: Valkey реально используется для кэша сессий (источник истины, expiry, инвалидация описаны выше) | smoke, затем valkey-cli --user health: dbsize, info stats, get | keyspace_hits больше нуля, ключи sess:* есть; доступ к другим ключам — NOPERM | evidence/valkey.txt |
| 4: параметризованные запросы | src/messenger/store.py | все значения передаются через %s, SQL не склеивается | код |
| 4: ограниченный connection pool и таймауты | src/messenger/db.py, config.py | пул PostgreSQL 1–10, таймауты 3 с/3 с/5 с; пул Valkey 20, 300 мс | код |
| 4: гонка регистрации одинакового username | python student-tests/race.py; db-test | 20 параллельных запросов: 201 x1, 409 x19 | evidence/race.txt, evidence/db-test.txt |
| 4: rollback составной операции | db-test | см. строку «создание чата атомарно» | evidence/db-test.txt |
| 4: индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | explain (21 614 сообщений, большой чат 12 000) | первая страница: Index Scan по messages_chat_history_idx, 51 строка, 4 буфера | evidence/explain-history.txt |
| 4: пагинация без полного scan истории | explain, запросы 2–4 | keyset со страницы из середины: 51 строка, 4 буфера; OFFSET 6000: 6051 строка, 161 буфер; без индекса: Seq Scan по всей таблице, Sort, 291 буфер | evidence/explain-history.txt |
| 4: автопроверка expiry при коротком SESSION_TTL_SECONDS | python student-tests/expiry.py (api-short-ttl, TTL=2) | до истечения 200, после — 401 на обоих API | evidence/expiry.txt |
| 4: автопроверка logout | student-tests (test_logout_revokes_only_current_session) | 204, затем 401, повторный logout — 401 | evidence/student-test.txt |
| 4: автопроверка неверного пароля | student-tests (test_wrong_password_and_unknown_user_look_the_same) | одинаковый 401 для неверного пароля и неизвестного пользователя | evidence/student-test.txt |
| 4: недоступность Valkey | python student-tests/dependency_failure.py valkey | ready 200, вход и сообщения через PostgreSQL; после unpause отозванный токен остаётся 401 | evidence/failure-valkey.txt |
| 4: недоступность БД, аноним не становится доверенным | python student-tests/dependency_failure.py postgres | ready 503; бизнес-запросы 503 unavailable; без токена 401; неизвестный токен не принят; после старта БД прежний токен работает | evidence/failure-postgres.txt |
| Выбранный трек 5 | не выбран |
Эксперименты и отказы
Windows 10 Pro, Docker Desktop 29.4.2 без лимитов на CPU и память. Нагрузочных экспериментов нет, так как трек 5 не выбран. Ниже проверки отказов уровня 4.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| restart hook: stop api, restart postgres и valkey, start api (volumes на месте) | данные и токен живы | тот же токен читает то же сообщение; ID контейнеров те же, Up сбросился у api, postgres, valkey; кэш пустой и заполняется из PostgreSQL | весь persistence-тест (создание данных, hook, ожидание готовности, проверка) — 11 с; потерь нет |
| docker compose pause valkey (память кэша сохраняется), logout токена, который уже был в кэше, unpause | API работает без кэша; после восстановления отозванный токен остаётся 401 | ready 200, вход, сообщения и logout идут через PostgreSQL; после unpause тот же токен снова 401 | кэш включается сам в течение 5 с; отозванная сессия не оживает |
| docker compose stop postgres | ограниченная ошибка, никого не пускаем без проверки | ready 503 за ~1 с, бизнес-запросы 503, без токена 401 | после start postgres прежний токен и сообщения на месте; запросы во время отказа не сохранены (получили 503) |
| 20 одновременных регистраций одного username | один победитель | 201 x1, 409 x19 | дублей нет |
| 10 клиентов x 10 сообщений одновременно | ровно 100 сообщений | 100, все id уникальны | потерь нет |
Ограничения и следующие шаги
- PostgreSQL одна: если упала она или весь Docker-host, API отвечает 503. Отказоустойчивости к потере хоста нет, бэкапов нет.
- Конкурентные вставки: created_at = время начала транзакции. Сообщение, которое закоммитилось позже, может получить более раннее время, и клиент, уже пролиставший дальше по курсору, его не увидит. Повторов нет, но такую запись можно пропустить; это ограничение keyset-пагинации по времени.
- Первый запрос после пропадания Valkey ждёт обнаружения сбоя (на Windows/Docker Desktop около 4 с), следующие идут без кэша сразу.
- Hash отозванных токенов помнит процесс API. После рестарта самого API их снова подтверждает PostgreSQL; эпоха кэша при этом уже другая, поэтому старый ключ Valkey не оживает.
- Приложение подключается к PostgreSQL пользователем-владельцем базы. Отдельная роль с минимальными правами — в lab7.
- Basic по HTTP передаёт пароль открыто (base64 — это не шифрование). Допустимо только на локальном стенде, TLS — в lab7.
- Старые сессии чистятся только при входе того же пользователя; периодической очистки нет.