# Отчёт — лабораторная 2 - Автор, группа: **Пинаев Олег Константинович, БПИ2302**. - Целевая оценка: **5, трек 1 — согласованность кэша**. - Коммиты: API `6fff618`, инфраструктура `1dc5f08`, проверки `6cccda1`, инструменты замеров `6866407`. Хеши измеренных модулей и образов сохранены в `evidence/`. - Источники: `README.md`, `contracts/`, документация PostgreSQL, Redis и Node.js; ИИ использовался для разработки, подготовки тестов, замеров и черновика отчёта. ## Запуск из чистого clone Docker с Compose, Python 3.9+ и `make`. Для локальной сборки и собственных тестов — Node.js **24.20.0**, pnpm **10.14.0**. ```sh cp .env.example .env docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build --wait make test PYTHON=python BASE_URL=http://127.0.0.1:8080 make test-persistence ACTION_SCRIPT=scripts/restart.sh PYTHON=python BASE_URL=http://127.0.0.1:8080 ``` `APP_PORT` задаёт опубликованный порт API; `POSTGRES_*` — настройки БД, `REDIS_PORT` — локальный порт Redis. Внутри Compose `DATABASE_URL` и `CACHE_URL` указывают на сервисы `postgres` и `redis`; локальные команды используют адреса из `.env`. `SESSION_TTL_SECONDS` — срок сессии, `CACHE_PREFIX` — пространство ключей; `SESSION_STORE=postgres`. Учебный пароль в `.env.example` следует заменить в локальном `.env`. ## Архитектура и решения NestJS/Fastify → PostgreSQL; Redis используется как кэш. Из lab1 сохранены пользователи, чаты, проверка членства, формат ошибок и cursor-пагинация. Состояние перенесено из памяти в таблицы `users`, `chats`, `chat_members`, `messages`, `sessions`; добавлены PK/FK, уникальность username и индексы. Создание чата, участников и увеличение эпох списков выполняются одной транзакцией. История упорядочена по `(created_at, id)` и имеет индекс `(chat_id, created_at, id)`; поздние страницы используют сравнение пары, без OFFSET. Пароли хранятся как **Argon2id** в PHC-формате: 19 MiB, 2 прохода, parallelism=1, соль 16 байт, ключ 32 байта. Basic применяется при входе; бизнес-запросы требуют opaque Bearer. В PostgreSQL хранится SHA-256 токена, срок истечения и признак отзыва. По умолчанию сессия действует 3600 секунд, logout отзывает её; PostgreSQL — источник истины. Redis хранит сущности на 300 секунд, страницы на 30 секунд. Ключ истории включает эпоху из БД и параметры страницы. Эпоха — сумма до **16 счётчиков** `chat_message_epochs`: запись атомарно увеличивает один из них и вставляет сообщение одним CTE. Это распределяет блокировки записей одного чата. Проверка сессии, публичный профиль, членство и эпоха для GET истории получаются одним SQL. Эпоха списка чатов хранится в `users.chats_epoch` и меняется вместе с созданием чата. После подтверждённой записи следующий GET получает новую эпоху и не использует старый ключ, даже если Redis пропустил инвалидацию. Задержавшаяся загрузка может заполнить только ключ старой эпохи; он исчезнет по TTL. При недоступном Redis API читает PostgreSQL; при недоступной БД возвращает 503. Ожидание подключения и SQL — 5 секунд, транзакция — 10 секунд; Redis-команда — 300 мс. Dockerfile разделяет сборку, миграции и runtime, запускает API от UID/GID 10001. ## Доказательства критериев | Проверка | Команда/сценарий | Результат | | --- | --- | --- | | Сборка, миграции, линтер | `docker compose build backend migrate`, `docker compose up -d backend`, `pnpm.cmd lint` | PASS, backend healthy; [проверки выбранной версии](evidence/epoch-variants-validation.json) | | Публичный smoke | `python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080` | PASS на текущем образе; [повторные проверки](evidence/checks-rerun.json) | | Полный перезапуск | `python -X utf8 scripts/test-persistence.py --scenario full-restart --base-url http://127.0.0.1:8080 --output evidence/cache-epochs-full-restart.json` | Сохранён PASS, 49,081 с на весь сценарий: те же контейнеры и volumes, данные и прежние токены сохранены; [JSON](evidence/cache-epochs-full-restart.json) | | Публичная сохранность | `python -X utf8 scripts/test-persistence.py --scenario public --base-url http://127.0.0.1:8080 --output evidence/persistence-public.json` | PASS на текущем образе, исходный HTTP-дедлайн 2 с; 34,502 с на сценарий. Все три сервиса перезапущены, контейнеры и volumes сохранены; [JSON](evidence/persistence-public.json) | | KDF, сессии, гонки и rollback | Проверки `test/passwords.mjs`, `test/persistence.mjs`, `test/resilience.mjs` через `node --test` в benchmark-контейнере | PASS на текущем образе, включая короткий TTL, logout, неверный пароль и отказы зависимостей; вместе с кэшем и пагинацией 15/15, [команда и результат](evidence/checks-rerun.json) | | Кэш и актуальные эпохи | `docker compose -f compose.yaml -f test/compose.benchmark.yaml run --rm --no-deps --pull never benchmark node --test test/cache-epochs.mjs test/cache.mjs` | PASS: 3 теста на текущей схеме, свежесть, конкурентная запись и rollback; [JSON](evidence/epoch-variants-validation.json) | | Индекс и пагинация | `node test/explain-history.mjs`, `pnpm test:pagination` | EXPLAIN на 60 000 сообщений; проверены границы timestamp, отсутствие пропусков/дублей и изоляция чатов; | Трек 1 | Конкурентный старый SELECT, пропущенная инвалидация, восстановление Redis со старыми ключами | Stale read воспроизведён до защиты; после — PASS. Hook `scripts/restart.sh` останавливает backend, PostgreSQL и Redis, запускает существующие контейнеры, ждёт готовности хранилищ и сохраняет volumes. `scripts/restart.cmd` вызывает его через Git Bash. Публичная проверка с HTTP-дедлайном 2 секунды прошла; проверки KDF, сессий, отказов, кэша и пагинации — 15/15 PASS. Запуск из чистого clone пока не проверен. ## Эксперименты и отказы Гипотеза трека 1: эпоха в PostgreSQL, изменяемая атомарно с сообщением, устраняет stale read при отказе Redis и запоздалом заполнении кэша. До защиты два сценария возвращали старую историю: восстановление Redis с прежними ключами и завершение старого SELECT после новой записи. После добавления эпох оба проходят. Первое сравнение: 10 000 сообщений, конкурентность 16, прогрев 3 с, чтение 10 с, 512 записей, три повтора. Медианы до / после: чтение — SQL/HTTP **1,412 / 2,011**, p95 **292,651 / 332,510 мс**; запись — SQL/HTTP **2,313 / 4**, p95 **216,752 / 894,578 мс**. Свежесть исправлена ценой дополнительных SQL и блокировки счётчика; Затем запись сведена к одному CTE, профиль включён в проверку сессии, проверки доступа объединены, общая эпоха разделена на 16 счётчиков. Матрица с меняющимся порядком, три повтора, 100 000 сообщений, 32 клиента, чтения по минуте и 4096 записей: | Вариант | Чтение, RPS | Запись, RPS | SQL/HTTP чтения | | --- | ---: | ---: | ---: | | Прежний CTE и один счётчик | 226,076 | 90,772 | 2,004 | | Профиль из JOIN сессии | 170,523 | 141,474 | 2,010 | | Единая проверка сессии/членства/эпохи | 246,934 | 117,777 | 1,006 | | Та же проверка и 16 счётчиков | **242,548** | **165,061** | **1,004** | Выбран последний вариант: близкая скорость чтения и лучшая средняя скорость записи в этой матрице. Отдельный контроль сравнивает выбранный код с теми же SQL-оптимизациями, но без Redis и чтения/обновления эпох. Три повтора, 100 000 сообщений, limit=50, конкурентность 32, прогрев 10 с, чтение 60 с, 4096 записей на повтор: | Метрика | Redis и эпохи | Без кэша и эпох | | --- | ---: | ---: | | Средний RPS чтения | **184,211** | 130,213 | | Средняя задержка чтения, мс | **173,466** | 245,478 | | Среднее p95 чтения, мс | **427,674** | 762,396 | | SQL/HTTP чтения | **1,009** | 2 | | Средний RPS записи | 120,634 | **128,279** | | Средняя задержка записи, мс | 264,880 | **249,032** | | Среднее p95 записи, мс | 666,798 | **556,831** | Чтение быстрее по среднему RPS на **41,5%**, запись медленнее на **6,0%**. Всего **81 693 успешных запроса**, ошибок нет. С Redis чтение быстрее во всех трёх повторах, но преимущество меняется от 5,7% до 120,2%; результаты записи пересекаются. Индекс исследован отдельно через `EXPLAIN (ANALYZE, BUFFERS)` на 60 000 сообщений. Медиана первой страницы — **28,718 → 0,094 мс** после индекса. На странице после 18 000 сообщений замена OR на сравнение пары снижает проверенные строки **18 051 → 51**, время **10,479 → 0,080 мс**. Результаты выборок совпадают; изменения экспериментальной схемы отменены ROLLBACK. [Планы](evidence/history-index-plans.txt). ## Ограничения и следующие шаги Один PostgreSQL и один Docker-host: проверена устойчивость к потере кэша, высокая доступность БД не реализована. Гарантия свежести относится к GET, начатому после подтверждения записи; чтения идут в основной PostgreSQL. Изменения данных в обход приложения должны увеличивать эпоху. После восстановления БД из старого backup нужно сменить `CACHE_PREFIX` или очистить Redis. Cache stampede отдельно не устранён. Нагрузка closed-loop; API, генератор и инструментация делят процесс, другие контейнеры делят host. CPU/RSS и p50/p95/p99 сохранены в сырых JSON; CPU PostgreSQL отдельно не измерялся. Средние p95 в таблице — среднее перцентилей повторов. Синтетические сессии обходят KDF; нагрузка измеряет первую страницу и запись в один чат. Последовательное сравнение с отключённым кэшем не позволяет точно отделить стоимость Redis от стоимости эпох.