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