11 KiB
Отчёт — лабораторная 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 теста.