Files
mtusi2026lab2/REPORT.md
T

162 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 2
- Автор, группа: Гаджиев Нухбала, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/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.
```sh
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 такого поиска не требует.