# Отчёт — лабораторная 2 - Автор, группа: Зюлина Екатерина Михайловна БВТ2302. - Целевая оценка: **4**. - Использованные источники и помощь: задание, контракт и публичные проверки этого репозитория; помощь Codex при анализе требований, реализации и подготовке отчёта. ## Воспроизводимый запуск (Windows PowerShell) Нужны Docker Desktop с Linux containers и Python 3.11. Приложение собирается из этого репозитория; миграции применяются автоматически при старте API. В новом clone подготовьте виртуальное окружение и локальный `.env`: ```powershell 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`. В сохранённом [плане запроса](evidence/history-plan.txt) 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` | Полный дополнительный сценарий запускается командой: ```powershell .\.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` измерен на одной машине, без повторов/статистического анализа и без сравнения индексов.