23 KiB
Отчёт — лабораторная 2
- Автор, группа: Кораблев Петр, БВТ2304
- Целевая оценка: 5
- Выбранный трек 5: трек 2 — план запроса и восстановление
- Commit/PR: solution/BVT2304-korablev
- Использованные библиотеки: pgx/v5 (pgxpool) — PostgreSQL, go-redis/v9 — Valkey, golang.org/x/crypto/argon2 — хеширование паролей, google/uuid; логирование — стандартный
log/slog. - Помощь ИИ использовалась для создания отчета.
Запуск из чистого clone
Требования: Docker 26+ с Compose v2, Python 3.9+ (тесты и генерация секретов), make — по желанию. Go локально не нужен: приложение собирается в Docker (golang:1.23.4-alpine3.21 → alpine:3.21.2, non-root). Версии образов зафиксированы: postgres:17.2-alpine3.21, valkey/valkey:8.0.2-alpine3.21.
make secrets # python scripts/init_secrets.py — secrets/* со случайными паролями и .env из .env.example
make up # docker compose up -d --build --wait api
Порядок старта: postgres → migrate (одноразовый bootstrap: версионируемые миграции, advisory lock, повторный запуск безопасен) → valkey → api. API слушает только 127.0.0.1:8080; порты PostgreSQL и Valkey наружу не публикуются.
Проверки:
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-student # собственные тесты уровня 4; останавливают и запускают postgres/valkey
make track2 # эксперимент трека 2 (--repeat 21) в отдельных контейнерах профиля research
Без make — те же команды через python: scripts/check_contract.py, tests/smoke.py, tests/resilience.py --mode persistence --action-script scripts/restart.sh, student-tests/run_tests.py, scripts/track2/run_track2.py.
На Windows Python не умеет запускать .sh через subprocess, поэтому рядом лежит scripts/restart.cmd с теми же командами Compose; на машине автора тест сохранности запускался с ним, а сам restart.sh проверен из Git Bash (rc=0).
Безопасная остановка: make down (docker compose stop) — данные остаются в volume mtusi-lab2_pgdata. Намеренное удаление всех учебных данных:
docker compose --profile ttl --profile research down -v
Секреты (secrets/, .env) создаются локально, исключены из Git и из Docker build context и передаются контейнерам как Compose secrets (/run/secrets/...). Приложение читает DATABASE_URL_FILE / CACHE_URL_FILE и не логирует их значения.
Архитектура и решения
Клиент → HTTP (net/http) → обработчики → Store на PostgreSQL (pgxpool, не более 10 соединений). Сессии: PostgreSQL как источник истины, Valkey как кэш перед ним. Из lab1 перенесены HTTP-слой, формат ошибок, request-id, валидация, keyset-курсоры (created_at, id) и graceful shutdown. In-memory Store заменён на PostgreSQL с теми же операциями, X-User-Id — на Bearer-сессии.
Схема (src/internal/db/migrations/0001_init.sql): users (UNIQUE username, CHECK формата), chats, chat_members (PK (chat_id, user_id), position хранит порядок member_ids), messages, sessions. В messages стоит составной FK (chat_id, sender_id) → chat_members: база сама гарантирует, что автор сообщения — участник чата. История читается по индексу (chat_id, created_at, id). Время назначает PostgreSQL с точностью до миллисекунд, так что все реплики используют одни часы.
Создание чата атомарно: INSERT chats и INSERT chat_members идут в одной транзакции. Неизвестный участник нарушает FK, транзакция откатывается целиком, клиент получает 400. Гонку регистрации одинакового username решает UNIQUE (23505 → 409), а не связка «SELECT, потом INSERT». Все SQL параметризованы ($1…). У пула есть ConnectTimeout 3 с; на сервере заданы statement_timeout 5 с, lock_timeout 2 с и idle_in_transaction_session_timeout 10 с. Каждый HTTP-запрос ограничен контекстом в 8 с.
Пароли хешируются Argon2id (m=19 MiB, t=2, p=1, соль 16 байт). Одновременно считается не больше 4 хешей, чтобы ограничить память. Для неизвестного username считается dummy-hash, поэтому ответ — тот же 401 за сопоставимое время. Токен состоит из 32 случайных байт (256 бит) в base64url. В БД и в ключах Valkey хранится только его SHA-256. Быстрый хеш здесь уместен: перебирать 256 бит бессмысленно, а у пароля энтропия низкая, поэтому для него нужен медленный KDF. expires_at = момент входа + SESSION_TTL_SECONDS; ни запросы, ни рестарт этот срок не продлевают.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test |
PASS: lab2 public API scenario |
evidence/smoke.txt |
| Контракт и структура | make check |
PASS |
evidence/check.txt |
| Полная валидация OpenAPI | make validate (venv с requirements-dev.txt) |
PASS: full OpenAPI 3.1 and JSON Schema validation |
evidence/validate.txt |
| gofmt, vet, build | gofmt -l, go vet ./..., go build ./... |
PASS | evidence/quality.txt |
| Docker build/run/health | make up, curl /health/* |
3 сервиса healthy, образ 7.5 MB, user=app | evidence/docker.txt |
| Рестарт API и всех хранилищ | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS; StartedAt у api/postgres/valkey до и после разный, volume тот же |
evidence/persistence.txt |
| Миграции с нуля и повторно | docker compose run --rm migrate |
migrations up to date, в schema_migrations одна строка |
evidence/migrations.txt |
| Durability COMMIT | SHOW на работающем стенде |
fsync=on, synchronous_commit=on, full_page_writes=on |
evidence/durability.txt |
Basic только на /auth/sessions, X-User-Id не даёт доступа |
smoke + student-tests | Basic на /users/me → 401; X-User-Id без Bearer → 401 |
evidence/smoke.txt |
| Пароль — KDF, токен не хранится | student-test | $argon2id$v=19$m=19456,t=2,p=1$…; сырого токена в БД нет |
evidence/student-tests.txt |
| Expiry при коротком TTL | student-test, api-short-ttl с TTL=2 |
через 2.5 с 401 и на :8081, и на основном API (кэш не продлил) | evidence/student-tests.txt |
| Logout и неверный пароль | student-tests | 204 → 401 → 401; неверный пароль и неизвестный пользователь получают одинаковый 401 за 37–47 мс | evidence/student-tests.txt |
| Гонка регистрации | 20 потоков с барьером | 1×201, 19×409, в БД одна строка | evidence/student-tests.txt |
| Rollback создания чата | неизвестный member | 400; строки чата нет, xact_rollback вырос |
evidence/student-tests.txt |
| Отказ Valkey / PostgreSQL | docker compose stop valkey / postgres |
см. раздел «Деградация» | evidence/student-tests.txt |
| Ограниченный пул | tests/load.py --concurrency 32 + pg_stat_activity |
10 соединений при 32 клиентах; 1110 RPS, 0 ошибок | evidence/load-32.json |
| Публичная нагрузка | python tests/load.py --duration 30 --concurrency 4 |
11 007 POST за 30 с, 366 RPS, 0 ошибок, p50/p95/p99 = 5.5/28.8/31.7 мс | evidence/load.json |
| EXPLAIN на ≥10 000 сообщений | трек 2, 110 025 сообщений | Index Scan using messages_chat_history_idx, 0.11 мс в одиночном прогоне (медиана 0.044 мс) |
evidence/track2/explain_production_deep_keyset.txt |
| Трек 2 | make track2 (--repeat 21) |
сравнение 4 индексов и 2 видов пагинации; backup → restore → сверка | evidence/track2/results.json |
Кэш Valkey (оценка 4)
Источник истины и роль Valkey
PostgreSQL — источник истины для пользователей, чатов, членства, сообщений и сессий. Valkey 8.0 — вспомогательный кэш сессий (cache-aside). Resolve сначала читает sess:<sha256(token)> из Valkey. При промахе или ошибке он идёт в PostgreSQL (sessions JOIN users WHERE revoked_at IS NULL AND expires_at > now()) и заполняет кэш на min(остаток TTL сессии, SESSION_CACHE_MAX_TTL_SECONDS). В записи кэша хранится expires_at, и приложение проверяет его даже при попадании, поэтому кэш никогда не продлевает сессию.
Реализация: internal/auth/sessions.go (логика) и internal/cache/valkey.go (клиент).
Конфигурация и отключение
SESSION_STORE=postgres— Valkey не подключается, сессии читаются только из PostgreSQL;SESSION_STORE=valkey(по умолчанию в compose) — PostgreSQL + кэш.SESSION_CACHE_MAX_TTL_SECONDS(по умолчанию 60) — максимальный TTL записи в кэше; ограничивает окно устаревания при сбое eviction во время logout.SESSION_TTL_SECONDS(3600) — срок жизни самой сессии;DB_MAX_CONNS(10) — размер пула.- Persistence Valkey выключена (
save "",appendonly no,infra/valkey/valkey.conf). Valkey не единственное хранилище сессий, поэтому после restart илиFLUSHALLкэш просто пуст, а сессии читаются из PostgreSQL. Проверено тестом: послеFLUSHALLтокен работает, кэш заполняется снова. maxmemory 64mb,volatile-ttl; пароль Valkey передаётся через Docker secret.
Инвалидация
Logout выполняет три шага: DEL в Valkey → UPDATE sessions SET revoked_at → повторный DEL. Второй DEL закрывает гонку с параллельным Resolve, который мог заново положить запись между первым DEL и COMMIT. Если Valkey недоступен, logout отвечает 503 ещё до изменения БД, иначе отозванный токен мог бы остаться в кэше. Худший случай — Valkey упал между COMMIT и вторым DEL — ограничен TTL записи, то есть не больше 60 с.
Деградация при потере зависимостей
- Valkey недоступен.
Resolveчитает из PostgreSQL, и запрос обслуживается. Таймауты клиента 0.3–0.5 с, повторов нет. Circuit breaker на 2 с: после первой ошибки следующие запросы сразу идут в БД, не дожидаясь таймаута. В тесте 8 запросов в режиме деградации заняли около 1.2 с суммарно. Readiness остаётся 200, регистрация, вход и отправка сообщений работают, logout возвращает 503. Послеstart valkeylogout снова отвечает 204. - PostgreSQL недоступен.
/health/live200,/health/ready503, бизнес-запросы 503. Без токена — 401. Неизвестный токен получает 503, а не 200: проверить его нельзя, доверять тоже. Послеstart postgresданные на месте. GET /health/readyпроверяет только PostgreSQL; Valkey некритичен.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Рестарт API + PostgreSQL + Valkey (volumes сохранены) | данные и действующая сессия сохраняются | PASS публичного теста, тот же токен, история без дублей | ~6.6 с на сценарий, потерь нет |
stop valkey |
обход кэша, logout отказывает безопасно | 2xx на чтение и запись, logout 503 | сразу после start, потерь нет |
FLUSHALL |
никто не разлогинен | токен работает, кэш перезаполнен | мгновенно |
stop postgres |
ready 503, бизнес 503, анонимы не проходят | так и есть | 2–5 с после start, подтверждённые данные целы |
Трек 2: план запроса и восстановление
Гипотеза. Для запроса истории WHERE chat_id=$1 AND (created_at,id) > cursor ORDER BY created_at, id LIMIT 51 составной индекс (chat_id, created_at, id) даёт постоянную стоимость для любого чата и любой глубины. Короткие индексы хороши только на части распределения размеров чатов. OFFSET-пагинация деградирует линейно при любом индексе.
Методика. scripts/track2/run_track2.py работает в отдельном контейнере pg-research со свежим volume; рабочая БД стенда не затрагивается. Схема берётся из того же файла миграции, что использует приложение.
- Данные. Детерминированный сид
scripts/track2/seed.sql(setseed, md5-UUID): 110 025 сообщений в 2 021 чате.- Один чат на 60 000 сообщений — 55 % всех данных.
- 20 чатов по 1 500 сообщений и 2 000 чатов по 1–19 (медиана 10).
- Средний текст — 421 символ, таблица — 64.7 MB.
- Перебор индексов. Вторичные индексы
messagesпересоздаются в 4 вариантах, после каждого —ANALYZE. - Чтение. Пять запросов, каждый через
EXPLAIN (ANALYZE, BUFFERS)21 раз (--repeat 21). Первый прогон — прогрев, в таблицу идёт медиана остальных 20. - Запись.
BEGIN; EXPLAIN (ANALYZE, WAL) INSERT 20 000; ROLLBACK, 10 прогонов, медиана 9. - Окружение. PostgreSQL 17.2 с настройками по умолчанию, Docker Desktop: 22 vCPU, 15.4 GiB.
Чтение (медиана, мс / буферы):
| Индекс | big: 1-я стр. | big: keyset после 55 000 | big: OFFSET 55 000 | medium (1 500) | small (≈10) |
|---|---|---|---|---|---|
| только PK | 11.87 / 6826 | 9.50 / 6768 | 48.70 / 6826 | 9.69 / 6738 | 9.67 / 6738 |
(chat_id) |
13.73 / 9900 | 9.32 / 3733 | 50.23 / 9900 | 0.42 / 129 | 0.042 / 5 |
(created_at, id) |
0.045 / 29 | 0.064 / 70 | 51.12 / 12977 | 0.37 / 1336 | 17.53 / 12889 |
(chat_id, created_at, id) |
0.041 / 8 | 0.044 / 9 | 54.47 / 16054 | 0.046 / 9 | 0.036 / 6 |
Запись (INSERT 20 000 строк в большой чат):
| Индекс | Время, мс | WAL, MB | Размер индекса, MB |
|---|---|---|---|
| только PK | 421 | 4.32 | 0 |
(chat_id) |
483 | 5.71 | 0.82 |
(created_at, id) |
498 | 5.95 | 4.27 |
(chat_id, created_at, id) |
503 | 6.27 | 6.20 |
Выводы.
- Production-индекс — единственный вариант, где все сценарии укладываются меньше чем в 0.05 мс и ≤ 10 буферов. Глубина страницы почти не влияет: 0.041 мс на первой странице и 0.044 мс после 55 000 сообщений. План —
Limit -> Index Scan using messages_chat_history_idx, без Sort. - Неравномерность размеров ломает короткие индексы.
(chat_id)хорош для маленьких чатов, но на большом даёт Bitmap Scan + Sort — примерно в 200 раз медленнее.(created_at, id)— наоборот: для чата из 10 сообщений планировщик уходит в Seq Scan (17.5 мс, 12 889 буферов).- На средних значениях этого не видно.
- OFFSET не спасает ни один индекс. Пропущенные 55 000 строк всё равно читаются, и keyset больше чем в 1000 раз быстрее (0.044 против 54.47 мс). Поэтому API использует курсор
(created_at, id). - Цена записи. Устойчиво измеряется объёмом WAL и размером индекса: составной индекс даёт +46 % WAL на вставку (6.27 против 4.32 MB на 20 000 строк) и весит 6.2 MB, около 10 % размера таблицы. Время пакетной вставки ненадёжно: в последнем прогоне оно росло вместе с числом индексов (421 → 503 мс, +20 %), но в предыдущих прогонах на той же машине порядок вариантов был другим, а абсолютные значения отличались почти вдвое (855–1010 мс). Поэтому разницу во времени я не считаю доказанной. Отдельный индекс
(chat_id)становится лишним: составной покрывает его как префикс.
Backup → восстановление в новое хранилище → сверка:
| Этап | Время, с |
|---|---|
pg_dump -Fc (дамп 6.9 MB) |
0.85 |
копирование дампа на хост (backups/, в .gitignore) |
0.22 |
новый контейнер pg-restore с пустым volume, копирование дампа внутрь |
0.69 |
pg_restore -j 4 --exit-on-error (данные, ключи, индексы) |
1.03 |
ANALYZE |
0.50 |
| Итого RTO после появления пустого сервера | 2.21 |
Сверка «источник на момент бэкапа» против восстановленной копии — 12 из 12 проверок совпали:
- количество строк во всех таблицах и
schema_migrations; - порядконезависимая контрольная сумма всех 110 025 сообщений;
- md5 счётчиков по каждому чату;
- md5 полной истории большого, среднего и маленького чата;
- md5 выборки из 200 сообщений;
- список индексов.
После восстановления запрос истории снова идёт через messages_chat_history_idx.
Граница потери данных. Сразу после дампа в источник записывается ещё одно сообщение, и в восстановленной копии его нет. pg_dump фиксирует снимок на момент старта, поэтому RPO равен интервалу между бэкапами. Уменьшить его можно только архивацией WAL (PITR) или репликой; в стенде это не реализовано.
Ограничения
- Logout зависит от Valkey. При недоступном Valkey возвращается 503 — сознательный выбор безопасности.
- Окно устаревания кэша. Если Valkey упал между COMMIT отзыва и вторым DEL, токен может приниматься до
SESSION_CACHE_MAX_TTL_SECONDS(60 с). - Кэшируются только сессии. Списки чатов и история всегда читаются из PostgreSQL; кэш истории потребовал бы инвалидации на каждую запись.
- Измерения трека 2 сделаны на тёплом кэше. Таблица помещается в
shared_buffers, замер в одном окружении и без параллельной нагрузки. Холодное чтение увеличит разрыв между Seq Scan и Index Scan. - Размер дампа занижен. Синтетический текст из повторов md5 хорошо сжимается: 64.7 MB → 6.9 MB. На реальных текстах дамп и время восстановления будут больше.
- Бэкап только логический (
pg_dump). Нет WAL-архива и расписания бэкапов. - Нет rate limiting на
POST /auth/sessions. Argon2id замедляет подбор пароля, но не заменяет лимит попыток. - HTTP без TLS. Допустимо только для локального изолированного стенда: Basic — это кодирование, а не шифрование.
- COMMIT гарантирует сохранность только на одном диске. При
fsync=onиsynchronous_commit=onответ 201 отправляется после записи WAL на диск volume; в Docker Desktop это виртуальный диск VM.