Files
mtusi2026lab2/REPORT.md
T

111 lines
14 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
- Автор, группа: Корнилов Михаил Андреевич, БПИ2304
- Целевая оценка: 3.
- Commit/PR: TODO после публикации (commit, на котором собраны доказательства, указан в `evidence/01-env.txt`)
- Использованные источники, библиотеки и помощь ИИ: Библиотеки: starlette, uvicorn, psycopg 3 + psycopg_pool, argon2-cffi. Каталог `tests/` и `contracts/` курса не менялись. При подготовке использовалась помощь Claude
## Запуск из чистого clone
Стенд проверялся на Windows + Docker Desktop (WSL2): Docker 28.0.4, Compose v2.34.0, Python 3.11.5 для тестов, хост 16 CPU / 8 ГБ. Образы: `postgres:16.4-alpine`, `python:3.12.7-slim-bookworm` (версии закреплены).
Команды выполняются в Git Bash (на Linux/macOS — в любом sh) из корня репозитория:
```sh
sh scripts/setup-secrets.sh # создаёт secrets/pg_password и secrets/database_url (в .gitignore, значения не печатаются)
docker compose up -d --build # миграции применяются при старте API
curl http://localhost:8080/health/ready # ждём {"status":"ok"}
python tests/smoke.py --base-url http://localhost:8080 # = make test
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080
# на Linux/macOS: --action-script scripts/restart.sh (= make test-persistence)
sh scripts/collect-evidence.sh # все проверки ниже и сохранение в evidence/ (--fresh сначала удаляет данные)
docker compose stop # безопасная остановка: контейнеры остановлены, данные сохранены
docker compose down -v # ОСОЗНАННОЕ удаление учебных данных (том pgdata)
```
Действия оператора: только `setup-secrets.sh` (создать секреты). `.env` не обязателен: у переменных есть значения по умолчанию в `compose.yaml`; при желании `cp .env.example .env`. Порт API опубликован только на `127.0.0.1:8080`, PostgreSQL наружу не опубликован.
## Архитектура и решения
Клиент → API (Starlette/uvicorn, непривилегированный пользователь в контейнере) → PostgreSQL 16 (именованный том `pgdata`). Источник истины — PostgreSQL, сессии тоже хранятся там, поэтому они переживают рестарт API и БД.
- Таблицы: `users`, `chats`, `chat_members`, `messages`, `sessions`, `schema_migrations`; PK/FK, `UNIQUE(username)`, CHECK на длины и формат (схема — `evidence/05-db-schema.txt`).
- Миграции: `src/migrations/*.sql`, применяются при старте API по порядку под advisory lock, версии пишутся в `schema_migrations`; повторный запуск ничего не дублирует.
- Транзакционная граница: создание чата (чат + участники) выполняется в одной транзакции.
- Пароли: Argon2id (argon2-cffi, параметры по умолчанию). Токен: `secrets.token_urlsafe(32)` (256 бит); в БД хранится только sha256 токена (32 байта).
- Basic принимается только на `POST /auth/sessions`; остальные endpoint — только Bearer. `X-User-Id` игнорируется. Logout ставит `revoked_at`; срок жизни — `SESSION_TTL_SECONDS` (по умолчанию 3600).
- История сообщений: keyset по `(created_at, id)`, индекс `messages(chat_id, created_at, id)`, cursor привязан к чату.
- Готовность: `/health/live` не зависит от БД; `/health/ready` и бизнес-endpoint при недоступной БД отвечают 503 в общем формате ошибок. Пул соединений (`min 2`, `max DB_POOL_MAX=10`, таймаут получения соединения 2 с) восстанавливается сам.
**Из lab1 перенесено:** все endpoint (`/users`, `/users/me`, `/chats`, `/chats/{id}`, сообщения), формат ошибок и `X-Request-Id`, валидация полей, keyset-пагинация, коды 400/401/404/413/415. Хранилище in-memory заменено PostgreSQL.
**Изменено по объявленным переходам:** при регистрации передаётся `password`; вместо `X-User-Id` — сессии (`POST /auth/sessions`, `DELETE /auth/sessions/current`, Bearer). Неверный UUID в пути везде даёт 400, как в lab1.
**Соответствие `.env.example`:**
| Переменная | Статус |
| --- | --- |
| `SESSION_TTL_SECONDS` | используется (compose передаёт в API) |
| `DATABASE_URL_FILE` | используется (`/run/secrets/database_url`, Docker secret) |
| `APP_ENV` | передаётся в контейнер, приложением не читается |
| `APP_HOST`, `APP_PORT` | не читаются; адрес и порт заданы в `CMD` Dockerfile (`0.0.0.0:8080`), наружу порт публикуется на `127.0.0.1` |
| `SESSION_STORE=postgres` | только маркер: сессии всегда в PostgreSQL |
| `CACHE_URL_FILE` | не используется (Redis/Valkey нужен на 4) |
| `DB_POOL_MAX` | читается приложением (по умолчанию 10), в `.env.example` отсутствует |
## Доказательства критериев
Все файлы лежат в `evidence/`; они собраны одним запуском `sh scripts/collect-evidence.sh`, токены и пароли в них не печатаются.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `python tests/smoke.py` | PASS; `scripts/check_contract.py` — PASS | `02-smoke.txt` |
| PostgreSQL, PK/FK, уникальный username | `\d` по всем таблицам | `users_pkey`, `UNIQUE(username)`, FK `chat_members`/`messages`/`sessions`, индексы истории | `05-db-schema.txt` |
| Версионируемые миграции, повтор без дублей | рестарт API + 2 явных вызова `migrate.run` | одна запись `001_init.sql`, число users/messages не изменилось | `06-migrations.txt` |
| Пароль хранится как KDF-хэш | `select left(password_hash,10)` | 10 из 10 хэшей начинаются с `$argon2id$` | `05-db-schema.txt` |
| Токен не хранится в открытом виде | `select length(token_hash)` | 10 из 10 — 32 байта (sha256) | `05-db-schema.txt` |
| Basic только на входе, Bearer на остальном; `X-User-Id` игнорируется | собственные проверки | Basic на `/users/me` → 401; один `X-User-Id` → 401; при Bearer + чужом `X-User-Id` владелец определяется токеном | `03-student-checks.txt` |
| Вход неотличим при неверном пароле и неизвестном пользователе | собственные проверки | оба случая 401 с одинаковыми code/message/`WWW-Authenticate` | `03-student-checks.txt` |
| Logout и срок жизни сессии | logout; TTL=2 с | logout 204, повтор → 401, токен после logout → 401; при TTL=2 токен рабочий сразу и недействителен через 3,5 с | `03-student-checks.txt`, `07-ttl.txt` |
| Гонка регистрации одного username | 10 параллельных запросов | ровно один 201, остальные 409 | `03-student-checks.txt` |
| Атомарное создание чата | чат с несуществующим участником | 400, число чатов пользователя не изменилось | `03-student-checks.txt` |
| Доступ только участникам | запросы постороннего | 404 на чат, историю и отправку; неверный UUID → 400 | `03-student-checks.txt` |
| Пагинация | `limit=2`, cursor | 6 сообщений без повторов; cursor другого чата, `limit=0/101/abc/+5`, повтор параметра → 400 | `03-student-checks.txt` |
| Сохранность при рестарте API и БД | `tests/resilience.py --mode persistence`, hook `scripts/restart.cmd` | PASS; `StartedAt` обоих контейнеров изменился, `RestartCount=0`; после рестарта в БД users=10, chats=4, messages=9, sessions=10 | `04-persistence.txt` |
| Hook действительно перезапускает процессы | `docker inspect … StartedAt` до/после | postgres 18:07:23 → 18:07:42, api 18:07:27 → 18:07:43 (UTC) | `04-persistence.txt` |
| Compose: именованный том, версии образов, готовность | `docker compose config/images/ps` | том `mtusi2026lab2_pgdata`, образы закреплены, оба сервиса `healthy` | `01-env.txt`, `05-db-schema.txt` |
| Секреты и volumes вне Git | `git check-ignore`, `git ls-files` | `secrets/` и `.env` игнорируются, отслеживаемых секретов нет | `09-git-hygiene.txt` |
Примечание к проверке hook: `tests/resilience.py` подтверждает сохранность данных и сессии, а какие процессы перезапущены, показывают значения `StartedAt` выше (перезапущены оба контейнера: сначала `postgres`, после `pg_isready` — `api`).
## Эксперименты и отказы
Нагрузочные измерения (RPS, p50/p95/p99) на уровне 3 не проводились. Проверены отказы:
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Рестарт `postgres` и `api` (`scripts/restart.cmd`) | данные и сессия сохраняются | PASS; оба контейнера перезапущены | ≈4 с до `/health/ready`; потерь нет |
| Рестарт только `api` | миграции не дублируются | одна запись `001_init.sql`, users и messages без изменений | готов сразу после старта; потерь нет |
| `docker compose stop postgres` при работающем API | `live` 200, `ready` и бизнес-endpoint 503 без падения API | `live` 200; `ready` и `/users/me` — 503 в общем формате (с `request_id`) | после `start postgres` `ready` вернулся ≈ через 1 с без рестарта API; потерь нет |
| `SESSION_TTL_SECONDS=2` | токен действует сразу и истекает | 200, затем 401 через 3,5 с | возврат к TTL 3600 пересозданием `api` |
Версии, лимиты и загрузка на момент прогона — `evidence/01-env.txt`; значения времени восстановления — из прогона, лежащего в `evidence/`, на другой машине они могут отличаться на секунды.
## Ограничения и следующие шаги
- Уровень 4 не реализован: нет Redis/Valkey, плана `EXPLAIN` на большом объёме и тестов отказа кэша. Нагрузочный эксперимент уровня 5 не выполнялся.
- Одна БД без репликации и бэкапов, один Docker-host: при потере тома `pgdata` данные потеряны (`down -v` делает это намеренно).
- Просроченные и отозванные сессии не удаляются из `sessions` (есть индекс по `expires_at`, но очистки нет): таблица растёт без фонового удаления.
- Время сообщения берётся из `clock_timestamp()` в момент вставки; при конкурентных вставках в один чат порядок коммитов может не совпасть с порядком времени, и keyset-cursor теоретически способен пропустить запись, зафиксированную позже. Практически не воспроизводилось; строгий порядок потребовал бы счётчика/последовательности на чат.
- API при старте завершается, если БД недоступна; восстановление обеспечивает `restart: unless-stopped` и `depends_on: service_healthy`. После старта пул соединений восстанавливается сам.
- Приложение не ограничивает частоту входа (нет rate limit), защита от перебора паролей — только стоимость Argon2id.
- Реализация учебная: работоспособна и проверена, но не претендует на промышленную готовность.
## Windows (без make)
```sh
python tests/smoke.py --base-url http://localhost:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080
```
Секреты: `sh scripts/setup-secrets.sh` из Git Bash (входит в Git for Windows). Docker Desktop с бэкендом WSL2.