# Отчёт — лабораторная 2 - Автор, группа: не указаны в исходных данных. - Целевая оценка: 5, исследовательский трек 2 — «План запроса и восстановление». - Commit/PR: не создавались. - Источники, библиотеки и помощь ИИ: перенесён и адаптирован собственный API-каркас из lab1; Python standard library; psycopg 3.2.10, psycopg-pool 3.3.3, redis-py 5.2.1; PostgreSQL 16.4, Redis 7.4.2; использовалась помощь ИИ. ## Запуск из чистого clone Требуются Docker Desktop с Compose v2 и Python 3.9+ для локальных проверок. Образы закреплены версиями `python:3.12.7-slim`, `postgres:16.4-alpine`, `redis:7.4.2-alpine`. Проведённые проверки — macOS arm64, Docker 28.0.4, Docker Compose 2.34.0, 10 логических CPU; фактическая память хоста и лимиты контейнеров зафиксированы в [track5_query_restore.json](evidence/track5_query_restore.json). ```sh cp .env.example .env # Заменить POSTGRES_PASSWORD в .env на hex-значение, например: python3 -c 'import secrets; print(secrets.token_hex(24))' # Не добавлять .env в Git. docker compose --env-file .env up -d --build curl --fail http://127.0.0.1:8080/health/ready make check make test make test-persistence ACTION_SCRIPT=scripts/restart.sh make grade4 make track5 ``` API применяет новые миграции из `migrations/` при старте; таблица `schema_migrations` и транзакционная advisory lock обеспечивают однократное применение. `scripts/restart.sh` перезапускает PostgreSQL, Redis и API с сохранением БД volume. Redis является кэшем, поэтому утрата его содержимого не удаляет учётные записи или сессии. Обычная остановка сохраняет состояние: ```sh docker compose --env-file .env down ``` Только для намеренного удаления всех учебных данных, включая пользователей, сообщения и сессии: ```sh docker compose --env-file .env down --volumes ``` `make grade4` выполняет проверки зависимостей и временно перезапускает API с двухсекундным TTL для сценария expiry, затем возвращает обычную конфигурацию. `make track5` использует случайно именованные временные базы, создаёт benchmark-данные, делает custom-format backup, восстанавливает его в новую пустую БД, сверяет counts/checksums и удаляет только созданные им базы. Не запускайте эти команды на production-окружении. ## Архитектура и решения - Перенесены и адаптированы REST-поведение, Dockerfile и ignore-правила из lab1. Сервер разделён по обязанностям: `config.py` — настройки, `errors.py` — API-ошибки, `security.py` — password KDF/UUID/time helpers, `store.py` — PostgreSQL и Redis, `handlers.py` — HTTP endpoints, `app.py` — сборка/жизненный цикл сервера, `server.py` — совместимая точка входа. Публичные `tests/` и `contracts/` текущей лабораторной сохранены без подмены. - PostgreSQL — источник истины для пользователей, чатов, членства, сообщений и сессий. Именованный volume `postgres_data` сохраняет их при перезапуске. - Redis кэширует результат проверки opaque session token по SHA-256 digest ключа и хранит только публичный объект пользователя. Redis key имеет TTL, рассчитанный по оставшемуся `sessions.expires_at`; пароль, сырой токен и его текст не попадают в кэш. - Создание и отзыв сессии записываются в PostgreSQL. Чтение сессии при промахе кэша и logout сериализуются транзакционной advisory lock на digest токена: конкурентное заполнение не может записать сессию в Redis уже после logout. Logout удаляет Redis-ключ до удаления записи в БД; при недоступном Redis logout завершается ограниченным `503`, а не сообщает об успехе без инвалидации кэша. При чтении недоступность Redis логируется, запрос безопасно переходит на PostgreSQL; после восстановления промах кэша заполняется из БД. При недоступной БД readiness и операции, требующие её, возвращают ограниченную ошибку. - Список чатов использует keyset-пагинацию по `(created_at, id)`: курсор привязан к пользователю, страницы не повторяют и не пропускают чаты при обходе неизменённого списка. - Индекс истории в рабочей схеме — `(chat_id, created_at, id)`, соответствующий keyset-пагинации. Все SQL-запросы параметризованы; пул ограничен 16 соединениями, timeout ожидания пула/подключения — 5 секунд, `statement_timeout` — 5 секунд, `lock_timeout` — 2 секунды. - Миграция создаёт ключи и ограничения таблиц. Создание чата и всех участников — одна транзакция; уникальный индекс `username` сериализует гонку регистрации. - Пароли хранятся как scrypt-хеши с индивидуальной солью (`N=32768`, `r=8`, `p=1`). Сессии имеют expiry и отзываются logout-запросом. `X-User-Id` не используется для авторизации. - Лимит Redis — 128 MB, политика вытеснения `allkeys-lru`; постоянство сессий не зависит от Redis, поэтому Redis AOF/RDB не включён. ## Доказательства критериев | Критерий | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | Минимум lab1 и lab2; публичный API | `make test` | PASS: регистрация, Basic login, Bearer auth, чаты, сообщения, пагинация, ошибочные credentials, отказ анониму, logout и отказ отозванного токена | `tests/smoke.py`, `tests/client.py` | | PostgreSQL, ограничения, миграции и сохранность | Чистый старт, повторный старт, `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Миграция записана один раз; прежний token и подтверждённое сообщение переживают рестарт PostgreSQL, Redis и API | `migrations/001_initial.sql`, `scripts/restart.sh`, `tests/resilience.py` | | Redis/Valkey используется с TTL | `make grade4` | Session cache entry обнаружена в Redis с положительным TTL; при остановленном Redis текущая сессия проверяется через PostgreSQL; после запуска Redis доступ восстанавливается | `student-tests/test_level4.py`, `src/server.py` | | Конкурентная регистрация и rollback | `make grade4` | 4 одновременных запроса к одному username дали ровно один `201`, три `409`, в БД осталась одна запись; попытка чата с отсутствующим участником дала `400` и ноль частичных строк | `student-tests/test_level4.py` | | Запросы, индекс истории и ошибки зависимостей | `make grade4`; `make track5` | Проверены параметризованные запросы, ограниченные timeout; при остановке PostgreSQL readiness и операция чтения вернули ограниченный `503`; 100k-набор использован для `EXPLAIN (ANALYZE, BUFFERS)` | `src/server.py`, `evidence/track5_query_restore.json` | | Короткий TTL, неверный пароль и отзыв | `make test`; `make grade4` | Неверный пароль и отозванная/истёкшая сессия дают 401; logout выдаёт 204; короткая сессия проверена при TTL=2 секунды | `student-tests/test_level4.py`, `scripts/test_expiry.sh`, `tests/smoke.py` | | Трек 5.2: планы двух индексов и write-cost | `make track5` | 100,000 синтетических строк на каждый индексный вариант, неравномерное распределение; одинаковый keyset SELECT измерен пять раз; сравнен INSERT cost | [track5_query_restore.md](evidence/track5_query_restore.md), [raw plans/results](evidence/track5_query_restore.json) | | Трек 5.2: backup → новая БД → проверка | `make track5` | Custom-format backup восстановлен в отдельную пустую БД; количество строк и контрольные суммы выбранных сообщений совпали; тест сообщил PASS | `evidence/track5_query_restore.json` | ## Исследование: план запроса и восстановление **Гипотеза.** Индекс только по `chat_id` должен обслужить фильтрацию истории, но keyset-фильтр/сортировка по `(created_at, id)` потребуют отсеивания и top-N сортировки. Составной `(chat_id, created_at, id)` должен уменьшить чтение/время страницы ценой более дорогой записи. **Методика.** Скрипт `student-tests/track5_query_restore.py` использует изолированные случайно именованные PostgreSQL database, не рабочую БД API. В двух вариантах создано по 100 000 synthetic rows: 80 000 в одном чате, оставшиеся 20 000 распределены поровну между 100 чатами. Выполняется один и тот же keyset SELECT страницы из небольшого чата с лимитом 25. После ANALYZE собирается пять `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` планов на вариант. Стоимость записи измеряется пятью EXPLAIN ANALYZE вставками по 2 000 строк; каждая вставка откатывается, поэтому результат отражает execution/index maintenance, но не durable commit/fsync. Затем custom-format `pg_dump` восстанавливается в новую пустую базу, сверяются 100 000 строк каждого варианта и MD5 агрегаты выбранных строк. **Результат текущего запуска.** Сводная таблица медиан, планы, buffer counts, параметры PostgreSQL, restore time и контрольные суммы записаны в [track5_query_restore.md](evidence/track5_query_restore.md) и JSON-файле рядом. В этом запуске составной индекс уменьшил медианное время выбранной страницы примерно с 0.297 ms до 0.097 ms (около 67%); вставка 2 000 строк заняла примерно 5.428 ms против 7.218 ms для составного индекса (около 33% дороже). Restore в новую БД и сверка количества/контрольных сумм завершились PASS. Результаты относятся к этому single-host synthetic run; для повторных запусков числа могут отличаться. ## Ограничения и следующие шаги Redis — ускоряющий кэш, а не самостоятельное долговременное хранилище; источником истины остаётся PostgreSQL. Проверены контролируемые остановки Redis и PostgreSQL, но не потеря host, повреждение диска, HA/failover БД, реальная нагрузка API/RPS, commit fsync или backup по расписанию. Benchmark использует две таблицы с одинаковыми данными и синтетическую нагрузку; он не доказывает пропускную способность production-системы. Docker-контейнеры запускаются без явных CPU/RAM limits (нулевые лимиты указаны в evidence). Сравнение планов и разовый restore PASS не заменяют регулярный проверенный backup/DR-процесс.