Files
mtusi2026lab2/REPORT.md
T

158 lines
22 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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` он пуст.