Files
2026-10-10 02:13:35 +03:00

26 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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.
  • Оба отказа проверяются автоматически (make test-dependencies): остановка и старт контейнеров, ограниченные ошибки без деталей драйвера, восстановление сессии и подтверждённых данных.

Схема данных и миграции

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 для остальных.

Валидация входа

  • Обязательные строки не состоят только из пробельных символов (contracts/README.md): у display_name и password есть проверка \S, поэтому пароль из 12 пробелов — 400, а не созданная учётная запись.
  • Курсор истории — непрозрачная строка, но сервер проверяет формат (YYYY-MM-DDTHH:MM:SS(.f)Z, диапазоны часов/минут/секунд) и календарь через date-fns parseISO + isValid. Несуществующие даты (2026-02-31, 2025-02-29) и 24:00:00 отклоняются как 400 invalid_request, потому что Date.parse молча переносит их на другой день и такое значение падало бы уже в PostgreSQL (500). Разобранный инстант нормализуется к каноническим миллисекундам.
  • Длины строк считаются в Unicode code points, как в JSON Schema и контракте: собственный декоратор @CodePointLength (app/src/common/validation/) заменяет @Length, который мерил UTF-16-единицы. Поэтому display_name и title — 1–100, пароль — 12–128, текст сообщения — 1–4000 code points независимо от наличия эмодзи вне BMP; подсчёт идёт по code points, а не по графемным кластерам (комбинирующие символы считаются отдельно, как в JSON Schema).
  • Неизвестные поля и неверные типы — 400; лимит истории — целое 1–100.

Политика кэша и трек 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-alpine c named volume postgres-data;
  • redis:7.4.2-alpine, AOF (appendonly yes, appendfsync everysec), named volume redis-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 9 passed, 1 gated
То же с SESSION_TTL_SECONDS=2 тот же набор с TTL=2 10 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 (автоматически) make test-dependencies /health/live 200; /health/ready и бизнес-запросы — ограниченная 503; анонимный запрос 401; после старта сессия и данные живы
Отказ PostgreSQL (автоматически) make test-dependencies /health/live 200; все бизнес-запросы и регистрация — 503 без утечки деталей; процесс жив; после старта запись работает
Логин/логаут/подмена набор + X-User-Id Basic на бизнес-endpoint 401, X-User-Id не меняет владельца, replay после logout 401
Ручной клиент (Bruno) bru run -r --env local ... из bruno/ 29 запросов, 58 проверок — все зелёные (включая негативные и метрики)

Отдельно исправлен реальный дефект: при падении 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
make test-dependencies
(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/ не изменялись.