Files
mtusi2026lab2-fork/REPORT1.md
T
2026-10-17 19:11:07 +03:00

23 KiB
Raw Blame History

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

  • Автор, группа: Миронов Алексей, бвт2302
  • Целевая оценка: 4
  • Commit/PR: 4905353 lab2 condition inpostgres, sessions in redis / mtusi2026/mtusi2026lab2#65
  • Использованные источники, библиотеки и помощь ИИ: исходный учебный репозиторий; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2; документация соответствующих библиотек; использовалась помощь ИИ

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

Требуются Docker Engine/Desktop с Docker Compose, Python 3.12+ и GNU Make. Команды ниже выполняются из корня репозитория.

  1. Создать локальную конфигурацию и заменить демонстрационный пароль:
    cp .env.example .env
    
    Отредактировать .env, задав длинный случайный POSTGRES_PASSWORD. Не добавлять .env в Git.
  2. Выполнить офлайн-проверку структуры:
    make check
    
  3. Установить зависимости для валидации контракта и запустить её:
    python -m pip install -r requirements-dev.txt
    make validate
    
  4. Проверить конфигурацию Compose:
    docker compose --env-file .env config --quiet
    
  5. Собрать и запустить PostgreSQL, Redis и API:
    docker compose --env-file .env up --build
    
    Приложение применяет SQL-миграцию migrations/001_init.sql при инициализации. Дождаться готовности:
    curl -i http://localhost:8080/health/ready
    
  6. Запустить основной сценарий API:
    make test
    
  7. После подготовки исполняемого hook перезапуска проверить сохранность данных и сессии:
    make test-persistence ACTION_SCRIPT=scripts/restart.sh
    
    scripts/restart.sh перезапускает API, PostgreSQL и Redis, не удаляя именованные volumes. Запускать проверку только на локальном тестовом стенде.
  8. Дополнительные проверки уровня 4 и их ожидаемые результаты описаны в разделах «Доказательства критериев» и «Эксперименты и отказы».
  9. Безопасно остановить сервисы, сохранив данные:
    docker compose --env-file .env down
    
    Намеренное удаление учебных данных вместе с именованными volumes:
    docker compose --env-file .env down -v
    
    Последняя команда удаляет сохранённые данные PostgreSQL и Redis; выполнять её только при осознанном сбросе локального учебного стенда.

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

Схема: клиент / smoke- и нагрузочные тесты -> FastAPI -> PostgreSQL и Redis.

  • PostgreSQL - источник истины для пользователей, чатов, участников чатов и сообщений. Данные хранятся в именованном volume postgres_data; схема создаётся SQL-миграцией migrations/001_init.sql.
  • Redis хранит серверные сессии. Ключ сессии строится как session:<sha256(token)>; значение содержит идентификатор пользователя и срок истечения. Исходный Bearer-токен не сохраняется. Redis настроен на AOF (appendonly yes, appendfsync everysec) и использует volume redis_data.
  • Docker Compose запускает PostgreSQL, Redis и API. API зависит от успешных healthcheck хранилищ. Наружу опубликован только API-порт 127.0.0.1:8080; PostgreSQL и Redis не публикуют порты на хост.
  • Пул PostgreSQL ограничивается DB_POOL_MIN_SIZE, DB_POOL_MAX_SIZE и DB_POOL_TIMEOUT_SECONDS; значение по умолчанию для максимального размера - 10 соединений. В подключении заданы ограничения времени соединения/выполнения запросов и транзакций.
  • Аутентификация: пароль хранится в виде Argon2id-хеша. Authorization: Basic используется для входа на POST /api/v1/auth/sessions; после входа выдаётся случайный непрозрачный Bearer-токен. Защищённые запросы проверяют сессию в Redis. TTL настраивается через SESSION_TTL_SECONDS; logout удаляет запись сессии.
  • Транзакции и целостность: создание чата и добавление его участников выполняются в одной транзакции, чтобы ошибка не оставляла частично созданный чат. Пагинация использует стабильный составной порядок (created_at, id) и непрозрачный base64url cursor. API возвращает X-Request-Id и единый JSON-формат ошибок. Недоступность обязательного хранилища должна отражаться в readiness и ответах затронутых запросов.
  • Конфигурация: переменные .env.example соответствуют Compose-конфигурации: APP_HOST, APP_PORT, SESSION_TTL_SECONDS, параметры пула DB_POOL_*, REDIS_URL и параметры PostgreSQL POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD. Пароль должен быть заменён локально; секреты не включаются в отчёт или Git.
  • Связь с lab1: сохранены основные сущности и сценарии API - пользователи, чаты, участники, сообщения, пагинация, общий формат ошибок, X-Request-Id и health-endpoints. Ключевое изменение - перенос состояния из памяти процесса в PostgreSQL и введение серверных сессий вместо доверия к одному лишь X-User-Id.

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

Все команды выполнены на локальном стенде (Windows, Git Bash и WSL, Docker Desktop) на синтетических данных. Проверки make check/make validate и тесты, запускаемые через python tests/..., выполнялись из корня репозитория. Вывод сохранён в evidence.txt, план запроса - в evidence/explain-level4.txt, нагрузка - в evidence/load-run.json.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура и синтаксис make check PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. Проверка офлайн, приложение ею не тестируется evidence/evidence.txt
OpenAPI и JSON Schema make validate PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. evidence/evidence.txt
Конфигурация Compose docker compose --env-file .env config --quiet Команда завершилась без вывода, сообщений об ошибках нет evidence/evidence.txt
Сборка и запуск docker compose --env-file .env up --build Образы redis и postgres загружены; образ api собран (12/12 шагов, 42.1 с, базовый образ python:3.12.11-slim-bookworm) evidence/evidence.txt
Живость и готовность curl -i http://localhost:8080/health/live, curl -i http://localhost:8080/health/ready Оба запроса: HTTP 200, тело {"status":"ok"}, заголовок x-request-id присутствует (16 Oct 2026, 16:32:06 и 16:33:35 GMT) evidence/evidence.txt
Состояние сервисов и порты docker compose --env-file .env ps api, postgres (postgres:17.6-alpine) и redis (redis:7.4.2-alpine) в статусе healthy. На хост опубликован только 127.0.0.1:8080->8080/tcp; у PostgreSQL и Redis указаны лишь внутренние 5432/tcp и 6379/tcp evidence/evidence.txt
Публичный smoke make test PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. evidence/evidence.txt
Персистентность при рестарте make test-persistence ACTION_SCRIPT=scripts/restart.sh (hook выполняет docker compose restart api postgres redis) PASS: persistence preserved confirmed data and existing session. Код возврата 0. До теста все три сервиса Up 22 minutes (healthy), после - Up 13 seconds (api) и Up 14 seconds (postgres, redis), все healthy; поле CREATED не изменилось (19-20 часов), то есть контейнеры перезапущены, а не пересозданы. Вывод hook тест скрывает намеренно, поэтому охват рестарта подтверждается этими ps evidence/evidence.txt
Redis AOF docker compose --env-file .env exec redis redis-cli CONFIG GET appendonly, ... CONFIG GET appendfsync, ... INFO persistence appendonly = yes, appendfsync = everysec. В INFO persistence: aof_enabled:1, aof_last_write_status:ok, aof_last_bgrewrite_status:ok, aof_current_size:5969, aof_base_size:88, aof_rewrites:0, aof_rewrites_consecutive_failures:0, aof_delayed_fsync:0 evidence/evidence.txt
Истечение TTL сессии SESSION_TTL_SECONDS=3 в .env, docker compose --env-file .env up -d --force-recreate api, затем python tests/session_ttl.py --base-url http://localhost:8080 PASS: expired Redis session is rejected with HTTP 401. После теста TTL возвращён к 3600, API пересоздан тем же up -d --force-recreate api evidence/evidence.txt
Отказ Redis python tests/storage_failure.py --target redis --base-url http://localhost:8080 PASS: /health/ready returned HTTP 503 while redis was unavailable; затем PASS: readiness recovered to HTTP 200 after redis restart evidence/evidence.txt
Отказ PostgreSQL python tests/storage_failure.py --target postgres --base-url http://localhost:8080 PASS: /health/ready returned HTTP 503 while postgres was unavailable; затем PASS: readiness recovered to HTTP 200 after postgres restart evidence/evidence.txt
Конкурентная регистрация python tests/grade4_checks.py --base-url http://localhost:8080 PASS: concurrent same-username registration produced exactly one 201 and seven 409 (8 одновременных запросов с одним username) evidence/evidence.txt, evidence/explain-level4.txt
Откат транзакции Та же команда tests/grade4_checks.py PASS: injected membership failure returned 503 and rolled back the chat row. Ошибка внедряется временным триггером на chat_members; скрипт удаляет триггер и функцию в блоке finally evidence/evidence.txt, evidence/explain-level4.txt
План запроса для 10 000 сообщений Та же команда tests/grade4_checks.py PASS: EXPLAIN (ANALYZE, BUFFERS) used messages_chat_created_id_idx; saved evidence\explain-level4.txt. Подробный разбор плана ниже evidence/evidence.txt, evidence/explain-level4.txt
Нагрузочный прогон python tests/load.py --base-url http://localhost:8080 --duration 30 --concurrency 4 --output evidence/load-run.json 60 успешных запросов, 0 ошибок, 1.91 RPS, задержка успешных запросов p50 = 2079 мс, p95 = 2125 мс, p99 = 2140 мс. Один прогон; интерпретация ниже evidence/evidence.txt, evidence/load-run.json

План запроса. Набор данных: 10 000 синтетических сообщений в 100 чатах (по 100 сообщений в чате). Запрос: история одного чата в порядке (created_at, id), LIMIT 51. Индекс messages_chat_created_id_idx построен по messages(chat_id, created_at, id), то есть соответствует фильтру по чату и порядку выдачи. Фактический план:

  • Bitmap Index Scan по messages_chat_created_id_idx с условием chat_id = ... вернул 100 строк (shared hit=3);
  • Bitmap Heap Scan прочитал 100 блоков, выбрав только строки этого чата;
  • Sort (quicksort, 38 kB) упорядочил эти 100 строк по (created_at, id), затем Limit оставил 51;
  • суммарно Buffers: shared hit=109, Planning Time: 0.974 ms, Execution Time: 0.696 ms.

Из плана следует, что запрос не сканирует всю таблицу из 10 000 строк: индекс сужает выборку до сообщений одного чата. Ограничения вывода: планировщик выбрал bitmap-план с отдельной сортировкой 100 строк, а не Index Scan, отдающий порядок индекса; измерялась первая страница без keyset-условия (created_at, id) > cursor; чаты одинакового размера. Поведение на очень больших или неравномерных чатах и со следующими страницами этим прогоном не проверялось.

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

Нагрузочный эксперимент. Использован синтетический closed-loop сценарий tests/load.py: 4 параллельных исполнителя в течение 30 с отправляют POST сообщений в один чат от имени одного пользователя, без автоматических повторов. Фактическая длительность 31.406 с. Результат единственного прогона:

Параметр Значение
Успешных / неуспешных запросов 60 / 0 (доля ошибок 0.0)
Успешных запросов в секунду 1.91
Задержка успешных запросов p50 / p95 / p99 2079 мс / 2125 мс / 2140 мс

Задержка почти постоянна (2.08-2.14 с), поэтому при 4 исполнителях RPS примерно равен 4 / 2.08 ≈ 1.9. Причина столь высокой задержки одного POST не исследовалась: не разделено время сервера, клиента и сетевого стека Docker Desktop на Windows, прогон не повторялся. Поэтому результат фиксируется как измерение одного локального профиля, а не как оценка пропускной способности системы.

OS: Майкрософт Windows 11 Pro 10.0.22631 (build 22631) CPU: Intel(R) Core(TM) i5-8350U CPU @ 1.70GHz, cores=4, threads=8 RAM: 15.9 GB

Docker Compose version v2.32.4-desktop.1

docker version Client: Version: 27.5.1 API version: 1.47 Go version: go1.22.11 Git commit: 9f9e405 Built: Wed Jan 22 13:41:44 2025 OS/Arch: windows/amd64 Context: desktop-linux

Server: Docker Desktop 4.38.0 (181591) Engine: Version: 27.5.1 API version: 1.47 (minimum version 1.24) Go version: go1.22.11 Git commit: 4c9b3b0 Built: Wed Jan 22 13:41:17 2025 OS/Arch: linux/amd64 Experimental: false containerd: Version: 1.7.25 GitCommit: bcc810d6b9066471b0b6fa75f557a15a1cbf31bb runc: Version: 1.1.12 GitCommit: v1.1.12-0-g51d5e946 docker-init: Version: 0.19.0 GitCommit: de40ad0

Контролируемые воздействия. Время восстановления в тестах отказа не измеряется: tests/storage_failure.py ждёт HTTP 503 не дольше 10 с после остановки и восстановления HTTP 200 не дольше 45 с после запуска. Сообщения Docker Stopped/Started (0.3-0.4 с) относятся к самой команде, а не к готовности API.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Истечение TTL (SESSION_TTL_SECONDS=3) Сразу после входа токен работает, после TTL запрос с тем же токеном получает HTTP 401 tests/session_ttl.py: PASS, просроченная сессия отклонена с HTTP 401 Не относится к отказу сервиса; сессия истекает по TTL Redis без явного logout
Остановка Redis Readiness становится HTTP 503; после восстановления Redis возвращается HTTP 200 /health/ready вернул 503 при остановленном Redis, после его запуска вернулся к 200 Восстановление уложилось в таймаут теста 45 с, точное время не измерялось. Данные в этом тесте не создавались; сохранность сессий после рестарта проверена отдельным persistence-тестом
Остановка PostgreSQL Readiness становится HTTP 503; после восстановления БД возвращается HTTP 200 /health/ready вернул 503 при остановленной БД, после её запуска вернулся к 200 Восстановление уложилось в таймаут теста 45 с, точное время не измерялось. Данные в этом тесте не создавались; сохранность данных проверена persistence-тестом
8 параллельных регистраций одного username Одна регистрация успешна (201), остальные получают конфликт (409) Ровно один ответ 201 и семь 409 Не относится к отказу сервиса; дубликаты не созданы, так как уникальность username обеспечивает БД
Искусственная ошибка при добавлении участника в чат Транзакция откатывается; частично созданный чат не остаётся API вернул ограниченную ошибку 503, строка чата в БД отсутствует Тестовые триггер и функция удаляются скриптом в finally
Запрос истории на 10 000 сообщений Получить и сохранить фактический EXPLAIN (ANALYZE, BUFFERS) Использован индекс messages_chat_created_id_idx, время выполнения 0.696 мс; детали и ограничения - в разделе «Доказательства критериев» Не является тестом восстановления; синтетические строки скрипт удаляет после проверки
Перезапуск API, PostgreSQL и Redis через hook Ранее созданные данные и действующая сессия остаются доступными, volumes сохраняются make test-persistence: PASS, подтверждённые данные и существующая сессия сохранились; после перезапуска все сервисы healthy Время восстановления отдельно не измерялось: через 13-14 с после перезапуска сервисы уже были healthy. Потери подтверждённых данных и действующей сессии не обнаружено

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

  • Нагрузочные измерения: тест использует closed-loop модель с фиксированным числом параллельных исполнителей. Это не полноценный open-loop capacity-тест; результаты зависят от времени ответа сервера, клиентских накладных расходов и характеристик машины. Без повторов и фиксации окружения нельзя делать универсальные выводы по одному запуску.
  • Персистентность Redis: AOF с appendfsync everysec снижает риск потери данных, но при аварии хоста последние примерно секунду изменений теоретически можно потерять. AOF не заменяет резервное копирование и не обеспечивает высокую доступность.
  • Отказы: предусмотрены контролируемые остановки одного хранилища и последующее восстановление. Автоматический failover, кластеризация PostgreSQL/Redis и восстановление из резервной копии не реализованы в текущей версии.
  • Масштабирование и безопасность: rate limiting и горизонтальное масштабирование не реализованы. Порт API привязан к localhost в Compose; стенд предназначен для учебных синтетических данных.