forked from mtusi2026/mtusi2026lab2
238 lines
26 KiB
Markdown
238 lines
26 KiB
Markdown
# Отчёт — лабораторная 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/` не изменялись.
|