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

238 lines
26 KiB
Markdown
Raw Permalink 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
- Автор, группа: Тюнин Илья БВТ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/<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-запросов истории.
Команды:
```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:<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/` не изменялись.