# Отчёт — лабораторная 2 - Автор, группа: Тюнин Илья БВТ2303 - Целевая оценка: 5, трек 1 («Согласованность кэша») - Commit/PR: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/33 ## Карта документации | Документ | Что содержит | | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Этот отчёт | Архитектура, схема данных, транзакции, аутентификация, политика кэша, методика и результаты трека 1, наблюдаемые проверки, ограничения. | | [`evidence/README.md`](evidence/README.md) | Индекс доказательств: что какой файл подтверждает и как всё регенерировать. | | [`evidence/level3-4-verification.md`](evidence/level3-4-verification.md) | Журнал проверок уровня 3/4 с наблюдаемым выводом команд и таблицей найденных дефектов. | | [`evidence/track1-cache-consistency.md`](evidence/track1-cache-consistency.md) | Трек 1: окружение, методика, числа по повторностям, сравнение, read-after-write, рестарт Redis, хеши артефактов. | | [`evidence/track1-explain.md`](evidence/track1-explain.md) | Тексты анализируемых SQL-запросов и `EXPLAIN (ANALYZE, BUFFERS)`. | | [`.github/pull_request_template.md`](.github/pull_request_template.md) | Краткая сводка работы, команды запуска, результаты проверок, чек-лист сдачи. | | [`tests/README.md`](tests/README.md) | Публичные проверки репозитория (`make check`, `make test`, persistence, load, TLS). | | [`docs/architecture/`](docs/architecture/README.md) | Граф модулей и провайдеров NestJS (`npm run graph`). | | [`bruno/README.md`](bruno/README.md) | Коллекция Bruno: ручные запросы на все эндпоинты, негативные кейсы и автосохранение токенов/ID между запросами. | | [`scripts/track1_cache_benchmark.py`](scripts/track1_cache_benchmark.py), [`scripts/track1_verify.py`](scripts/track1_verify.py) | Инструменты измерения трека 1 и проверки рестарта Redis. | | [`scripts/restart.sh`](scripts/restart.sh) | Хук перезапуска для `make test-persistence`. | ## Архитектура и роли компонентов ```text 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 — один запрос владельца, остальные ждут и попадают в кэш. ## Воспроизводимый запуск ```sh 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//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-запросов истории. Команды: ```sh 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:*`: ```json { "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/level3-4-verification.md); методика и по-повторностные числа трека — [`evidence/track1-cache-consistency.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`](evidence/track1-explain.md). ## Команды проверок ```sh 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:@:5432/messenger \ REDIS_URL=redis://: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 ` и возвращают `{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/` не изменялись.