Files
mtusi2026lab2/REPORT.md
T

14 KiB
Raw Blame History

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

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.