31 KiB
Отчёт — лабораторная 2
- Автор: Алихан Абдурашидов. Группа: БВТ2301.
- Целевая оценка: 5, трек 2 «План запроса и восстановление».
- Основа:
mtusi2026/mtusi2026lab2, commit65003b61195361aac238f19c9bff0027ca58e09e. - Ветка решения:
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-транспорта; чужие студенческие решения не переносились.
Что выполнено
- Изучены новый README, COURSE, OpenAPI, семантика сессий, инфраструктурные роли и публичные проверки. Исходный
make checkпрошёл; smoke на ещё отсутствовавшем lab2-сервере ожидаемо получил ошибку соединения. - До SQL-запросов описаны таблицы, ограничения, индексы и транзакции. Добавлена версионируемая миграция
001_initial.sql; повторный запуск проверяет SHA-256 и не дублирует данные. - Из lab1 перенесены строгий HTTP/JSON-транспорт, Unicode-валидация, единый формат ошибок, Request-Id и обработка остановки. Память процесса как источник данных заменена PostgreSQL.
- Добавлены регистрация с scrypt, Basic-вход без JSON body, непрозрачные 256-битные Bearer-токены, абсолютный expiry и logout. Сессии сохраняются в PostgreSQL; X-User-Id не влияет на идентификацию.
- Подготовлены Dockerfile и Compose с API, PostgreSQL и Valkey, именованным volume, локальными secret-файлами, healthchecks и закреплёнными версиями/digest.
- Valkey используется как cache-aside неизменяемого публичного профиля с TTL. История и действительность сессии всегда читаются из PostgreSQL; отказ кэша допускает fallback.
- Добавлены собственные HTTP-тесты, автоматические проверки отказов/expiry/rollback, публичный hook реального перезапуска всех трёх компонентов и проверка отдельного чистого clone.
- Проведено исследование на трёх изолированных БД по 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.
