Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Blame History

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

  • Автор, группа: Нурлыгаянова Екатерина, БП2302
  • Целевая оценка: 5, трек 1 «Согласованность кэша»
  • Commit/PR: ветка solution/bpi2302-nurlygayanova, базовый commit 65003b6; хеш итогового commit и ссылка на PR — после публикации
  • Библиотеки: echo/v4 4.16.2, pgx/v5 5.7.6, go-redis/v9 9.7.3, x/crypto/argon2 0.57.0, x/sync/singleflight 0.23.0, google/uuid 1.6.0, миграции — goose 3.26.0.
  • Источники: документация PostgreSQL (transactions, EXPLAIN, PREPARE, pg_stat_statements), Valkey persistence, Valkey eviction, RFC 7617, OWASP Password Storage Cheat Sheet.
  • Помощь ИИ: Claude Code (Anthropic) — проверка по рубрике, кэш истории и эксперимент трека 1 (internal/cache, cmd/cachebench, scripts/track1*), тесты, скрипты доказательств, черновик отчёта. Результаты получены реальными прогонами.

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

Образы: сборка golang:1.26.10-alpine3.24, runtime alpine:3.24.3, postgres:17.6-alpine, valkey/valkey:8.1.3-alpine (×2). Нужны Docker + Compose v2.20+, POSIX sh, Python 3.9+ (публичные тесты), Go 1.26 (собственные тесты). Лимиты CPU/RAM контейнерам не заданы.

sh scripts/init-secrets.sh        # secrets/* (в .gitignore); существующие файлы не перезаписывает
cp .env.example .env              # при занятом 5432: POSTGRES_PORT=55432 в .env
docker compose --env-file .env up -d --build --wait   # migrate (goose) отрабатывает до api
until curl -fsS http://localhost:8080/health/ready >/dev/null; do sleep 1; done

make check && make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh

# собственные проверки (против запущенного стенда, данные синтетические)
cd app && go test ./...                       # unit/HTTP; интеграционные и e2e пропускаются
sh scripts/integration-tests.sh               # гонка username, rollback, кэш (PostgreSQL + valkey-cache)
sh scripts/failures-tests.sh                  # уровень 4: пароль, logout, expiry, отказы → evidence/failures.txt
sh scripts/explain.sh                         # EXPLAIN → evidence/explain.txt
sh scripts/migrations-check.sh                # миграции с нуля и повторно → evidence/migrations.txt
sh scripts/persistence-evidence.sh            # persistence + StartedAt до/после → evidence/persistence.txt
REPEATS=3 DURATION=30s sh scripts/track1.sh   # трек 1 → evidence/track1/

Остановка без потери данных: docker compose --env-file .env stop (или down — volumes остаются). Удаление учебных данных (необратимо): docker compose --env-file .env down -v (volumes mtusi-lab2_pgdata, mtusi-lab2_valkeydata), rm -r secrets.

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

клиент ─HTTP─▶ api (Go) ─pgx pool≤10─▶ postgres      источник истины: users, chats, chat_members, messages (volume pgdata)
                  ├──────pool≤20─────▶ valkey        сессии: AOF everysec, noeviction (volume valkeydata)
                  └──────pool≤20─────▶ valkey-cache  кэш истории: без persistence, allkeys-lru, не критичен
migrate (goose, одноразовый) ─▶ postgres до старта api
Service Health Volume Порт Credentials
api /health/ready = ping PostgreSQL + Valkey сессий — 8080 secrets database_url, cache_url, history_cache_url
postgres pg_isready pgdata 127.0.0.1:5432 POSTGRES_PASSWORD_FILE
valkey valkey-cli ping valkeydata 127.0.0.1:6379 --requirepass из secret
valkey-cache valkey-cli ping (не в readiness) нет 127.0.0.1:6380 --requirepass из secret
migrate service_completed_successfully — — secret database_url

Из lab1 перенесены роутер, middleware (request id, recover, логи, лимиты), валидация, формат ошибок, keyset-курсоры. Изменено: хранилище — PostgreSQL; Basic только на POST /auth/sessions, далее opaque Bearer; X-User-Id не читается.

Схема (migrations/0000{1..4}): users (UNIQUE username, CHECK формата), chats, chat_members (PK (chat_id, user_id), индекс (user_id, chat_id)), messages (FK (chat_id, sender_id) → chat_members — отправитель обязан быть участником на уровне БД; индекс (chat_id, created_at, id) под keyset).

Транзакции. Создание чата — одна транзакция INSERT chats + INSERT chat_members SELECT unnest(...); неизвестный участник → FK → rollback → 400. Регистрация — один INSERT, гонку решает UNIQUE (→ 409). Сообщение — один INSERT, членство проверяет FK. COMMIT с synchronous_commit=on переживает падение процесса PostgreSQL, но не потерю диска.

Сессии. Токен — 256 бит crypto/rand; в Valkey хранится только его SHA-256: SET NX EXAT expires_at. Срок абсолютный — рестарт его не продлевает; в коде срок проверяется повторно. Logout — DEL. Valkey — единственное хранилище сессий, поэтому AOF everysec (штатный рестарт — без потерь, падение — до ~1 с) и noeviction.

Пароли — Argon2id (m=19 MiB, t=2, p=1), PHC-строка, ≤4 хеширования одновременно; для неизвестного username считается dummy-hash. Медленный солёный KDF защищает от перебора утёкших хешей; быстрый SHA-256 подходит токену, у которого полная энтропия.

Пул и таймауты: PostgreSQL ≤10 соединений, запрос ≤3 с; Valkey сессий ≤20, 1 с; кэш ≤20, 200 мс, breaker 1 с; HTTP ≤64 запроса одновременно (429), тело ≤64 KiB (413). Все SQL параметризованы, ошибки БД → доменные без деталей; недоступность зависимостей → 503.

Конкурентные вставки. created_at = now() начала транзакции; транзакции могут закоммититься не в порядке created_at, поэтому читатель, прошедший позицию курсора, может не увидеть более раннее по времени сообщение. Повторов при обходе неизменной истории нет.

Переменная .env.example Назначение
APP_HOST, APP_PORT, APP_ENV адрес HTTP 0.0.0.0:8080; поле env в логах
SESSION_TTL_SECONDS TTL сессии, 3600 (переопределяется из shell для теста expiry)
DATABASE_URL_FILE, CACHE_URL_FILE DSN PostgreSQL и URL Valkey сессий из secrets
SESSION_STORE только valkey, иное — ошибка конфигурации
API_PUBLISH_PORT, POSTGRES_PORT, VALKEY_PORT, VALKEY_CACHE_PORT хост-порты compose
HISTORY_CACHE, HISTORY_CACHE_TTL_SECONDS режим кэша off/naive/safe (по умолчанию safe), TTL страницы 30 с
HISTORY_CACHE_FILL_DELAY_MS fault injection эксперимента, в работе 0
необязательные DB_*, CACHE_*, APP_* значения по умолчанию в config/config.go

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

Критерий Команда Результат Файл
Уровень 3
Публичный smoke make test PASS: lab2 public API scenario evidence/checks.txt
Данные и сессии переживают рестарт API и всех хранилищ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt всех 4 контейнеров новый, volumes те же evidence/persistence.txt
PK/FK, UNIQUE username, миграции с нуля и повторно scripts/migrations-check.sh 4 миграции на пустом volume; повтор — no migrations to run, строк столько же evidence/migrations.txt
Атомарное создание чата TestCreateChatRollback неизвестный участник → 400, таблицы без изменений evidence/integration-tests.txt
Basic только на вход, Bearer на остальном, X-User-Id не даёт доступ TestFailures, TestAuth_BearerRequired X-User-Id → 401; Basic на /users/me → 401 evidence/failures.txt
Expiry и logout TestFailures TTL=2: 200 → 401; logout 204 → 401 evidence/failures.txt
Password KDF TestHashVerify $argon2id$v=19$m=19456,t=2,p=1$… evidence/checks.txt
Secrets/volumes вне Git git check-ignore -v .env secrets/x игнорируются; .dockerignore исключает их из build context evidence/checks.txt
Уровень 4
Valkey для сессий с TTL и persistence compose.yaml, persistence-тест, TestFailures токен валиден после рестарта и stop/start Valkey evidence/persistence.txt, evidence/failures.txt
Параметризованные запросы, пул, таймауты internal/store/db, config только $n; MaxConns=10; запрос ≤3 с исходники
Гонка регистрации username TestUsernameRace 20 параллельных: 1 created, 19 conflict, 1 строка evidence/integration-tests.txt
Индекс истории, EXPLAIN на ≥10 000 scripts/explain.sh 54 682 сообщения; страница после 10 000 — Index Scan, 5 буферов, ~0,2 мс; OFFSET — 135 буферов; без индекса — Seq Scan + Sort, 986 буферов, ~10 мс evidence/explain.txt
Неверный пароль TestFailures одинаковый 401 + WWW-Authenticate: Basic для пароля и username evidence/failures.txt
Valkey недоступен TestFailures: stop valkey Bearer → 503, без токена → 401, вход → 503, ready → 503 evidence/failures.txt
PostgreSQL недоступен TestFailures: stop postgres запись → 503 без деталей, ready → 503 evidence/failures.txt
Кэш недоступен — обход TestFailures, TestCacheDown_Bypass ready 200, запись 201, чтение из PostgreSQL evidence/failures.txt
Уровень 5, трек 1
Stale read и stampede воспроизведены scripts/track1.sh, TestReadAfterWrite_FillRace, TestStampede_SQLCount naive: stale reads во всех 6 прогонах; stampede 50 промахов → 50 SQL (safe — 1) evidence/track1/summary.md, evidence/integration-tests.txt
SQL и latency до/после scripts/track1.sh SQL на чтение 2,014 → 0,0034; p95 28,5 → 14,4 мс evidence/track1/summary.md
Read-after-write cachebench safe: 0 нарушений на 826 552 проверках evidence/track1/*.json
Восстановление после рестарта кэша track1.sh: stop/start и pause/unpause под нагрузкой 0 ошибок, 0 stale evidence/track1/summary.md

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

Трек 1. Согласованность кэша истории

Гипотеза. Классический cache-aside (naive: прочитать БД → положить в кэш; после COMMIT удалить ключи) на горячем чате (1) нарушает read-after-write — читатель кладёт в кэш снимок, прочитанный до COMMIT, уже после удаления ключей; (2) даёт stampede. Версионные ключи + singleflight + lock (safe) устраняют оба эффекта.

Защита (app/internal/cache/history.go). Страница лежит под hc:page:{chat}:{ver}:…, ver — случайные 64 бита. Запись: COMMIT → DEL hc:ver:{chat} → 201. Снимок, прочитанный до COMMIT, попадает только под старую версию, которую никто не прочитает. Версия случайная, поэтому её потеря (LRU, рестарт) — только промах. Stampede: singleflight в процессе + SET NX PX 500 lock между репликами. Доступ проверяется до выдачи страницы. При отказе кэша — breaker и чтение из PostgreSQL; несработавший DEL повторяется каждые 200 мс, чат до этого читается мимо кэша. Ошибка кэша не превращает подтверждённую запись в 503.

Методика. REPEATS=3 DURATION=30s sh scripts/track1.sh: для каждого режима API пересоздаётся с нужным HISTORY_CACHE и FILL_DELAY (0 или 20 мс — расширенное окно гонки), кэш очищается. cachebench в той же Docker-сети создаёт чат со 150 сообщениями; 3 с прогрева, 30 с замера. 32 читателя в closed loop опрашивают хвост истории; 2 писателя раз в 100 мс пишут и сразу читают (RAW). Каждое полное чтение хвоста сверяется со всеми сообщениями, получившими 201 до его начала (stale read). SQL — pg_stat_statements, hit/miss — INFO stats, CPU/RAM — docker stats.

Стенд. Windows 10 Pro, Docker Desktop 27.2.0 / WSL2, 12 vCPU / 1.9 GiB, генератор на том же host. В БД ~69 000 сообщений.

Результаты (медианы трёх 30-секундных прогонов; нарушения — сумма):

Режим Чтений/с p50 / p95 / p99, мс SQL на чтение Hit RAW нарушений Stale reads Ошибки
off 2 267 12,0 / 28,5 / 39,6 2,014 — 0 / 1 358 0 / 204 418 0
naive 2 712 9,9 / 25,5 / 36,0 0,010 99,2 % 712 / 1 379 128 731 / 248 013 0
safe 4 631 5,9 / 14,4 / 20,2 0,0034 97,8 % 0 / 1 417 0 / 428 275 0
naive + 20 мс 4 813 4,7 / 23,3 / 30,0 0,053 97,3 % 3 / 1 282 13 484 / 361 325 0
safe + 20 мс 4 456 5,3 / 23,5 / 29,8 0,0030 97,5 % 0 / 1 344 0 / 398 277 0

CPU postgres: off 175 % → naive 8 % → safe 3 %; RAM api ≤74 MiB, postgres ≤71 MiB (подробно — evidence/track1/summary.md).

Выводы. Stale read воспроизведён во всех 6 прогонах naive, в том числе без fault injection; в safe — 0 на 826 552 проверках. В safe SQL страницы ≈ числу записей (одно заполнение на инвалидацию при 32 читателях); в naive при окне 20 мс — в 19 раз больше. Относительно off кэш снимает ~99,8 % SQL чтения, пропускная способность ×2, p95 почти вдвое ниже. Цена — +1 обращение к Valkey на чтение и +1 DEL на запись.

Ограничения. Один host, closed-loop генератор (coordinated omission): абсолютные RPS не переносимы, устойчивы SQL на чтение и наличие/отсутствие нарушений. Доказана одна реплика API. Не закрыто окно: DEL не удался, а другая реплика (lab3) видит кэш — устаревание ≤ TTL страницы 30 с.

Отказы

Воздействие Ожидаем Наблюдали Восстановление / потери
scripts/restart.sh данные и токен на месте persistence PASS, все 4 контейнера перезапущены потерь нет
stop valkey 503, не анонимный доступ Bearer 503, без токена 401, вход 503, ready 503 ready через 0,1–0,5 с; сессии сохранены (AOF)
stop postgres ограниченный 503 запись 503, ready 503, без деталей БД ready через 0,5–0,7 с; запись 201 тем же токеном
stop valkey-cache обход кэша ready 200, запись 201, чтение из PostgreSQL без ошибок; кэш холодный
stop/start кэша под нагрузкой 0 ошибок, 0 stale 153 522 чтения, 0 ошибок, 0 stale без потерь
pause/unpause кэша под нагрузкой 0 stale при сохранённых старых страницах 160 911 чтений, 0 ошибок, 0 stale; p95 записи 211 мс (таймаут DEL) отложенные инвалидации выполнены до первого чтения из кэша

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

  • Один Docker-host, без реплик PostgreSQL/Valkey: потеря host или volume — потеря данных и сессий.
  • appendfsync everysec: при аварии теряется до ~1 с входов/logout; отозванная сессия может «воскреснуть» до expires_at. always убирает окно ценой задержки.
  • Кэш: окно ≤30 с при неудачном DEL и нескольких репликах или падении API до повтора. Полностью закрыла бы его версия в PostgreSQL в той же транзакции — не реализовано.
  • ListChats использует $2 IS NULL OR …; при большом числе чатов на пользователя запрос стоит разделить, как для истории.
  • valkey-cache получает анонимный volume из образа, но с --save "" --appendonly no он пуст.