Files
mtusi2026lab2/REPORT.md
T

11 KiB
Raw Blame History

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

  • Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
  • Целевая оценка: 5, трек 2 (сравнение запросов и восстановление). Кэш и отказы проверены; индекс и исследование трека дополняются в следующих блоках.
  • Ветка: solution/bpi2302-samohvalov; commit/PR указываются после публикации.
  • Источники: README.md, COURSE.md, contracts/README.md, contracts/openapi.json, публичные тесты и примеры этого репозитория; FastAPI, psycopg, PostgreSQL и Argon2id. Код и инструкции подготовлены с помощью ИИ Codex и проверяются запуском команд ниже.

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

Нужны Docker с Compose, Python 3.9+ и make. Стенд рассчитан на учебный localhost. API собирается из исходников в python:3.12.12-slim-bookworm; БД — postgres:17.6-bookworm, кэш — valkey/valkey:8.0.2-alpine. Python-зависимости закреплены в requirements.txt; кэш использует короткий RESP-клиент стандартной библиотеки. Порт API опубликован только на 127.0.0.1:8080; PostgreSQL и Valkey наружу не публикуются. На моей macOS с Colima команды make test и make test-persistence выполнялись на хосте с разрешённым доступом к Docker socket и loopback. В ограниченном sandbox 127.0.0.1:8080 был недоступен; проверка не запускалась внутри VM и SSH-туннель не требовался.

После чистого clone создать локальные файлы, которые исключены из Git:

cp .env.example .env
mkdir -p secrets
python3 - <<'PY'
from pathlib import Path
from secrets import token_urlsafe

password = token_urlsafe(32)
Path('secrets/postgres_password').write_text(password)
Path('secrets/database_url').write_text(
    f'postgresql://messenger:{password}@postgres:5432/messenger'
)
PY
chmod 600 .env secrets/*
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh

На каждом старте API выполняет scripts/migrate.py под advisory lock: миграции 001 и 002 применяются только один раз и завершаются до приёма запросов. docker compose --env-file .env exec -T api python scripts/migrate.py безопасно повторить вручную. GET /health/ready требует доступную БД. docker compose --env-file .env down останавливает стенд с сохранением именованного volume. Только для намеренного уничтожения учебных данных: docker compose --env-file .env down -v.

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

Клиент → FastAPI (api) → PostgreSQL (postgres) и необязательный Valkey (valkey); postgres_data сохраняет состояние между перезапусками. PostgreSQL — источник истины для users, chats, memberships, messages и sessions. Создание чата с участниками выполняется одной транзакцией. Пароль хранится как Argon2id hash, непрозрачный токен выдаётся только клиенту, в БД лежит его SHA-256 и абсолютный срок действия. Из lab1 сохранены чаты, членство, сообщения и keyset-пагинация; X-User-Id заменён входом по Basic и запросами по Bearer. .env.example задаёт опубликованный APP_PORT и SESSION_TTL_SECONDS; DATABASE_URL_FILE, VALKEY_URL, APP_HOST и порт внутри контейнера установлены Compose. Pool ограничен восемью соединениями и SQL timeout 5 секунд.

Каждый Bearer-запрос проверяет hash, срок и отзыв сессии в PostgreSQL. После этого публичная проекция User читается по UUID из Valkey с TTL 60 секунд; на промахе или отказе кэша читается PostgreSQL. После регистрации создаётся новый UUID; endpoint изменения/удаления пользователя в lab2 нет, поэтому инвалидация при записи не требуется. Потеря Valkey очищает лишь ускоритель, не сессии или подтверждённые данные. У кэша нет именованного volume, и приложение не полагается на сохранность его данных. При потере PostgreSQL авторизация не использует даже заполненный кэш и возвращает 503; /health/ready зависит от БД, но не от кэша.

Роль Образ/версия Проверка Хранилище/секрет
API Собственный build на Python 3.12.12 /health/ready Без volume; database_url через Docker secret
PostgreSQL postgres:17.6-bookworm pg_isready postgres_data; postgres_password через Docker secret
Valkey valkey/valkey:8.0.2-alpine valkey-cli ping Временный кэш User; без именованного volume и внешнего порта

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke make test BASE_URL=http://127.0.0.1:8080 PASS, lab2 public API scenario evidence/restart-2026-10-02.txt
Стенд и миграции уровня 3 docker compose --env-file .env up -d --build --wait; повторный scripts/migrate.py API и БД healthy, повторная миграция завершилась без ошибки evidence/restart-2026-10-02.txt
Сохранность уровня 3 make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: прежние данные и сессия после рестарта обоих сервисов evidence/restart-2026-10-02.txt
Отказ обязательной БД Остановить postgres, запросить readiness и защищённый endpoint Оба HTTP 503; затем БД восстановлена, сервисы healthy evidence/restart-2026-10-02.txt
Кэш и отказы уровня 4 docker compose exec -T api python - < student-tests/test_cache_failures.py; отказ Valkey/БД Два интеграционных теста PASS; SQL 2/1/2 на miss/hit/reload; Valkey hit/miss 1/2; smoke проходит без кэша; при отказе БД 503, отозванный токен после рестарта кэша 401 evidence/cache-2026-10-02.txt
Индекс и остальные проверки уровня 4 Выполняются в следующем блоке Пока не заявлены как проверенные —
Трек 5 Выполняется после уровня 4 Пока не заявлен как проверенный —

У api, postgres и valkey изменились времена StartedAt при сохранении именованного volume; точные значения приведены в evidence. Это подтверждает фактический перезапуск трёх контейнеров. Проверка make validate локально пока не завершена: DNS до files.pythonhosted.org не позволил установить openapi-spec-validator==0.7.2; отдельный CI workflow устанавливает зависимости из requirements-dev.txt для проверки контракта.

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

Исследование производительности и восстановления выполняется в блоках уровня 4 и трека 5. Текущий стенд — Colima на arm64 macOS с Docker/Compose; значения производительности здесь не заявлены.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Полный restart API и PostgreSQL Тот же действующий токен читает сообщение Публичный persistence PASS Подтверждённая запись сохранена; время восстановления в пределах лимита hook
Остановка PostgreSQL Readiness и защищённый запрос дают ограниченный отказ Оба HTTP 503; после запуска БД healthy Без принятия анонимного запроса
Остановка Valkey Запросы идут через PostgreSQL Публичный smoke PASS при остановленном кэше; затем Valkey healthy Данные и сессии не зависят от кэша
Остановка PostgreSQL при заполненном User-кэше Кэш не авторизует без БД Readiness и защищённый запрос 503; после восстановления действующий токен 200 HTTP-клиенту нужен timeout больше 5-секундного ожидания pool
Отзыв токена и рестарт Valkey Старый токен остаётся недействительным После restart кэша прежний токен 401 Отзыв хранится в PostgreSQL

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

Подтверждён рестарт одного API, одного PostgreSQL и Valkey с сохранением volume БД. Это не высокая доступность: отказ БД временно делает API недоступным, а заполненный кэш не может заменить проверку сессии. Локальный HTTP не предназначен для удалённой передачи паролей без TLS. Проверки индекса на ≥10 000 сообщений, сравнение ≥100 000 сообщений и восстановление в новое хранилище ещё должны быть добавлены; их результаты нельзя выводить из smoke или persistence теста.