26 KiB
Отчёт — лабораторная 2
- Автор, группа: Гаджиев Нухбала, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR: mtusi2026/mtusi2026lab2#29
- Использованные источники, библиотеки и помощь ИИ: 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 11 в Git Bash. Версии: Docker 29.6.2 (Docker Desktop), Docker Compose v5.3.1, Python 3.11.5 (нужен только для тестов), GNU Make 4.4.1. В контейнерах: python:3.12.8-slim-bookworm (API), postgres:17.10-bookworm, valkey/valkey:8.1.9.
git clone https://gitea.privcloud.tech/ng14/mtusi2026lab2.git && cd mtusi2026lab2
git checkout solution/bvt2303-gadzhiev
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
make ps # api, postgres, valkey: running (healthy)
make check PYTHON=python
make test PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # Linux/macOS: scripts/restart.sh
make student-test PYTHON=python
make race PYTHON=python
make db-test
make expiry PYTHON=python
make failure-valkey PYTHON=python
make failure-postgres PYTHON=python
make failure-valkey-pause PYTHON=python
make explain > evidence/explain-history.txt
По умолчанию тесты ходят на http://127.0.0.1:8080 (в Makefile BASE_URL заменён с localhost на 127.0.0.1: на Windows localhost резолвится очень медленно).
Миграции применяет само приложение при старте (см. «Архитектура»), отдельной команды не нужно. Оператору нужно только один раз создать секреты (sh scripts/init-secrets.sh). Пароли там случайные, на экран не выводятся, в Git не попадают.
Безопасная остановка: make down (= docker compose 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 с) нужен только для make expiry и в этом тесте не участвует.
Почему два 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, 003_text_as_bytes.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.users.display_name,chats.title,messages.textхранятся как байты UTF-8 (bytea, миграция003_text_as_bytes.sql): типtextв PostgreSQL не может хранить символ U+0000, а контракт его разрешает. Точное число символов проверяет API, CHECK в базе ограничивает длину в байтах. Если база отвергнет значение (DataError), клиент получит 400, а не 500.
Транзакционные границы:
- регистрация — один 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, затем кладёт в кэш вместо записи о сессии отметку «отозвано» (на 30 с). Запись о сессии кладётся в кэш только если ключа нет (
SET NX), поэтому запрос, прочитавший сессию из базы за мгновение до logout, не может вернуть её в кэш после logout; - поколение кэша: каждая запись о сессии помечена поколением процесса (случайное значение при старте). При любой ошибке Valkey процесс начинает новое поколение и записям старого больше не доверяет. Если Valkey был недоступен в момент logout (например,
docker compose pause), запись о сессии осталась в кэше, но после возвращения Valkey она старого поколения: проверка идёт в PostgreSQL, там сессия отозвана — 401. Отметки «отозвано» действуют в любом поколении: они только запрещают; - 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 | make test | PASS: lab2 public API scenario | evidence/test.txt |
| Замечание к MR: отозванный токен после возвращения Valkey | make failure-valkey-pause (pause valkey → logout → unpause) | во время паузы logout 204 → 401; после unpause 24 проверки за 12 с, GET и POST — всегда 401; другие токены работают | evidence/failure-valkey-pause.txt |
| Замечание к MR: граничная дата в cursor | make student-test (test_bad_cursor_returns_400) | 0001-01-01T00:00:00+14:00 и 9999-12-31T23:59:59-14:00 в курсоре → 400, не 500 | evidence/student-test.txt |
| Строки с U+0000 сохраняются (нашёл сам по замечанию к похожей работе) | make student-test (test_nul_character_is_stored) | display_name, title и text с U+0000 → 201, читаются без изменений; вход с таким логином → 401, не 500 | evidence/student-test.txt |
| Структура skeleton и контракт не изменены | make check | PASS: offline skeleton structure | evidence/check.txt |
| 3: минимум lab1 сохранён, переход на новую аутентификацию | make test, make student-test (тесты lab1 переведены на пароль и Bearer) | smoke PASS; Ran 22 tests, OK | evidence/test.txt, evidence/student-test.txt |
| 3: данные и действующие сессии переживают рестарт API и хранилищ без удаления volumes | make ps; make test-persistence ACTION_SCRIPT=scripts/restart.cmd; make 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; make db-test | FK не даёт записать сообщение от не-участника (ForeignKeyViolation); дубль username — 409 | migrations/, evidence/db-test.txt |
| 3: миграции с нуля | docker compose up на пустом volume, docker compose logs api | «Миграции применены: 001_core, 002_sessions», затем при обновлении 003_text_as_bytes | evidence/stack.txt, evidence/persistence.txt |
| 3: повторный запуск миграций без дублирования | make db-test; логи api после рестарта | повторный migrate() ничего не применил; «Миграции: новых нет» | evidence/db-test.txt, evidence/persistence.txt |
| 3: создание чата атомарно | make db-test (test_create_chat_rolls_back_when_failing_midway) | ошибка посреди транзакции, строк chats/chat_members не осталось | evidence/db-test.txt |
| 3: Basic только на POST /auth/sessions | make student-test (test_bearer_required_on_business_endpoints) | Basic на /users/me -> 401 с WWW-Authenticate: Bearer | evidence/student-test.txt |
| 3: остальные endpoint требуют Bearer, X-User-Id не даёт доступ | make test, make student-test | только X-User-Id -> 401; X-User-Id рядом с Bearer не меняет пользователя | evidence/test.txt, evidence/student-test.txt |
| 3: срок жизни сессии и отзыв | make expiry; make student-test (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, инвалидация описаны выше) | make test, затем make cache-stats (valkey-cli --user health: dbsize, info stats) | 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 | make race; make db-test | 20 параллельных запросов: 201 x1, 409 x19 | evidence/race.txt, evidence/db-test.txt |
| 4: rollback составной операции | make db-test | см. строку «создание чата атомарно» | evidence/db-test.txt |
| 4: индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | make explain (21 500 сообщений, большой чат 12 000) | первая страница: Index Scan по messages_chat_history_idx, 51 строка, 6 буферов | evidence/explain-history.txt |
| 4: пагинация без полного scan истории | make explain, запросы 2–4 | keyset со страницы из середины: 51 строка, 6 буферов; OFFSET 6000: 6051 строка, 163 буфера; без индекса: Seq Scan по всей таблице, Sort, 289 буферов | evidence/explain-history.txt |
| 4: автопроверка expiry при коротком SESSION_TTL_SECONDS | make expiry (api-short-ttl, TTL=2) | до истечения 200, после — 401 на обоих API | evidence/expiry.txt |
| 4: автопроверка logout | make student-test (test_logout_revokes_only_current_session) | 204, затем 401, повторный logout — 401 | evidence/student-test.txt |
| 4: автопроверка неверного пароля | make student-test (test_wrong_password_and_unknown_user_look_the_same) | одинаковый 401 для неверного пароля и неизвестного пользователя | evidence/student-test.txt |
| 4: недоступность Valkey | make failure-valkey | ready 200, вход, сообщения и logout работают через PostgreSQL | evidence/failure-valkey.txt |
| 4: недоступность БД, аноним не становится доверенным | make failure-postgres | ready 503; бизнес-запросы 503 unavailable; без токена 401; неизвестный токен не принят; после старта БД прежний токен работает | evidence/failure-postgres.txt |
| Выбранный трек 5 | не выбран |
Эксперименты и отказы
Ноутбук: AMD Ryzen 7 4700U (8 ядер), 7,4 ГБ памяти, Windows 11, Docker Desktop без лимитов на CPU и память. Нагрузочных экспериментов нет, так как трек 5 не выбран. Ниже проверки отказов уровня 4.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| restart hook: stop api, restart postgres и valkey, start api (volumes на месте) | данные и токен живы | тот же токен читает то же сообщение; ID контейнеров те же, Up сбросился у api, postgres, valkey; кэш пустой и заполняется из PostgreSQL | весь make test-persistence (создание данных, hook, ожидание готовности, проверка) — 12,5 с; потерь нет |
| docker compose stop valkey | API работает без кэша | ready 200, вход, сообщения, logout работают; первый запрос после остановки ждал около 4 с (на нём обнаружился сбой: подключение к остановленному контейнеру), дальше запросы десятки мс, в том числе через 6 с | после start valkey кэш включается сам в течение 5 с; потерь нет |
| docker compose pause valkey, logout, unpause (данные в кэше сохранились) | отозванный токен не оживает | во время паузы 401; после unpause кэш снова включился, но запись до сбоя старого поколения — 401 при каждой из 24 проверок | кэш снова работает через ≤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 с), следующие идут без кэша сразу.
- Поколение кэша своё у каждого процесса API. Если logout во время сбоя Valkey прошёл через один экземпляр (например, api-short-ttl), а другой экземпляр сбоя не заметил, второй может до 30 с доверять своей старой записи. В lab2 основной API один; для нескольких реплик (lab3) поколение нужно хранить общим.
- Приложение подключается к PostgreSQL пользователем-владельцем базы. Отдельная роль с минимальными правами — в lab7.
- Basic по HTTP передаёт пароль открыто (base64 — это не шифрование). Допустимо только на локальном стенде, TLS — в lab7.
- Старые сессии чистятся только при входе того же пользователя; периодической очистки нет.
- Свободный текст хранится как
bytea: искать по нему средствами SQL (LIKE, полнотекстовый поиск) напрямую нельзя. Обязательный API такого поиска не требует.