Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор, группа: Саргсян Сона, БВТ2302
  • Целевая оценка: 4
  • Commit/PR:
  • Использованные источники, библиотеки и помощь ИИ: Claude Code. Библиотеки: FastAPI, Pydantic, Uvicorn, asyncpg, argon2-cffi, redis-py (клиент для Valkey).

Запуск из чистого clone

Нужны Git, Docker с запущенным daemon (Compose v2), Make, Python 3.9+ (для публичных проверок, только стандартная библиотека) и openssl. Порты 8080 (API), 18080 (только SIGTERM-тест) должны быть свободны. При первой сборке нужен доступ к Docker Hub и PyPI.

Версии: Python 3.12.7 (образ python:3.12.7-slim, закреплён digest), FastAPI 0.115.2, Pydantic 2.14.1, Uvicorn 0.32.0, asyncpg 0.30.0, argon2-cffi 23.1.0, redis-py 5.2.1, PostgreSQL 16.6 (postgres:16.6-alpine), Valkey 8.0.1 (valkey/valkey:8.0.1-alpine). Все runtime-зависимости закреплены в requirements.txt.

Действия оператора (один раз). Секреты создаются локально и в Git не попадают (secrets/ и .env в .gitignore и .dockerignore):

mkdir -p secrets
PW=$(openssl rand -hex 24)
printf '%s' "$PW" > secrets/postgres_password
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$PW" > secrets/database_url
chmod 644 secrets/*
cp .env.example .env
chmod +x scripts/restart.sh

Права 644 нужны, чтобы непривилегированный пользователь app в контейнере прочитал секрет; допустимо только для локального стенда с синтетическими данными.

Сборка, миграции и запуск. Миграции применяет само приложение при старте (src/db.py), отдельного шага нет:

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl --fail --retry 20 --retry-connrefused --retry-delay 1 http://localhost:8080/health/ready

Проверки:

make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 student_tests/test_lab2.py
python3 student_tests/test_lifecycle.py
python3 student_tests/test_sigterm.py
python3 -m unittest discover -s student_tests -p "test_level4.py" -v
docker compose --env-file .env exec -T postgres psql -U messenger -d messenger < scripts/explain.sql

test_level4.py останавливает и запускает контейнеры valkey/postgres/api; volumes не удаляются. test_sigterm.py запускает отдельный контейнер API в сети compose (имя сети по умолчанию mtusi-lab2_default, переопределяется COMPOSE_NETWORK).

Остановка с сохранением данных: docker compose --env-file .env down. Намеренное удаление учебных данных (БД и Valkey): docker compose --env-file .env down -v.

Архитектура и решения

Клиент ──HTTP──> API (FastAPI) ──> PostgreSQL 16 (volume pgdata)  - источник истины
                       └────────> Valkey 8 (без persistence)       — кэш сессий с TTL

Источник истины. PostgreSQL хранит пользователей, чаты, участников, сообщения и сессии (migrations/001_init.sql). Сессия — строка в sessions: SHA-256 токена (сам токен не хранится), user_id, expires_at, revoked_at. Токен - 256 бит случайности (secrets.token_urlsafe(32)).

Роль Valkey. Кэш проверенных сессий: ключ sess:<sha256 токена>, значение - данные пользователя. Valkey запущен без persistence (--save "" --appendonly no), с лимитом памяти 64 МБ и политикой allkeys-lru. Потеря кэша (рестарт, FLUSHALL) ничего не теряет: следующий запрос получает данные из PostgreSQL и наполняет кэш заново.

Политика expiry и инвалидации кэша.

  • TTL записи = min(остаток жизни сессии, CACHE_TTL_SECONDS=60), то есть кэш никогда не живёт дольше сессии.
  • Logout: сначала UPDATE sessions SET revoked_at в PostgreSQL, затем DEL ключа в Valkey.
  • Данные пользователя в кэше неизменяемы (в API нет редактирования), поэтому других причин инвалидации нет.
  • Если Valkey недоступен, кэш обходится (любой сбой - промах); после сбоя обращения к кэшу приостанавливаются на 5 секунд, чтобы не ждать таймаут на каждом запросе. Readiness зависит только от PostgreSQL: Valkey - оптимизация, а не критичная зависимость.

Аутентификация. POST /auth/sessions принимает только Authorization: Basic; остальные endpoint - только Bearer (зависимость current_user). X-User-Id не читается. Пароли хешируются Argon2id (argon2-cffi, параметры по умолчанию библиотеки), вычисление выполняется в thread pool. Для несуществующего пользователя проверка идёт по хешу-заглушке, ответ одинаковый 401. Это отличает password KDF (медленный, с солью, защищает слабые пароли от перебора) от быстрого checksum: токен имеет 256 бит случайности, поэтому для него достаточно SHA-256.

Транзакционные границы.

  • Создание чата: INSERT chats + INSERT chat_members в одной транзакции; неизвестный участник нарушает FK и откатывает всё.
  • Отправка сообщения: проверка членства и INSERT - один оператор (INSERT ... SELECT ... WHERE EXISTS).
  • Регистрация: гонку одинаковых username решает UNIQUE, приложение ловит UniqueViolationError и отвечает 409.
  • Миграции: каждая в транзакции вместе с записью в schema_migrations, под pg_advisory_lock.

Что перенесено из lab1. Структура приложения (middleware с X-Request-Id, формат ошибок, строгая валидация Pydantic, обработка SIGTERM), Dockerfile, собственные тесты (адаптированы под пароль/Bearer). Что изменено. In-memory словари заменены PostgreSQL; X-User-Id заменён Bearer; добавлены password KDF, сессии, Valkey, миграции, compose. Курсор пагинации теперь keyset (created_at, id), непрозрачный и привязанный к ресурсу (раньше был ID записи).

Соответствие переменных .env.example.

Переменная Реализация
APP_HOST, APP_PORT задаются в Dockerfile (0.0.0.0 / 8080)
APP_ENV передаётся в контейнер, поведение не меняет
SESSION_TTL_SECONDS срок жизни сессии (по умолчанию 3600)
DATABASE_URL_FILE путь к секрету с адресом PostgreSQL
SESSION_STORE не используется: сессии всегда в PostgreSQL, Valkey - кэш
CACHE_URL_FILE поддерживается; в compose адрес Valkey передаётся через CACHE_URL (в нём нет секретов)

Дополнительно: DB_POOL_MIN=2, DB_POOL_MAX=10, DB_CONNECT_TIMEOUT=5, DB_COMMAND_TIMEOUT=5, CACHE_TTL_SECONDS=60, CACHE_TIMEOUT=0.5, MIGRATIONS_DIR.

Доказательства критериев

Дата проверок: 03.11.2026; стенд: <macOS / Docker Desktop, число CPU и RAM>.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test PASS: lab2 public API scenario evidence/smoke.txt
Данные и сессии переживают рестарт API и хранилищ без удаления volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; контейнеры postgres/valkey Up 5 seconds, api Up Less than a second после hook evidence/persistence.txt, evidence/restart-before.txt, evidence/restart-after.txt
Полный жизненный цикл: тот же токен читает те же данные после рестарта, logout → 401 python3 student_tests/test_lifecycle.py PASS (7 проверок) evidence/lifecycle.txt
Таблицы, PK/FK, UNIQUE username, миграции с нуля migrations/001_init.sql, запуск с пустым volume миграция применена evidence/migrations.txt
Миграции повторно запускаются без дублирования перезапуск стенда, logs api | grep migration одна строка Applied migration 001_init.sql за все рестарты evidence/migrations.txt
Атомарность создания чата test_chat_creation_rolls_back чат с неизвестным участником → 400, count(*) в БД = 0 evidence/student-tests-level4.txt
Basic только на POST /auth/sessions, Bearer на остальных, X-User-Id без доступа, срок жизни, отзыв test_lab2.py (test_validation_and_unicode), test_x_user_id_gives_no_access, test_logout_..., test_zz_session_expiry PASS evidence/student-tests.txt, evidence/student-tests-level4.txt
Пароли хешируются KDF src/auth.py (Argon2id), в БД только password_hash см. код src/auth.py
Secrets/volumes не в Git .gitignore, .dockerignore, git status перед коммитом .env, secrets/ не отслеживаются —
4: Valkey реально используется (сессии с TTL) valkey-cli keys 'sess:*' после запросов; test_valkey_flush_keeps_sessions ключи sess:... есть, после FLUSHALL сессия работает и кэш наполняется снова evidence/student-tests-level4.txt
4: параметризованные запросы, ограниченный пул, таймауты src/db.py, src/chats.py (все запросы с $n) пул 2–10, таймауты соединения и команд 5 с src/db.py
4: гонка регистрации test_register_race_same_username 10 параллельных POST: ровно один 201, девять 409 evidence/student-tests-level4.txt
4: индекс истории + EXPLAIN на ≥10 000 сообщений scripts/explain.sql с индексом messages_history_idx: Index Scan, 3 страницы буфера и для первой страницы, и для страницы из середины истории (0.03 мс); без индекса: Seq Scan + сортировка, 123 страницы (0.9 мс) evidence/explain.txt
4: expiry при коротком TTL, logout, неверный пароль test_zz_session_expiry (TTL=2), test_logout_..., test_wrong_password PASS evidence/student-tests-level4.txt
4: недоступность Valkey и PostgreSQL test_valkey_down_falls_back_to_postgres, test_postgres_down_returns_bounded_error Valkey остановлен: запросы работают через PostgreSQL; PostgreSQL остановлен: /health/ready 503, неизвестный токен 503, запрос без токена 401, регистрация 503 evidence/student-tests-level4.txt
Собственные тесты python3 student_tests/test_lab2.py PASS: 12 сценариев evidence/student-tests.txt
Корректная остановка python3 student_tests/test_sigterm.py PASS: exit code 0, idle 0.34 с, с незавершённым POST 8.4 с evidence/sigterm.txt

Трек 5 не заявлен.

Эксперименты и отказы

Объём данных EXPLAIN: 10 000 сообщений в одном чате, синтетика (scripts/explain.sql), PostgreSQL 16.6, все чтения из shared buffers (shared hit), диска нет. Замер единичный, прогрев не выполнялся, поэтому важно соотношение (3 страницы против 123), а не абсолютные миллисекунды.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Полный рестарт api + postgres + valkey (volumes сохранены) токен и данные сохраняются тот же токен читает ту же историю сервисы Up через ~5 с; потери данных нет
FLUSHALL в Valkey сессии работают, кэш наполняется заново ответ 200 из PostgreSQL, ключи sess:* появляются снова без прерывания; потери данных нет
Остановка Valkey чтение и вход работают через PostgreSQL 200 для действующего токена, 401 для неизвестного и анонимного после start кэш снова используется не позднее чем через 5 с; потери данных нет
Остановка PostgreSQL ограниченная ошибка, аноним не доверенный /health/ready 503 (код unavailable), неизвестный токен 503, запрос без токена 401, регистрация 503 API снова готов после старта PostgreSQL в пределах 90 с ожидания теста (точное время не измерялось)
SESSION_TTL_SECONDS=2 токен истекает через 3.5 с запрос с тем же токеном → 401 (в том числе из-за TTL кэша ≤ остатка сессии) не применимо

Ограничения измерения: нагрузочный профиль не снимался (трек 5 не заявлен), время восстановления PostgreSQL точно не измерялось.

Ограничения и следующие шаги

  • Устаревание кэша при сбое инвалидации. Если logout выполнился, а DEL в Valkey не прошёл (кратковременный сбой), запись может остаться в кэше не дольше CACHE_TTL_SECONDS (60 с). Это сознательный компромисс; снизить окно можно, уменьшив TTL кэша.
  • Порядок истории при конкурентной записи. created_at задаётся через clock_timestamp() в момент вставки, а видимость строки определяется моментом COMMIT. При конкурентных записях возможно, что сообщение с чуть более ранним created_at станет видимым после того, как читатель уже получил курсор за ним; такая запись не повторится и не пропадёт при следующем чтении с начала, но может быть пропущена при продолжении по старому курсору. Гарантируется отсутствие повторов при обходе неизменной истории.
  • Просроченные сессии не удаляются из таблицы sessions (нет фоновой очистки); они не принимаются, но занимают место. Следующий шаг - периодическая очистка по индексу sessions_expires_idx.
  • Один экземпляр PostgreSQL и Valkey, без репликации и бэкапов; отказ диска PostgreSQL приведёт к потере данных (backup/restore - трек 2 уровня 5, не реализован).
  • HTTP и Basic без TLS - допустимо только для локального изолированного стенда с синтетическими данными. Права 644 у секретов - учебное упрощение для локального запуска.
  • Argon2id использует параметры по умолчанию библиотеки; подбор параметров под целевое железо не выполнялся.
  • Удалённый CI для сборки приложения не добавлен: .github/workflows/contracts.yml проверяет только контракт.

Ответы на вопросы защиты

  • Что подтверждает COMMIT? Транзакция записана в WAL и (при synchronous_commit=on, значение по умолчанию) сброшена на диск до ответа клиенту; гарантия зависит от настроек fsync/synchronous_commit и от надёжности диска и Docker volume.
  • Где хранятся сессии и что будет после flush/restart Redis/Valkey? Источник истины - таблица sessions в PostgreSQL; Valkey лишь кэш без persistence. После flush или рестарта кэш пуст, сессии не теряются и наполняют кэш заново (test_valkey_flush_keeps_sessions).
  • Чем аутентификация отличается от доступа к чату? Аутентификация отвечает «кто вы» (Bearer-сессия), доступ - «можно ли этому пользователю в этот чат» (проверка членства в chat_members); постороннему возвращается 404, чтобы не раскрывать существование чата.
  • Почему hash пароля и быстрый checksum - разные задачи? Пароль имеет низкую энтропию и должен защищаться от перебора, поэтому нужен медленный salted KDF (Argon2id); токен сессии - 256 бит случайности, перебор невозможен, и достаточно быстрого SHA-256.