22 KiB
Отчёт — лабораторная 2
- Автор, группа: Нурлыгаянова Екатерина, БП2302
- Целевая оценка: 5, трек 1 «Согласованность кэша»
- Commit/PR: ветка
solution/bpi2302-nurlygayanova, базовый commit65003b6; хеш итогового commit и ссылка на PR — после публикации - Библиотеки:
echo/v44.16.2,pgx/v55.7.6,go-redis/v99.7.3,x/crypto/argon20.57.0,x/sync/singleflight0.23.0,google/uuid1.6.0, миграции —goose3.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
# если 127.0.0.1:8080 занят другим процессом: sh scripts/failures-tests.sh 'http://[::1]:8080'
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..6}): 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). 00005 — экранирование U+0000 в текстовых полях, 00006 — cache_invalidations (долг инвалидации кэша, см. трек 1).
Транзакции. Создание чата — одна транзакция 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 |
6 миграций на пустом 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 |
Read-after-write: DEL не удался, затем рестарт API |
TestFailures (pause кэша → 201 → restart api), TestReadAfterWrite_InvalidationFailedThenRestart |
сообщение с 201 есть в первом же чтении после рестарта; без cache_invalidations — отсутствует до 30 с |
evidence/failures.txt, evidence/integration-tests.txt |
Эксперименты и отказы
Трек 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. Ошибка кэша не превращает подтверждённую запись в 503.
Неудачный DEL и рестарт API. Если DEL hc:ver:{chat} не прошёл, старая версия и её страницы остаются в Valkey. Раньше долг помнила только память процесса: после рестарта API кэш отдавал страницу без подтверждённого сообщения до истечения TTL (30 с). Теперь до ответа 201 долг записывается в PostgreSQL — INSERT … ON CONFLICT DO UPDATE в cache_invalidations (chat_id, gen). Чат с долгом читается мимо кэша; повтор каждые 200 мс делает DEL, затем DELETE … WHERE gen = $2. При старте API долги загружаются из PostgreSQL, и пока загрузка не удалась, мимо кэша читаются все чаты. gen берётся из общей последовательности, а запись в памяти получает новый номер при каждом сбое: повтор, начатый до нового сбоя, не снимает его ни в памяти, ни в таблице (TestRetryDoesNotDropNewerFailure, TestPendingInvalidationCAS). Цена — один upsert в PostgreSQL только на запись, у которой не прошёл DEL; в штатном режиме лишних запросов нет.
Методика. 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.
Отказы
| Воздействие | Ожидаем | Наблюдали | Восстановление / потери |
|---|---|---|---|
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) |
отложенные инвалидации выполнены до первого чтения из кэша |
pause кэша → запись 201 → restart api → unpause |
сообщение видно сразу | 3 чтения после рестарта, сообщение в каждом; в логе invalidation deferred gen=… → pending invalidations loaded chats=1 |
долг из cache_invalidations погашен после unpause |
Ограничения и следующие шаги
- Один Docker-host, без реплик PostgreSQL/Valkey: потеря host или volume — потеря данных и сессий.
appendfsync everysec: при аварии теряется до ~1 с входов/logout; отозванная сессия может «воскреснуть» доexpires_at.alwaysубирает окно ценой задержки.ListChatsиспользует$2 IS NULL OR …; при большом числе чатов на пользователя запрос стоит разделить, как для истории.valkey-cacheполучает анонимный volume из образа, но с--save "" --appendonly noон пуст.