Files

79 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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-процесс.