Files
2026-10-09 15:15:58 +03:00

160 lines
23 KiB
Markdown
Raw Permalink 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
- Целевая оценка; 4
- Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/29
- Использованные источники, библиотеки и помощь ИИ: FastAPI, Uvicorn, Pydantic, psycopg 3 и psycopg-pool, argon2-cffi, redis-py (точные версии в requirements.txt); образы python:3.11.13-slim, postgres:17.11-alpine, redis:7.4.11-alpine; документация PostgreSQL (транзакции, индексы, EXPLAIN), документация Redis (persistence, AOF), RFC 7617 (Basic). Помощь ИИ: использовался как консультант по git и PowerShell, для разбора ошибок Docker (монтирование секретов, пароль PostgreSQL в старом volume)
## Запуск из чистого clone
Проверял на Windows 11, все команды в PowerShell. Версии: Docker 28.1.1 (Docker Compose v2.35.1-desktop.1), Python <<python --version>> (Python нужен только для тестов, приложение работает в контейнере).
```powershell
git clone https://gitea.privcloud.tech/Kalibr/mtusi2026lab2.git
cd mtusi2026lab2
git checkout solution/bvt2303-babichenko
Copy-Item .env.example .env
python scripts/init_secrets.py # случайные пароли в secrets/ (папка в .gitignore)
docker compose up -d --build --wait # api, postgres, redis; ждём статус healthy
docker compose ps
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
python student-tests/test_api.py
python student-tests/test_race.py
python student-tests/test_db.py
python student-tests/test_expiry.py
python student-tests/test_failures.py
python student-tests/redis_info.py
python student-tests/explain.py # пишет evidence/explain-history.txt
```
Это те же проверки, что в Makefile, только без make (на моём Windows его нет): `make check` = `python scripts/check_contract.py`, `make test` = `python tests/smoke.py ...`, `make test-persistence ACTION_SCRIPT=...` = `python tests/resilience.py --mode persistence ...`. Где make есть: `make check`, `make test BASE_URL=http://127.0.0.1:8080`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080`. Адрес 127.0.0.1 вместо localhost: на Windows localhost сначала пробует IPv6 и отвечает медленнее.
На Linux/macOS вместо `scripts/restart.cmd` указывается `scripts/restart.sh`. Restart-скриптов два, потому что тест запускает hook напрямую, без shell, а Python на Windows не умеет запускать `.sh` (ошибка WinError 193). Команда в обоих одна: `docker compose restart`.
Миграции применяет само приложение при старте, отдельной команды нет. Секреты создаются один раз скриптом `scripts/init_secrets.py`, значения на экран не выводятся.
Остановка без потери данных: `docker compose down` (контейнеры удаляются, volumes `pgdata` и `redisdata` остаются, следующий `docker compose up -d --wait` поднимает те же данные). Намеренное удаление учебных данных: `docker compose down -v`, затем удалить папку `secrets` и снова запустить `python scripts/init_secrets.py`.
## Архитектура и решения
```text
Клиент --HTTP--> api (FastAPI, порт 8080 только на 127.0.0.1)
|--> postgres пользователи, чаты, участники, сообщения (volume pgdata)
|--> redis сессии: session:<SHA-256 токена> -> id пользователя (AOF, volume redisdata)
```
PostgreSQL и Redis наружу не опубликованы, к ним ходит только API внутри сети Compose.
| Роль | Сервис Compose | Версия | Health / готовность | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| API | `api` (собирается из Dockerfile) | python:3.11.13-slim | `/health/ready` (Docker HEALTHCHECK) | нет | `127.0.0.1:8080` на хосте | читает `/run/secrets/database_url` и `/run/secrets/cache_url` |
| База данных | `postgres` | postgres:17.11-alpine | `pg_isready` | `pgdata` | только сеть Compose, 5432 | `POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password` |
| Сессии | `redis` | redis:7.4.11-alpine | `redis-cli ping` с паролем | `redisdata` (AOF) | только сеть Compose, 6379 | `include /run/secrets/redis_auth` (requirepass) |
Bootstrap: секреты — `python scripts/init_secrets.py` (повторный запуск ничего не меняет), схема — миграции при старте API (повторный старт ничего не применяет). Redis подготовки не требует.
Что перенесено из lab1 и что изменилось:
- `main.py` остался главным файлом: модели Pydantic, формат ошибок, X-Request-Id, курсоры и маршруты из lab1. Вместо словарей `users`, `chats`, `messages` маршруты вызывают функции из `db.py`.
- Новые файлы: `db.py` (пул соединений, миграции, SQL-запросы), `auth.py` (Argon2id, разбор Basic/Bearer, сессии в Redis), `settings.py` (настройки из окружения и секретов), `errors.py` (ошибка API с кодом), `migrations/001_init.sql`, `compose.yaml`, `infra/redis.conf`, скрипты в `scripts/`.
- Вход: регистрация с `password`, `POST /api/v1/auth/sessions` только с Basic, дальше только `Authorization: Bearer`. `X-User-Id` больше ничего не значит. Токен проверяется в middleware до разбора тела, поэтому без токена всегда 401, а не 400 или 404.
- Свои тесты lab1 лежали в `tests/test_lab1.py`. По CONTRIBUTING публичную папку `tests/` переносить нельзя, поэтому свои тесты теперь в `student-tests/` и переведены на пароль и Bearer.
- Контейнер теперь запускается командой `python main.py`: хост и порт берутся из окружения, при SIGTERM uvicorn ждёт начатые запросы не дольше 5 с.
Схема БД (`migrations/001_init.sql`):
- `users`: PK `id`, UNIQUE `username`, CHECK формата username и длины display_name, `password_hash`.
- `chats`; `chat_members` с PK (chat_id, user_id) и FK на `chats` и `users`; индекс по `user_id` для списка чатов.
- `messages`: FK (chat_id, sender_id) -> `chat_members`, то есть база сама не даст записать сообщение от того, кто не в чате. Индекс `(chat_id, created_at, id)` под историю.
Транзакции:
- регистрация: один INSERT. Повтор username ловит уникальный индекс (ответ 409), без проверки «есть ли такой» в коде, которая пропустила бы две одновременные регистрации;
- создание чата: одна транзакция, сначала INSERT чата, потом всех участников. Если участника нет, FK падает, транзакция откатывается целиком, ответ 400;
- сообщение: один INSERT; если отправитель не в чате, срабатывает FK и ответ 404.
Миграции: файлы `migrations/*.sql` применяются при старте API по порядку. Применённые записываются в `schema_migrations`, повторный старт ничего не применяет. Файл и запись о нём в одной транзакции. `pg_advisory_lock` не даёт двум API применять миграции одновременно.
Сессии и роль Redis:
- источник истины для сессий — Redis, это единственное хранилище сессий (README допускает такой вариант при включённой persistence). Ключ `session:<SHA-256 токена>`, значение — id пользователя. Сам токен нигде не хранится;
- истечение: у ключа абсолютное время истечения (`SET ... PXAT`), равное `expires_at` из ответа. Redis удаляет ключ сам, рестарт срок не продлевает;
- сброс: logout удаляет ключ (`DEL`). `FLUSHALL` или удаление volume `redisdata` удалят все сессии, всем придётся войти заново; пользователи и сообщения в PostgreSQL при этом не пострадают;
- сохранность: раз Redis — единственное хранилище сессий, одного TTL мало, включён AOF с `appendfsync always`: Redis отвечает «OK» только после записи на диск. Поэтому после рестарта Redis действующие токены работают, и даже после аварийного `docker compose kill redis`;
- `maxmemory-policy noeviction`: при нехватке памяти Redis откажет во входе (503), но не удалит молча чужие сессии;
- Redis закрыт паролем (`requirepass` из секрета `secrets/redis_auth`).
Пароли и токены: пароль хешируется Argon2id (m=12 МиБ, t=3, p=1, один из вариантов OWASP) с солью. Токен — 32 случайных байта (256 бит). Для ключа в Redis используется быстрый SHA-256: токен случайный, подбирать его бессмысленно. Неверный пароль и несуществующий пользователь дают одинаковый 401, и для несуществующего пароль тоже проверяется, чтобы время ответа было одинаковым.
Пул и таймауты: PostgreSQL — пул psycopg от 1 до 10 соединений, ожидание соединения 3 с, подключение 3 с, `statement_timeout` 5 с, соединение проверяется перед выдачей. Redis — пул до 20 соединений, таймауты 500 мс, без повторов. Все SQL-запросы параметризованные (`%s`).
Health: `/health/live` — процесс жив. `/health/ready` — отвечают и PostgreSQL, и Redis: без любого из них обычный запрос обслужить нельзя. Docker healthcheck API проверяет `/health/ready`.
Durability: PostgreSQL с `fsync=on` и `synchronous_commit=on` (значения по умолчанию, в compose.yaml записаны явно). 201 отдаётся после COMMIT, а COMMIT — после записи WAL на диск. Данные в именованном volume `pgdata`.
Соответствие `.env.example`:
| Переменная | Что делает в этом решении |
| --- | --- |
| APP_HOST, APP_PORT, APP_ENV | где слушает API (0.0.0.0:8080), APP_ENV пишется в лог при старте |
| SESSION_TTL_SECONDS | срок жизни сессии, 3600 с; тест истечения временно запускает API с 2 с |
| DATABASE_URL_FILE | путь к секрету с адресом PostgreSQL (`/run/secrets/database_url`) |
| SESSION_STORE=redis | сессии хранятся в Redis (другие значения не поддерживаются) |
| CACHE_URL_FILE | путь к секрету с адресом Redis (`/run/secrets/cache_url`) |
| DB_*, REDIS_* | дополнительные: размеры пулов и таймауты |
Секреты передаются файлами через `secrets:` в Compose (`/run/secrets/...`), а не значениями переменных, поэтому их нет в `docker inspect`. `.env` и `secrets/` в `.gitignore`.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `python tests/smoke.py --base-url http://127.0.0.1:8080` | PASS | evidence/smoke.txt |
| Skeleton и контракт не изменены | `python scripts/check_contract.py` | PASS | evidence/check.txt |
| 3: минимум lab1 сохранён, переход на новую аутентификацию | smoke; `python student-tests/test_api.py` (тесты lab1 переведены на пароль и Bearer) | smoke PASS; 18 passed, 0 failed | evidence/smoke.txt, evidence/student-tests.txt |
| 3: данные и сессии переживают рестарт API и хранилищ без удаления volumes | `docker compose ps`; resilience.py с `scripts/restart.cmd`; `docker compose ps` | PASS; ID контейнеров те же, время Up у api, postgres и redis сбросилось | evidence/persistence.txt |
| 3: PostgreSQL: users, chats, members, messages; PK/FK; уникальный username | `migrations/001_init.sql`; `python student-tests/test_db.py` | UNIQUE (username); прямой INSERT сообщения от не-участника отклонён по FK | evidence/db.txt |
| 3: миграции с нуля | `docker compose up` на пустом volume, `docker compose logs api` | «Migrations applied: 001_init.sql» | evidence/stack.txt |
| 3: повторный запуск миграций без дублирования | test_db.py (рестарт api) | «Migrations applied: none», в schema_migrations одна запись | evidence/db.txt |
| 3: создание чата атомарно | test_db.py (test_create_chat_rolls_back) | 400; строки чата нет, хотя счётчик вставок в chats вырос: вставка была и откатилась | evidence/db.txt |
| 3: Basic только на POST /auth/sessions | test_api.py (test_bearer_required) | Basic на /users/me -> 401 с WWW-Authenticate: Bearer | evidence/student-tests.txt |
| 3: остальные endpoint требуют Bearer, X-User-Id не даёт доступ | test_api.py (test_bearer_required, test_x_user_id_ignored) | только X-User-Id -> 401; X-User-Id рядом с токеном не меняет пользователя | evidence/student-tests.txt |
| 3: срок жизни сессии и logout | `python student-tests/test_expiry.py`; test_api.py (test_logout) | после TTL 2 с -> 401 и ключа в Redis нет; после logout -> 401, вторая сессия работает | evidence/expiry.txt, evidence/student-tests.txt |
| 3: пароль хешируется password KDF | test_db.py (test_password_is_argon2id) | `$argon2id$v=19$m=12288,t=3,p=1$...` | evidence/db.txt |
| 3: secrets и volumes не попадают в Git | `git check-ignore -v .env secrets/database_url` | оба файла игнорируются | evidence/stack.txt |
| 4: Redis реально используется (источник истины, expiry, сброс описаны выше) | `docker compose exec redis ...`: число ключей session:*, TTL ключа, настройки AOF | ключи session:* есть, TTL около 3600 с, appendonly yes, appendfsync always | evidence/redis.txt |
| 4: параметризованные запросы | `db.py` | все значения через `%s`, SQL не склеивается со вводом | код |
| 4: ограниченный пул и таймауты | `db.py`, `auth.py`, `settings.py` | PostgreSQL: пул 1–10, 3 с / 3 с / 5 с; Redis: пул 20, 500 мс | код |
| 4: гонка регистрации одного username | `python student-tests/test_race.py` | 20 параллельных запросов: 201 x1, 409 x19 | evidence/race.txt |
| 4: rollback составной операции | test_db.py | см. строку «создание чата атомарно» | evidence/db.txt |
| 4: индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | `python student-tests/explain.py` (20 000 сообщений, большой чат 15 000) | Index Scan по messages_history, 51 строка, 4 буфера | evidence/explain-history.txt |
| 4: пагинация без полного scan истории | explain.py, запросы 2–4 | keyset после 10 000-го сообщения: 6 буферов; OFFSET 10000: 10 051 строка и 257 буферов; без индекса: Seq Scan по всей таблице и Sort, 255 буферов | evidence/explain-history.txt |
| 4: автопроверка expiry при коротком SESSION_TTL_SECONDS | test_expiry.py (API пересоздаётся с TTL=2) | до истечения 200, после 401 | evidence/expiry.txt |
| 4: автопроверка logout | test_api.py (test_logout) | 204, потом 401, повторный logout 401 | evidence/student-tests.txt |
| 4: автопроверка неверного пароля | test_api.py (test_wrong_password) | одинаковый 401 для неверного пароля и неизвестного пользователя | evidence/student-tests.txt |
| 4: недоступность Redis | `python student-tests/test_failures.py redis` | ready 503; с токеном 503; с чужим токеном 503, а не 200; без токена 401; регистрация 201 | evidence/failures.txt |
| 4: persistence Redis выдерживает проверяемый рестарт | resilience.py (restart всего стенда); test_failures.py redis (test_redis_crash: `docker compose kill redis`, затем start) | прежний токен работает и после обычного рестарта, и после аварийной остановки | evidence/persistence.txt, evidence/failures.txt |
| 4: недоступность БД, аноним не становится доверенным | `python student-tests/test_failures.py postgres` | ready 503; бизнес-запросы 503 без подробностей; без токена и с чужим токеном 401; после старта БД прежний токен работает | evidence/failures.txt |
| Выбранный трек 5 | | не выбран | |
## Эксперименты и отказы
Компьютер: <<процессор, память>>, Windows 11, Docker Desktop без отдельных лимитов. Дата прогона: 9 октября 2026. Нагрузочных экспериментов нет, трек 5 не выбран. Ниже проверки отказов уровня 4.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| restart hook: `docker compose restart` (api, postgres, redis), volumes на месте | данные и токен живы | тот же токен читает то же сообщение | около 3,6 с (real 00:03.587); потерь нет |
| `docker compose stop redis` | без проверки сессии никого не пускаем | ready 503, запросы с токеном 503, без токена 401, регистрация 201 | после `start redis` прежний токен работает сразу; сессии не потеряны (AOF) |
| `docker compose kill redis` (SIGKILL, без корректной остановки) | сессии не теряются | сессия, выданная до сбоя, работает после `start redis` | потерь нет: каждая запись в AOF на диске до ответа «OK» |
| `docker compose stop postgres` | ограниченная ошибка, анонимов не пускаем | ready 503, бизнес-запросы 503, без токена и с чужим токеном 401 | после `start postgres` токен и сообщения на месте; запросы во время отказа не сохранены (получили 503) |
| 20 одновременных регистраций одного username | один победитель | 201 x1, 409 x19 | дублей нет |
| 10 клиентов x 10 сообщений одновременно | ровно 100 сообщений | 100, все id уникальны | потерь нет |
## Ограничения и следующие шаги
- Одна PostgreSQL и один Redis, без реплик и бэкапов. Упал любой из них — API отвечает 503.
- Если Redis недоступен, не работает никто из вошедших: сессии хранятся только там. Цена — простая схема: один источник истины для сессий.
- Если потерять volume `redisdata` или выполнить `FLUSHALL`, все пользователи разлогинятся (данные в PostgreSQL останутся).
- Время сообщения — время начала транзакции. При одновременных вставках сообщение, закоммиченное позже, может получить более раннее время, и клиент, уже пролиставший историю дальше, его не увидит. Это ограничение keyset-пагинации по времени.
- API подключается к PostgreSQL владельцем базы. Отдельная роль с минимальными правами — в lab7.
- Basic по HTTP передаёт пароль открыто (base64 — не шифрование). Допустимо только на локальном стенде, TLS — в lab7.