Files
mtusi2026lab2/REPORT.md
T

235 lines
28 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: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ:
- библиотеки: FastAPI 0.143.0, Uvicorn 0.54.0, psycopg 3.3.6 и psycopg-pool 3.3.3, redis-py 8.1.0, argon2-cffi 25.1.0 (полный список с версиями в `requirements.txt`);
- источники: документация PostgreSQL (транзакции, EXPLAIN), Redis persistence, psycopg, Docker Compose, RFC 7617, `contracts/README.md`;
- помощь ИИ: ИИ-ассистент использовался во вспомогательных целях.
## Запуск из чистого clone
Нужны Docker с Compose v2 (проверено на Docker 29.3.0, Compose 5.1.0), `make`, `openssl`, `curl` и Python 3.9+ на хосте для тестов. Сервер, PostgreSQL и Redis работают только в контейнерах.
```sh
make up # создаёт .env с паролями, собирает образ, поднимает стенд и ждёт /health/ready
make check # структура skeleton
make test # публичный smoke
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make student-test # собственные тесты API
make test-failures # истечение сессии, остановка Redis и PostgreSQL, откат транзакции
make explain # 60 000 синтетических сообщений и планы запросов
python3 scripts/sigterm_check.py
make down # остановить и удалить контейнеры, данные остаются в volumes
make clean # то же и удалить volumes: намеренное удаление учебных данных
```
То же без `make`:
```sh
./scripts/init-env.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
./scripts/wait-ready.sh
```
`scripts/init-env.sh` копирует `.env.example` в `.env` и дописывает в него случайные пароли PostgreSQL и Redis (`openssl rand`). Файл `.env` исключён из Git. Повторный запуск скрипта пароли не меняет: пароль PostgreSQL задаётся один раз при создании volume, поэтому после `make clean` нужно либо оставить старый `.env`, либо удалить его и создать заново.
Миграции отдельной команды не требуют: при `up` одноразовый контейнер `migrate` применяет их до старта API. Повторить вручную можно командой `docker compose --env-file .env run --rm migrate`.
`make test-failures` сам останавливает и запускает `redis` и `postgres` и поднимает второй экземпляр API на порту 8081, поэтому запускать его нужно только на учебном стенде.
## Архитектура и решения
```
клиент ──HTTP──> api (uvicorn + FastAPI) ──┬──> postgres: пользователи, чаты, участники, сообщения
└──> redis: сессии с TTL
```
### Роли и сервисы
| Роль | Сервис compose | Образ | Готовность | Volume | Сеть и порт | Как получает секреты |
| --- | --- | --- | --- | --- | --- | --- |
| api | `api` | собирается из `Dockerfile` на `python:3.13.16-slim-bookworm` | HEALTHCHECK → `/health/ready` | нет, состояния не хранит | опубликован `127.0.0.1:8080` | файлы `/run/secrets/database_url`, `/run/secrets/cache_url` |
| миграции | `migrate` | тот же образ, команда `python migrate.py` | одноразовый, код выхода 0 | нет | только внутренняя сеть | файл `/run/secrets/database_url` |
| postgres | `postgres` | `postgres:17.11-alpine` | `pg_isready` | `pgdata` | только внутренняя сеть, 5432 | `POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password` |
| redis | `redis` | `redis:7.4.11-alpine` | `redis-cli ping` | `redisdata` | только внутренняя сеть, 6379 | `--requirepass` из `/run/secrets/redis_password` |
Секреты описаны в `compose.yaml` как `secrets` с источником из переменных `.env`. Compose кладёт их в контейнеры файлами, в окружении контейнеров паролей нет (проверка в `evidence/07-containers.txt`). Наружу опубликован только порт API.
### Файлы
| Файл | Что в нём |
| --- | --- |
| `migrations/0001_init.sql` | таблицы, ключи, ограничения, индексы |
| `src/migrate.py` | применяет миграции по порядку, ведёт таблицу `schema_migrations` |
| `src/store.py` | все SQL-запросы и пул соединений |
| `src/sessions.py` | сессии в Redis |
| `src/security.py` | hash пароля (Argon2id), разбор заголовков Basic и Bearer |
| `src/main.py` | endpoint, middleware, обработка ошибок |
| `src/schemas.py`, `src/errors.py`, `src/config.py` | валидация JSON, формат ошибки, настройки |
### Схема данных
- `users`: `id` (PK), `username` (UNIQUE и CHECK по шаблону), `display_name`, `password_hash`, `created_at`.
- `chats`: `id` (PK), `title`, `created_at`.
- `chat_members`: PK `(chat_id, user_id)`, внешние ключи на `chats` и `users`, `position` — порядок участника в запросе. Индекс `(user_id, chat_id)` для списка чатов пользователя.
- `messages`: `id` (PK), внешние ключи `chat_id` и `sender_id`, `text` (CHECK 1–4000 символов), `created_at`. Индекс `(chat_id, created_at, id)` для истории.
`id` и `created_at` назначает PostgreSQL (`gen_random_uuid()`, `now()`). Ограничения длины продублированы в CHECK, чтобы неверные данные не попали в БД даже в обход приложения.
### Транзакционные границы
Каждый метод `Store` берёт одно соединение из пула и выполняется в одной транзакции: `with pool.connection()` делает COMMIT при выходе и ROLLBACK при исключении.
- **Регистрация** — один `INSERT`. Уникальность username проверяет сама БД; нарушение ограничения превращается в 409. Поэтому два одновременных запроса не создадут двух пользователей.
- **Создание чата** — составная операция: `INSERT` в `chats`, затем `INSERT` всех участников в `chat_members`. Если участника нет, срабатывает внешний ключ, транзакция откатывается вместе с уже вставленным чатом, клиент получает 400.
- **Отправка сообщения** — проверка членства и `INSERT` в одной транзакции.
- Ответ 201 отправляется только после COMMIT. PostgreSQL работает с настройками по умолчанию (`fsync=on`, `synchronous_commit=on`), то есть подтверждённая запись уже на диске.
Все значения попадают в запросы только параметрами `%s`, строки SQL из пользовательских данных не собираются.
### Аутентификация
- Пароль хешируется Argon2id (`argon2-cffi`, 19 МиБ памяти, 2 прохода, 1 поток — минимальные параметры из рекомендаций OWASP). В БД хранится только hash.
- `POST /api/v1/auth/sessions` принимает только `Authorization: Basic`. Неизвестный username и неверный пароль дают одинаковый 401 с `WWW-Authenticate: Basic`. Если пользователя нет, пароль всё равно сверяется с заранее посчитанным hash, чтобы время ответа не выдавало существование username.
- Токен — `secrets.token_urlsafe(32)`, 256 бит случайности. Остальные endpoint принимают только `Authorization: Bearer`; `X-User-Id` не читается, Basic на бизнес-запросах даёт 401.
- Проверка токена выполняется до валидации параметров и тела и до обращения к чату: сначала аутентификация, потом доступ к конкретному ресурсу.
### Роль Redis
Redis — **единственное хранилище сессий**. PostgreSQL о сессиях ничего не знает; источник истины для пользователей, чатов и сообщений — PostgreSQL, для сессий — Redis.
- Ключ `session:<sha256 от токена>`, значение — id пользователя. Сам токен в Redis не хранится, поэтому по дампу нельзя получить рабочий токен.
- **Expiry**: ключ записывается командой `SET ... EX SESSION_TTL_SECONDS`, срок отсчитывается от входа и запросами не продлевается. Истёкший ключ Redis удаляет сам.
- **Инвалидация**: logout — это `DEL` ключа текущей сессии. Другие сессии того же пользователя остаются.
- **Persistence**: включён AOF с `appendfsync always`, данные лежат в volume `redisdata`. Сессия переживает перезапуск Redis, а оставшийся TTL при этом не увеличивается (`evidence/04-redis-sessions.txt`: 3591 с до перезапуска, 3583 с после).
- Политика вытеснения — `noeviction`: при нехватке памяти Redis откажет в записи новой сессии, но не удалит действующие.
- После `FLUSHALL` или удаления volume `redisdata` все сессии пропадают: каждый токен получит 401, пользователям нужно войти заново. Данные в PostgreSQL при этом не страдают.
### Пул соединений и таймауты
| Что | Значение | Где задаётся |
| --- | --- | --- |
| соединений с PostgreSQL | от 2 до 10 | `DB_POOL_MIN_SIZE`, `DB_POOL_MAX_SIZE` |
| ожидание свободного соединения | 3 с | `DB_POOL_TIMEOUT` |
| установка соединения с PostgreSQL | 3 с | `DB_CONNECT_TIMEOUT` |
| выполнение одного запроса | 5 с (`statement_timeout`) | `DB_STATEMENT_TIMEOUT` |
| соединений с Redis | до 20 | `CACHE_POOL_MAX_SIZE` |
| операция с Redis и ожидание соединения | 2 с | `CACHE_TIMEOUT` |
Перед выдачей из пула соединение с PostgreSQL проверяется, поэтому после перезапуска БД запросы не получают мёртвые соединения.
### Поведение при отказе зависимостей
- **Redis недоступен**: проверить токен нечем, поэтому любой запрос с токеном получает 503 `unavailable`. Запрос не выполняется ни от имени владельца токена, ни как анонимный. Запрос без токена по-прежнему получает 401.
- **PostgreSQL недоступен**: запросы, которым нужны данные, получают 503 не позже чем через 3 секунды (ожидание соединения из пула).
- `/health/ready` проверяет обе зависимости (`SELECT 1` и `PING`) и отвечает 503 в общем формате ошибки, если хотя бы одна недоступна. `/health/live` от них не зависит.
- API стартует, даже если БД ещё не поднялась, и отвечает 503 до её появления.
### Пагинация и порядок
Запрос истории:
```sql
SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id LIMIT $4
```
Cursor — base64 от JSON `[область, created_at, id]` последней выданной записи; область привязывает его к конкретному чату или к списку чатов конкретного пользователя. Запрашивается `limit + 1` строк: лишняя строка показывает, есть ли следующая страница.
**Семантика при конкурентных вставках.** `created_at` — это `now()` PostgreSQL, то есть время начала транзакции. Две параллельные транзакции могут зафиксироваться не в порядке своих `created_at`. Поэтому сообщение с чуть более ранним временем может появиться в истории уже после того, как клиент прошёл это место по cursor, и при обходе вперёд он его не увидит (окно — миллисекунды, длительность транзакции вставки). Повторов при обходе нет. Чтение после записи выполняется: ответ 201 приходит после COMMIT, следующий `GET` это сообщение видит.
### Соответствие переменных окружения
| Переменная в `.env` | По умолчанию | Что делает |
| --- | --- | --- |
| `APP_HOST`, `APP_PORT` | `0.0.0.0`, `8080` | адрес сервера; в compose заданы жёстко, из `.env` не читаются |
| `APP_ENV` | `lab` | выводится в лог при старте |
| `SESSION_TTL_SECONDS` | `3600` | срок жизни сессии |
| `SESSION_STORE` | `redis` | поддерживается только `redis`, с другим значением сервер не стартует |
| `DATABASE_URL_FILE`, `CACHE_URL_FILE` | `/run/secrets/...` | пути к файлам со строками подключения; в compose заданы жёстко |
| `LOG_LEVEL`, `SHUTDOWN_TIMEOUT` | `info`, `8` | как в lab1 |
| `DB_POOL_*`, `DB_*_TIMEOUT`, `CACHE_*` | см. таблицу выше | пул и таймауты |
| `POSTGRES_PASSWORD`, `REDIS_PASSWORD`, `DATABASE_URL`, `CACHE_URL` | создаёт `init-env.sh` | источник compose-секретов; в контейнер `api` попадают только файлами |
### Что перенесено из lab1 и что изменено
Перенесены: структура `src/`, формат ошибок и `X-Request-Id`, валидация JSON, cursor-пагинация, логирование без содержимого, Dockerfile (непривилегированный пользователь, healthcheck, корректная остановка по SIGTERM), собственные тесты.
Изменено: хранилище в памяти заменено на PostgreSQL; `X-User-Id` заменён на пароль, Basic и Bearer; добавлены миграции, Redis, compose, проверка зависимостей в `/health/ready` и ответ 503. Строки теперь проверяются ещё и на символ NUL, который PostgreSQL не хранит. Контракт и публичные тесты не менялись.
## Доказательства критериев
Стенд: Apple M3 Pro, 11 CPU, 18 ГБ RAM, macOS 26.1, Docker 29.3.0, Compose 5.1.0, без ограничений CPU/RAM для контейнеров. Все файлы получены из чистого clone на пустых volumes, commit `6473fd0`.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab2 public API scenario` | `evidence/01-up-and-smoke.txt` |
| 3: данные и сессии переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`; у контейнеров `postgres`, `redis`, `api` новое время старта, volumes те же | `evidence/03-persistence.txt` |
| 3: таблицы, ключи, уникальность username, миграции с нуля | `make up` на пустом volume | `применена: 0001_init.sql`, smoke проходит | `evidence/01-up-and-smoke.txt`, `migrations/0001_init.sql` |
| 3: создание чата атомарно | `make test-failures` (`test_transactions.py`) | после неудачного создания в `chats` 0 строк, после удачного — чат и 2 участника | `evidence/05-failures.txt` |
| 3: Basic только на входе, Bearer на остальном, срок жизни, отзыв, `X-User-Id` не даёт доступ | `make student-test` (`test_auth.py`) | 15 тестов `ok` | `evidence/02-student-tests.txt` |
| 3: пароли хешируются KDF | `test_password_is_stored_as_argon2id_hash` | hash в БД начинается с `$argon2id$` | `evidence/05-failures.txt` |
| 3: миграции повторяются без дублирования | `docker compose run --rm migrate` | `уже применена: 0001_init.sql`, в `schema_migrations` одна строка, число строк в таблицах не изменилось | `evidence/03-persistence.txt`, `evidence/05-failures.txt` |
| 3: secrets и volumes не в Git | `git ls-files \| grep -E "^\.env$\|secrets"` | пусто | `evidence/07-containers.txt` |
| 4: Redis реально используется для сессий с TTL и persistence | `redis-cli CONFIG GET`, `TTL`, `docker compose restart redis` | `appendonly yes`, `appendfsync always`; ключ пережил перезапуск, TTL 3591 → 3583 | `evidence/04-redis-sessions.txt` |
| 4: параметризованные запросы, ограниченный пул, таймауты | `src/store.py`, `src/sessions.py`; остановка зависимостей | 503 через 0,01 с без Redis и через 3,0 с без PostgreSQL | `evidence/05-failures.txt` |
| 4: гонка регистрации одного username | `test_username_race_creates_one_row`, `test_same_username_registered_once` | один ответ 201 и девять 409, в `users` одна строка | `evidence/05-failures.txt`, `evidence/02-student-tests.txt` |
| 4: rollback составной операции | `test_chat_with_unknown_member_is_rolled_back` | 400, в `chats` 0 строк с этим названием, участников без чата нет | `evidence/05-failures.txt` |
| 4: индекс истории обоснован EXPLAIN на ≥10 000 сообщений | `make explain` | Index Scan, 8 буферов на страницу в любом месте истории | `evidence/06-explain.txt` |
| 4: автоматическая проверка expiry при коротком TTL | `test_expiry.py`, API с `SESSION_TTL_SECONDS=2` | через 3 с токен получает 401, запросы срок не продлевают | `evidence/05-failures.txt` |
| 4: автоматическая проверка logout и неверного пароля | `test_auth.py` | после logout 401, вторая сессия работает; неверный пароль — 401 | `evidence/02-student-tests.txt` |
| 4: недоступность Redis и БД | `test_dependencies.py` | 503 `unavailable` за ограниченное время, аноним получает 401, после восстановления прежний токен и данные на месте | `evidence/05-failures.txt` |
| Возможности lab1: непривилегированный пользователь, закреплённые версии, SIGTERM | `docker compose exec api id`, `scripts/sigterm_check.py` | `uid=10001(app)`; начатый запрос получил 201, выход за 1,45 с с кодом 0 | `evidence/07-containers.txt`, `evidence/08-sigterm.txt` |
## Эксперименты и отказы
Нагрузочное исследование (трек 5) не проводилось.
### Индекс истории
Гипотеза: индекс `(chat_id, created_at, id)` позволяет читать любую страницу истории за число обращений к диску, не зависящее от длины истории и от положения страницы.
Методика: `scripts/seed_history.sql` создаёт 21 чат и 60 000 сообщений, из них 10 000 в исследуемом чате, остальные 50 000 поровну в 20 других; затем `ANALYZE`. `scripts/explain_history.sql` выполняет `EXPLAIN (ANALYZE, BUFFERS)` для четырёх запросов с `LIMIT 51` (страница 50 плюс одна строка). Данные небольшие и целиком в кэше, поэтому сравнивать нужно число буферов, а не миллисекунды.
| Запрос | План | Буферов | Время выполнения |
| --- | --- | --- | --- |
| первая страница | Index Scan по `messages_chat_history_idx` | 8 | 0,025 мс |
| страница после 5000-го сообщения, keyset | Index Scan, условие на `(created_at, id)` внутри Index Cond | 8 | 0,034 мс |
| та же страница через `OFFSET 5000` | Index Scan, прочитано 5051 строка | 491 | 0,469 мс |
| keyset без индекса | Seq Scan всей таблицы (отброшено 55 140 строк) и сортировка | 862 | 2,266 мс |
Вывод: с индексом и keyset страница из середины стоит столько же, сколько первая, сортировка не нужна. OFFSET читает все пропущенные строки, и стоимость растёт с номером страницы. Без индекса каждая страница читает всю таблицу, включая чужие чаты.
Ограничение измерения: одна таблица на 60 000 строк, один запуск, всё в памяти. Для вывода о реальной нагрузке этого мало. Четвёртый запрос выполняет `DROP INDEX` внутри транзакции с `ROLLBACK`: на это время таблица `messages` заблокирована, поэтому скрипт годится только для учебного стенда.
### Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker compose restart postgres redis api` | данные и сессия на месте | прежний токен читает прежние сообщения | готов через несколько секунд, потерь нет |
| `docker compose stop redis` | запросы с токеном не выполняются | 503 за 0,01 с; без токена 401; `/health/ready` 503, `/health/live` 200 | после `start redis` прежний токен работает, сообщение, отправленное во время отказа, не записано |
| `docker compose stop postgres` | запросы к данным не выполняются | 503 за 3,0 с; без токена 401 | после `start postgres` данные на месте, запись снова работает |
| сессия с TTL 2 с | через 2 с токен недействителен | через 3 с 401, logout с ним тоже 401, новый вход работает | — |
| чат с несуществующим участником | ничего не создаётся | 400, в `chats` и `chat_members` следов нет | — |
| 10 одновременных регистраций одного username | один пользователь | один 201, девять 409, одна строка | — |
| SIGTERM процессу API | начатый запрос завершится | 201, новые соединения не принимаются, выход за 1,45 с | — |
## Ограничения и следующие шаги
- Один экземпляр API, один PostgreSQL, один Redis на одном хосте. Отказ хоста, диска или любого из хранилищ не переживается, резервных копий нет.
- При недоступном Redis не работает ни один запрос с токеном: запасного пути проверки сессии нет. Это осознанный выбор в пользу простоты и того, что отозванная сессия не может «ожить» из другого хранилища.
- `appendfsync always` делает каждую запись сессии синхронной записью на диск. Для учебного стенда это незаметно, под нагрузкой вход станет узким местом.
- Нет ограничения числа попыток входа и числа сессий на пользователя, код 429 не используется.
- Порядок истории при параллельных вставках описан выше: возможен пропуск сообщения при обходе вперёд в окне длительности транзакции.
- Если JSON синтаксически сломан, FastAPI отвечает 400 раньше, чем проверяется токен. На доступ к данным это не влияет.
- При недоступной БД ответ 503 приходит через 3 секунды, а не сразу: столько запрос ждёт соединение из пула.
- Пароли в `.env` лежат открытым текстом на диске разработчика (права 600). Для локального стенда с синтетическими данными это допустимо.
- `make explain` оставляет в БД синтетические чаты и 60 000 сообщений; убрать их можно только `make clean`.
- Проверено на одном стенде (macOS, Docker Desktop). На Linux не запускалось.