20 KiB
Отчёт — лабораторная 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.