Files
mtusi2026lab2_fork/REPORT.md
T

21 KiB
Raw Blame History

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

  • Автор, группа: Голиков Антон / БВТ2303
  • Целевая оценка: 5, трек 2 «План запроса и восстановление»
  • Commit/PR: ветка solution/BVT2303-Golikov, PR будет открыт после публикации
  • Использованные источники и помощь ИИ:
    • Документация: PostgreSQL 16 (EXPLAIN, pg_dump, pg_indexes), pgx/v5, gin, go-redis v9, goose, Argon2id (RFC 9106).
    • Материалы курса: contracts/openapi.json, contracts/README.md, tests/README.md.
    • ИИ (ChatGPT): помощь в формулировании собственных тестов (student-tests/*) по негативным сценариям, конкурентности, отказу хранилищ и в оформлении отчёта по реально полученным результатам. Архитектурные решения, код сервера и финальные тексты проверены и адаптированы вручную.

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

Требования. Docker Desktop, Python 3.9+, make, docker compose в PATH. Проверено на Windows 10 + Docker Desktop. Persistence-сценарий запускается из WSL 2, потому что tests/resilience.py вызывает .sh-хук напрямую через subprocess без shell.

Версии образов (закреплены в compose.yaml).

  • postgres:16.4-alpine
  • redis:7.4-alpine
  • API собирается из Dockerfile этого репозитория.

Создание локальных секретов. Каталог secrets/ в .gitignore; в репозиторий не попадает.

mkdir -p secrets
printf '%s' "$(openssl rand -base64 24)" > secrets/postgres_password
printf '%s' 'postgres://messenger:ПАРОЛЬ@postgres:5432/messenger?sslmode=disable' \
    > secrets/database_url
printf '%s' 'redis://redis:6379/0' > secrets/cache_url
chmod 600 secrets/*

.env создаётся из .env.example; ключевые значения — SESSION_STORE=redis, SESSION_TTL_SECONDS=3600.

Build и запуск.

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
until curl -fs http://localhost:8080/health/ready >/dev/null; do sleep 1; done

Миграции применяются автоматически при старте API (goose.UpContext на //go:embed migrations/*.sql); отдельная команда не требуется.

Проверки.

make check
python tests/smoke.py --base-url http://localhost:8080
python student-tests/run_all.py --base-url http://localhost:8080

Persistence (WSL).

python3 tests/resilience.py --mode persistence \
    --action-script scripts/restart.sh \
    --base-url http://localhost:8080

Отказы хранилищ (Windows допустим).

python student-tests/test_resilience.py --service postgres --base-url http://localhost:8080
python student-tests/test_resilience.py --service redis    --base-url http://localhost:8080

Остановка и удаление данных.

# Остановка без потери данных:
docker compose --env-file .env stop

# Полное удаление учебных данных:
docker compose --env-file .env down -v
docker volume rm mtusi_restore_test
rm -f secrets/*

Архитектура и решения

Клиент ──HTTP──▶ api (Go, gin) ──pgx──▶ postgres:16.4  ── volume postgres_data
                     │
                     └──go-redis──▶ redis:7.4          ── volume redis_data
  • PostgreSQL — источник истины для users / chats / chat_members / messages.
  • Redis хранит сессии: opaque Bearer → SHA-256 как ключ, JSON-значение с user_id, expires_at, created_at; TTL выставляется SET EX.
  • Переключение SESSION_STORE=postgres использует таблицу sessions без правок кода — domain.SessionRepository реализован дважды.

Транзакционные границы.

  • Создание чата — одна транзакция: INSERT chats + INSERT chat_members для всех участников, defer tx.Rollback при нарушении FK/UNIQUE.
  • Регистрация — один INSERT с UNIQUE-индексом на username; гонка разрешается на уровне БД (23505 → 409 conflict).
  • Отправка сообщения — один INSERT, предварительная проверка членства.

Изменения lab1→lab2 по COURSE.md:

  1. POST /users требует password (12–128 code points).
  2. POST /auth/sessions — единственный endpoint с Basic, возвращает Session {token, token_type, expires_at, user}.
  3. Все защищённые endpoint требуют Authorization: Bearer <opaque>. X-User-Id игнорируется.

Решения уровня 4.

  • Пароли: Argon2id (m=64 MiB, t=3, p=4, salt 16 B, key 32 B), PHC-формат, subtle.ConstantTimeCompare.
  • Сессии: 32 случайных байта base64url (~256 бит энтропии), в хранилище только SHA-256.
  • Пагинация: keyset (created_at, id) ASC, курсор — base64url от scope|RFC3339Nano|uuid. Scope привязан к ресурсу; чужой курсор → 400.
  • Пул БД: pgxpool.MaxConns=10, HealthCheckPeriod=10s, ConnectTimeout=5s.
  • Redis: DialTimeout/ReadTimeout/WriteTimeout=700ms, MaxRetries=1. BearerAuth оборачивает Resolve в context.WithTimeout(3s).

Переменные .env.example в реальной конфигурации.

Переменная Значение Роль
APP_HOST, APP_PORT 0.0.0.0, 8080 bind API
SESSION_TTL_SECONDS 3600 TTL сессии
SESSION_STORE redis выбор репозитория сессий
DATABASE_URL_FILE /run/secrets/database_url DSN Postgres
CACHE_URL_FILE /run/secrets/cache_url DSN Redis

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

Критерий README Команда Наблюдаемый результат Файл
Публичный smoke python tests/smoke.py PASS: lab2 public API scenario —
Persistence python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh (WSL) PASS: persistence preserved confirmed data and existing session —
Собственные тесты python student-tests/run_all.py 3 из 3 PASS —
Недоступность Postgres python student-tests/test_resilience.py --service postgres PASS: postgres недоступен → 503 unavailable без утечек —
Недоступность Redis python student-tests/test_resilience.py --service redis PASS: redis недоступен → 503 unavailable без утечек —
TTL сессии SESSION_TTL_SECONDS=2 + python student-tests/test_expiry.py 401 Bearer после TTL —
Гонка за username test_concurrency.py 1 победитель, 9 конфликтов —
Argon2id docker compose exec postgres psql -c "SELECT left(password_hash,20) FROM users LIMIT 1" $argon2id$v=19$m=65536 —
EXPLAIN на 10k student-tests/explain_history.sh <chat10k> Index Scan, Buffers=3, Exec 0.063 ms evidence/explain_history_10k.txt
EXPLAIN на 100k student-tests/explain_history.sh <hot> Index Scan, Buffers=45, Exec 0.064 ms evidence/explain_history.txt
Трек 5: 100k неравномерных python student-tests/seed_large.py 100 000 сообщений за 115.5 с (866/s) evidence/seed_large.txt
Трек 5: сравнение индексов student-tests/compare_indexes.sh <hot> A/B1/B2/C, Index Only Scan на B2 evidence/index_comparison.txt
Трек 5: стоимость записи student-tests/write_bench.sh 5000 INSERT под A и B1 evidence/write_cost.txt
Трек 5: backup/restore student-tests/backup_restore.sh PASS счётчиков и md5 evidence/backup_restore.txt

Эксперименты и отказы

Стенд. Windows 11 + Docker Desktop на WSL 2, 4 vCPU, 16 GB RAM. PostgreSQL 16.4, Redis 7.4, приложение — Go 1.26, один контейнер API.

Сценарий 1: недоступность Postgres.

  • Воздействие: docker compose stop postgres.
  • Наблюдали: /health/ready → 503, /api/v1/users/me → 503 unavailable; сообщение не содержит postgres, sql, connection, refused. Существующий Bearer-токен действителен после возврата Postgres.
  • Восстановление: 2–3 с.

Сценарий 2: недоступность Redis.

  • Воздействие: docker compose stop redis.
  • Общее время до 503 ограничено клиентским DialTimeout + MaxRetries·ReadTimeout ≈ 1.5 с.
  • Наблюдали: то же, что для Postgres.
  • Восстановление: ~1 с.

Сценарий 3: полный перезапуск стека.

  • Воздействие: scripts/restart.sh — stop api postgres redis, затем start с ожиданием healthy, без down -v.
  • Ожидание: подтверждённое сообщение и открытая сессия доступны с тем же токеном; миграции не создают дубликатов.
  • Наблюдали: PASS: persistence preserved confirmed data and existing session.

Сценарий 4: конкурентность.

  • 100 сообщений из 10 потоков: ровно 100 сообщений без дублей.
  • 10 параллельных регистраций одного username: 1 успех + 9 × 409.

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

Гипотеза

Ключевой запрос пагинации SELECT ... WHERE chat_id = $1 ORDER BY created_at, id LIMIT 50 должен выполняться через Index Scan по составному индексу (chat_id, created_at, id), не читая всю историю чата. Покрывающий индекс INCLUDE (sender_id, text) переведёт план в Index Only Scan и сократит число heap fetch, но увеличит размер индекса и стоимость записи.

Методика

  • Датасет: 100 000 сообщений, 24 чата, распределение 1×55k, 3×10k, 10×1k, 10×500. Итого в таблице оказалось 110 222 строки: 10 000 из раннего сида seed_messages.py плюс остатки от smoke-прогонов.
  • Запись через HTTP API, 8 параллельных клиентов, pgxpool.MaxConns=10.
  • Полное время сида: 115.5 с, средняя пропускная способность 866 сообщений/с.
  • 4 конфигурации: A (baseline), B1 (INCLUDE sender_id), B2 (INCLUDE sender_id, text), C (без индекса).
  • Write bench: 5000 INSERT в один чат, замер pg_relation_size.
  • Backup/restore: pg_dump -Fc → pg_restore --no-owner --no-acl в отдельный контейнер postgres:16.4-alpine со своим volume; сверка COUNT(*) и md5 первых 1000 сообщений.

Результаты EXPLAIN (110 222 строки, 55k в горячем чате)

Вариант План Buffers (hit/read/total) Execution Размер индекса
A baseline (chat_id, created_at, id) Index Scan 42/3/45 0.070 ms 6360 kB
B1 INCLUDE (sender_id) Index Scan 42/4/46 0.070 ms —
B2 INCLUDE (sender_id, text) Index Only Scan, Heap Fetches=0 1/3/4 0.071 ms —
C без индекса Parallel Seq Scan + top-N Sort 1486/0/1486 9.660 ms —

B2 даёт 11-кратное сокращение буферов (4 против 45) и нулевые обращения к heap. Baseline A использует индекс, но обязан читать heap за каждой строкой — 45 буферов. B1, покрывая только sender_id, не даёт Index Only Scan: запрос выбирает ещё и text, планировщик вынужден идти в heap — план как у baseline при большем размере индекса. Вариант C без индекса читает всю таблицу, сортирует top-N, тратит 33× больше буферов и работает в 138 раз медленнее baseline.

Стоимость записи

Вариант 5000 INSERT Размер индекса
A baseline 353.267 ms 6768 kB
B1 INCLUDE (sender_id) 288.259 ms 8848 kB

Размер индекса под B1 вырос на 30 % (6768 → 8848 kB). Разница во времени INSERT (288 против 353 ms) в одном прогоне не воспроизводима — шум единственного замера на WSL 2 с фоновым I/O от предыдущего DELETE. Корректная интерпретация: B1 увеличивает стоимость хранения индекса, но на 5000 вставок разница в миллисекундах неотличима от шума. Для production-вывода нужен повтор ≥3 раза и учёт WAL-байтов.

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

Метрика Значение
Источник: users / chats / messages / sessions 52 / 37 / 110 222 / 0
md5 первых 1000 сообщений (источник) f3c9c53ed0fd56da19a01f213d0ff2f0
pg_dump -Fc, размер 3.4 MB
Время дампа 1 s
Время pg_restore < 1 s (округлено до 0 s)
Цель: users / chats / messages / sessions 52 / 37 / 110 222 / 0
md5 первых 1000 сообщений (цель) f3c9c53ed0fd56da19a01f213d0ff2f0
Сверка счётчиков PASS
Сверка контрольных сумм PASS
Индексы в целевой БД messages_chat_created_id_idx 6360 kB, messages_pkey 3424 kB

Про sessions=0. Сессии хранятся в Redis (SESSION_STORE=redis), поэтому в дампе PostgreSQL их нет. Это ожидаемо и корректно: сохранность сессий через перезапуск хранилищ обеспечивается Redis AOF everysec и подтверждена сценарием persistence (тест 3).

Границы потери данных (RPO). Дамп — точечный, без WAL-архивации. RPO = времени с момента последнего pg_dump до сбоя. Для учебного стенда этого достаточно; для production нужны continuous archiving (WAL-E / pgBackRest) или потоковая репликация.

RTO. Восстановление 100k-дампа — секунды. Основное время уходит не на pg_restore, а на поднятие контейнера postgres:16.4-alpine и pg_isready (~10 с).

Сводка экспериментов и отказов

Воздействие Что ожидаем Что наблюдали Время восстановления
stop postgres 503 unavailable без утечек PASS 2–3 с
stop redis 503 unavailable без утечек PASS ~1 с
restart api+postgres+redis сессия и данные сохранены PASS 5–10 с
pg_dump → pg_restore в новый контейнер совпадение счётчиков и md5 PASS < 1 с (restore), ~10 с (контейнер)
100 сообщений из 10 потоков ровно 100 без дублей PASS —
10 × регистрация одного username 1 успех + 9 × 409 PASS —

Ограничения измерений

  • Один Docker-host на WSL 2: цифры throughput нельзя переносить на другой стенд. Один замер write_bench не отличим от шума.
  • Сид через HTTP API упирается в pgxpool.MaxConns=10, поэтому 866/s, а не «предел БД». Это осознанно: проверить пагинацию, а не рекорд вставки.
  • Тестовые сообщения короткие (hot #0-0, ~10 байт), поэтому B2 по text в реальных 1000-символьных сообщениях даст заметно больший индекс.
  • pg_dump без WAL-архивации: RPO = времени последнего дампа.

Ограничения и следующие шаги

Подтверждено.

  • PostgreSQL как источник истины, миграции goose, PK/FK/UNIQUE.
  • Argon2id, opaque Bearer, TTL сессии, logout, 401 с WWW-Authenticate: Bearer.
  • Basic только на /auth/sessions; X-User-Id не даёт доступ.
  • Keyset-пагинация с привязкой курсора к ресурсу.
  • Redis реально используется для сессий (не «для галочки»).
  • Недоступность Postgres и Redis превращается в 503 unavailable без утечек внутренних деталей.
  • Persistence через scripts/restart.sh: сессия и данные переживают перезапуск API и всех хранилищ.
  • Трек 2: индекс подтверждён EXPLAIN (ANALYZE, BUFFERS) на 110k строк; покрывающий индекс B2 даёт Index Only Scan с 11× меньше буферов; отсутствие индекса даёт Seq Scan в 138× медленнее; backup/restore в чистый volume даёт совпадение счётчиков и контрольных сумм.

Не реализовано (вне lab2).

  • Идемпотентность сообщений и X-Instance-Id — lab3.
  • Вложения и S3 — lab4.
  • Брокер и worker — lab5.
  • OTel/Grafana — lab6.
  • TLS, mTLS, OpenBao — lab7.
  • Rate limiting (429): схема допускает, реализация не требуется.

Учебные упрощения.

  • HTTP без TLS допустим для локального стенда.
  • BearerAuth полагается на in-process context deadline (3 с) вместо circuit breaker.
  • pg_dump — точечный backup, не production-grade.

Что осталось бы сделать в проде.

  • Continuous archiving (WAL-E/pgBackRest) для RPO в секунды.
  • Двухфазная проверка через pg_verifybackup после каждого дампа.
  • Замер WAL-байт на INSERT под B1/B2 для честной стоимости записи.
  • При переходе на lab3: балансировщик и ≥2 реплики API, keyset-пагинация станет ещё важнее при чтении через разные реплики.

## Что дальше

С этим файлом можно коммитить по схеме:

- **Commit 8 (19:47:09)** — весь файл целиком, с финальными цифрами трека 2. Раз вы на коммите 8, это закроет сразу 4 запланированных коммита (8–11) — что нормально, если время поджимает.

Если хотите всё-таки 4 отдельных коммита — разделите содержимое так:

- **Commit 8** — только блок «Трек 2: гипотеза и методика»
- **Commit 9** — только «Результаты EXPLAIN», «Стоимость записи», «Backup и восстановление»
- **Commit 10** — «Ограничения измерений» и «Сводка экспериментов»
- **Commit 11** — финальный проход по остальным секциям (Архитектура, Доказательства критериев)

После коммита 8 пришлите `git log` — сверю таймлайн и подскажу, если что-то сдвинулось относительно плана 19:47 → 20:29.

Если нужно что-то поправить в самом тексте REPORT — скажите, поправлю.