Files
mtusi2026lab2/REPORT.md
T

26 KiB
Raw Blame History

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

Автор: Майорова Софья, БВТ2301. Целевая оценка: 5, трек 2 «План запроса и восстановление».

Ветка: solution/BVT2301-Mayorova. Заголовок МР: ЛР 2 — БВТ2301 — Майорова — на 5. Текущий commit: git log -1 --oneline.

Запуск из чистого clone

Нужны Docker Engine с Compose v2+ и Linux-контейнерами, Python 3.9+, make. Исходники, собственные тесты и HTTP-слой перенесены из своей lab1; контракты и публичные тесты взяты из skeleton lab2, без замены на старые версии.

python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build --wait
make check test test-student
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-dependencies
make research

Bootstrap один раз создаёт .env и случайные локальные secrets; повтор не перезаписывает пароль или БД. Никаких вручную установленных PostgreSQL/Redis не требуется. API сам применяет версии миграций при запуске, до открытия HTTP-порта. Для нового порта задайте APP_PORT=18086 docker compose up -d --wait и передайте соответствующий BASE_URL тестам. Сценарий expiry временно занимает 18083, исследование не публикует порт PostgreSQL.

Полная валидация OpenAPI:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

Остановка с сохранением данных: docker compose down; повторный запуск — docker compose up -d --wait. Намеренное удаление всех учебных данных основного стенда: docker compose down -v. Это не команда restart/persistence-проверки. Файлы backup сохраняются отдельно в игнорируемом каталоге backups/. Исследование дополнительно оставляет отдельный остановленный PostgreSQL и собственный том восстановления; их имена записаны в evidence/index-study.json. Для их намеренного удаления используйте docker rm <restore_container> и docker volume rm <fresh_restore_volume> только после проверки этих имён. Не выполняйте общий docker system prune.

Архитектура, схема и границы транзакций

Клиент → API → PostgreSQL; Redis кэширует неизменяемые публичные профили User. PostgreSQL — источник истины для пользователей, чатов, участников, сообщений и сессий. История сообщений никогда не берётся из Redis: успешный COMMIT виден следующему чтению. Удаления/редактирования профилей в контракте нет, поэтому cache-aside профиля не нарушает read-after-write истории.

Схема в migrations/001_initial.sql; миграция 002_unicode_nul.sql сохраняет существующие строки и переводит display_name/title/text в UTF-8 BYTEA:

  • users: UUID PK, UNIQUE username, display_name, scrypt hash, server timestamp.
  • chats: UUID PK, title, created_at, last_message_at.
  • chat_members: составной PK (chat_id, user_id), FK в chats/users, обратный индекс (user_id, chat_id).
  • messages: UUID PK, FK в chats/users, составной FK (chat_id, sender_id) в членство; индекс (chat_id, created_at, id).
  • sessions: PK SHA-256 случайного токена, FK user_id, expiry и индекс expiry. SHA-256 здесь индексирует высокоэнтропийный токен, не пароль.
  • schema_migrations: применённые имена версий. Advisory transaction lock исключает одновременное применение миграции несколькими API.

PostgreSQL TEXT не поддерживает U+0000, хотя контракт допускает его в Unicode-строке. Три пользовательских поля хранятся как UTF-8 bytes в BYTEA, на границе API кодируются/декодируются без потерь. Python проверяет длину в code points (100/100/4000); ограничения БД дополнительно ограничивают UTF-8 размер 400/400/16000 байт. Username, password_hash и данные сессий остаются TEXT. Миграция конвертирует прежние строки через convert_to. TEXT, BYTEA.

Создание чата, проверка всех участников и вставка членства — одна транзакция. Ошибка неизвестного участника после INSERT чата откатывает весь составной объект; собственный тест проверяет отсутствие даже невидимого orphan через SQL COUNT. Запись сообщения и увеличение last_message_at — одна транзакция. UPDATE строки чата сериализует timestamp внутри чата; сервер выбирает max(часы, предыдущий timestamp + 1 мкс). Это сохраняет порядок keyset при конкурентных отправках и переводе часов назад. Уровень изоляции — PostgreSQL READ COMMITTED; snapshot между HTTP-страницами не обещается.

SQL-параметры передаются отдельно от текста запросов. Connection pool: min=1, max=8, ожидание 2 с; connect timeout 2 с, statement timeout 2 с, lock timeout 1,5 с. Ошибки зависимости ограничены JSON 503, внутренний SQL не возвращается клиенту. Чужие объекты скрыты 404. Readiness зависит от PostgreSQL; liveness — только от процесса.

Аутентификация и Redis

Регистрация принимает 12–128 Unicode code points пароля, включая двоеточие и emoji. KDF — библиотечный hashlib.scrypt: N=16384, r=8, p=1, 16-байтовая случайная соль, dklen=32. Хранятся алгоритм/параметры/соль/hash. Сравнение через hmac.compare_digest; для неизвестного пользователя при допустимом формате credentials вычисляется dummy hash. Неверные credentials возвращают одинаковый 401 с Basic challenge. Профили не содержат паролей/hash.

Basic разрешён только на POST /auth/sessions, без JSON body. Токен — secrets.token_urlsafe(32), 256 бит энтропии. На бизнес-endpoint принимается Bearer; X-User-Id не меняет владельца и не даёт доступ. На каждом защищённом запросе PostgreSQL проверяет действительность сессии и expiry. Logout удаляет сессию, поэтому даже тёплый кэш профиля не даёт повторного доступа. Ещё действующие сессии переживают рестарт, TTL не продлевается.

Redis: cache-aside user:<UUID>, TTL 60 с, лимит 32 MiB и allkeys-lru. При miss профиль читается из PostgreSQL; Redis не хранит bearer token и не определяет аутентификацию. При недоступности Redis с таймаутом 150 мс запрос безопасно идёт в PostgreSQL. После рестарта кэш прогревается повторно. Его persistence намеренно выключен: обязательных данных в Redis нет. Если в будущем появится редактирование User, потребуется инвалидация user:<UUID> после COMMIT.

Собственный конкурентный тест выявил OOM при 10 параллельных scrypt в контейнере 256 MiB (EXIT 137). Исправлено ограничением KDF до двух одновременных вычислений и MALLOC_ARENA_MAX=2; ожидание KDF ограничено 1,5 с, далее 503. Тот же тест под тем же лимитом памяти теперь проходит: один 201, девять 409. Доказательства — evidence/kdf-regression.json, evidence/student-tests.txt.

Компоненты и конфигурация

Роль / service Версия Health / readiness Хранение / сеть
API / api Python 3.12.8, digest в Dockerfile /health/live, /health/ready, Docker healthcheck UID 10001; без локального состояния; только 127.0.0.1:8080 опубликован
PostgreSQL / postgres 17.2-bookworm, digest в compose.yaml pg_isready и SQL SELECT 1 через API именованный postgres_data, порт только внутри Compose
Redis / redis 7.4.1-bookworm, digest в compose.yaml redis-cli ping; не критичен для readiness API только внутренний порт; кэш disposable

API ограничен 1 CPU / 256 MiB; PostgreSQL — 1 CPU / 512 MiB; Redis — 0,5 CPU / 64 MiB. Окружение измерения: macOS arm64, Linux Colima VM 4 vCPU / 4 GiB. Python-зависимости и транзитивный typing-extensions закреплены в requirements.txt.

APP_HOST=0.0.0.0 и внутренний APP_PORT=8080 заданы Dockerfile. APP_PORT из .env задаёт опубликованный порт Compose. APP_ENV — информационная метка skeleton. SESSION_TTL_SECONDS реально передаётся API, default 3600; нормальные smoke/persistence выполняются с TTL ≥300. DATABASE_URL_FILE/CACHE_URL_FILE указывают на Docker secrets. SESSION_STORE=postgres из исходного примера соответствует выбранному решению; переключение backend по этой переменной не реализовано.

secrets/ имеет host mode 0700; пароль PostgreSQL — 0600. Файлы URL имеют 0644 внутри защищённого host-каталога, чтобы Compose мог смонтировать их для UID 10001. Secrets, .env, volumes и backups исключены из Git и build context. В публичном отчёте нет токенов и паролей. Локальный учебный HTTP и доверенная внутренняя сеть не заменяют TLS и ограничение DB-role для реального сервиса.

Доказательства критериев

После исправлений выполнен новый чистый локальный git clone, сборка и запуск на новом пустом volume. Применены обе миграции 001/002; публичный smoke и все девять собственных тестов проходят: evidence/review-clean-clone.txt. Первичный прогон до ревью сохранён в evidence/clean-clone.txt. Сохранность и отказы текущей версии дополнительно проверены: evidence/review-persistence.txt, evidence/review-dependencies.txt.

Критерий Команда / сценарий Реальный результат Файл
Offline / OpenAPI make check, make validate PASS evidence/check.txt, evidence/validation.txt
Обязательный API make test PASS lab2 evidence/smoke.txt
Негативные сценарии и Unicode make test-student 9 тестов, все PASS, включая U+0000 evidence/review-tests.txt
Конкурентные сообщения / cursor тот же набор, 100 POST / 10 клиентов 100 уникальных ID, без потерь тот же файл
Гонка username тот же набор ровно один 201, девять 409 тот же файл
FK/UNIQUE/миграции с нуля первый compose up, повторные старты версии 001/002 применены; исследование создаёт схему с нуля migrations/, evidence/review-restore-runs.json
Атомарность составного чата make test-dependencies, SQL COUNT до/после rollback, количество chats не изменилось evidence/dependencies.json
Сохранность данных и прежнего токена make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS после рестарта API + PostgreSQL + Redis evidence/persistence.txt
Реальность restart hook сравнение StartedAt и volumes всех трёх services процессы новые по времени старта, том PostgreSQL тот же evidence/restart-before.json, evidence/restart-after.json
Реальный Redis DEL профиля, затем GET /users/me и Redis TTL ключ реально заполнен, TTL 60 с evidence/dependencies.json
Expiry отдельный API, TTL=2, ожидание 2,2 с прежний Bearer → 401 тот же файл
Logout / неверный пароль / Basic только на login smoke + собственный тест ожидаемые 401/204 smoke и student-tests
Отказ Redis остановка redis, чтение/запись с прежним токеном работа продолжается, поддельный Bearer → 401 dependencies
Отказ PostgreSQL остановка postgres me/ready → 503; live → 200; после возврата прежний токен работает dependencies
Индекс ≥10000 сообщений EXPLAIN ANALYZE BUFFERS на 100000 keyset использует составной индекс evidence/index-study.json
Трек 5: ≥2 индекса, запись make research 100000 сообщений, 2 индекса, 5 повторов чтения и 3 записи тот же файл
Трек 5: backup → новое хранилище pg_dump/pg_restore в отдельный контейнер и новый volume count, 5 образцов и SHA-256 всей истории совпадают тот же файл, evidence/research.txt

Исследование индекса и восстановления

Гипотеза: индекс только по chat_id заставляет отфильтровывать/сортировать значительную часть большого чата при глубоком cursor. B-tree (chat_id, created_at, id) позволит читать limit+1 сразу из нужного диапазона; за это придётся платить размером индекса и записью WAL.

student-tests/index_study.py создаёт отдельную синтетическую БД, не заполняет рабочие чаты тестового API. Размеры десяти чатов: 70000, 20000, 5000, 2000, 1000, 800, 500, 300, 200, 200 — суммарно 100000. Текст — 64 байта UTF-8. Одна контрольная строка содержит U+0000 и имеет UUID=0, чтобы обязательно попасть в образцы backup/restore; остальные UUID случайные. Timestamp с шагом 1 мкс. Сравниваются messages_history(chat_id) и messages_history(chat_id, created_at, id); PK(id) и прочие ограничения одинаковы.

Запрос совпадает с API keyset: фильтр chat_id и (created_at,id)>cursor, ORDER BY created_at,id, LIMIT 51. Для чатов 70000, 20000 и 200 cursor ставится на 80% истории. Перед замером — ANALYZE и один прогрев; затем пять EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON), без отключения seqscan и других подсказок планировщику. Сохранены все планы, включая buffers. Поочерёдно меняется один индекс.

Индекс Сообщений в чате Медиана Execution Time, мс
chat_only 70000 4.463
chat_only 20000 1.273
chat_only 200 0.020
composite 70000 0.011
composite 20000 0.011
composite 200 0.008

Для большого чата простой индекс приводит к полному/широкому проходу и сортировке, составной — к ограниченному индексному диапазону. Для маленького чата разница близка к шуму. Сам API использует составной индекс из миграции.

Стоимость записи: для каждого варианта три отдельных COPY по 1000 новых сообщений в большой чат, время от COPY до завершения COMMIT; UUID подготовлены до таймера. После каждого повтора добавленные сообщения удаляются и фиксируются отдельно; cleanup не входит в измерение. WAL — разница pg_current_wal_insert_lsn() до/после. Все исходные измерения сохранены.

Индекс Размер индекса, байт Медиана COPY+COMMIT 1000 строк, мс Медиана WAL, байт
chat_only 753664 9.849 241648
composite 6127616 9.935 311584

Большой индекс ускоряет чтение, но увеличивает занимаемое место и WAL. Время записи в этих коротких последовательных прогонах заметно колеблется, на него влияют checkpoint, кэш, COPY, CPU quota и фоновые процессы; три повтора не дают универсального коэффициента замедления. Порядок вариантов фиксирован, cold-cache I/O не исследовался. Это анализ query plan и компромисса индекса, не измерение HTTP RPS всего приложения.

Backup и новое хранилище

student-tests/research.py:

  1. Запускает исследование в отдельной БД; делает pg_dump -Fc согласованного снимка.
  2. Создаёт другой PostgreSQL-контейнер с новым именованным volume, тем же закреплённым образом и собственным каталогом данных; порты хоста не публикуются.
  3. Ожидает TCP-готовность на 127.0.0.1, затем выполняет pg_restore -h 127.0.0.1 --exit-on-error в новую пустую БД. Временный Unix-socket сервер инициализации не проходит эту проверку.
  4. Сравнивает количества users/chats/chat_members/messages/sessions, пять выбранных сообщений и SHA-256 всех 100000 сообщений в порядке UUID, включая поля сообщений. В research fixture sessions=0; сохранность действующей сессии отдельно доказана persistence-тестом.
  5. Сохраняет JSON-сводку, останавливает restore-контейнер; backup и новый volume оставляет для проверки.

Размер dump: 2655198 байт. Dump: 0.280 с; bootstrap нового PostgreSQL: 0.820 с; pg_restore: 0.267 с. Bootstrap + восстановление: 1.087 с, без последующей проверки checksum. Это локальный учебный набор, не RTO большого сервиса.

Исходный volume: mtusi-lab2_postgres_data; новый: mtusi-lab2-restore_4bc6680354a1-data. Разные ID контейнеров и полный результат сверки — в JSON. Backup не коммитится. Восстановленный SHA-256 истории: 8c3e317ab75daa8a5e97641eac51e3a349cffe2293bb83bc2ba22ce602cbf112.

Отказы и ограничения durability

При потере Redis обязательных данных не теряется, кэш восстановим. В тесте чтение/запись/проверки при выключенном Redis заняли 0.050 с суммарно. При выключенном PostgreSQL первый защищённый запрос вернул 503 за 0.004 с; анонимный доступ не разрешался. После возврата зависимостей исходная сессия работала.

Рестарт контейнера с сохранённым volume не теряет подтверждённые данные при обычных настройках PostgreSQL fsync/synchronous_commit. Он не доказывает устойчивость к поломке диска/host или потере volume. Резервная копия даёт состояние на момент snapshot pg_dump: сообщения после этого снимка будут потеряны при восстановлении только из данного backup. PITR/WAL archiving, репликация PostgreSQL и HA не реализованы. Readiness честно становится 503 без БД.

Учебные ограничения: один PostgreSQL и один API; DB-role bootstrap владеет учебной БД, ограничение его production-прав не сделано. Накопленные истёкшие сессии не обслуживаются, но фоновый cleanup таблицы пока не добавлен. Redis не кэширует историю и не сокращает обязательную проверку сессии в БД. Общий HTTP-слой не предназначен для публичного Internet-deployment без TLS/reverse proxy.

Исправления по замечаниям преподавателя

  • U+0000: миграция 002 и lossless UTF-8 BYTEA для трёх строковых полей. Новый black-box тест проверяет NUL, буквальную последовательность backslash-u0000, emoji, границу 4000 code points, профиль из login/БД/Redis, title и чтение истории. Девять собственных тестов и публичный smoke проходят: evidence/review-tests.txt.
  • Сохранность: профиль, чат и сообщение с U+0000 без изменений прочитаны после рестарта API/PostgreSQL/Redis, прежний Bearer действителен: evidence/review-unicode-persistence.txt.
  • Гонка init-сервера: readiness и restore используют TCP. Три последовательных полных исследования с новыми контейнерами и томами прошли; каждый раз совпали counts, выбранные строки (включая NUL) и SHA-256 всей истории: evidence/review-research.txt, evidence/review-restore-runs.json. Метрики выше обновлены по последнему прогону текущей схемы.

Коротко для защиты

COMMIT подтверждает транзакцию; устойчивость зависит от WAL, fsync, synchronous_commit и сохранности носителя. Аутентификация определяет пользователя по Bearer, членство отдельно определяет доступ к чату. Flush/restart Redis затрагивает только кэш профилей; сессии остаются в PostgreSQL. Password KDF намеренно затратен и использует соль, быстрый checksum для паролей не подходит.

Источники и помощь

Исходный skeleton lab2, его контракты и публичные tests; собственные src/common.py, src/server.py и тесты из lab1. Документация: PostgreSQL EXPLAIN, pg_dump, pg_restore, psycopg pool, Python scrypt, Redis EXPIRE, RFC 7617. Codex использован для реализации, тестирования, экспериментов и отчёта. Все численные результаты получены локальными запусками; контракты и публичные проверки не ослаблялись.