Files
mtusi2026lab2/REPORT.md
T
Алиса Шурман 078b14840e
Application integration / integration (pull_request) Canceled after 0s
Skeleton contracts / contracts (pull_request) Canceled after 0s
docs: добавить ссылку на PR лабораторной 2
2026-10-29 16:33:17 +03:00

14 KiB
Raw Blame History

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

  • Автор, группа: Шурман А.Р., БПИ2302.
  • Целевая оценка: 4. Треки оценки 5 не выполнялись.
  • Ветка: solution/bpi2302-shurman в aliska/mtusi2026lab2-fork; PR #113 в исходный mtusi2026/mtusi2026lab2. Реализация и локальные проверки: commit e634ea9.
  • Источники: контракт и публичные тесты текущего skeleton; собственный мессенджер лабораторной 1; помощь OpenAI Codex при реализации, тестировании и оформлении. Библиотеки FastAPI, Uvicorn, psycopg/pool, argon2-cffi и redis-py; полный lock версий в app/requirements.txt.

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

Нужны Git, Python 3.9+ для тестов и Docker с Compose v2+ (проверено Compose 5.5.1). Приложение работает на Python 3.12.7 в контейнере. Образы закреплены: python:3.12.7-slim-bookworm, postgres:16.6-bookworm, valkey/valkey:8.0.2-alpine.

git clone https://gitea.privcloud.tech/aliska/mtusi2026lab2-fork.git
cd mtusi2026lab2-fork
git switch solution/bpi2302-shurman
python3 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait api
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 student-tests/verify.py
python3 student-tests/explain.py

Полный набор с сохранением вывода и подтверждением рестарта каждого контейнера: python3 scripts/verify.py. Собственные тесты временно останавливают только PostgreSQL/Valkey этого Compose-проекта, затем восстанавливают их через finally. Стенд предназначен для синтетических учебных данных. Проверка expiry поднимает дополнительный API на 8082 с TTL=2, затем останавливает его.

OpenAPI-проверка отдельно (зависимости только для валидатора):

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

API: http://localhost:8080; Swagger: http://localhost:8080/docs. Создание пользователя требует password; затем POST /api/v1/auth/sessions с Basic (UTF-8 username:password), далее Bearer. Примеры — в исходном examples/requests.http. UI для лабораторной не требуется.

Bootstrap не перезаписывает существующие secrets. Он генерирует случайный пароль PostgreSQL и локальные файлы secrets/; каталог 0700, файлы 0644 для чтения Docker Desktop UID 10001. .env содержит TTL и порт, секреты не печатаются. Они исключены из Git и build context. DB/Valkey не публикуют порты на host; API привязан только к 127.0.0.1. APP_HOST/APP_PORT/APP_ENV, SESSION_TTL_SECONDS, SESSION_STORE=postgres, DATABASE_URL_FILE, CACHE_URL_FILE из .env.example заданы Compose; HOST_PORT управляет host-портом. Переключение SESSION_STORE не реализовано: источник сессий всегда PostgreSQL.

Миграция запускается отдельным сервисом до API. Повторный запуск: docker compose run --rm migrate. Версии и checksums — в schema_migrations; advisory lock сериализует миграторы. Изменять уже применённый SQL нельзя.

Безопасная остановка: docker compose --profile test down — volumes остаются. Повторный старт сохраняет все данные и срок сессий. Намеренный сброс учебных данных, если оператору нужен полностью пустой стенд: docker compose --profile test down -v (безвозвратно удаляет volumes этого проекта). При обычном запуске и проверке сохранности эта команда не используется.

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

Клиент → FastAPI → PostgreSQL; дополнительно Valkey для cache-aside публичного профиля. Проект схемы, индексы, FK и границы транзакций описаны в infra/SCHEMA.md. Из lab1 перенесены модели, строгий набор полей, проверки строк, ошибки/request ID, разграничение доступа и cursor; in-memory Store заменён SQL. Новая аутентификация — объявленный переход курса. README, COURSE, contracts и публичные tests сохранены.

Пользователи, чаты, участники, сообщения и сессии находятся в PostgreSQL. Регистрация защищена UNIQUE; создание чата и всех участников атомарно. Токен — 32 случайных байта (256 бит), сервер хранит только его SHA-256 и абсолютный expires_at. Пароли — Argon2id (19 MiB, time_cost=2, parallelism=1), без усечения UTF-8. Basic разрешён только для login; X-User-Id не авторизует запросы. Logout удаляет сессию. Истёкшие записи не дают доступ даже до физической очистки.

Valkey хранит публичный неизменяемый User на 60 секунд. Это убирает повторный SELECT профиля после проверки сессии. Сессия при каждом запросе проверяется в PostgreSQL: cached profile не продлевает TTL и не отменяет logout. Источник истины — PostgreSQL, инвалидация профилей — TTL/eviction (операции изменения профиля нет). При сбое Valkey чтение идёт в PostgreSQL. AOF и именованный volume настроены, но потеря кэша допустима. История не кэшируется, чтение после COMMIT идёт в primary.

SQL параметризован; pool 1–8 соединений, очередь до 32, ожидание 3 s, connect timeout 3 s, statement timeout 3 s, lock timeout 2 s. Valkey connect/socket timeout 0.2 s. Синхронная работа выполняется в worker pool. Readiness зависит от PostgreSQL, liveness от жизни API. Контейнер API non-root 10001:10001, SIGTERM получает Uvicorn напрямую.

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

Измерения выполнены локально 29.10.2026; реальные выводы в evidence/.

Критерий Команда/сценарий Наблюдение Доказательство
Структура и обязательный API make check; make validate; make test PASS check.txt, validate.txt, smoke.txt
Данные и сессия переживают полный рестарт make test-persistence ACTION_SCRIPT=scripts/restart.sh прежний токен читает подтверждённые данные persistence.txt
Перезапущены API и оба хранилища сравнение Docker StartedAt до/после время старта всех трёх изменилось, IDs/volumes сохранены restart-containers.json
Миграции с нуля / повторяемость чистые именованные volumes при bootstrap; два compose run --rm migrate старт с нуля успешен; количество сущностей не изменилось student-tests.json, migration_reapply
Password KDF, Unicode/двоеточие регистрация/вход, проверка записи БД Argon2id, plaintext отсутствует, вход PASS student-tests.json
Bearer, Basic только login, отказ X-User-Id публичный smoke PASS, чужой чат 404 smoke.txt
Logout и expiry cached profile + logout; отдельный API TTL=2 отозванный/истёкший token 401 student-tests.json
Реальная роль Valkey запрос User → TTL ключа TTL в диапазоне 1–60; fallback работает student-tests.json
Гонка username 8 одновременных регистраций один 201, семь 409 student-tests.json
Rollback чата существующий и несуществующий участники 400, количество чатов не меняется, сирот нет student-tests.json
Конкурентная запись/пагинация 100 сообщений из 8 потоков, страницы по 7 100 уникальных ID без потерь; чужой cursor 400 student-tests.json
Индекс истории python3 student-tests/explain.py Index Scan messages_history, без Seq Scan explain.json, explain.txt
Отказы зависимостей python3 student-tests/verify.py Valkey fallback 200; PostgreSQL 503; анонимный 401 student-tests.json

Полные пути: все файлы доказательств из таблицы находятся в evidence. GitHub integration workflow добавлен отдельно от исходной проверки контракта; на Gitea наличие файла само по себе не означает запуска CI. Доказательства здесь получены локально, CI-status не заявляется.

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

Docker Desktop aarch64, 10 доступных CPU, 8 319 504 384 байта RAM VM (~7.75 GiB). Это функциональная проверка, не оценка максимальной производительности. HTTP: 8 клиентских потоков, 100 сообщений; отдельная гонка из 8 регистраций. EXPLAIN: 10 000 синтетических сообщений в одном чате, cursor около позиции 9000, LIMIT 51 (50 + один элемент для next_cursor), один прогон, тёплый buffer cache после INSERT/ANALYZE. Данные эксперимента откатываются транзакцией.

Гипотеза: составной B-tree позволяет прочитать только следующую страницу, вместо сканирования истории с начала. Получен Index Scan using messages_history, 51 строка, 4 shared hit blocks, без чтений диска. Последний прогон: Execution Time 0.019 ms, Planning Time 0.063 ms. Актуальные повторные результаты — в explain.json. Это подтверждает выбор плана, но не cold-cache latency и не throughput API; RPS/p50/p95/p99 и CPU/RAM процесса не измерялись и не заявляются.

Воздействие Ожидание Последний наблюдаемый результат Потеря данных
Restart API + PostgreSQL + Valkey тот же токен и история persistence PASS нет потерь проверенных данных
Остановка Valkey fallback, ready 200 User 200 за 0.4205 s; запись успешна нет
Остановка PostgreSQL bounded 503, live 200 503 за 3.009 s; ready 503, anonymous 401 подтверждённое сообщение сохранено
Запуск PostgreSQL после отказа возвращается готовность 1.045 s ожидания после compose start нет в проверенном сценарии
SESSION_TTL_SECONDS=2 expiry без продления через 2.2 s token 401 ожидаемый отзыв доступа

Числа повторного запуска могут отличаться; машинные результаты каждого последнего прогона находятся в student-tests.json. Время восстановления отсчитывается после завершения compose start, а не от начала аварии. Штатный stop/restart не моделирует поломку диска или потерю питания. Секреты/токены в доказательства не записываются.

Ограничения

Один PostgreSQL — точка отказа; HA, backup/restore и исследования уровня 5 не входят в выбранную оценку. Успешный COMMIT использует стандартные fsync и synchronous_commit PostgreSQL, но не гарантирует выживание при потере volume. HTTP допустим здесь только на loopback для синтетических данных. Нет фоновой уборки истёкших сессий, rate limiting и изменения профилей. При будущем редактировании профиля потребуется явная инвалидация Valkey.

Keyset гарантирует отсутствие повторов на неизменной истории; snapshot между страницами не создаётся. При конкурентных вставках поздний COMMIT с более ранним created_at может оказаться за уже пройденным cursor; это не протокол доставки событий. Проверка истории после подтверждённой записи читает актуальную БД.