26 KiB
Отчёт — лабораторная 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:
- Запускает исследование в отдельной БД; делает
pg_dump -Fcсогласованного снимка. - Создаёт другой PostgreSQL-контейнер с новым именованным volume, тем же закреплённым образом и собственным каталогом данных; порты хоста не публикуются.
- Ожидает TCP-готовность на 127.0.0.1, затем выполняет
pg_restore -h 127.0.0.1 --exit-on-errorв новую пустую БД. Временный Unix-socket сервер инициализации не проходит эту проверку. - Сравнивает количества users/chats/chat_members/messages/sessions, пять выбранных сообщений и SHA-256 всех 100000 сообщений в порядке UUID, включая поля сообщений. В research fixture sessions=0; сохранность действующей сессии отдельно доказана persistence-тестом.
- Сохраняет 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 использован для реализации, тестирования, экспериментов и отчёта. Все численные результаты получены локальными запусками; контракты и публичные проверки не ослаблялись.