# Отчёт — лабораторная 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.