forked from mtusi2026/mtusi2026lab2
169 lines
22 KiB
Markdown
169 lines
22 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Саватеев Артём, БВТ2302
|
||
- Целевая оценка: **4** (все пункты уровней 3 и 4)
|
||
- Commit/PR: TODO после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: FastAPI, Pydantic, Uvicorn, loguru, asyncpg, redis-py, argon2-cffi; для тестов pytest, httpx; документация PostgreSQL (transactions, EXPLAIN, advisory locks, `uuidv7`) и Valkey
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии: Docker Engine 29.0.1, Docker Compose v2.40.3 (проверено на Docker Desktop, linux/arm64). Образы закреплены явными тегами: `python:3.12.12-slim`, `postgres:18.22`, `valkey/valkey:8.1.4`. Python-зависимости закреплены в `pyproject.toml` (точные версии) и `poetry.lock`.
|
||
|
||
Prerequisites: Docker с Compose, make, curl, Python ≥ 3.9 для публичных тестов. Для собственных тестов дополнительно Python 3.12 и Poetry 2.2.1.
|
||
|
||
```sh
|
||
# Запуск
|
||
cp .env.example .env
|
||
make up # docker compose up -d --build --wait; миграции API применяет сам при старте
|
||
|
||
# Проверки
|
||
make check # структура skeleton
|
||
make test # публичный smoke
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # рестарт api, postgres, valkey с сохранением volume
|
||
make install # dev-окружение Poetry (один раз)
|
||
make student-test # собственные тесты, одна команда
|
||
make test-migrations # миграции на пустом volume отдельного compose-проекта
|
||
make test-expiry # второй API с SESSION_TTL_SECONDS=2 на :8081
|
||
make test-failures # останавливает и запускает valkey и postgres
|
||
make explain # сид ≥10 000 сообщений и планы запроса истории
|
||
|
||
# Безопасная остановка без потери данных
|
||
make down # = docker compose --profile expiry down
|
||
```
|
||
|
||
Намеренное удаление учебных данных — `make destroy-data` (`docker compose down -v`): volume `postgres_data` будет стёрт. Остальные команды volume не удаляют.
|
||
|
||
Операторских действий кроме создания `.env` не требуется. `make up` ждёт healthcheck всех сервисов, готовность API — `GET /health/ready`. `.env` в образ не копируется (`.dockerignore`), конфигурация передаётся через `env_file` в `compose.yaml`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
Клиент ──HTTP :8080──▶ api (FastAPI, uvicorn) ──asyncpg pool 2..10──▶ postgres источник истины, volume postgres_data
|
||
│
|
||
└──redis-py pool ≤20, timeout 0.5 s──▶ valkey read-through кэш сессий, без persistence
|
||
сети: default (только api, 127.0.0.1:8080) + backend (internal: api, postgres, valkey)
|
||
```
|
||
|
||
Слои в `src/`:
|
||
|
||
| Каталог | Ответственность |
|
||
| --- | --- |
|
||
| `config/` | чтение окружения через envparse, логирование loguru в stdout |
|
||
| `domain/` | Pydantic-схемы запросов/ответов, сессии и учётные данные, коды и исключения ошибок |
|
||
| `interfaces/` | ABC-репозитории и кэш сессий: сервисы зависят от абстракций, а не от PostgreSQL/Valkey |
|
||
| `infrastructure/` | репозитории PostgreSQL, кэш Valkey, сервисы, Argon2id и токены (`security/`), пул БД и кэша, пагинация/cursor, `ServiceCreator` для DI |
|
||
| `application/api/` | роутеры, Basic/Bearer зависимости, middleware, обработчики ошибок |
|
||
| `gateway.py` | сборка приложения, lifespan (пул, миграции, кэш), запуск uvicorn |
|
||
|
||
Миграции — нумерованные SQL-файлы в `migrations/`.
|
||
|
||
Роли и сервисы `compose.yaml`:
|
||
|
||
| Роль | Сервис | Версия | Health / readiness | Volume | Сеть / порт | Credentials |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| API | `api` | сборка из `Dockerfile` | `src/healthcheck.py` → `/health/ready` | нет | default + backend, `127.0.0.1:8080` | `DB_*`, `VALKEY_*` из `.env` (env_file) |
|
||
| PostgreSQL | `postgres` | `postgres:18.2-alpine3.22` | `pg_isready` | `postgres_data:/var/lib/postgresql` | backend (internal), не публикуется | `POSTGRES_PASSWORD` ← `DB_PASS` |
|
||
| Valkey | `valkey` | `valkey/valkey:8.1.4-alpine3.22` | `valkey-cli ping` | нет (чистый кэш) | backend (internal), не публикуется | `--requirepass` ← `VALKEY_PASS` |
|
||
| API с коротким TTL | `api-short-ttl` (profile `expiry`) | тот же образ | как у API | нет | `127.0.0.1:8081` | как у API, `SESSION_TTL_SECONDS=2` |
|
||
|
||
**Что перенесено из lab1.** Слои `application/domain/interfaces/infrastructure`, контракт ошибок, `X-Request-Id`, keyset-cursor, graceful shutdown, Dockerfile с пользователем не root. In-memory хранилище удалено, вместо него репозитории `Postgres*Repository` и `ValkeySessionCache` за теми же интерфейсами.
|
||
|
||
**Переходы API по COURSE.md.** Регистрация требует `password` (12–128 code points). Вход только через `POST /api/v1/auth/sessions` с Basic. Все бизнес-endpoint требуют Bearer. Basic на бизнес-endpoint и `X-User-Id` возвращают 401 и не влияют на владельца сессии.
|
||
|
||
**Источник истины** — PostgreSQL. Схема — `migrations/0001_init.sql`:
|
||
|
||
| Таблица | Ключи и ограничения |
|
||
| --- | --- |
|
||
| `users` | PK `id uuid DEFAULT uuidv7()`, `UNIQUE (username)`, CHECK формата username и длины display_name, `password_hash` (PHC Argon2id) |
|
||
| `sessions` | PK `token_hash bytea` (SHA-256 токена, 32 байта), FK `user_id → users`, `expires_at`, `revoked_at`, CHECK `expires_at > created_at` |
|
||
| `chats` | PK uuid v7, FK `created_by → users`, CHECK длины title |
|
||
| `chat_members` | PK `(chat_id, user_id)`, FK на chats и users, `position` (порядок `member_ids`), `UNIQUE (chat_id, position)`, индекс `(user_id, chat_id)` |
|
||
| `messages` | PK uuid v7, FK `(chat_id, sender_id) → chat_members`: отправитель обязан быть участником; CHECK длины text; индекс `(chat_id, created_at, id)` |
|
||
|
||
UUID v7 упорядочен по времени, поэтому вставки в B-tree PK идут в правую часть, как у bigint, а наружу отдаётся UUID, как требует контракт.
|
||
|
||
**Регистрация** — один `INSERT`. Гонку одинаковых username разрешает `UNIQUE`, `UniqueViolationError` превращается в 409. Проверки «сначала SELECT» нет.
|
||
|
||
**Вход.** `SELECT` пользователя, проверка Argon2id в отдельном пуле потоков, затем `INSERT sessions` с `expires_at = clock_timestamp() + TTL` по часам БД. Токен — 32 случайных байта (256 бит), в БД хранится только его SHA-256. Для неизвестного username проверяется dummy-hash, поэтому ответ и время одинаковы.
|
||
|
||
**Создание чата** — `BEGIN` → `INSERT chats` → `INSERT chat_members` (unnest) → `COMMIT`. Неизвестный участник нарушает FK, транзакция откатывается целиком, клиент получает 400. Предварительной проверки участников нет: она была бы гонкой и маскировала бы откат.
|
||
|
||
**Сообщение** — `BEGIN` → `pg_advisory_xact_lock(2, hashtext(chat_id))` → `INSERT … created_at = GREATEST(clock_timestamp(), MAX(created_at) + 1 µs)` → `COMMIT`. Внутри чата `created_at` строго возрастает, и порядок коммитов совпадает с порядком `(created_at, id)`. Поэтому читатель с cursor не пропустит сообщение, вставленное «задним числом» конкурентной транзакцией. Это замена `asyncio.Lock` и `MonotonicClock` из lab1, корректная для нескольких процессов. Записи в один чат сериализуются, записи в разные чаты нет.
|
||
|
||
**Logout** — `UPDATE sessions SET revoked_at` для действующей сессии (0 строк → 401), затем `DEL` ключа в Valkey.
|
||
|
||
**Valkey.** Read-through кэш сессий: ключ `session:<sha256(token) hex>`, значение `{user, expires_at}`. При попадании в кэш аутентификация выполняется без SQL. Источник истины — таблица `sessions`, Valkey хранит только копию. TTL записи — `min(остаток жизни сессии, SESSION_CACHE_TTL_SECONDS=60)`, приложение дополнительно сверяет `expires_at`. Logout удаляет ключ после фиксации отзыва в БД; если Valkey в этот момент недоступен, запись может остаться не дольше 60 с, это логируется как warning.
|
||
|
||
**Persistence Valkey выключена** (`--save "" --appendonly no`). Valkey не единственное хранилище сессий: после рестарта или flush кэш пуст и заполняется из PostgreSQL, сессии не теряются. Заодно запись, не удалённая при logout во время сбоя, не «воскресает» после рестарта Valkey.
|
||
|
||
**Отказ Valkey.** Ошибка (таймаут 0.5 с, без встроенных повторов) переводит кэш в режим обхода на `VALKEY_RETRY_AFTER_SEC=5` с: все запросы идут в PostgreSQL без сетевых попыток к Valkey, сервис работает, `/health/ready` = 200.
|
||
|
||
**Readiness.** Критичен только PostgreSQL: `/health/ready` выполняет `SELECT 1`, без него ответ — `503 unavailable` без деталей SQL. Анонимный запрос — 401. Неизвестный токен при недоступной БД — 503, а не 200: доверие без проверки невозможно. Valkey не критичен.
|
||
|
||
**Пул и таймауты.** asyncpg: `min_size=2`, `max_size=10`, connect/acquire timeout 3 с, `command_timeout` 5 с и серверный `statement_timeout` 5 с. Ошибки соединения превращаются в `UnavailableError` (503); первая такая ошибка вызывает `pool.expire_connections()`, чтобы после рестарта PostgreSQL 503 получил один запрос, а не все соединения пула по очереди. Запросы только параметризованные (`$1…$n`), SQL написан в методах репозиториев, значения в текст запроса не подставляются.
|
||
|
||
| Переменная | Где используется | Значение в примере |
|
||
| --- | --- | --- |
|
||
| `APP_HOST` | адрес bind uvicorn; в контейнере обязательно `0.0.0.0` | `0.0.0.0` |
|
||
| `APP_PORT` | порт uvicorn, healthcheck, публикация порта в `compose.yaml` | `8080` |
|
||
| `APP_ENV` | имя окружения в логе запуска приложения | `lab` |
|
||
| `LOG_LEVEL` | уровень loguru | `INFO` |
|
||
| `SHUTDOWN_TIMEOUT_SEC` | `timeout_graceful_shutdown` uvicorn | `5` |
|
||
| `DB_USER`, `DB_PASS`, `DB_NAME`, `DB_HOST`, `DB_PORT` | подключение asyncpg; учётные данные сервиса `postgres`. В контейнере API `compose.yaml` подставляет `DB_HOST=postgres` | `test`, `test`, `test`, `localhost`, `5432` |
|
||
| `DB_POOL_MIN_SIZE`, `DB_POOL_MAX_SIZE` | границы пула asyncpg | `2`, `10` |
|
||
| `DB_CONNECT_TIMEOUT_SEC`, `DB_COMMAND_TIMEOUT_SEC` | таймаут подключения/ожидания соединения и выполнения запроса | `3`, `5` |
|
||
| `DB_STARTUP_TIMEOUT_SEC` | сколько ждать БД при старте API | `30` |
|
||
| `VALKEY_HOST`, `VALKEY_PORT`, `VALKEY_PASS` | подключение к Valkey; пароль сервиса `valkey`. В контейнере API `compose.yaml` подставляет `VALKEY_HOST=valkey` | `localhost`, `6379`, `test` |
|
||
| `VALKEY_POOL_MAX_SIZE`, `VALKEY_TIMEOUT_SEC`, `VALKEY_RETRY_AFTER_SEC` | пул redis-py, таймаут операции, пауза обхода кэша после ошибки | `20`, `0.5`, `5` |
|
||
| `SESSION_TTL_SECONDS` | срок жизни сессии | `3600` |
|
||
| `SESSION_CACHE_TTL_SECONDS` | верхняя граница TTL записи в Valkey | `60` |
|
||
| `PASSWORD_HASH_WORKERS` | потоки Argon2id: ограничение CPU/RAM на одновременные входы | `4` |
|
||
|
||
Переменные skeleton: `DATABASE_URL_FILE` заменён на `DB_*`, `CACHE_URL_FILE` — на `VALKEY_*`; `SESSION_STORE=postgres` соответствует реализации: сессии в PostgreSQL, Valkey — кэш.
|
||
|
||
## Доказательства критериев
|
||
|
||
Полный вывод команд сохранён в каталоге `evidence/`, имя файла указано в скобках.
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат |
|
||
| --- | --- | --- |
|
||
| 3: публичный smoke | `make check && make test` | `PASS: lab2 public API scenario` (smoke.txt) |
|
||
| 3: данные и действующие сессии переживают рестарт API и хранилищ | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS`; `StartedAt` у api, postgres, valkey изменился, volume сохранён, токен до рестарта работает после (persistence.txt) |
|
||
| 3: PK/FK, уникальность username, индексы | `\d+ messages`, `\di` | ограничения и индексы из миграции (migrations.txt) |
|
||
| 3: миграции с нуля и повторно без дублирования | `make test-migrations` | пустой volume: 0 таблиц → запуск 1 применяет `0001_init` → запуски 2–3 ничего не меняют (migrations_from_zero.txt) |
|
||
| 3: атомарное создание чата | `test_failed_chat_creation_is_rolled_back` | 400; в БД 0 строк `chats` с этим title и 0 участников-сирот (race_rollback.txt) |
|
||
| 3: Basic только на `POST /auth/sessions`, Bearer на остальных, X-User-Id не даёт доступа | `test_auth.py`, `test_users.py`, smoke | 401 с `WWW-Authenticate: Basic …` / `Bearer …`; Basic на бизнес-endpoint — 401; `X-User-Id` игнорируется (student_tests.txt) |
|
||
| 3: KDF паролей | `test_password_is_not_stored_in_plaintext` | в `users.password_hash` строка `$argon2id$…`, пароля нет (student_tests.txt) |
|
||
| 3: секреты и volumes не в Git | `git check-ignore .env`, `.gitignore` | `.env`, `volumes/`, `data/`, `secrets/` игнорируются |
|
||
| 4: Valkey реально используется для сессий с TTL | `test_valkey_down_cache_is_bypassed`, раздел «Valkey» | read-through кэш, TTL ≤ min(сессия, 60 с), DEL при logout (dependency_failures.txt) |
|
||
| 4: параметризованные запросы, ограниченный пул и таймауты | `infrastructure/repositories/*/postgres.py`, `dependencies/database.py`, `dependencies/cache.py` | только `$n`; пул 2..10; таймауты 3/5 с; Valkey ≤20, 0.5 с |
|
||
| 4: гонка регистрации одинакового username | `test_same_username_race_creates_exactly_one_user` | 20 параллельных запросов → 1×201, 19×409, 1 строка в БД (race_rollback.txt) |
|
||
| 4: rollback составной операции | `test_failed_chat_creation_is_rolled_back` | откат проверен по содержимому БД, а не только по ответу (race_rollback.txt) |
|
||
| 4: индекс истории и `EXPLAIN (ANALYZE, BUFFERS)` на ≥10 000 сообщениях | `make explain` | 138 769 сообщений, в чате 20 000. Страница из середины: `Index Scan … Index Cond: chat_id AND ROW(created_at,id) > ROW(…)`, 5 буферов, 0.036 мс; generic plan (как в asyncpg) — тот же Index Scan. Без индекса — `Parallel Seq Scan`, 128 768 строк отброшено, 1 792 буфера, 7.28 мс (explain_history.txt) |
|
||
| 4: expiry при коротком `SESSION_TTL_SECONDS` | `make test-expiry` | токен работает и попадает в кэш, через 3 с — 401 на `/users/me`, `/chats`, logout (expiry.txt) |
|
||
| 4: logout, неверный пароль | `test_logout_revokes_only_current_session`, `test_wrong_password_and_unknown_user_are_indistinguishable` | 204 без тела → 401 → повторный logout 401; другая сессия жива; неверный пароль и неизвестный логин дают одинаковый 401 (student_tests.txt) |
|
||
| 4: недоступность Valkey/БД | `make test-failures` | без Valkey вход, запись и logout работают, ответ < 3 с. Без PostgreSQL — `/health/ready` 503, аноним 401, неизвестный токен 503, регистрация/вход 503 без деталей. После рестарта PostgreSQL прежний токен работает (dependency_failures.txt) |
|
||
|
||
Сводка собственных тестов: `make student-test` — 87 passed, 6 skipped (их запускают `make test-expiry` и `make test-failures`).
|
||
|
||
## Эксперименты и отказы
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `scripts/restart.sh`: рестарт postgres, valkey, api | данные и сессии на месте | PASS, прежний токен читает те же сообщения | ~2 с до ready; потерь нет |
|
||
| `docker compose stop valkey` | кэш обходится, API работает | вход, Bearer, запись, logout — OK, ready 200; один warning, далее 5 с без попыток | мгновенно; потерь нет (кэш) |
|
||
| logout при остановленном valkey, затем его старт | отозванный токен не принимается | 401 после подъёма: кэш без persistence пуст | — |
|
||
| `docker compose stop postgres` | ограниченный 503, без доверия анониму | ready 503, аноним 401, неизвестный токен 503, ответ < 3 с | — |
|
||
| `docker compose restart postgres` при живом API | API переподключается сам | после ready прежний токен работает | до ~2 с; данные на volume |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Один Docker-host: отказ хоста, диска или единственного экземпляра PostgreSQL не переживается, реплик и бэкапов нет. HA для Valkey тоже нет, но он не критичен.
|
||
- `COMMIT` подтверждается после записи WAL на диск (`synchronous_commit=on`, `fsync=on`); гарантия ограничена честностью fsync в Docker Desktop VM и одним диском.
|
||
- Если Valkey недоступен ровно в момент logout, но не перезапускался (например, сетевой разрыв), отозванная сессия может приниматься ещё до 60 с. Граница задаётся `SESSION_CACHE_TTL_SECONDS`.
|
||
- Запись в один чат сериализуется advisory lock: пропускная способность одного «горячего» чата ограничена. Коллизии `hashtext` изредка сериализуют разные чаты.
|
||
- Символ U+0000 в `text`/`title`/`display_name` отклоняется с 400: тип `text` в PostgreSQL его не хранит. Тест lab1 с `\u0000` заменён на отдельный тест отказа.
|
||
- Список чатов пользователя сортируется по `(created_at, id)` после соединения `chat_members` → `chats`, отдельного keyset-индекса нет. Для пользователя с тысячами чатов понадобится денормализация `created_at` в `chat_members`.
|
||
- Устаревшие строки `sessions` не удаляются: фоновой очистки пока нет.
|
||
- `expire_connections` срабатывает на первой ошибке соединения; запрос, который на неё попал, получает 503 и не повторяется прозрачно — автоматических повторов POST нет намеренно.
|