forked from mtusi2026/mtusi2026lab2
160 lines
23 KiB
Markdown
160 lines
23 KiB
Markdown
# Отчёт — лабораторная 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.
|