forked from mtusi2026/mtusi2026lab2
154 lines
20 KiB
Markdown
154 lines
20 KiB
Markdown
# Отчёт — лабораторная 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
|
||
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` он пуст.
|