20 KiB
Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка: 4 (трек 5 не заявлен)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: FastAPI, uvicorn, pydantic, asyncpg, redis-py (клиент к Valkey), argon2-cffi; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617. Код lab1 перенесён из собственного решения. При переносе на PostgreSQL, написании тестов и отчёта использовался ИИ-ассистент Claude (Anthropic); решения проверены и объяснимы автором.
Запуск из чистого clone
Требования: Docker Engine с Compose v2 (проверено: Docker 28.0.1, Compose 2.33.1), Python 3.9+ для тестов (проверено на 3.14), make.
| Роль | Образ | Версия |
|---|---|---|
| api / migrate | mtusi-messenger:lab2, сборка из Dockerfile |
python:3.12.8-slim-bookworm, зависимости закреплены в requirements.txt |
| postgres | postgres:17.6-alpine3.22 |
PostgreSQL 17.6 |
| valkey | valkey/valkey:8.1.4-alpine3.22 |
Valkey 8.1.4 |
cp .env.example .env # при занятом 8080 поменять APP_PORT
make secrets # scripts/init-secrets.sh: случайные пароли в ./secrets (в .gitignore)
docker compose --env-file .env config --quiet
make up # docker compose up -d --build --wait: postgres -> migrate -> api; ждёт healthcheck /health/ready
make check
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
make test-student BASE_URL=http://localhost:8080 # собственные тесты; останавливает/запускает контейнеры
make explain # засев 70 000 синтетических сообщений + EXPLAIN
- Миграции: отдельный одноразовый сервис
migrate(python -m app.migrate). API стартует только после его успешного завершения. Повторный запуск безопасен (schema_migrations+pg_advisory_lock). - Безопасная остановка без потери данных:
make down(=docker compose --profile ttl-test down, volumepgdataсохраняется). - Намеренное удаление учебных данных:
docker compose --profile ttl-test down -v(удаляет volumemessenger-lab2_pgdata; необратимо). - Действия оператора: только
make secretsперед первым запуском. Секреты в образ и Git не попадают.
Архитектура и решения
клиент ──HTTP──> api (FastAPI/uvicorn, 1 процесс)
├──> postgres : источник истины — users, chats, chat_members, messages, sessions
└──> valkey : кэш поиска сессии (только ускорение, может пропасть в любой момент)
migrate (one-shot) ──> postgres : применение migrations/*.sql
Перенесено из lab1: модели pydantic, формат ошибок и X-Request-Id, keyset-курсор, привязанный к ресурсу, проверки контракта (пустой текст, дубликаты участников, 404 на чужой чат), Dockerfile (non-root, graceful SIGTERM). In-memory Store заменён на репозиторий PostgreSQL (app/storage.py).
Изменено по контракту lab2: password при регистрации, POST /auth/sessions через Basic, Bearer на всех бизнес-endpoint, DELETE /auth/sessions/current. X-User-Id не читается вообще.
Схема БД (migrations/0001_init.sql)
| Таблица | Ключи и ограничения | Индексы |
|---|---|---|
| users | PK id; UNIQUE(username); CHECK формата username и длины display_name |
уникальный по username |
| chats | PK id; CHECK длины title | — |
| chat_members | PK (chat_id, user_id); FK на chats и users; position хранит порядок member_ids |
(user_id, chat_id) для списка чатов пользователя |
| messages | PK id; FK (chat_id, sender_id) → chat_members: отправитель обязан быть участником на уровне БД; CHECK длины текста | (chat_id, created_at, id) для истории |
| sessions | PK token_hash (sha256 токена, сам токен не хранится); FK user_id; expires_at, revoked_at | (expires_at) |
Время (created_at, expires_at) назначает PostgreSQL (clock_timestamp()), в API выдаётся RFC 3339 UTC с микросекундами. Порядок (created_at, id); сравнение uuid в PostgreSQL побайтовое и совпадает с порядком UUID-int в тестах.
Транзакционные границы
- Создание чата — одна транзакция:
INSERT chats+INSERT chat_members … FROM unnest($2::uuid[]). Неизвестный участник отлавливает FK внутри транзакции →ROLLBACK→ 400. Предварительного SELECT нет, поэтому откат реально выполняется (тестdb_integrity_test.py). - Регистрация — один
INSERT; гонку одинаковых username решаетUNIQUE(UniqueViolationError→ 409), а не проверка «SELECT, потом INSERT». - Отправка сообщения — одна инструкция
INSERT … SELECT … WHERE EXISTS(участник): проверка доступа и запись атомарны. - Logout —
UPDATE sessions SET revoked_at(истина), затем надгробие в Valkey. COMMITподтверждает запись в WAL; при настройках по умолчанию (fsync=on,synchronous_commit=on) подтверждённое сообщение переживает падение процесса PostgreSQL. Ответ 201 отправляется только после COMMIT.
Аутентификация и сессии
- Пароль: Argon2id (argon2-cffi, профиль RFC 9106 low-memory: t=3, m=64 MiB, p=4). Хеширование в thread pool, не более 4 одновременно (
PASSWORD_HASH_CONCURRENCY), чтобы ограничить RAM. Для несуществующего username проверяется фиктивный хеш, поэтому время ответа одинаковое. - Basic разбирается строго: base64 → UTF-8 → разделение по первому
:(двоеточие в пароле допустимо), username только ASCII, пароль 12–128 code points. Любая ошибка даёт одинаковый 401 сWWW-Authenticate: Basic realm="messenger", charset="UTF-8". - Токен —
secrets.token_urlsafe(32)(256 бит). В БД и кэше хранится толькоsha256(token). Быстрый хеш здесь уместен: токен случайный, перебирать его бессмысленно, в отличие от человеческого пароля, которому нужен медленный KDF. - Срок жизни
SESSION_TTL_SECONDS(по умолчанию 3600) задаётся в БД какexpires_at, поэтому рестарт его не продлевает.
Роль Valkey (уровень 4): кэш сессий
- Источник истины — PostgreSQL. Valkey хранит
session:<sha256 hex>→{user, expires_at}, чтобы не ходить в БД на каждом запросе;/users/meобслуживается вообще без БД. - Expiry: TTL записи =
min(остаток сессии, SESSION_CACHE_MAX_SECONDS=300), плюс при чтении из кэша сравниваетсяexpires_at. Просроченная сессия не принимается ни из кэша, ни из БД. - Инвалидация: при logout сначала
revoked_atв PostgreSQL, затем в Valkey пишется надгробиеrevoked(а не DEL). Заполнение кэша идёт черезSET NX, поэтому параллельный запрос, прочитавший БД до отзыва, не сможет вернуть сессию в кэш. - Сбой записи tombstone (исправлено по замечанию к PR): раньше ошибка записи в Valkey проглатывалась и logout отвечал 204, хотя в кэше оставалась действующая запись сессии; после восстановления Valkey отозванный токен снова получал 200 до 5 минут. Теперь:
- logout отвечает 503 («не подтверждён»), если tombstone не записан; сессия в PostgreSQL при этом уже отозвана;
- хеш токена запоминается в процессе как «отзыв ожидает записи», и запись из кэша для него игнорируется: проверка идёт в PostgreSQL → 401;
- фоновая задача раз в секунду повторяет запись tombstone, пока Valkey не ответит, но не дольше
SESSION_CACHE_MAX_SECONDS(за это время устаревшая запись истекла бы сама).
- Persistence не нужна и выключена (
save "",appendonly no): после flush или рестарта Valkey первая проверка идёт в PostgreSQL. Потеря кэша ничего не ломает, это подтверждает тест сохранности, где Valkey тоже перезапускается. - Отказ Valkey: таймаут 0.3 с, затем circuit breaker на 5 с, в течение которых кэш не используется. Readiness при этом остаётся 200: Valkey не критичен.
- Конфигурация с
requirepassлежит в секретеsecrets/valkey.conf, порт наружу не публикуется.
Устойчивость к отказам
- asyncpg pool:
max_size=10, таймауты подключения 3 с, захвата соединения 3 с, команды 5 с.min_size=0позволяет API стартовать при недоступной БД (тогда readiness = 503). - Недоступность или рестарт PostgreSQL (
OSError,PostgresConnectionError,InterfaceError,TooManyConnections, admin shutdown, statement timeout) превращается в503 unavailableбез деталей. Без токена по-прежнему 401. Токен, который нельзя проверить (нет в кэше, БД недоступна), получает 503 и никогда не считается аутентифицированным. - Readiness: 200 только при успешном
SELECT 1в PostgreSQL. Liveness всегда 200. - Все SQL-запросы параметризованы (
$1…), строк, склеенных из пользовательского ввода, нет.
Переменные .env.example → реальная конфигурация
| Переменная | Где используется |
|---|---|
| APP_HOST / APP_PORT | uvicorn внутри контейнера слушает 0.0.0.0:8080; APP_PORT в .env — порт хоста (127.0.0.1:${APP_PORT}) |
| APP_ENV | передаётся в контейнер, логики не меняет |
| SESSION_TTL_SECONDS | срок сессии; у api-short-ttl = 2 |
| DATABASE_URL_FILE | /run/secrets/database_url (compose secret из secrets/database_url) |
| SESSION_STORE=postgres | сессии хранятся в PostgreSQL |
| CACHE_URL_FILE | /run/secrets/cache_url, URL Valkey; без него кэш отключён |
| SESSION_CACHE_MAX_SECONDS, DB_POOL_MAX, SHORT_TTL_PORT | добавлены этой работой (см. выше) |
Доказательства критериев
Файлы в evidence/ сняты 2026-10-07 (explain_history), 2026-10-08 UTC (основные) и 2026-10-15 UTC (logout_cache_failure, на отдельном стенде с портом 18280) на MacBook (Apple Silicon, Docker Desktop, без CPU/RAM-лимитов в compose).
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make check, make test |
PASS обоих | evidence/smoke.txt |
| 3: данные и сессии переживают рестарт API и хранилищ | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS; StartedAt api/postgres/valkey изменились, volume тот же, тот же токен читает данные |
evidence/persistence.txt |
| 3: миграции с нуля и повторно | docker compose -p lab2-clean up на пустом volume, затем ещё run migrate |
1 applied now, 0 before, затем 0 applied now, 1 before; smoke PASS на новом стенде |
evidence/fresh_migrations.txt |
| 3: PK/FK, UNIQUE username, атомарное создание чата | student-tests/db_integrity_test.py |
чат с неизвестным участником → 400, в chats 0 строк с этим title и 0 чатов без участников |
evidence/student_tests.txt |
| 3: Basic только на /auth/sessions, Bearer, X-User-Id игнорируется, logout, KDF | auth_test.py, smoke, db_integrity_test.py |
Basic/X-User-Id на бизнес-endpoint → 401; повторный logout → 401; hash начинается с $argon2id$ |
evidence/student_tests.txt |
| 3: secrets/volumes не в Git | git status, .gitignore (secrets/, .env) |
секреты только в ./secrets, в репозитории нет |
.gitignore |
| 4: Valkey реально используется, TTL, инвалидация | dependency_test.py |
ключи session:* с TTL ≤ 300, после logout значение revoked |
evidence/student_tests.txt |
| 4: параметризованные запросы, ограниченный pool, таймауты | код app/storage.py, app/config.py |
$n-параметры, max_size=10, таймауты 3/3/5 с |
— |
| 4: гонка регистрации | db_integrity_test.py |
20 параллельных запросов → 1×201, 19×409, 1 строка | evidence/student_tests.txt |
| 4: rollback составной операции | db_integrity_test.py |
см. строку «атомарное создание чата» | evidence/student_tests.txt |
| 4: индекс истории + EXPLAIN на ≥10 000 | make explain |
70 000 сообщений, в чате 20 000; с индексом Index Scan, 4 буфера, 0.03 мс на первой и глубокой (#15000) странице; без индекса Seq Scan + Sort, 940 буферов, 3–4 мс | evidence/explain_history.txt |
| 4: expiry при коротком TTL | auth_test.py против api-short-ttl (TTL=2) |
через 3 с → 401 (и из кэша) | evidence/student_tests.txt |
| 4: logout, неверный пароль | auth_test.py |
неверный пароль и неизвестный user дают одинаковый 401 | evidence/student_tests.txt |
| 4: logout при сбое записи в кэш | dependency_test.py (docker compose pause valkey во время logout) |
до исправления: 204 и отозванный токен → 200 из кэша; после: 503, токен → 401, tombstone дописан после unpause |
evidence/logout_cache_failure.txt |
| 4: недоступность Redis/БД | dependency_test.py |
Valkey stop: ready=200, запросы ~4 мс; PostgreSQL stop: live=200, ready и бизнес-запросы 503 мгновенно, непроверенный токен → 503, без токена 401; после start всё восстанавливается без рестарта API | evidence/student_tests.txt |
| Graceful shutdown (из lab1) | sigterm_test.sh |
docker compose stop api → exit 0 за < 1 с |
evidence/student_tests.txt |
Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
scripts/restart.sh: stop api, valkey, postgres → up |
данные и сессия на месте, токен тот же | PASS, кэш пустой, сессии берутся из PostgreSQL | ~11 с весь hook / потерь нет |
docker compose stop valkey |
API работает без кэша | 200, ~4 мс на запрос (breaker), revoked-токен 401 | мгновенно / потерь нет (кэш) |
docker compose pause valkey во время logout |
logout не сообщает об успехе, отозванный токен не принимается | 503; после unpause токен → 401, tombstone записан фоновой задачей |
~1 с после восстановления Valkey / потерь нет |
docker compose stop postgres |
503 без зависаний, анонимный доступ не появляется | ready 503, бизнес 503, live 200, всё за < 0.1 с | API восстанавливается сам после start postgres, без своего рестарта; подтверждённые данные целы |
| SIGTERM api | graceful exit 0 | exit 0, «Application shutdown complete» | docker compose up -d --wait api |
Ограничения и следующие шаги
- Один Docker-host, по одному PostgreSQL и Valkey, без репликации: потеря host или диска = потеря сервиса (бэкапы не настроены, это трек 2 пятёрки).
- Защита от устаревшей записи после неудачного logout живёт в памяти процесса API. Если сам API перезапустится до того, как Valkey снова станет доступен, или (с lab3) запрос придёт на другую реплику, устаревшая запись может приниматься до
SESSION_CACHE_MAX_SECONDS(≤ 5 мин). Клиент при этом получил 503, а не 204. Для нескольких реплик нужен общий механизм, например версия сессии в кэше или pub/sub-инвалидация. - Просроченные строки
sessionsне удаляются автоматически (есть индексexpires_atдля будущей периодической очистки). /health/readyне проверяет Valkey намеренно.- Тело запроса проверяется до аутентификации: на неавторизованный запрос с битым JSON вернётся 400, а не 401 (особенность FastAPI). Это не раскрывает данных.
make testсоздаёт синтетических пользователей при каждом запуске; удаления в API нет.- Нагрузочное измерение (
make load) не делалось: для уровня 4 не требуется.