Files
mtusi2026lab2/REPORT.md

19 KiB
Raw Permalink Blame History

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

  • Автор, группа: Рестеу Даниил Андреевич, БВТ2302.
  • Целевая оценка: 4. Трек уровня 5 не выполнялся.
  • Commit/PR: вписать ссылку после публикации в своём fork.
  • Использованные источники, библиотеки и помощь ИИ: собственный API лабораторной 1; FastAPI, Pydantic, Psycopg 3/psycopg-pool, argon2-cffi, redis-py, Uvicorn; документация PostgreSQL, Redis, Psycopg, Docker и RFC 7617/6750. ChatGPT/Codex использован для доработки реализации, проверки требований, тестов, ревью и подготовки объяснения кода. Это отмечается как помощь ИИ, а не как полностью самостоятельное написание всех строк.

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

Необходимы Docker с Compose v2 и Python 3.9+ для публичных скриптов на хосте. В Dockerfile закреплён python:3.14.8-slim-bookworm, в Compose — postgres:17.11-bookworm и redis:8.2.10-bookworm. Зависимости Python перечислены в requirements.txt с точными версиями.

На чистом стенде скопировать .env.example в .env и задать локальный учебный POSTGRES_PASSWORD. Если данные PostgreSQL уже существуют, использовать прежние настройки .env: изменение переменной само не меняет пароль в БД.

PowerShell:

Copy-Item .env.example .env
# Здесь задать свой POSTGRES_PASSWORD в .env, если стенд создаётся впервые.
docker compose config --quiet
docker compose up -d --build --wait api
Invoke-RestMethod http://localhost:8080/health/ready
python scripts/check_contract.py
docker compose exec -T api python tests/smoke.py
docker compose exec -T api python -m unittest discover -s student-tests -v
docker compose exec -T api python scripts/explain_history.py
python scripts/check_grade4.py --base-url http://127.0.0.1:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd

Для уже существующего стенда строку Copy-Item пропустить, сохранив .env.

Linux:

cp .env.example .env
# Задать локальный POSTGRES_PASSWORD.
docker compose config --quiet
docker compose up -d --build --wait api
make check
make test
docker compose exec -T api python -m unittest discover -s student-tests -v
docker compose exec -T api python scripts/explain_history.py
python3 scripts/check_grade4.py
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh

Мигратор автоматически запускается перед api. Для отдельного повторного запуска: docker compose run --rm migrate. Уже применённые файлы получают SKIP.

Обычная остановка: docker compose down — volumes сохраняются. Намеренное удаление всех учебных данных: docker compose down -v. В .gitignore/.dockerignore исключены .env, закрытые ключи и локальные данные.

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

Клиент обращается к api. PostgreSQL — источник истины для users, chats, chat_members и messages. Redis — единственный источник истины для сессий. Кэширование истории не используется; чтения идут в основную БД.

Из lab1 перенесены API, валидация, формат ошибок, request ID, health endpoints, Docker-запуск и собственные HTTP-тесты. MemoryStore удалён. X-User-Id игнорируется.

Basic используется только для POST /api/v1/auth/sessions. Пароли 12–128 code points хешируются Argon2id. Оpaque Bearer token генерируется из 32 случайных байт. Redis хранит UUID владельца под session: с абсолютным PXAT. TTL по умолчанию 3600 секунд, задаётся SESSION_TTL_SECONDS. Logout удаляет ключ. AOF с appendfsync always и volume redis_data сохраняет действующие сессии и отзыв; рестарт не продлевает срок. FLUSHALL уничтожит сессии, но не доменные данные.

Таблицы имеют UUID PK, FK и UNIQUE username. Составной PK (chat_id,user_id) предотвращает дубли членства. 01_initial.sql создаёт схему, 02_chat_order.sql добавляет индекс списка чатов. schema_migrations предотвращает повторное применение. Создание чата и всех его участников выполняется в одной транзакции; ошибка FK неизвестного участника откатывает весь чат.

SQL параметризован. Пул одного api-процесса содержит 1–5 соединений, очередь ожидающих ограничена 20. Ожидание пула — 3 с, подключение — 5 с, statement_timeout — 5000 мс, lock_timeout — 3000 мс. Redis имеет socket/connect timeouts по 2 с и не делает автоматические retry. При отказах защищённые операции возвращают 503 в общем формате. /health/live не зависит от хранилищ; /health/ready проверяет PostgreSQL и Redis, обе зависимости критичны.

История сортируется по (created_at,id) ASC. SQL получает максимум limit+1 строк через ключевую границу; полного чтения/сортировки истории в Python нет. Cursor содержит область запроса, UTC timestamp и UUID. Для неизменной истории повторов нет, изменение limit допускается. Общего snapshot между страницами нет: конкурентная запись с уже пройденным временем может быть пропущена этим обходом. Часы БД должны быть корректны. Подтверждённая запись видна следующему чтению.

POSTGRES_DB/USER/PASSWORD и SESSION_TTL_SECONDS из .env.example действительно используются Compose и приложением. Внутренние адреса — postgres:5432 и redis:6379, наружу опубликован только api на 127.0.0.1:8080. POSTGRES_HOST/PORT и REDIS_HOST/PORT дополнительно можно переопределить для локальной проверки без Docker.

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

Итоговый прогон выполнен 19.10.2026 на Windows в PowerShell с Docker Desktop. Приложение собрано из python:3.14.8-slim-bookworm, PostgreSQL — 17.11-bookworm, Redis — 8.2.10-bookworm. Публичный smoke, все 16 собственных тестов, короткий TTL, отказы обоих хранилищ и полный persistence-сценарий завершились успешно. Публичные tests/, contracts/, Makefile и README.md по содержимому не изменены.

evidence/windows-api.txt — предоставленный исходный вывод PowerShell со сборкой, smoke и 16 тестами. evidence/windows-summary.md — сводка остальных предоставленных результатов; это не полный необработанный журнал всех команд. evidence/grade4-windows.txt содержит вывод проверки TTL/отказов.

Файлы с native-результатами относятся к отдельному предварительному прогону на Python 3.12.14 / PostgreSQL 16.15 / Redis 7.0.15. Его версии и параметры оборудования не являются характеристиками компьютера студента.

Критерий README Команда/сценарий Наблюдаемый результат локальной проверки Файл доказательства
Структура контракта python scripts/check_contract.py PASS на Windows evidence/windows-summary.md
Синтаксис Compose и сборка docker compose config --quiet; up -d --build --wait api конфигурация принята, образы собраны, api/postgres/redis healthy evidence/windows-api.txt
Публичный API docker compose exec -T api python tests/smoke.py PASS lab2 на Windows/Docker evidence/windows-api.txt
Миграции с нуля python -m src.migrate на новой БД предварительного native-стенда APPLIED обе миграции; этот лог относится к native-прогону evidence/migrations.txt
Повтор миграций повтор python -m src.migrate на native-стенде SKIP обе миграции evidence/migrations-repeat.txt
Сохранены проверки API lab1 docker compose exec -T api python -m unittest discover -s student-tests -v 16 тестов OK, 5.909 с на Windows/Docker evidence/windows-api.txt
Безопасные запросы, конкурентная регистрация test_registration_race тест OK: один 201, три 409; в БД одна строка evidence/windows-api.txt
Атомарное создание чата test_chat_rollback_after_unknown_member тест OK: 400; нет частичного чата и членства evidence/windows-api.txt
KDF, UTF-8 пароль с двоеточием, 256 бит токена test_unicode_password_with_colon_and_hash тест OK: вход успешен, Argon2id в БД, 32 случайных байта токена evidence/windows-api.txt
Bearer, неправильный пароль, logout, X-User-Id smoke и test_login_logout_and_legacy_header smoke PASS и тест OK на Windows/Docker evidence/windows-api.txt
Expiry в Redis при TTL=2 python scripts/check_grade4.py --base-url http://127.0.0.1:8080 PASS: активный токен после истечения получает 401 evidence/grade4-windows.txt
Отказы Redis и БД тот же scripts/check_grade4.py оба PASS: bounded 503, live=200, anonymous=401; старый токен работает после восстановления evidence/grade4-windows.txt
Сохранность после полного рестарта python tests/resilience.py --mode persistence --action-script scripts/restart.cmd PASS: confirmed data и прежняя сессия сохранились evidence/windows-summary.md
Область фактического native restart hook PID api, postgres, redis до/после все три процесса заменены evidence/native-restart-processes.json
Индекс на >=10000 сообщениях docker compose exec -T api python scripts/explain_history.py PostgreSQL 17.11, 10000 сообщений; обе страницы используют messages_history_idx evidence/windows-summary.md
Собственные негативные проверки cursor scope/time, NUL, строгие поля, чужой чат соответствующие тесты OK на Windows/Docker evidence/windows-api.txt
Фактический Compose restart hook restart.cmd вызывает restart.py в persistence-тесте сценарий PASS; hook записывает service/ID/StartedAt/status до и после evidence/restart-before.txt, evidence/restart-after.txt

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

Среда предварительного прогона: x86_64, 9 видимых CPU, cgroup RAM limit 8 GiB. У контейнеров Compose отдельные CPU/RAM limits не назначены. Конкурентный тест: 10 HTTP-клиентов, по 10 последовательных отправок; прочитаны все 100 уникальных сообщений, ID и тексты совпали. В предварительном native-прогоне 16 тестов заняли 5.023 с; на Windows/Docker — 5.909 с. Параметры CPU/RAM компьютера студента не фиксировались. Это проверка корректности, не измерение максимальной производительности; RPS, p50/p95/p99 и CPU/RAM под нагрузкой не измерялись и не заявляются.

EXPLAIN использует 10000 синтетических сообщений одного чата в транзакции с принудительным rollback. После измерения фикстуры не сохраняются. Выполняется ANALYZE и затем EXPLAIN (ANALYZE, BUFFERS) тех же SQL-констант, которые использует API. LIMIT 51 соответствует странице 50 + одной строке для next_cursor. Для выбора тестовой границы после 9000-й строки используется OFFSET только при подготовке эксперимента; запрос страницы использует keyset.

В итоговом Windows/Docker-прогоне на PostgreSQL 17.11 первая страница имела Execution Time 0.031 мс и 4 shared buffer hits; страница после 9000-й записи — 0.056 мс и 3 hits. Обе читали 51 строку через Index Scan messages_history_idx. Это один локальный прогон с прогретыми данными, а не универсальный SLA.

После замены адреса тестового API с localhost на 127.0.0.1 проверка короткой сессии на Windows завершилась успешно. Значение TTL осталось равным 2 секундам. Из одного первоначального 401 нельзя однозначно установить причину задержки.

Воздействие Что ожидаем Что наблюдали Восстановление / потеря данных
Истечение TTL=2 с токен больше не принимается 200 до ожидания, 401 после 2.2 с повторный вход нужен
Logout немедленный отзыв 204, затем GET/DELETE с тем же токеном 401 повторный вход нужен
Остановка Redis безопасный отказ 503; live=200; анонимный GET=401 после старта старый действующий токен работает
Остановка PostgreSQL безопасный отказ 503; live=200; анонимный GET=401 пул восстанавливается, старый токен работает
Перезапуск api и обоих хранилищ данные и сессия сохраняются публичный persistence PASS исходное подтверждённое сообщение не потеряно
Неизвестный участник после INSERT чата rollback всей операции 400; частичных строк нет состояние БД не изменилось

Native restart проверял реальные процессы предварительного стенда. Итоговый Windows persistence-тест вызвал Docker hook через restart.cmd; он перезапускает api, postgres и redis с сохранением volumes. Для проверки области рестарта приложены restart-before.txt и restart-after.txt со StartedAt. Времена полного восстановления отдельно не измерялись: тесты подтвердили восстановление в пределах своих ожиданий, а не обещание конкретного SLA.

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

Один api, PostgreSQL и Redis на одном узле; высокой доступности и резервного копирования нет. Volumes и AOF выдерживают проверяемый рестарт, но не заменяют backup при удалении данных, потере диска или аппаратном сбое. Гарантии COMMIT зависят от настроек PostgreSQL, fsync и реального диска; они не отключались. Redis appendfsync always выбран ради durability, цена — дополнительные fsync.

HTTP и синтетические credentials предназначены для локального стенда; удалённая демонстрация требует TLS согласно заданию. История не кэшируется, поэтому отсутствует задача инвалидации кэша сообщений. После потери Redis-сессий нужен повторный вход. В текущем API нет удаления пользователей/членства и редактирования сообщений. Между HTTP-страницами не поддерживается snapshot.

Публичные тесты проверяют схему WWW-Authenticate; отдельные собственные assertions на точное значение realm не добавлялись. Заголовки задаются явно в error_response.

Закреплённые Docker-версии проверены на Windows. Перед сдачей остаётся вписать ссылку commit/PR после публикации и подготовиться объяснить код.

Первичные источники