Files
mtusi2026lab2/REPORT.md
T
Чиняева df31f4a9fb Реализовать лабораторную 2 на оценку 4
PostgreSQL как источник истины, непрозрачные сессии в Redis с TTL и AOF, миграции под advisory lock, пул и таймауты, проверки гонки/отката/отказов и отчёт с evidence.
2026-11-06 22:37:31 +03:00

15 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Чиняева, БВТ2301
  • Целевая оценка: 4; трек 5 не заявлен.
  • Commit/PR: заполняется после публикации ветки solution/BVT2301-Chinyaeva и открытия MR.
  • Использованные источники, библиотеки и помощь ИИ: официальная документация PostgreSQL (транзакции, EXPLAIN, keyset pagination), Redis (AOF/expiry), RFC 7617 (Basic), Flask, psycopg 3, redis-py, argon2-cffi, gunicorn. ИИ-ассистент использовался для генерации черновика кода, проверки контракта и подготовки отчёта; все команды и результаты ниже воспроизведены на локальном стенде.

Запуск из чистого clone

Стенд проверялся на Windows 11 + Docker Desktop 29.9.2 (16 logical CPU, ~15.2 GiB доступно Docker). Образы закреплены тегами, latest не используется:

Роль Образ/рантайм Порт/volume
API python:3.12.7-slim-bookworm, gunicorn 23.0.0, Flask 3.1.0 8080 (публикуется Docker)
PostgreSQL postgres:16.4-alpine 5432 внутри сети, pgdata
Redis redis:7.4.0-alpine, AOF everysec 6379 внутри сети, redisdata
git clone <fork-url>
cd mtusi2026lab2-Chinyaeva

# Локальные синтетические credentials; .env находится в .gitignore.
cp .env.example .env

docker compose --env-file .env up -d --build
# ждать готовности, не только /health/live:
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done

make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080

На проверочной машине порт 8080 был занят WSL, поэтому локально использовался API_PORT=18080 в .env; это единственное отличие от команд выше. restart.sh предназначен для Linux/macOS, restart.cmd — эквивалент для Windows. Оба выполняют docker compose restart и не удаляют volumes.

Остановка и намеренное удаление учебных данных:

docker compose --env-file .env down          # остановка, данные сохраняются
docker compose --env-file .env down -v       # ТОЛЬКО осознанный сброс volumes
rm .env                                      # локальные credentials

Секреты не попадают в Git: .env, secrets/, *.key, *.pem уже перечислены в .gitignore; compose.yaml получает DATABASE_URL/CACHE_URL из окружения. postgres и redis не публикуют порты на хост, API общается с ними по внутренней сети.

Архитектура и решения

client --HTTP--> api (gunicorn/Flask, 1 process, 8 threads)
                   |-- PostgreSQL: users, chats, chat_members, messages  (источник истины)
                   '-- Redis: session:<sha256(token)> -> {user_id, expires_at}, TTL
  • PostgreSQL — источник истины для пользователей, чатов, членства и сообщений. Все запросы параметризованы (%s), SQL собирается только из фиксированных фрагментов.
  • Redis — хранилище активных сессий. В ключ пишется SHA-256 от bearer-токена, сам токен в Redis не хранится. SESSION_TTL_SECONDS (по умолчанию 3600) — единственная политика продления: TTL не скользит и не продлевается рестартом. Logout удаляет ключ. Источник истины для сессий — Redis; для пользователей/сообщений — PostgreSQL. Если Redis потеряет данные, пользователи и сообщения останутся, но сессии станут недействительными (401). AOF appendfsync everysec + redisdata переживают штатный рестарт; при потере питания возможна потеря до ~1 секунды последних записей.
  • Миграции лежат в migrations/001_init.sql и применяются при старте API под pg_advisory_lock; версия фиксируется в schema_migrations, повторный запуск пропускает уже применённую миграцию и не дублирует данные.
  • Транзакционные границы. Создание чата и всех chat_members — одна транзакция; сбой вставки участника откатывает чат (проверено инъекцией trigger). Регистрация опирается на UNIQUE(username); конкурентная гонка даёт один 201, остальные 409.
  • Пул и таймауты. psycopg_pool 1–10 соединений, acquire timeout 3 с; statement_timeout=5s, idle_in_transaction_session_timeout=10s, lock_timeout=3s; Redis socket/connect timeout 2 с. При недоступности зависимости API возвращает ограниченный 503 unavailable, а не 200/401 с анонимным доступом.
  • Индексы. messages(chat_id, created_at, id) обслуживает keyset-запрос WHERE chat_id=? AND (created_at,id)>(?,?) ORDER BY created_at,id LIMIT ?. chats(created_at,id) — порядок списка чатов; chat_members(user_id,chat_id) — выборка чатов пользователя; users.username уникален.
  • Ошибки и заголовки. Каждый ответ, включая 204/health/ошибки, содержит X-Request-Id; тело ошибки — {"error":{"code","message","request_id"}} с тем же request_id. Basic принимается только на POST /auth/sessions; бизнес-endpoint требуют Bearer. X-User-Id игнорируется. Пароли — Argon2id (argon2-cffi), не SHA-256.

Доказательства критериев

Все команды выполнялись 2026-11-06 на указанном стенде; файлы лежат в evidence/.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Offline-структура и синтаксис python scripts/check_contract.py (make check) PASS: offline skeleton structure... evidence/check.txt
Публичный smoke уровня 3 python tests/smoke.py --base-url http://localhost:18080 PASS: lab2 public API scenario evidence/smoke.txt
Все данные и сессия переживают рестарт API+БД+Redis python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:18080 PASS: persistence preserved confirmed data and existing session; контейнеры до/после рестарта evidence/persistence.txt, evidence/containers-before-restart.txt, evidence/containers-after-restart.txt
PostgreSQL: таблицы, PK/FK, уникальность, миграции psql-запросы к information_schema/pg_indexes/schema_migrations 5 таблиц, 9 индексов, 001_init; повторный старт не дублирует evidence/schema.txt
Redis/Valkey с TTL и persistence redis-cli INFO persistence, DBSIZE, TTL session:* aof_enabled:1, aof_last_write_status:ok, TTL сессии ~3486 с evidence/redis.txt
Ограниченный пул и SQL-таймауты docker compose exec -T api python student-tests/pool_settings.py statement_timeout=5s, pool 1–10, acquire timeout 3 с evidence/pool_settings.txt
Гонка регистрации username python student-tests/race_username.py --workers 8 ровно один 201, семь 409, затем успешный вход evidence/race_username.txt
Откат составной операции docker compose exec -T api python student-tests/rollback_chat.py после сбоя вставки участника чата нет; следующий чат создаётся evidence/rollback_chat.txt
Индекс истории и EXPLAIN на ≥10 000 сообщений docker compose exec -T api python student-tests/explain_history.py Index Scan using messages_chat_created_at_id_idx, rows=51, shared hit=4, 0.124 ms evidence/explain_history.txt
Expiry при коротком TTL API с SESSION_TTL_SECONDS=10, python student-tests/expiry.py --wait 12 свежая сессия 200, через 12 с — 401 + Bearer challenge evidence/expiry.txt
Неверный пароль, Basic на бизнес-endpoint, logout python student-tests/auth_negative.py 401 Basic / 401 Bearer / 204, повторный logout 401 evidence/auth_negative.txt
Недоступность Redis и PostgreSQL python student-tests/fault_matrix.py в обоих случаях 503 unavailable; после старта Redis readiness 0.48 с, PostgreSQL 3.01 с; тот же токен снова 200 evidence/fault_matrix.txt
Граничные случаи контракта локальный edge-сценарий extra fields/пустое тело/неизвестный участник/чужой cursor/4001 символ — 400; лимит ровно limit даёт next_cursor=null evidence/edge_cases.txt
Нагрузочный профиль (не доказательство capacity) python tests/load.py --duration 15 --concurrency 4 --output evidence/load.json 2599 успешных POST, 0 ошибок, 172.7 RPS, p50 22.96 ms / p95 38.87 ms / p99 44.76 ms evidence/load.json, evidence/load.txt

Комментарии к доказательствам

  • explain_history.txt получен после ANALYZE на 10 000 сообщениях в одном чате. План — Index Scan, а не Seq Scan; на страницу читается 51 строка, а не вся история. Это подтверждает отсутствие полного скана на каждую страницу.
  • fault_matrix.txt отдельно показывает, что при отказе Redis уже выданный bearer-токен не превращается в анонимный доступ: запрос возвращает 503, а после восстановления AOF тот же токен снова даёт 200.
  • persistence.txt дополнен containers-*.txt: в after все три контейнера имеют статус Up с малым временем работы, то есть hook действительно перезапустил API, PostgreSQL и Redis, а не только приложение.
  • evidence/redis.txt содержит только хэш ключа сессии (session:<sha256>), не токен. В отчёте и evidence нет паролей, токенов и приватных ключей.

Эксперименты и отказы

Стенд: один Docker host, API + PostgreSQL + Redis в одной Compose-сети; синтетические пользователи и сообщения. Это не проверка HA и не production-сертификат.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
docker compose restart (API+PostgreSQL+Redis), volumes сохранены данные и прежний токен живы PASS persistence; контейнеры перезапущены данные не потеряны; TTL сессии не продлён рестартом
Остановка Redis readiness/запросы с Bearer — 503, не 200 и не доверенный аноним 503 unavailable на /health/ready и /users/me после start redis readiness 0.48 с; тот же токен 200 (AOF)
Остановка PostgreSQL readiness/запросы — 503 503 unavailable на /health/ready и /users/me после start postgres readiness 3.01 с; тот же токен 200
Инъекция ошибки во вставку chat_members чат не должен остаться API вернул ограниченный 500 internal_error, строки чата нет целостность восстановлена откатом транзакции
8 одновременных регистраций одного username ровно один пользователь один 201, семь 409 conflict дубликатов нет

Ограничения измерения нагрузки: tests/load.py — closed-loop генератор, клиент и сервер на одном хосте; 172.7 RPS отражают HTTP-подтверждения в этом стенде, а не предел PostgreSQL. В отчёте нет универсального проходного RPS.

Ограничения и следующие шаги

  • Один API-процесс и один Docker host: отказ хоста, потеря БД или единственного Redis не компенсируются. Горизонтальное масштабирование и LB — задача lab3.
  • Redis хранит только сессии; при полной потере AOF активные сессии исчезнут, но пользователи, чаты и сообщения в PostgreSQL останутся. Это осознанная граница: сессия — не бизнес-данные.
  • AOF everysec допускает потерю до ~1 секунды последних сессионных записей при аварийном завершении хоста; штатный рестарт проверен. Для production нужен отдельный анализ durability/backup.
  • HTTP без TLS допустим только для локального изолированного стенда с синтетическими данными; для удалённой демонстрации нужен TLS (lab7).
  • Нет rate limiting, публичного поиска пользователей, WebSocket и UI — они не входят в обязательный минимум lab2.
  • Следующий шаг для lab3: ≥2 API-реплики, общий LB, Idempotency-Key и X-Instance-Id, проверка failover и отсутствия дублей.