15 KiB
Отчёт — лабораторная 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 измерен на одной машине, без повторов/статистического анализа и без сравнения индексов.