Files
mtusi2026lab2/REPORT.md
T
Zyulina_Ekaterina 3af3a132ca
Skeleton contracts / contracts (pull_request) Canceled after 0s
Лабораторная 2:Оценка 4
2026-10-19 23:09:12 +03:00

15 KiB
Raw Blame History

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

  • Автор, группа: Зюлина Екатерина Михайловна БВТ2302.
  • Целевая оценка: 4.
  • Использованные источники и помощь: задание, контракт и публичные проверки этого репозитория; помощь Codex при анализе требований, реализации и подготовке отчёта.

Воспроизводимый запуск (Windows PowerShell)

Нужны Docker Desktop с Linux containers и Python 3.11. Приложение собирается из этого репозитория; миграции применяются автоматически при старте API. В новом clone подготовьте виртуальное окружение и локальный .env:

Copy-Item .env.example .env
# В .env заменить POSTGRES_PASSWORD случайным значением длиной не менее 32 символов.
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
$ready = $false; $deadline = (Get-Date).AddMinutes(2); while (-not $ready -and (Get-Date) -lt $deadline) { try { $ready = (Invoke-WebRequest http://localhost:8080/health/ready -UseBasicParsing -TimeoutSec 2).StatusCode -eq 200 } catch { Start-Sleep -Seconds 2 } }; if (-not $ready) { throw 'API did not become ready' }
.\.venv\Scripts\python.exe scripts\check_contract.py
.\.venv\Scripts\python.exe scripts\validate_openapi.py
.\.venv\Scripts\python.exe tests\smoke.py --base-url http://localhost:8080
.\.venv\Scripts\python.exe tests\resilience.py --mode persistence --action-script scripts\restart.bat --base-url http://localhost:8080
.\.venv\Scripts\python.exe tests\level4.py --base-url http://localhost:8080

scripts/restart.bat перезапускает PostgreSQL, Redis и API без удаления volumes. Не выполняйте docker compose down -v, пока данные нужны: эта команда намеренно удаляет сохраняемые данные. Секреты находятся только в локальном игнорируемом .env.

Архитектура и инфраструктура

Путь запроса: клиент → FastAPI → PostgreSQL; Redis используется API для активных сессий. PostgreSQL — источник истины для пользователей, хешей паролей, сессий и предметных данных (чаты, участники, сообщения). Redis — TTL-кэш сессий, не единственное хранилище токенов. Volume postgres_data сохраняет PostgreSQL; redis_data сохраняет AOF Redis. Оба хранилища подключены только во внутреннюю Compose-сеть; наружу опубликован порт API.

Роль Compose service / образ Готовность и постоянные данные
HTTP API api, собирается из Dockerfile, python:3.11.10-slim-bookworm /health/ready проверяет БД и Redis; исходники поставляются с репозиторием. Порт на хосте задаёт APP_PORT (по умолчанию 8080).
SQL-хранилище db, postgres:16.4-alpine pg_isready; именованный postgres_data; порт 5432 не публикуется на хост.
Кэш сессий redis, redis:7.4.2-alpine PING; именованный redis_data; AOF и appendfsync always; порт 6379 не публикуется на хост.

Compose использует внутренний DNS сервисов db и redis. Пароль PostgreSQL передаётся API и БД из .env; у Redis credentials не заданы, так как он доступен только во внутренней сети локального учебного Compose-стенда. Указанные теги образов закреплены, latest не используется. На машине проверки: Windows, Docker Desktop Linux Engine 26.1.4 / Compose 2.27.1, Intel Core i5-11320H, 15.8 GiB RAM. Явные CPU/RAM-лимиты контейнеров не устанавливались; результаты плана запроса относятся только к этому локальному стенду.

Схема создаётся версионируемыми миграциями Alembic: 001 создаёт начальную структуру; 002 укрепляет временные поля, уникальность членства и индексы истории/списка чатов. Entry point ждёт PostgreSQL, затем выполняет alembic upgrade head. Повторный запуск не создаёт вторую схему.

Модель данных и транзакции

  • users: уникальное имя пользователя, display name, соль и результат password KDF; пароль не сохраняется.
  • sessions: уникальный случайный bearer-токен, пользователь и абсолютный срок expires_at; внешний ключ связывает с пользователем.
  • chats, chat_members: чат и участники; (chat_id,user_id) уникален, внешние ключи не допускают отсутствующих владельцев.
  • messages: чат, отправитель, текст и серверное время; внешние ключи связывают сообщение с чатом и пользователем.

Каждая операция Store открывает свою SQLAlchemy-сессию. Создание чата и всех участников находится в одной транзакции: неизвестный/повторный участник приводит к rollback целиком. Уникальное ограничение username разрешает гонку на стороне PostgreSQL; проигравшая регистрация преобразуется в 409, а не в дубликат. ORM использует параметры, пул ограничен пятью постоянными и пятью overflow соединениями, заданы pool_timeout=5, PostgreSQL connect_timeout=5 и statement_timeout=5s.

Пароли, сессии и Redis

Пароль обрабатывается стандартной библиотекой hashlib.scrypt: индивидуальная случайная соль 128 бит, N=16384, r=8, p=1; сравнение хешей constant-time. Это медленный password KDF с солью, а не быстрый checksum. Basic принимается только на POST /api/v1/auth/sessions. После успешного входа сервер возвращает opaque bearer-токен с 256 битами случайности; бизнес-endpoint определяют пользователя по действующей серверной сессии, а X-User-Id не даёт полномочий.

При создании сессии строка сначала фиксируется в PostgreSQL, затем копируется в Redis с TTL, равным оставшемуся сроку жизни. Если Redis недоступен при создании, строка удаляется, а клиент получает 503, чтобы не выдавать сессию без кэша. Проверка токена сначала читает Redis; cache miss обращается к PostgreSQL и заполняет Redis оставшимся TTL. PostgreSQL остаётся авторитетным и позволяет восстановить действующую сессию после потери/перезапуска Redis. Logout удаляет ключ кэша и запись источника истины. TTL не продлевается чтением или рестартом API; просроченная запись не авторизует запрос даже при задержанном физическом удалении строки.

Redis настроен на AOF с appendfsync always. Тест перезапускает Redis без удаления redis_data, затем подтверждает, что прежняя действующая сессия работает; отдельный источник истины в PostgreSQL также позволяет пересобрать ключ кэша при cache miss. Быстрая проверка TCP-порта Redis с таймаутом 0.2 секунды позволяет вернуть ограниченную ошибку при остановленном сервисе, не ожидая цикла повторных попыток клиента.

Пагинация и индекс истории

История использует непрозрачный URL-safe cursor, связанный с chat id и содержащий (created_at,id). Следующая страница фильтруется сравнением этой пары и сортируется по ней же; последний элемент предыдущей страницы не повторяется. Составной индекс ix_messages_chat_created_id(chat_id, created_at, id) соответствует равенству по чату, диапазону по cursor и порядку выдачи. Между HTTP-запросами нет snapshot-гарантии; контракт гарантирует обход без повторов для неизменной истории.

Тест создал отдельный синтетический чат с 12 000 сообщениями, выполнил ANALYZE и запрос EXPLAIN (ANALYZE, BUFFERS) с keyset-диапазоном и LIMIT 50. В сохранённом плане запроса PostgreSQL выбрал Index Only Scan using ix_messages_chat_created_id, прочитал 50 строк; указаны 6 buffer hits и execution time 0.125 ms на итоговом прогоне. Это свидетельствует об использовании подходящего индекса для данного набора и запроса, но не является нагрузочным бенчмарком или обещанием такой задержки на другом окружении.

Результаты проверок уровня 3 и 4

Требование Проверка Результат
Контракт и структура проекта scripts/check_contract.py PASS
Валидность Compose docker compose --env-file .env config --quiet PASS
OpenAPI 3.1 и JSON Schema scripts/validate_openapi.py PASS, полная валидация; приложение не подменяется тестом схемы
Сквозной API smoke tests/smoke.py --base-url http://localhost:8080 PASS — lab2 public API scenario на итоговой сборке
Перезапуск БД/API/Redis и сохранение данных/прежнего токена tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080 PASS — данные и действующая сессия подтверждены после выполнения hook на итоговой сборке
Две одновременные регистрации с одним username tests/level4.py PASS: ровно 201 и 409
Rollback чата с неизвестным участником tests/level4.py PASS: в списке не осталось частичного чата
Redis TTL, AOF и отказ сервисов tests/level4.py PASS: активные ключи в Redis; сессия доступна после restart Redis; при отключении Redis и PostgreSQL readiness и запрос с Bearer дают 503, после возврата сервисов API снова готов
Истечение сессии, logout и неверный пароль tests/level4.py PASS: неверный пароль 401, logout 204 с последующим 401, сессия с TTL 2 секунды после ожидания даёт 401
История ≥10 000 строк и индексный план tests/level4.py PASS: 12 000 синтетических строк; keyset-страница 50 записей; план использовал составной индекс, сохранён в evidence/history-plan.txt

Полный дополнительный сценарий запускается командой:

.\.venv\Scripts\python.exe tests\level4.py --base-url http://localhost:8080

Он управляет только api, db, redis этой Compose-группы, не удаляет volumes и создаёт уникальные синтетические fixtures. Для проверки истечения временно меняет SESSION_TTL_SECONDS в локальном .env, затем восстанавливает исходное содержимое файла. 12 000 сообщений и записи сценариев намеренно остаются в учебной БД. Повторный прогон добавляет новый синтетический набор.

Итог проверки уровня 4: PASS на итоговой сборке.

Границы решения и вопросы к защите

Это локальный учебный стенд с синтетическими данными и HTTP на localhost. Basic кодирует, но не шифрует пароль; удалённая демонстрация требует TLS. Один Docker host и один PostgreSQL не обеспечивают HA. AOF appendfsync always настраивает локальную политику Redis, но не защищает от потери всего Docker host/диска; устойчивость PostgreSQL зависит от WAL и хранения volume. EXPLAIN ANALYZE измерен на одной машине, без повторов/статистического анализа и без сравнения индексов.