49 lines
11 KiB
Markdown
49 lines
11 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: заполнить перед сдачей
|
||
- Целевая оценка: 4
|
||
- Commit/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 и БД наружу.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий 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, `make test-grade4`, restart hook, shutdown | Вывод каждой команды сохранён отдельно; метаданные запуска и состояние контейнеров записаны отдельно, UUID обезличены | `evidence/make-check.txt`, `evidence/make-validate.txt`, `evidence/compose-config.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)`. В последнем локальном запуске PostgreSQL выбрал `messages_history_idx`; страница из 50 строк прочитала 6 shared buffers, время выполнения составило 0.056 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.
|