forked from mtusi2026/mtusi2026lab2
59 lines
14 KiB
Markdown
59 lines
14 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Федотов Михаил, БВТ2302
|
||
- Целевая оценка: 4
|
||
- Commit/PR: `be7a901` (реализация; PR ещё не создан)
|
||
- Источники и библиотеки: PostgreSQL 16.4, Redis 7.4.2, FastAPI 0.115.6, asyncpg 0.30.0, redis-py 5.2.1, Argon2id через argon2-cffi 23.1.0. При подготовке кода использовалась помощь ИИ.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Python 3.12.8-slim, PostgreSQL 16.4-alpine и Redis 7.4.2-alpine; зависимости Python закреплены в requirements-app.txt. Создать локальный .env по .env.example, задать пароль из букв и цифр, затем выполнить `docker compose --env-file .env config --quiet`, `docker compose --env-file .env up -d --build`, дождаться healthy у api/postgres/redis через `docker compose ps` и выполнить `make test`. Миграции применяются API при старте. Сохранность проверяется `chmod +x scripts/restart.sh` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. Полный набор дополнительных проверок: `make test-grade4`; план истории отдельно: `docker compose exec -T api python scripts/explain_history.py`. Обычная остановка: `docker compose down`; намеренное удаление учебных данных: `docker compose down -v` (не выполнять перед persistence-тестом). Секреты в отчёт не помещать.
|
||
|
||
## Архитектура и решения
|
||
|
||
Lab1 в указанном репозитории — skeleton без готового приложения. По правилам курса перенесён обязательный минимум API, а переход аутентификации выполнен так: регистрация принимает пароль, Basic используется только для создания сессии, защищённые запросы используют Bearer. Преподавательские контракты, публичные тесты и комментарии вне `app/` сохранены.
|
||
|
||
FastAPI обращается к PostgreSQL через asyncpg и ограниченный пул соединений. PostgreSQL — источник истины для пользователей, хешей паролей, чатов, участников и сообщений. Redis — источник истины для сессий; Redis AOF использует `appendfsync always`, а сессии задаются абсолютным PXAT и не продлеваются запросами. Logout удаляет ключ. Переходная миграция 0002 аннулирует старые хеши сессий PostgreSQL; после обновления клиент должен войти заново. Миграции выполняются при запуске и отмечаются в schema_migrations; создание чата и его участников проходит в одной транзакции. Bearer-токен генерируется с 256 битами энтропии; Redis содержит только SHA-256-ключ токена, user_id и expires_at. Индексы: уникальность username, список чатов по участнику и история сообщений по (chat_id, created_at, id). Параметры .env задают локальные реквизиты PostgreSQL и TTL; Compose передаёт API внутренние DATABASE_URL и REDIS_URL. Запросы параметризованы asyncpg; пул ограничен min/max size, временем ожидания свободного соединения и таймаутом SQL-команды. История сообщений читает только одну keyset-страницу через индекс `(chat_id, created_at, id)`. Порты API и PostgreSQL проброшены только на `127.0.0.1`, чтобы не выставлять учебный HTTP API и БД наружу.
|
||
|
||
### Карта инфраструктуры
|
||
|
||
| Роль | Compose service и версия | Health/readiness | Volume | Сеть и опубликованный порт | Передача credentials |
|
||
| --- | --- | --- | --- | --- | --- |
|
||
| HTTP API | `api`; локальная сборка из `Dockerfile`, база `python:3.12.8-slim`; Python-пакеты закреплены в `requirements-app.txt` | Compose проверяет `GET /health/ready`; запуск зависит от healthy PostgreSQL и Redis | Нет: API stateless | Внутренняя сеть Compose; наружу только `127.0.0.1:${APP_PORT:-8080}:8080` | Compose подставляет значения `.env` в `DATABASE_URL`; Redis доступен по внутреннему `REDIS_URL` |
|
||
| Основная БД | `postgres`, `postgres:16.4-alpine` | `pg_isready` с пользователем и базой из конфигурации | Именованный `postgres_data` → `/var/lib/postgresql/data` | Внутренняя сеть Compose; наружу только `127.0.0.1:${POSTGRES_PORT:-5432}:5432` | `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` берутся из локального `.env`; пароль также входит во внутренний `DATABASE_URL` API |
|
||
| Сессии | `redis`, `redis:7.4.2-alpine` | `redis-cli ping`; API отдельно проверяет доступность зависимости в readiness | Именованный `redis_data` → `/data`; включены AOF и `appendfsync always` | Только внутренняя сеть Compose, host port не опубликован | Пароль Redis не задан; Redis не опубликован на host и доступен сервисам только по внутреннему имени `redis` |
|
||
|
||
Bootstrap схемы выполняет API при старте: `apply_migrations` создаёт `schema_migrations`, берёт PostgreSQL advisory lock и применяет упорядоченные SQL-файлы. Каждая новая версия и запись о ней фиксируются в одной транзакции; уже отмеченные версии пропускаются, поэтому повторный запуск безопасен. Отдельные bucket/broker provisioning-команды не нужны: эти сервисы в Lab 2 не используются. `scripts/restart.sh` перезапускает PostgreSQL, Redis и API, сохраняя именованные volumes; отдельный failover hook не добавлен, поскольку стенд содержит одну API-реплику и проверяет отказы зависимостей напрямую.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Структура, контракт и синтаксис | `make check` | PASS: локальная структура, ссылки и синтаксис Python | Вывод `make test-grade4` |
|
||
| Compose-конфигурация | `docker compose --env-file .env config --quiet` | PASS: конфигурация разобрана без ошибок | Команда воспроизводима из README |
|
||
| PostgreSQL, миграции и smoke API | `make test` | PASS: регистрация, Basic/Bearer, доступ к чату, keyset-пагинация, сообщения и logout | Вывод `make test-grade4` |
|
||
| Persistence API + PostgreSQL + Redis | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS: подтверждённые данные и действующий токен сохранились после перезапуска API и обоих хранилищ с сохранением томов | `scripts/restart.sh`; вывод `make test-grade4` |
|
||
| Регистрация при гонке | 8 параллельных `POST /api/v1/users` с одним username | PASS: 1 ответ 201, 7 ответов 409 | `tests/grade4.py`; вывод `make test-grade4` |
|
||
| Атомарность создания чата | POST с неизвестным UUID участника и сверка числа чатов | PASS: API вернул 400; частичная запись не осталась | `tests/grade4.py`; вывод `make test-grade4` |
|
||
| Redis-сессии и короткий expiry | override `SESSION_TTL_SECONDS=2`, последующий Bearer-запрос | PASS: сессия истекла по исходному TTL и запрос вернул 401; logout также проверяется smoke-тестом | `tests/grade4.py`, `tests/smoke.py`; вывод `make test-grade4` |
|
||
| Отказ Redis | остановка Redis и проверка readiness/создания сессии | PASS: оба пути вернули ограниченный 503 `unavailable`; после запуска readiness восстановилась | `tests/grade4.py`; вывод `make test-grade4` |
|
||
| Отказ PostgreSQL | остановка PostgreSQL и проверка readiness/регистрации | PASS: оба пути вернули ограниченный 503 `unavailable`; после запуска readiness восстановилась | `tests/grade4.py`; вывод `make test-grade4` |
|
||
| План keyset-истории на 10 000 сообщениях | `scripts/explain_history.py` внутри контейнера | PASS: выбран `messages_history_idx`, 50 строк, 6 buffer hits; execution time 0.056 ms в этом запуске | `evidence/explain-history.txt` |
|
||
| Обезличенные протоколы stdout | `make check`, `make validate`, Compose config/up/down, `make test`, `make test-grade4`, restart hook | Вывод каждой команды сохранён отдельно; метаданные запуска и состояние контейнеров записаны отдельно, UUID обезличены | `evidence/make-check.txt`, `evidence/make-validate.txt`, `evidence/compose-config.txt`, `evidence/compose-start.txt`, `evidence/make-test.txt`, `evidence/make-test-grade4.txt`, `evidence/restart-hook.txt`, `evidence/compose-shutdown.txt`, `evidence/verification-metadata-2026-10-18.txt` |
|
||
|
||
Все сценарии запускаются командой `make test-grade4`; она собирает образ, задаёт короткий TTL, выполняет дополнительные проверки, восстанавливает штатную конфигурацию, затем запускает smoke и persistence.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Целевой уровень — 4, поэтому сравнительный нагрузочный трек уровня 5 не заявляется. Для критерия плана запроса сценарий создаёт 10 000 синтетических сообщений в отдельном чате, выполняет `ANALYZE`, затем сохраняет фактический `EXPLAIN (ANALYZE, BUFFERS)`. В последнем полном `make test-grade4` запуске PostgreSQL выбрал `messages_history_idx`; страница из 50 строк прочитала 6 shared buffers, время выполнения составило 0.066 ms. Это единичный плановый замер в контейнере, не benchmark и не обещание производительности.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Остановка Redis | Readiness и создание сессии не должны доверять недоступному хранилищу | Ограниченный 503 `unavailable`; после `docker compose start redis` API снова готов | Время измеряется сценарием ожидания, точное число секунд не заявляется; данные Redis-volume не удалялись |
|
||
| Остановка PostgreSQL | Readiness и операция записи должны вернуть ограниченную ошибку | Ограниченный 503 `unavailable`; после запуска БД API снова готов | Точное число секунд не заявляется; PostgreSQL-volume не удалялся |
|
||
| Перезапуск API, PostgreSQL и Redis | Подтверждённые данные и ещё действующий токен должны сохраниться | Persistence-сценарий повторно прочитал подтверждённые данные с прежним токеном | Томы сохранялись; сценарий проверяет итог, но не измеряет RTO/RPO |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
Подтверждены перезапуск всех трёх сервисов без потери тестовых подтверждённых данных, фиксированный expiry Redis-сессии и ограниченная ошибка при недоступности PostgreSQL/Redis. Отказ Redis означает недоступность аутентифицированных операций, а не переход на запасное хранилище. Redis AOF с `appendfsync always` включён, но сбой хоста/файловой системы и восстановление из отдельной резервной копии здесь не проверялись. Нагрузочная пропускная способность и RTO/RPO не измерялись; это не заявлено как трек уровня 5.
|