24 KiB
Отчёт — лабораторная 2
- Автор, группа: Тюнин Илья БВТ2303
- Целевая оценка: 5, трек 1 («Согласованность кэша»)
- Commit/PR: mtusi2026/mtusi2026lab2#33
Карта документации
| Документ | Что содержит |
|---|---|
| Этот отчёт | Архитектура, схема данных, транзакции, аутентификация, политика кэша, методика и результаты трека 1, наблюдаемые проверки, ограничения. |
evidence/README.md |
Индекс доказательств: что какой файл подтверждает и как всё регенерировать. |
evidence/level3-4-verification.md |
Журнал проверок уровня 3/4 с наблюдаемым выводом команд и таблицей найденных дефектов. |
evidence/track1-cache-consistency.md |
Трек 1: окружение, методика, числа по повторностям, сравнение, read-after-write, рестарт Redis, хеши артефактов. |
evidence/track1-explain.md |
Тексты анализируемых SQL-запросов и EXPLAIN (ANALYZE, BUFFERS). |
.github/pull_request_template.md |
Краткая сводка работы, команды запуска, результаты проверок, чек-лист сдачи. |
tests/README.md |
Публичные проверки репозитория (make check, make test, persistence, load, TLS). |
docs/architecture/ |
Граф модулей и провайдеров NestJS (npm run graph). |
bruno/README.md |
Коллекция Bruno: ручные запросы на все эндпоинты, негативные кейсы и автосохранение токенов/ID между запросами. |
scripts/track1_cache_benchmark.py, scripts/track1_verify.py |
Инструменты измерения трека 1 и проверки рестарта Redis. |
scripts/restart.sh |
Хук перезапуска для make test-persistence. |
Архитектура и роли компонентов
Client
-> Fastify/Nest API
AuthController (Basic -> opaque Bearer session)
CurrentUserGuard (Bearer -> Redis session -> PostgreSQL user)
UsersController / ChatsController / MessagesController
-> UsersRepository -> pg.Pool -> PostgreSQL
-> ChatsRepository -> pg.Pool -> PostgreSQL (transaction)
-> MessagesRepository-> pg.Pool -> PostgreSQL (transaction)
-> MessagesCacheService -> Redis versioned message page
-> SessionRepository -> Redis session:{token} (AOF)
-> MetricsService -> token-gated /internal/metrics
Источник истины:
- PostgreSQL — пользователи, чаты, membership, сообщения.
- Redis — действующие безопасные сессии (AOF persistence) и производный кэш истории.
- Удаление Redis cache не теряет подтверждённые данные: они восстанавливаются из PostgreSQL.
- Отказ Redis не даёт анонимного доступа: сессионный путь возвращает ограниченную 503.
- Отказ PostgreSQL не убивает процесс API и даёт ограниченную 503.
Схема данных и миграции
001_initial.sql:
users(id uuid pk, username unique, display_name, password_hash, created_at);chats(id uuid pk, title, created_at, message_version bigint);chat_members(chat_id, user_id)— composite PK, cascade FK;messages(id, chat_id, sender_id, text, created_at), FK на chat и на member;messages_chat_created_id_idx (chat_id, created_at, id);chat_members_user_chat_idx (user_id, chat_id).
002_timestamp_precision.sql приводит created_at к timestamptz(3), чтобы значения совпадали с millisecond timestamps JavaScript. Без этого следующая страница keyset-пагинации повторяла последнее сообщение предыдущей.
Migration runner сам находит NNN_*.sql, сортирует по имени и применяет каждую незаписанную миграцию в отдельной транзакции через schema_migrations. Повторный запуск — no-op; сиды не выполняются.
Транзакционные границы
Создание чата: валидация member_ids через ANY($1::uuid[]), вставка chats, вставка всех chat_members, commit либо полный rollback. Создание сообщения: проверка membership, вставка messages, инкремент chats.message_version, commit либо rollback.
Аутентификация и доступ
POST /api/v1/users— регистрация с паролем 12–128 code points; Argon2id.POST /api/v1/auth/sessions— только Basic, UTF-8, разделение по первому:; тело не принимается.- Токен — 32 случайных байта (Base64URL), серверная сессия в Redis с TTL.
- Бизнес-endpoint — только Bearer; истёкший/отозванный/неизвестный токен → 401 +
WWW-Authenticate: Bearer realm="messenger". X-User-Idне аутентифицирует и не подменяет владельца сессии.DELETE /api/v1/auth/sessions/current→ 204 без тела; повтор с тем же токеном → 401.- Ответы 401 содержат корректный challenge: Basic для создания сессии, Bearer для остальных.
Политика кэша и трек 1
Ключ страницы: messages:{chat_id}:v{message_version}:c{cursor|start}:l{limit}.
Protected режим: exact-page lock lock:{cache_key} (SET NX PX + compare-owner Lua unlock), ограниченные повторы, повторная проверка кэша, запись результата владельцем, best-effort запись кэша и fallback в PostgreSQL при недоступности Redis. Любой commit сообщения увеличивает message_version, поэтому старые страницы становятся недостижимыми.
Naive режим — управляемый baseline без распределённой блокировки; CACHE_MISS_DELAY_MS расширяет окно гонки.
Гипотеза: при одном холодном ключе и N конкурентных читателях naive порождает около N SQL-запросов истории, protected — один запрос владельца, остальные ждут и попадают в кэш.
Воспроизводимый запуск
cp .env.example .env
password=$(openssl rand -hex 32)
sed -i "s/^POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$password/" .env
sed -i "s|^DATABASE_URL=.*|DATABASE_URL=postgresql://messenger:$password@postgres:5432/messenger|" .env
sed -i "s/^METRICS_TOKEN=.*/METRICS_TOKEN=$(openssl rand -hex 16)/" .env
unset password
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -fsS http://localhost:8080/health/ready
postgres:16.4-alpinec named volumepostgres-data;redis:7.4.2-alpine, AOF (appendonly yes,appendfsync everysec), named volumeredis-data;- одноразовый сервис
migrate; apiс healthcheck/health/ready.
Конфигурация и секреты
Все параметры, включая POSTGRES_PASSWORD, DATABASE_URL и REDIS_URL, задаются в .env
(вне Git). Это сознательный выбор для локального синтетического стенда:
.envуже игнорируется.gitignore; отдельных файлов секретов и лишнего маппинга не требуется;- значения видны через
docker inspect//proc/<pid>/environ— для учебного стенда с синтетическими данными это допустимо, для production нужен внешний secret store; postgres-dataхранит пароль, заданный при первой инициализации: сменаPOSTGRES_PASSWORDсама по себе его не меняет, поэтомуDATABASE_URLдолжен указывать на пароль этого volume;- файловый вариант (
DATABASE_URL_FILE,REDIS_URL_FILE, docker secrets/Swarm) поддержан в конфигурации как опциональная альтернатива и описан в.env.example.
scripts/restart.sh перезапускает postgres redis api и ждёт готовности, не удаляя volumes и не выполняя FLUSHALL.
Track 1: методика и результаты
Методика: режим кэша и задержка промаха задаются переменными окружения при пересоздании контейнера (CACHE_MODE, CACHE_MISS_DELAY_MS; shell-значение перекрывает .env). Каждая повторность использует новый чат (холодный ключ), поэтому FLUSHALL не нужен. Барьер синхронизирует старт конкурентных GET, метрики сбрасываются через POST /internal/metrics/reset.
Важно: CACHE_MISS_DELAY_MS действует только в naive-пути (пауза между промахом и запросом в PostgreSQL) и намеренно расширяет окно гонки. Protected-путь задержку не использует, поэтому замеренная разница p50/p95 между режимами включает эти 75 мс и не является «честным» сравнением скорости; независимая от задержки метрика — число SQL-запросов истории.
Команды:
printf '%s' "$METRICS_TOKEN" > /tmp/track1-metrics-token
CACHE_MODE=naive CACHE_MISS_DELAY_MS=75 docker compose --env-file .env up -d api
python3 scripts/track1_cache_benchmark.py --base-url http://localhost:8080 --mode naive \
--concurrency 32 --repetitions 5 --metrics-token-file /tmp/track1-metrics-token \
--runtime-version node=25.7.0 --runtime-version postgres=16.4 --runtime-version redis=7.4.2 \
--output evidence/track1-raw/naive.json
CACHE_MODE=protected docker compose --env-file .env up -d api
python3 scripts/track1_cache_benchmark.py --base-url http://localhost:8080 --mode protected \
--concurrency 32 --repetitions 5 --metrics-token-file /tmp/track1-metrics-token \
--runtime-version node=25.7.0 --runtime-version postgres=16.4 --runtime-version redis=7.4.2 \
--output evidence/track1-raw/protected.json
python3 scripts/track1_verify.py --summary \
--naive-raw evidence/track1-raw/naive.json --protected-raw evidence/track1-raw/protected.json \
--output evidence/track1-cache-consistency.md
Наблюдено (concurrency 32, 5 повторностей, 160 успешных GET в каждом режиме, ошибок 0):
| Режим | messages.history SQL |
Cache misses | Cache hits | Lock waits |
|---|---|---|---|---|
| naive | 160 | 160 | 0 | 0 |
| protected | 5 | 46 | 155 | 41 |
Снижение числа SQL-запросов истории: 160 → 5 (96.9 %). Латентность успешных запросов: naive p50 ≈ 82–117 ms, protected p50 ≈ 28–44 ms (сырые значения в evidence/track1-raw/). Эта разница не является чистым сравнением скорости: в naive-путь искусственно добавлена пауза CACHE_MISS_DELAY_MS=75 (задержка применяется только в naive), тогда как protected её не использует. Независимая от задержки метрика — число SQL-запросов истории.
Read-after-write (protected, вторая действующая сессия): asserted=true, stale_observed=false.
Рестарт Redis с сохранением AOF-volume и последующим удалением только messages:*:
{
"restart_redis": true,
"same_token_users_me": true,
"history_equal": true,
"cache_eviction": { "requested": true, "message_keys_deleted": 9 }
}
Уровень 3/4: наблюдаемые проверки
| Проверка | Команда/сценарий | Наблюдаемый результат |
|---|---|---|
| Публичный smoke | make test |
PASS: lab2 public API scenario |
| Сохранность через полный рестарт | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session |
| Интеграционный набор (реальные PG/Redis) | npx vitest run --config vitest.config.e2e.ts |
7 passed, 1 gated |
То же с SESSION_TTL_SECONDS=2 |
тот же набор с TTL=2 | 8 passed (включая expiry → 401) |
| Гонка одинакового username | набор: два одновременных POST + select count(*) |
201 и 409; в users ровно 1 строка (гарантия — unique index users_username_key, ошибка 23505 → 409) |
| Rollback чата с неизвестным участником | HTTP 400 + select count(*) |
400; строк в chats — 0 |
| Индекс истории | EXPLAIN (ANALYZE, BUFFERS) на 10 002 строках |
Index Scan using messages_chat_created_id_idx для первой страницы (0.040 мс) и для keyset-продолжения (0.048 мс) |
| Отказ Redis | stop redis | /health/ready 503, /users/me 503 (анонимного доступа нет), после старта — 200 |
| Отказ PostgreSQL | stop postgres | /health/ready 503, /users/me 503; процесс API жив; после старта — 200 с тем же токеном |
| Логин/логаут/подмена | набор + X-User-Id |
Basic на бизнес-endpoint 401, X-User-Id не меняет владельца, replay после logout 401 |
| Ручной клиент (Bruno) | bru run -r --env local ... из bruno/ |
28 запросов, 56 проверок — все зелёные (включая негативные и метрики) |
Отдельно исправлен реальный дефект: при падении PostgreSQL процесс API завершался из-за необработанного события error у idle-клиента пула. Добавлен обработчик pool.on('error'), а ошибки доступности БД в фильтре отображаются в ограниченную 503 вместо 500.
Полный журнал проверок с наблюдаемым выводом команд — evidence/level3-4-verification.md; методика и по-повторностные числа трека — evidence/track1-cache-consistency.md.
EXPLAIN (фрагмент): Index Scan using messages_chat_created_id_idx on messages, первая страница actual time=0.020..0.028 ms / Execution Time: 0.040 ms, keyset-продолжение Index Cond: ((chat_id = ...) AND (ROW(created_at, id) > ROW(...))) / Execution Time: 0.048 ms — полного скана истории нет, предикат продолжения уходит в индекс. Тексты проанализированных запросов и подготовка данных — evidence/track1-explain.md.
Команды проверок
make check
make validate
(cd app && npm run build && npm test && npx tsc --noEmit)
make test BASE_URL=http://localhost:8080
make test-persistence ACTION_SCRIPT=scripts/restart.sh
(cd app && API_BASE_URL=http://localhost:8080 \
DATABASE_URL=postgresql://messenger:<password>@<pg-host>:5432/messenger \
REDIS_URL=redis://<redis-host>:6379 npx vitest run --config ./vitest.config.e2e.ts)
Примечание: набор для интеграционных тестов читает API_BASE_URL, потому что Vitest сам устанавливает process.env.BASE_URL.
Наблюдаемость отказов
GET /internal/metrics и POST /internal/metrics/reset открыты только с Authorization: Bearer <METRICS_TOKEN> и возвращают {counters, latency_ms} без секретов и SQL-текста. Счётчики, по которым видно деградацию (а не «тихое» проглатывание ошибок):
| Счётчик | Когда растёт |
|---|---|
cache_hit / cache_miss |
попадание/промах страницы |
cache_lock_wait / cache_lock_timeout |
ожидание владельца lock; владелец не успел за отведённые повторы |
cache_fallback |
Redis недоступен на чтении/lock/повторном чтении, ответ отдан из PostgreSQL |
cache_write_error / cache_unlock_error |
не удалось записать страницу или снять lock (ответ не ломается) |
cache_corrupt_entry |
повреждённая запись кэша трактуется как промах и перезаписывается |
database.pool_error / database.rollback_error |
обрыв idle-клиента пула; ошибка ROLLBACK (исходная ошибка операции сохраняется) |
redis.error |
ошибка соединения/reconnect Redis |
Те же события дополнительно пишутся в лог уровнем warn с контекстом, поэтому один сбойный запрос уже видно без разбора дампов.
Ограничения и границы
- Метрики локальны процессу API и сбрасываются при его рестарте; PostgreSQL и Redis не затрагиваются.
- Измерения выполнены на одном локальном хосте (closed-loop, конкуренция 32, 5 повторностей); это не production-пропускная способность и не распределённая телеметрия.
redis-data— источник истины сессий: удаление volume осознанно разлогинивает пользователей; сохранённый AOF — проверенная граница durability.CACHE_MODE=naiveпредназначен только для эксперимента и не должен включаться в штатном профиле.- Файлы
evidence/track1-raw/*.jsonигнорируются git (содержат локальные идентификаторы); в репозитории хранится санитизированная сводка. - Публичные
contracts/иtests/не изменялись.