Files
mtusi2026lab3/REPORT.lab2.md
2026-10-29 13:00:25 +03:00

28 KiB
Raw Permalink Blame History

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

  • Автор, группа: Савельев Иван БВТ2304
  • Целевая оценка: 5, уровень 3 + весь уровень 4 + трек 2 «План запроса и восстановление».
  • Commit/PR: TODO после публикации. Сохранённые проверки относятся к рабочим изменениям поверх коммита, указанного в evidence.
  • Стек: Python 3.11.15 в образе, FastAPI 0.142.4, Uvicorn 0.54.0, Pydantic 2.13.5, Psycopg 3.3.6, PostgreSQL 17.6, Valkey 8.1.3, Argon2id. Прямые и транзитивные зависимости приложения закреплены в requirements.txt.

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

Нужны Docker Engine с Compose v2, Python 3.11, Bash и make. Для demo.sh также нужны curl и jq. Все компоненты запускаются из этого репозитория. Команды выполнять из корня:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
./scripts/start.sh
./scripts/check.sh
./scripts/demo.sh

start.sh создаёт .env и secrets через scripts/init_local.py, собирает API, запускает PostgreSQL и Valkey, затем ждёт готовности API. Пустая БД мигрируется при старте приложения. POST /users теперь требует password; бизнес-запросы принимают Authorization: Bearer. Адрес по умолчанию — http://localhost:8080.

Локальный пароль PostgreSQL создаётся случайно и сохраняется в secrets/postgres_password; URL соединений — в secrets/database_url и secrets/cache_url. Значения не печатаются. Существующие файлы не перезаписываются. Каталог secrets имеет права 0700; файлы 0444, чтобы непривилегированный пользователь контейнера мог читать примонтированные secrets. Содержимое каталога исключено из Git. .env содержит настройки и пути к secrets. Его и .venv в образе нет.

Настройка Использование
APP_HOST, APP_PORT Адрес Uvicorn; внутри контейнера оставить 0.0.0.0:8080
HOST_PORT Порт публикации на 127.0.0.1 компьютера
SESSION_TTL_SECONDS Срок новой сессии; по умолчанию 3600 секунд
SESSION_STORE В этой реализации valkey
DATABASE_URL_FILE Файл с PostgreSQL DSN
CACHE_URL_FILE Файл с URL Valkey, который хранит сессии
APP_ENV Метка учебного окружения; поведение API не переключает

Другой внешний порт и команды управления:

HOST_PORT=8081 ./scripts/start.sh
BASE_URL=http://localhost:8081 ./scripts/check.sh
BASE_URL=http://localhost:8081 ./scripts/demo.sh

docker compose logs --tail 30 api
./scripts/migrate.sh   # повторное применение безопасно
./scripts/restart.sh   # перезапускает API, PostgreSQL и Valkey
./scripts/stop.sh      # удаляет контейнеры и сеть, сохраняет volumes

Для рестарта с нестандартным внешним портом передать то же HOST_PORT или записать его в .env. Команда docker compose down --volumes намеренно удаляет учебные данные текущего Compose project, включая сессии; для обычной остановки она не нужна. scripts/run-local.sh вызывает start.sh: локальный стенд lab2 включает все три сервиса.

PostgreSQL и Valkey не публикуют порты на хост. API запускается от UID/GID 10001 и является PID 1. Лимиты: API — 1 CPU / 256 MiB, PostgreSQL — 1 CPU / 512 MiB, Valkey — 0.5 CPU / 128 MiB. Именованные volumes: postgres_data и valkey_data. Секреты API примонтированы файлами, состояние в API-контейнере не хранится.

Архитектура и транзакции

Сохранены обработчики и модель пользователей/чатов/сообщений из lab1, строгая валидация, единые ошибки, X-Request-Id, пагинация и проверки доступа. Вместо словарей используется PostgreSQL, вместо X-User-Id — Bearer. Контракт, публичные tests, README и COURSE второй работы не изменялись.

Схема спроектирована перед SQL-реализацией в docs/schema.md. Миграция — migrations/001_initial.sql:

Таблица Содержимое и ограничения
users UUID PK, username UNIQUE, display_name, password_hash, created_at
chats UUID PK, title, created_at
chat_members PK (chat_id, user_id); FK на пользователей и чаты
messages UUID PK; chat_id; sender_id; text; created_at; составной FK на участника чата
schema_migrations Версия, SHA-256 и время применения миграции

Одна функция записи в storage.py — одна транзакция. Контекст соединения делает COMMIT при успехе и ROLLBACK при исключении. Ответ 201 формируется после выхода из транзакции. Уникальность username гарантирует ограничение PostgreSQL. Создание чата сначала вставляет чат, затем всех участников: FK violation откатывает и чат, и уже вставленных участников. Проверка доступа и запись сообщения находятся в одной транзакции; составной FK дополнительно требует членства отправителя.

Все значения клиента передаются параметрами %s, без подстановки в SQL. Динамические имена индексов в исследовании выбираются только из фиксированных вариантов программы. Пул API: от 1 до 5 соединений, не более 20 ожидающих; ожидание пула — 2 с, connect_timeout — 2 с, statement_timeout — 3 с, lock_timeout — 2 с, idle_in_transaction_session_timeout — 5 с. При недоступности PostgreSQL возвращается общий 503.

Миграции выполняются в транзакции под advisory lock. Повторная версия пропускается, checksum обнаруживает редактирование уже применённого SQL. Повторный запуск не создаёт новые пользовательские данные. Новое изменение схемы оформляется следующим SQL-файлом.

Пароли и сессии

password имеет длину 12–128 Unicode code points и не возвращается в User. В БД сохраняется Argon2id с собственной случайной солью: memory_cost=19456 KiB, time_cost=2, parallelism=1. Это конфигурация 19 MiB / 2 / 1 из OWASP Password Storage. Не более двух вычислений хеша одновременно ограничивают расход памяти.

POST /api/v1/auth/sessions принимает только Basic без тела. Пароль декодируется как UTF-8; разделение по первому двоеточию позволяет использовать двоеточие в пароле. Неверный пароль и неизвестное имя дают одинаковый 401 с WWW-Authenticate: Basic. Бизнес-запросы требуют Bearer и при 401 возвращают WWW-Authenticate: Bearer. X-User-Id игнорируется и сам по себе доступа не даёт.

Токен содержит 32 случайных байта, представленных непрозрачной строкой. Valkey хранит session:SHA256(token) → user_id и expires_at с TTL. Токен не является username/UUID; его исходное значение не сохраняется в ключе. Чтение сессии не продлевает срок. Абсолютный expires_at дополнительно проверяется приложением. DELETE /auth/sessions/current удаляет только текущую сессию, возвращает пустой 204; повторное использование — 401.

Valkey — источник истины для сессий. Включены AOF, appendfsync always, постоянный volume и noeviction. Поэтому обычный рестарт не сбрасывает ещё действующие сессии. При недоступности Valkey возвращается 503, перехода на доверие к X-User-Id или анонимному запросу нет. Ошибка подключения ограничена таймаутом 0.5 с, автоматические повторы отключены. Истечение TTL и logout не требуют инвалидации отдельного кэша.

/health/live показывает доступность процесса; /health/ready проверяет PostgreSQL и Valkey. Docker healthcheck проверяет HTTP 200 и JSON status=ok. При остановке зависимости live остаётся 200, ready возвращает 503.

Пагинация и индекс истории

Запрос истории выбирает из БД только limit + 1 записей после пары (created_at, id), упорядоченных по той же паре. Индекс messages_history_idx(chat_id, created_at, id) соответствует равенству по чату и диапазону по ключу. Наличие опорной записи курсора проверяется отдельным индексным запросом; полная история в Python не загружается.

Курсор содержит scope, время и UUID в Base64. Scope привязан к чату или списку чатов пользователя. Чужой, повреждённый или несуществующий anchor даёт 400. limit — 1..100, по умолчанию 50; изменение limit при продолжении допустимо. Неучастник и отсутствующий чат возвращают одинаковый 404.

Каждая страница отражает отдельное чтение. Общего snapshot между HTTP-запросами нет. Неизменная история обходится без повторов; конкурентная запись с ключом меньше уже выданного курсора может не попасть на следующие страницы. Время берётся из часов PostgreSQL, поэтому остаётся ограничение при переводе системных часов назад.

Проверки уровней 3 и 4

# На работающем стенде: структура, публичный smoke и 23 собственных теста
./scripts/check.sh

# Явный persistence-тест с прежним токеном; сохраняет volumes
make test-persistence PYTHON=.venv/bin/python ACTION_SCRIPT=scripts/restart.sh

# Полный прогон в отдельном временном Compose project, включая отказы и короткий TTL
./scripts/check-docker.sh

# Полная валидация исходного OpenAPI
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python

check-docker.sh собирает образ и запускает student-tests/docker_lifecycle.py. Проверка использует случайный порт и свой Compose project; в конце удаляет только его контейнеры и тестовые volumes. Пользовательский стенд не перезапускается. Вывод автоматически сохраняется в evidence/docker-checks.txt; вывод сборки остаётся в терминале.

Критерий Наблюдение Доказательство
API lab2 и объявленный переход от lab1 Публичный smoke прошёл; Basic/Bearer, Unicode, доступ и ошибки проверены evidence/docker-checks.txt
Собственные отрицательные тесты и пагинация 23 теста прошли, включая неверный JSON, поля, страницы и чужой cursor evidence/docker-checks.txt
Конкурентная запись 10 клиентов × 10 сообщений; ровно 100 уникальных подтверждённых записей evidence/docker-checks.txt
Гонка регистрации Одинаковый username: одна 201, девять 409 test_concurrency.py, evidence/docker-checks.txt
Откат составной операции После FK violation нет строки chats с проверяемым title evidence/docker-checks.txt
Миграции с нуля и повторно Пустой volume; повторный запуск дважды, одна версия и прежнее число сообщений evidence/docker-checks.txt
Полный рестарт с прежней сессией Публичный persistence прошёл; StartedAt изменился у всех трёх сервисов evidence/docker-checks.txt
Срок сессии, logout, неверный пароль 2-секундная сессия истекла; отзыв одной сессии не затронул другую; Basic с неверным паролем — 401 test_sessions.py, evidence/docker-checks.txt
Недоступность Valkey и PostgreSQL Доверенный запрос — 503, анонимный — 401, live 200 / ready 503; после восстановления прежний токен работает evidence/docker-checks.txt
Индекс истории на ≥10000 сообщений EXPLAIN на 100000: Index Scan по составному индексу, без полного сканирования каждой страницы evidence/query-plans.json
Условия Docker из lab1 non-root, PID 1, healthcheck, логи без паролей/токенов/сообщений; завершение по SIGTERM <10 с evidence/docker-checks.txt

SIGTERM проверяется с незавершённым HTTP-запросом. Новые соединения должны перестать приниматься до выхода процесса. Uvicorn ждёт текущие запросы до 5 с; весь тест требует <10 с. Конкретные времена сохранены в evidence и зависят от машины.

Трек 5: план запроса и восстановление

Гипотеза. Индекс только по chat_id не обеспечивает порядок истории: PostgreSQL приходится отбирать и сортировать множество записей. Индекс (chat_id, created_at, id) позволяет сразу перейти к anchor и прочитать небольшую страницу; ожидаем выигрыш чтения ценой большего индекса и дополнительных затрат записи.

Повторить весь эксперимент:

./scripts/research.sh

Никакой соседний репозиторий и подготовленная БД не требуются. Скрипт создаёт отдельный Compose project с двумя PostgreSQL-контейнерами и разными новыми volumes. Основной стенд и его данные не используются. SQL-измерения выполняет research/benchmark.py внутри API-образа; управление контейнерами, backup и restore — research/run.py. Прямой запуск benchmark требует специальной отметки из драйвера и пустой БД.

Методика:

  1. Создать схему из миграции, 10 синтетических пользователей, 4 чата и 100000 сообщений с распределением 70000 / 20000 / 9000 / 1000. Данные и UUID детерминированы; хеш пароля синтетических аккаунтов создаётся Argon2id, пароль не выводится.
  2. Сравнить индекс A (chat_id) и индекс B (chat_id, created_at, id). PK сообщений и остальные ограничения одинаковы. В каждом из трёх повторов таблица сообщений очищается только в исследовательской БД, затем индекс создаётся до записи. Порядок A/B чередуется.
  3. Измерить один INSERT SELECT на 100000 строк с COMMIT, объём WAL и размер исследуемого индекса. Генерация UUID, текстов и проверки FK входят в стоимость записи обоих вариантов.
  4. После VACUUM ANALYZE для каждого чата прочитать страницы около 10%, 50% и 90% истории. На каждый случай — один прогрев и пять измерений; страница 51 строка, как API для limit=50 с проверкой продолжения. Всего 180 измерений на вариант. SQL параметризован, OFFSET в исследуемом запросе нет.
  5. Сохранить EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) для 24 случаев первого повтора и времена остальных повторов.
  6. Сделать pg_dump в custom format. После завершения dump записать ещё одно сообщение в источник. Восстановить backup через pg_restore --exit-on-error --single-transaction в другой контейнер с новым volume.
  7. Сравнить счётчики всех таблиц, 12 выбранных сообщений и SHA-256 всех полей всех 100000 сообщений в порядке UUID. Подтвердить отсутствие записи, сделанной после backup.

Результаты реального прогона

Проверено 22.10.2026: macOS arm64, Docker Engine 29.0.1, Linux/aarch64, PostgreSQL 17.6. Docker VM: 10 CPU, 8217448448 байт RAM. Для каждой БД установлен одинаковый лимит 1 CPU / 512 MiB, для Python-клиента — 1 CPU / 256 MiB. Нагрузка — последовательные SQL-запросы с concurrency=1 и прогретыми страницами. Ошибок измеряемых запросов — 0.

Метрика Только chat_id chat_id, created_at, id
p50 чтения, мс 1.685 0.226
p95 чтения, мс 7.566 0.297
p99 чтения, мс 46.402 0.338
Медиана записи 100000, мс 1386.76 1404.49
Размер индекса, байт 671744 7315456
Медиана WAL записи, байт 38822560 43108512
Успешных последовательных SQL/с 282.0 4322.8

Медиана чтения уменьшилась примерно в 7.45 раза. Время массовой записи отличается на 1.28% в этом прогоне; трёх повторов недостаточно для универсального вывода о стоимости записи. Составной индекс заметно больше, и WAL записи также увеличился.

Для чата на 70000 сообщений около середины истории план A использовал Parallel Seq Scan и сортировку, 2443 shared hit blocks; план B — Index Scan messages_history_idx, 6 shared hit blocks. Время EXPLAIN было 7.042 мс против 0.019 мс. Это отдельный пример плана, а не медиана всех измерений.

В research.json сохранён снимок docker stats после SQL-измерений: PostgreSQL занимал около 63.24 MiB из 512 MiB. Это посленагрузочный снимок, не измерение пикового потребления. p50/p95/p99 объединяют страницы разных размеров чатов и позиций; подробные значения сохранены отдельно. successful_sql_rps вычислен по сумме времени успешных последовательных SQL-запросов, без прогревов и EXPLAIN: это не HTTP throughput и не предел производительности системы.

Backup и восстановление

Custom dump размером 3067615 байт создан за 0.54 с. pg_restore завершился за 0.68 с; запуск проверки восстановленных данных и сверка заняли ещё 2.34 с. Весь сценарий, включая создание исследовательских контейнеров и SQL-измерения, до cleanup занял 22.90 с.

Источник и приёмник имели разные container ID и разные volume, что записано в research.json. Восстановлены 10 пользователей, 4 чата, 8 участников, 100000 сообщений и одна миграция. Совпали все счётчики, все поля 12 образцов и SHA-256 всей истории. В источнике после backup было 100001 сообщение; дополнительная запись отсутствует в восстановленной БД, как и ожидается для снимка.

Граница потери данных: pg_dump сохраняет согласованный снимок на момент начала backup. Записи после этого снимка без WAL-архива/репликации не восстанавливаются. Показанная потеря одной последующей записи — явный пример этой границы. COMMIT и стандартные fsync/synchronous_commit PostgreSQL обеспечивают локальную фиксацию в пределах гарантий диска и Docker VM; один host не даёт защиты от потери самого host.

Измеренное время pg_restore относится к уже работающему пустому PostgreSQL. Полный RTO включает также создание среды, проверки и переключение API. Переключение рабочего API на восстановленную БД в эксперименте не выполнялось. Сессии находятся в отдельном Valkey AOF-volume и не входят в SQL dump; для полного аварийного восстановления сервиса их резервирование требуется отдельно. Проверка обычного рестарта Valkey с сохранённым volume выполнена в основном прогоне.

Файлы доказательств и повторяемость

  • evidence/docker-checks.txt — автоматически перезаписывается check-docker.sh; публичные и собственные тесты, рестарты, отказы, TTL и SIGTERM.
  • evidence/research.txt — краткий реальный stdout исследования, автоматически перезаписывается research.sh.
  • evidence/research.json — все повторы, латентности, стоимость записи, счётчики, SHA-256, ID контейнеров/volumes и времена backup/restore.
  • evidence/query-plans.json — реальные JSON-планы PostgreSQL.
  • backups/*.dump — локальные dump-файлы, исключённые из Git; содержат только синтетическую исследовательскую БД. Контейнеры и volumes временного research project удаляются в finally. Рабочие volumes обычного стенда сохраняются.

При повторе числа могут измениться. PostgreSQL работает в Docker VM, исследуются прогретые данные на одной машине. Холодный старт диска, сетевые задержки между машинами, высокая конкуренция и другие распределения данных не измерялись. Гипотеза подтверждена для проверенных страниц и распределения, универсального ускорения для любых запросов не заявляется.

CI и дальнейшее развитие

Исходный workflow contracts.yml проверяет контракт. application.yml собирает приложение, выполняет check-docker.sh и research.sh, затем сохраняет evidence как артефакт. Локальные команды выполнены; успешный удалённый запуск CI не заявлен без отдельного результата GitHub Actions.

Код остаётся разделён по назначению: app.py — HTTP, models.py — поля, storage.py — SQL, db.py — пул, auth.py — сессии, passwords.py — Argon2id, pagination.py — курсор, migrate.py — миграции. Исследование находится отдельно в research/. HTTP-контракт и публичные проверки не ослаблялись.

Ограничения: одна API-реплика, один PostgreSQL и один Valkey без HA; нет лимита количества сообщений; сессии теряются при намеренном удалении их volume; сроки жизни зависят от системных часов. Для следующих лабораторных можно сохранить SQL-хранилище, сессии и API, добавляя требуемые контрактом возможности.

Источники