# Отчёт — лабораторная 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](https://www.postgresql.org/docs/current/tutorial-transactions.html), [EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html), [PREPARE](https://www.postgresql.org/docs/current/sql-prepare.html), [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html)), [Valkey persistence](https://valkey.io/topics/persistence/), [Valkey eviction](https://valkey.io/topics/lru-cache/), [RFC 7617](https://www.rfc-editor.org/info/rfc7617/), 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 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` он пуст.