Files
mtusi2026lab2/REPORT.md
T
ng14 d0eaaea5b6
Skeleton contracts / contracts (pull_request) Canceled after 0s
исправление замечаний
2026-10-10 00:22:30 +03:00

26 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Гаджиев Нухбала, БВТ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
  • Commit/PR: #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 такого поиска не требует.