Files
mtusi2026lab2/REPORT.md
T

31 KiB
Raw Blame History

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

  • Автор: Алихан Абдурашидов. Группа: БВТ2301.
  • Целевая оценка: 5, трек 2 «План запроса и восстановление».
  • Основа: mtusi2026/mtusi2026lab2, commit 65003b61195361aac238f19c9bff0027ca58e09e.
  • Ветка решения: solution/bvt2301-abdurashidov. Проверенный commit записывается в evidence/clean-clone.json; хеши исходников измерений — в evidence/research.json.
  • Дата проверок: 30 октября 2026 года.
  • Источники и библиотеки: контракт курса, Python stdlib, psycopg 3, redis-py, официальная документация PostgreSQL/Docker/Valkey. matplotlib/NumPy нужны только для рисунка. Собственное Python-решение lab1 использовано как основа HTTP-транспорта; чужие студенческие решения не переносились.

Что выполнено

  1. Изучены новый README, COURSE, OpenAPI, семантика сессий, инфраструктурные роли и публичные проверки. Исходный make check прошёл; smoke на ещё отсутствовавшем lab2-сервере ожидаемо получил ошибку соединения.
  2. До SQL-запросов описаны таблицы, ограничения, индексы и транзакции. Добавлена версионируемая миграция 001_initial.sql; повторный запуск проверяет SHA-256 и не дублирует данные.
  3. Из lab1 перенесены строгий HTTP/JSON-транспорт, Unicode-валидация, единый формат ошибок, Request-Id и обработка остановки. Память процесса как источник данных заменена PostgreSQL.
  4. Добавлены регистрация с scrypt, Basic-вход без JSON body, непрозрачные 256-битные Bearer-токены, абсолютный expiry и logout. Сессии сохраняются в PostgreSQL; X-User-Id не влияет на идентификацию.
  5. Подготовлены Dockerfile и Compose с API, PostgreSQL и Valkey, именованным volume, локальными secret-файлами, healthchecks и закреплёнными версиями/digest.
  6. Valkey используется как cache-aside неизменяемого публичного профиля с TTL. История и действительность сессии всегда читаются из PostgreSQL; отказ кэша допускает fallback.
  7. Добавлены собственные HTTP-тесты, автоматические проверки отказов/expiry/rollback, публичный hook реального перезапуска всех трёх компонентов и проверка отдельного чистого clone.
  8. Проведено исследование на трёх изолированных БД по 100 000 сообщений; сравниваются три индекса, keyset/OFFSET и стоимость committed INSERT. Backup восстановлен в отдельный новый PostgreSQL-контейнер с новым volume; сверена вся история.

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

Требуются Git, Docker с Compose, Python 3.11+ и make. Внешняя установленная БД не нужна. Исходный README задания, contracts/ и публичные tests/ сохранены.

# В корне checkout решения:
make up
make check test student-test
make infra-test
# Отдельно публичный persistence:
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Исследование:
make research

make up вызывает scripts/bootstrap.py: создаются .env из примера и случайные локальные credentials только при их отсутствии. Затем docker compose up -d --build --wait собирает исходники и ждёт healthcheck. Миграции применяются при старте API до bind HTTP-порта. Оператор не создаёт таблицы вручную и не передаёт пароли в командной строке.

Приложение слушает 0.0.0.0:8080 внутри контейнера, опубликовано только на 127.0.0.1:8082. Другие сервисы не публикуют host-порты. 8082 выбран для сосуществования с lab1 на 8080; make передаёт BASE_URL явно. При смене HOST_PORT изменить также BASE_URL команд тестов.

Компонент Закреплённая версия Назначение
API Python 3.13.12 slim-bookworm, digest в Dockerfile HTTP и драйверы, UID 10001, read-only rootfs
PostgreSQL 17.9-bookworm, digest в compose.yaml Источник истины; persistent postgres_data
Valkey 8.1.3-alpine, digest в compose.yaml Только профильный кэш; память 64 MB, allkeys-lru
psycopg / psycopg-binary 3.3.6 Параметризованный SQL и бинарный libpq
psycopg-pool 3.3.1 Ограниченный потокобезопасный пул
redis-py 6.4.0 Valkey protocol client
typing_extensions 4.16.0 Закреплённая зависимость пула

Все Python-зависимости приложения закреплены в requirements.txt. Dockerfile копирует только исходники и миграции; .dockerignore исключает Git, .env, secrets, backups, локальные окружения, тесты, исследования и bytecode. Build/runtime для компилируемого языка здесь неприменимы.

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

Переменная Реальное поведение
APP_HOST / APP_PORT В Compose фиксированы 0.0.0.0 / 8080, внутренний HTTP bind
HOST_PORT Host published port; по умолчанию 8082
APP_ENV Метка лабораторного окружения в .env; не переключает хранилище
SESSION_TTL_SECONDS Абсолютный срок сессии, 3600 с по умолчанию; тест отдельно использует 2 с
SESSION_STORE Поддерживается и проверяется postgres; Valkey не является хранилищем сессий
PROFILE_CACHE_TTL_SECONDS TTL публичного профиля, по умолчанию 300 с
DB_POOL_MAX Максимум 8 соединений по умолчанию; допустимо 1–32
DATABASE_URL_FILE / CACHE_URL_FILE DSN читаются из явно смонтированных /run/secrets/...

Папка secrets/ имеет режим 0700 на хосте; файлы читаемы сервисными UID только в тех контейнерах, куда явно смонтированы. Compose secrets локального стенда — файловые mounts, не шифрованное secret-хранилище. .env содержит настройки без credentials. Сами пароли/DSN не печатаются и не входят в Git или отчёт.

# Остановка с сохранением volume и secret-файлов:
docker compose down
# Возобновление:
docker compose up -d --wait
# Намеренное удаление учебных данных только этого проекта:
docker compose down --volumes

Удаление volume не удаляет secret-файлы. Удаление/регенерация файлов при сохранённой БД не меняет её пароль автоматически. Секреты следует хранить вместе с инструкцией эксплуатации вне Git.

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

Клиент → HTTP API (Python, один процесс, потоки)
                     ├→ PostgreSQL: пользователи, чаты, членство, история,
                     │              хеши сессий/expiry, cursor key, миграции
                     └→ Valkey: public User по user_id, TTL 300 с

Реализация хранит users, chats, chat_members, messages, sessions, app_settings, schema_migrations. PK/FK, уникальность username и CHECK обеспечивают базовые инварианты. У сообщения составной FK (chat_id,sender_id) на участника чата. Индекс членства (user_id,chat_id) поддерживает список доступных чатов. Схема и её обоснование сохранены отдельно до SQL-реализации.

Регистрация атомарно вставляет пользователя, конфликт уникальности возвращает 409. Создание чата и всех участников — одна транзакция; неизвестный участник вызывает FK violation и полный rollback. Отправка сообщения обновляет last_message_at чата и вставляет сообщение в одной транзакции. Контекст соединения фиксирует COMMIT до возврата успешного HTTP-ответа; исключения откатывают операцию. SQL-параметры передаются драйверу отдельно от текста запроса.

Пул: минимум 1, максимум 8 соединений, очередь не более 32 ожидающих, ожидание 2 с. Connect timeout 2 с, statement timeout 2 с, lock timeout 1 с, idle-in-transaction 5 с. Исчерпание пула/таймаут/потеря БД дают 503 без внутренних деталей. Потоки HTTP не являются отдельными независимыми источниками состояния.

Миграции инициализируются под транзакционной advisory lock; применённые версии и SHA-256 хранятся в БД. Повторное применение не создаёт бизнес-данные. Изменение уже применённого файла обнаруживается; изменение схемы требует новой миграции. Все pending migrations одного запуска фиксируются вместе с созданием постоянного cursor key.

Пароли, сессии и доступ

Пароли: scrypt N=16384, r=8, p=1, dklen=32, случайная соль 16 байт; параметры, соль и hash записаны вместе. Длина 12–128 Unicode code points; пароль кодируется в UTF-8 без усечения, двоеточие допускается. Сравнение constant-time. Для неизвестного username выполняется dummy KDF; текст и challenge 401 совпадают с неверным паролем существующего пользователя.

POST /auth/sessions принимает Basic только в Authorization, без JSON body. Выдаётся secrets.token_urlsafe(32) — 256 бит случайности, не UUID и не username. В БД сохраняется SHA-256 токена, user_id и абсолютное expires_at по часам PostgreSQL. Здесь быстрый SHA-256 уместен для случайного высокоэнтропийного токена; пароль обрабатывается медленным password KDF.

Каждый защищённый запрос проверяет Bearer и expiry в PostgreSQL. Logout удаляет только текущую сессию; другая сессия пользователя остаётся действительной. X-User-Id игнорируется. Сначала аутентификация, затем доступ; чужой/отсутствующий чат одинаково возвращает 404. Пароль, hash и session-данные в User не включаются. HTTP используется только для локального синтетического стенда.

Кэш и read-after-write

Valkey хранит только четыре поля public User: id, username, display_name, created_at. В текущем контракте профили не изменяются, поэтому TTL 300 с и cache miss безопасны; при добавлении UPDATE/DELETE потребуется явная инвалидация/версионирование ключей. Ключ имеет namespace profile:v1:<UUID>.

Сначала PostgreSQL подтверждает сессию, затем разрешается cache hit профиля. Поэтому cache hit никогда не позволяет обойти expiry или logout. При недоступности Valkey timeout 200 мс, автоматических retry нет: профиль читается из PostgreSQL, cache set может быть пропущен. Потеря всего кэша не теряет сессии. Valkey persistence намеренно выключен: это восстанавливаемый кэш, а не единственное хранилище данных или сессий.

Сообщения и история вообще не кэшируются. Следующий GET обращается к primary PostgreSQL после завершённого COMMIT записи. Членство тоже проверяется в БД. Это обеспечивает read-after-write без риска устаревшей страницы из Valkey.

Пагинация и часы

Cursor подписан HMAC-SHA256 постоянным ключом из app_settings, включает resource scope и (created_at,id). Он переживает рестарт API/БД, привязан к чату либо текущему пользователю для списка чатов. Неверная подпись/scope — 400; limit 1–100 может меняться между страницами.

SELECT id, chat_id, sender_id, text, created_at
FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4;

Рабочий индекс — (chat_id,created_at,id). API читает limit+1 строку для определения next_cursor, возвращает только limit. OFFSET в API не используется. Timestamp сообщений монотонен внутри чата: row lock и greatest(clock_timestamp(), last_message_at + interval '1 microsecond') защищают порядок конкурентных вставок и откат часов. Время может слегка опережать физические часы; это не распределённые часы.

Snapshot isolation между HTTP-страницами не обещается. Подтверждённое между страницами новое сообщение может попасть в последующие страницы. Отсутствие повторов гарантируется для неизменной истории. Для создаваемых конкурентно чатов порядок определяется парой, но страницы не являются снимком всех будущих COMMIT.

Health и остановка

Live проверяет HTTP-процесс. Ready проверяет PostgreSQL; Valkey некритичен, поскольку есть fallback. SIGTERM прекращает приём новых запросов и дренирует потоки; socket timeout 3 с, общий срок 7,5 с с закрытием оставшихся сокетов, stop_grace_period 10 с. Содержимое сообщений, Authorization и DSN не логируются; лог содержит request_id, метод, статус и длительность.

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

Критерий Команда / сценарий Результат Доказательство
Целостность контракта и схемы make check validate PYTHON=.venv/bin/python PASS contracts.txt
Обязательный lab2 API make test Публичный сценарий PASS smoke.txt
PostgreSQL, миграции, сессии переживают рестарт make test-persistence ACTION_SCRIPT=scripts/restart.sh Тот же токен читает прежние данные persistence.txt
Все реальные процессы/хранилища перезапущены make infra-test StartedAt изменился у API, PostgreSQL и Valkey; volumes не удалены infrastructure.json
Valkey используется осмысленно make infra-test Есть profile keys с положительным TTL, только public поля; flush/restart восстанавливается infrastructure.json
Параметризованные SQL, pool/timeouts src/store.py; отказ PostgreSQL 503 примерно за 2,01 с; анонимные запросы не доверены store.py, infrastructure.json
Гонка username make student-test 10 одновременных запросов → ровно 1×201 и 9×409 student-tests.txt
Rollback составной операции make student-test; make infra-test Ошибка неизвестного участника не оставляет чат и членство; количества сверяются в SQL student-tests.txt, clean-clone.json
Конкурентная история make student-test 100 сообщений / 10 клиентов, без потерь и дублей student-tests.txt
Expiry/logout/неверный пароль make student-test; make infra-test 401, отдельный TTL 2 с, другая сессия сохраняется student-tests.txt, infrastructure.json
Отказ Valkey и PostgreSQL make infra-test Cache fallback; PG→503; live 200 / ready 503; восстановление с прежней сессией infrastructure.json
Индекс и EXPLAIN на ≥10 000 make research Измерены 100 000 сообщений; index condition по chat_id и tuple; 50 строк вместо фильтрации 79 900 explain-plans.json
Чистый clone / новая БД / воспроизводимость make clean-clone-test Отдельные clone, порт, credentials, сеть и volumes; сборка, HTTP и infrastructure проверки clean-clone.json, clean-clone-run.txt
Трек 2: ≥100 000, неравномерные чаты, ≥2 индекса/запроса make research 3 индекса × 4 чата × 2 запроса × 30 чтений; 10 write-batch на индекс research.json, CSV
Backup → новое хранилище → сверка make research Новый контейнер и volume; 100 000 сообщений, все counts, 7 samples и полный SHA-256 совпали research.json

make clean-clone-test проверяет текущий commit, а не незакоммиченные изменения. Он удаляет только свои одноразовые тестовые volumes. CI workflow приложения добавлен отдельно; удалённый запуск GitHub Actions на Gitea не заявляется.

Исследование и фактические результаты

Гипотеза, полный метод и ограничения: research/README.md. Аппаратная среда: Apple M4, 16 GiB RAM, Docker Desktop 29.4.3, Linux arm64. PostgreSQL и клиент имеют по 1 CPU / 512 MiB; Valkey — 0,5 CPU / 128 MiB, внутренний cache maxmemory 64 MB.

Исследуются три отдельных БД с одинаковой схемой и 100 000 сообщениями в чатах 80 000 / 15 000 / 4 000 / 1 000. Структурное отличие — только индекс: chat_id, составной keyset, либо covering с INCLUDE. После 3 прогревов выполняется по 30 последовательных чтений; сохраняются все времена и nearest-rank p50/p95/p99. Стоимость записи — 10 реальных транзакций по 1000 сообщений, время включает EXPLAIN ANALYZE и COMMIT. Write-строки после измерения удаляются только в исследовательской БД; VACUUM ANALYZE предшествует чтению. Это не нагрузочный HTTP-тест.

Индекс / запрос, чат 80 000 p50, мс p95, мс p99, мс
chat_id / keyset 7,0761 7,1933 7,1945
составной / keyset 0,2249 0,2545 0,3508
covering / keyset 0,1993 0,3393 0,4040
составной / OFFSET 6,9243 12,6501 15,0282

При поздней странице большого чата p95 составного keyset-запроса меньше исходного примерно в 28,26 раза. EXPLAIN показывает: исходный индекс фильтрует 79 900 строк и сортирует, затрагивает 2017 shared hit blocks; составной — Index Scan с tuple в Index Cond, только 50 строк и 6 shared hit blocks. Covering даёт Index Only Scan, 0 heap fetches, 5 blocks, но это не гарантирует лучший p95 в короткой выборке.

Индекс Все индексы messages, MiB INSERT 1000 + COMMIT p50, мс p95, мс Средний WAL bytes
chat_id 5,203 9,6394 11,5286 379 956
составной 11,156 10,2890 12,1678 453 492
covering 27,609 13,9626 64,6203 708 616

Выбран узкий составной индекс: он устраняет линейный просмотр поздней страницы, а covering увеличивает размер индексов примерно в 2,47 раза относительно составного и медиану write-batch примерно в 1,36 раза. Малые разницы субмиллисекундных чтений не перевешивают этот расход в данном стенде. OFFSET остаётся затратным даже с составным индексом. Планировщик и реальные buffers подтверждают механизм изменения; один факт наличия индекса этого не доказывает.

Индексы, задержки и стоимость записи

Backup custom-format: 3 004 503 bytes, создание 0,5288 с. Подготовка нового PostgreSQL с новым volume — 1,3216 с, restore — 0,6135 с, вместе 1,9351 с без последующей проверки. После восстановления совпали counts всех семи таблиц, 7 выбранных сообщений и SHA-256 всей истории. Orphan messages — 0. Сессия и постоянный cursor key также присутствуют в снимке; функциональная сохранность реальных API-сессий отдельно проверена публичным restart-тестом.

После dump в источник добавлена canary-запись. Источник содержит 100 001 сообщение, восстановленная БД — исходные 100 000. Это ожидаемая граница snapshot backup: подтверждённая после снимка запись в этот backup не входит. Нулевой RPO не заявляется; нужны WAL archive/PITR. Время здесь относится к маленькому локальному синтетическому набору, не к полному production RTO.

Полные результаты: таблица, raw JSON, EXPLAIN, CSV. Dump хранится только локально в игнорируемом backups/; реальные рабочие данные не экспортировались.

Отказы, ограничения и дальнейшие шаги

Воздействие Ожидание Наблюдение Потери / восстановление
Valkey down Fallback в PostgreSQL, logout действует Сценарий 0,85 с, корректные profile/history и 401 после logout Потерян только восстанавливаемый кэш
Valkey flush/restart Перезаполнение профилей; revoked token не оживает PASS Пользователи/сообщения/сессии не теряются
PostgreSQL down 503, ready 503, live 200, без доверия анониму Первый защищённый запрос 2,01 с Данные на volume; прежняя сессия работает после старта
API + все хранилища restart Данные и неизменённый expiry сохраняются Публичный persistence PASS; все StartedAt изменились Воспроизведённое восстановление около 7,924 с
SESSION_TTL_SECONDS=2 401 после expiry PASS в отдельном API-контейнере Истекает только сессия
Неизвестный участник в создании чата Полный rollback HTTP и SQL-проверка отсутствия остаточных строк Нет частичного чата
Restore снимка Совпадение состояния на момент dump 100 000 сообщений и полный checksum совпали Canary после снимка отсутствует ожидаемо

Ограничения: один локальный PostgreSQL, нет репликации/HA/PITR; именованный volume не защищает от потери диска/хоста. Synchronous COMMIT опирается на настройки PostgreSQL и честность fsync нижележащего хранилища. Истёкшие сессии логически не дают доступ, но фоновая очистка их строк пока не реализована. Кэш не измерялся на stampede/stale read — трек 1 не заявляется. Обновление/удаление пользователей, вложения, idempotency и балансировка относятся к следующим работам.

Короткие последовательные SQL-измерения с прогретыми страницами и фиксированным порядком вариантов не дают production SLA, максимальный throughput или статистически устойчивые tail-percentiles. CPU-профилирование не проводилось; ограничения ресурсов заданы явно. Полноценный HTTP-сервер промышленного развёртывания потребовал бы дополнительных ограничений соединений и внешнего TLS.

Ответы на вопросы защиты

  • COMMIT: фиксирует всю транзакцию либо не фиксирует её при ошибке; возврат API происходит после завершения контекста транзакции. Durability зависит от synchronous_commit, fsync, full_page_writes, диска и сохранности volume. Ответ на неопределённый сетевой обрыв ещё не гарантирует отсутствие совершённой записи.
  • Сессии и Redis/Valkey: сессии находятся в PostgreSQL, Valkey содержит только public User. Flush/restart теряет cache hit, но не токен/expiry. Logout всегда проверяется по БД.
  • Аутентификация и доступ: Bearer устанавливает текущего пользователя; членство решает, может ли он читать/писать конкретный чат. Действительный токен постороннего всё равно получает 404.
  • Password KDF и checksum: человеческий пароль низкоэнтропийный, нужен salted memory-cost KDF; случайный 256-битный токен можно искать по SHA-256. SHA-256 истории в backup-проверке обнаруживает отличие данных и не заменяет password KDF.

Первичные источники