26 KiB
Отчёт — лабораторная 2
- Автор, группа: Антонов Егор, БПИ2301
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявляется
- Commit/PR: ветка
solution/БПИ2301-Antonov; ссылка на PR — после публикации - Использованные источники, библиотеки и помощь ИИ: документация NestJS, Fastify, Prisma, PostgreSQL (transactions, EXPLAIN, row comparison), Redis (persistence,
SET NX PX), OWASP Password Storage Cheat Sheet, RFC 7617. Библиотеки:@nestjs/*10,@prisma/client/prisma6.1.0,argon20.41.1,ioredis5.4.1,class-validator,jest+supertest. ИИ-ассистент использовался как парный программист: генерация кода, тестов и отчёта по моим решениям (стек, модель данных, роль Redis, границы транзакций) с последующим ревью и переработкой; все проверки воспроизведены мной на своём стенде.
Запуск из чистого clone
На хосте нужен только Docker (Engine + Compose v2); python/node/make/sh на хосте не требуются, команды одинаковы в PowerShell и bash. Проверено: Docker 29.3.1, Compose v5.1.1, Docker Desktop (WSL2), 12 vCPU, 8 GiB RAM.
| Компонент | Версия |
|---|---|
| API runtime | node:20.17.0-slim + openssl, NestJS 10 / Fastify, Prisma 6.1.0 |
| PostgreSQL | postgres:17.2-alpine |
| Redis | redis:7.4.1-alpine |
| secrets-init | alpine:3.20.3 |
| tools (проверки) | docker:27.3.1-cli + python3, make, git |
# 1. Запуск: secrets-init → postgres, redis → migrate → api; ждёт healthcheck
docker compose up -d --build --wait
# 2. Публичные проверки (внутри контейнера tools, BASE_URL=http://api:8080)
docker compose run --rm --build tools make check
docker compose run --rm tools make test
docker compose run --rm tools make test-persistence ACTION_SCRIPT=scripts/restart.sh
# 3. Собственные тесты: отдельные postgres (tmpfs) и redis, миграции в globalSetup
docker compose -f compose.test.yaml run --rm --build tests
docker compose -f compose.test.yaml down
# 4. Все доказательства в evidence/*.txt одной командой
docker compose run --rm tools sh scripts/collect-evidence.sh
# Безопасная остановка (данные и секреты сохраняются)
docker compose stop # или: docker compose down
# Намеренное удаление учебных данных и сгенерированных секретов
docker compose down -v
.envнеобязателен: вcompose.yamlте же значения по умолчанию. Для своих значений:cp .env.example .env, затемdocker compose --env-file .env up -d --build --wait.- Секреты создаёт one-shot сервис
secrets-initпри первом запуске: случайные пароли PostgreSQL и Redis (24 байта из/dev/urandom) и строки подключения кладутся в именованный volumesecrets, который монтируется read-only в/run/secrets. Уже созданные пароли не перезаписываются. Действий оператора не требуется; секреты не попадают в Git, образы и логи. - Миграции: сервис
migrateвыполняетprisma migrate deployпри каждомup. Повторный запуск безопасен — применённые миграции записаны в_prisma_migrations(docker compose run --rm migrate→No pending migrations to apply). - API опубликован только на
127.0.0.1:8080; PostgreSQL и Redis наружу не публикуются. - Swagger UI: http://localhost:8080/docs (документ — http://localhost:8080/docs-json). Это обязательный контракт
contracts/openapi.jsonбез изменений, который при старте API дополняется в памяти пошаговой инструкцией и 57 именованными примерами запросов и ответов (src/docs/examples.ts); Authorize поддерживает basicAuth (вход) и bearerAuth (остальное). Все примеры проверяются по JSON Schema контракта вtest/docs.e2e-spec.ts, поэтому документация не может разойтись с контрактом.
Архитектура и решения
client ──HTTP──▶ api (127.0.0.1:8080) ──SQL (pool 10)──▶ postgres ── volume pgdata
│
└──read-through кэш сессий──▶ redis (без persistence)
secrets-init ──▶ volume secrets (/run/secrets, ro) ◀── postgres, redis, migrate, api
migrate ── prisma migrate deploy ──▶ postgres (api стартует после успешного migrate)
| Роль | Service | Health/readiness | Volume | Порт | Credentials |
|---|---|---|---|---|---|
| API | api |
Docker HEALTHCHECK /health/live; /health/ready = SELECT 1 |
— (stateless) | 127.0.0.1:8080 |
DATABASE_URL_FILE, CACHE_URL_FILE |
| БД | postgres |
pg_isready |
pgdata |
внутренняя сеть | POSTGRES_PASSWORD_FILE |
| Кэш сессий | redis |
redis-cli ping |
— | внутренняя сеть | requirepass из /run/secrets/redis_password |
| Bootstrap | secrets-init, migrate |
exit 0 | secrets |
— | — |
Модель данных (prisma/schema.prisma, миграции prisma/migrations/*):
| Таблица | Ключи и ограничения | Индексы → запрос |
|---|---|---|
users |
PK id; UNIQUE(username); CHECK формата username и непустого display_name; password_hash (Argon2id) |
users_username_key → вход, гонка регистрации |
chats |
PK id; CHECK непустого title |
— |
chat_members |
PK (chat_id, user_id); FK → chats (CASCADE), FK → users |
PK → проверка членства; (user_id) → список чатов пользователя |
messages |
PK id; FK → chats, FK → users (sender); text ≤ 4000 символов |
(chat_id, created_at, id) → история (keyset) |
sessions |
PK token_hash (sha256 токена); FK → users (CASCADE); expires_at |
PK → проверка Bearer |
CHECK-ограничения дописаны в SQL миграции вручную (Prisma их не описывает); prisma migrate diff схемы с БД — No difference detected.
Транзакционные границы:
- Создание чата — явный
prisma.$transaction:INSERT chats+INSERT chat_members. Неизвестный участник нарушает FK (P2003) → откат всей транзакции →400. - Регистрация — один
INSERT; гонка одинакового username решаетсяUNIQUE(P2002 →409), а не проверкой «select, затем insert». Хеш пароля считается до транзакции. - Сообщение — один
INSERT; проверка членства — отдельным чтением перед ним (удаления участников в API нет, поэтому окно гонки не влияет на результат). - Logout —
DELETEизsessions(источник истины), затем tombstone в Redis; если записать tombstone нельзя, кэш перестаёт считаться достоверным до очистки (см. «Отказ Redis»).
Время и порядок. created_at назначает PostgreSQL (DEFAULT CURRENT_TIMESTAMP, timestamptz(3)) — один источник часов для всех реплик API. Миллисекундная точность выбрана, чтобы значение в JS Date совпадало с хранимым и keyset-сравнение не теряло строки. Пагинация: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT limit+1; курсор — base64url {chatId, id}, сервер находит created_at якоря по PK; курсор другого чата или несуществующей записи → 400. Список чатов использует тот же приём. Keyset в Prisma написан через $queryRaw с параметрами (tagged template), потому что штатный cursor Prisma строит OR-условие, которое не превращается в Index Cond.
Аутентификация. Пароль — Argon2id (m=19 MiB, t=2, p=1, параметры OWASP), 12–128 code points, UTF-8, двоеточие допустимо (Basic делится по первому :). Для неизвестного username проверяется фиктивный хеш, чтобы время ответа не раскрывало существование пользователя; ответ 401 одинаковый. Токен — 32 байта crypto.randomBytes (256 бит) в base64url; в БД хранится только sha256 токена: для случайного 256-битного значения быстрый хеш достаточен, а утечка таблицы не даёт рабочих токенов. Guard принимает только Authorization: Bearer; X-User-Id не читается вовсе.
Сессии и Redis (уровень 4).
- Источник истины — таблица
sessionsв PostgreSQL, поэтому сессии переживают рестарт любых контейнеров, а TTL не продлевается рестартом (хранитсяexpires_at). - Роль Redis — read-through кэш проверки токена: ключ
session:v1:<sha256>, значение — пользователь иexpires_at. Промах → чтение из PostgreSQL →SET NX PX. - Expiry кэша —
min(остаток сессии, 60 с): запись в кэше никогда не переживает сессию. - Инвалидация — logout удаляет строку и пишет tombstone
revokedна 60 с; заполнение кэша идёт сNX, поэтому конкурентный запрос, прочитавший сессию до logout, не перезапишет tombstone. - Persistence Redis выключена (
--save '' --appendonly no),maxmemory 64mb allkeys-lru: после flush/restart кэш пуст и прогревается из PostgreSQL. - Отказ Redis — любая ошибка = промах, запрос идёт в PostgreSQL (
enableOfflineQueue: false,commandTimeout 200 ms,connectTimeout 1 s). Redis не входит в/health/ready. - Восстановление после разрыва — после обрыва соединения или ошибки любой команды кэш помечается недостоверным: чтения и записи в него не выполняются, соединение переустанавливается, и при каждом подключении сначала выполняется
FLUSHDB, только затем кэш снова используется (src/cache/cache.service.ts). Поэтому запись, пережившая разрыв (logout во время разрыва не смог записать tombstone), не может вернуть доступ отозванному токену. Очистка безопасна, так как Redis — только кэш. - Отказ PostgreSQL — ошибки подключения Prisma (
PrismaClientInitializationError, P1001/P1002/P1008/P1017/P2024) →503 unavailableбез деталей. Аноним иX-User-Idполучают401; неизвестный токен —503(его нельзя проверить, значит нельзя и доверять); токен из кэша проходит аутентификацию, но бизнес-запрос получает503.
Пул и таймауты (параметры строки подключения Prisma в secrets/database_url): connection_limit=10, pool_timeout=5 с, connect_timeout=5 с, socket_timeout=10 с, statement_timeout=5000 мс (через options=-c statement_timeout=5000), application_name=api. Все запросы параметризованы (Prisma Client и $queryRaw tagged template).
Перенесено из lab1: NestJS + Fastify, DTO-валидация (class-validator, длина в code points, запрет пробельных строк), формат ошибок и X-Request-Id, курсоры base64url, Dockerfile (multi-stage, non-root, HEALTHCHECK), 47 e2e-тестов. Изменено: in-memory StoreService заменён на Prisma/PostgreSQL, сервисы стали асинхронными, гонки решаются ограничениями БД, а не однопоточностью; X-User-Id заменён на Basic → Bearer; /health/ready проверяет БД; в Dockerfile добавлены stages test, migrate, prod-deps; тесты переведены на Bearer и PostgreSQL.
Соответствие .env.example:
| Переменная | Где используется |
|---|---|
APP_HOST, APP_PORT |
API слушает 0.0.0.0:8080; APP_PORT в .env — опубликованный порт на 127.0.0.1 |
APP_ENV |
передаётся в API, поведение не меняет |
SESSION_TTL_SECONDS |
TTL сессии, по умолчанию 3600 |
DATABASE_URL_FILE |
/run/secrets/database_url (задано в compose); в тестах — DATABASE_URL |
SESSION_STORE=postgres |
фиксировано: источник истины сессий — PostgreSQL |
CACHE_URL_FILE |
/run/secrets/cache_url (задано в compose); в тестах — CACHE_URL; без него API работает без кэша |
Доказательства критериев
Все файлы собраны docker compose run --rm tools sh scripts/collect-evidence.sh; в заголовке каждого — дата и commit.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | docker compose run --rm tools make test |
PASS: lab2 public API scenario |
evidence/smoke.txt |
| Структура контракта | make check |
PASS: offline skeleton structure |
evidence/smoke.txt |
| 3: данные и действующие сессии переживают рестарт API и хранилищ | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session; started= у postgres, redis, api изменился до/после |
evidence/persistence.txt |
3: PostgreSQL, PK/FK, UNIQUE(username), миграции с нуля |
prisma/migrations/*, docker compose up на пустом volume |
2 миграции применяются к пустой БД; migrate diff — без расхождений |
evidence/tests.txt (globalSetup), evidence/container.txt |
| 3: повторный запуск миграций без дублей | docker compose run --rm migrate |
No pending migrations to apply |
evidence/container.txt (migrate Exited (0) при каждом up) |
| 3: атомарное создание чата | тест «откатывает создание чата целиком…» | 400, в БД 0 чатов с этим title и 0 строк chat_members |
evidence/tests.txt |
3: Basic только на POST /auth/sessions, остальное — Bearer; X-User-Id не даёт доступ |
smoke + test/auth.e2e-spec.ts |
Basic на /users/me → 401 Bearer realm; X-User-Id → 401; рядом с Bearer игнорируется |
evidence/smoke.txt, evidence/tests.txt |
| 3: срок жизни и отзыв сессии | smoke (logout), probe.py expiry 2 на API с SESSION_TTL_SECONDS=2 |
logout 204 → 401 → повтор 401; 200 сразу, 401 через 3 с |
evidence/failures.txt §4, evidence/tests.txt |
| 3: password KDF | тест «хранит пароль как Argon2id-хеш» | password_hash начинается с $argon2id$ |
evidence/tests.txt |
| 3: secrets/volumes вне Git | secrets-init → volume secrets; .gitignore |
в репозитории нет .env и секретов; volumes messenger-lab2_pgdata, messenger-lab2_secrets |
evidence/container.txt |
| 4: Redis с конкретной ролью | read-through кэш сессий, TTL ≤ 60 с, tombstone | appendonly no; после рестарта Redis smoke проходит |
evidence/failures.txt §1, §3, evidence/container.txt |
| 4: параметризованные запросы, ограниченный пул, таймауты | Prisma + $queryRaw tagged template; параметры URL |
connection_limit=10, pool_timeout=5, statement_timeout=5000 |
раздел «Пул и таймауты», compose.yaml |
| 4: гонка регистрации одинакового username | 10 параллельных POST /users |
ровно один 201, девять 409 |
evidence/tests.txt |
| 4: rollback составной операции | см. «атомарное создание чата» | транзакция откатывается целиком | evidence/tests.txt |
4: индекс истории + EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений |
scripts/explain.sql (50 000 сообщений, 10 000 в целевом чате) |
keyset: Index Scan, 4–5 buffers, < 0,1 мс на первой и 9000-й странице; без индекса/OFFSET — Seq Scan, 667 buffers |
evidence/explain.txt |
| 4: автотест expiry при коротком TTL | failures.e2e-spec.ts, SESSION_TTL_SECONDS=2 |
200, через 2,5 с 401 (в т. ч. после попадания в кэш) |
evidence/tests.txt |
| 4: автотесты logout и неверного пароля | auth.e2e-spec.ts |
204 → 401; неверный пароль и неизвестный пользователь — одинаковый 401 с WWW-Authenticate: Basic |
evidence/tests.txt |
| 4: отзыв токена при разрыве связи с Redis | тест «logout при обрыве связи с Redis…»: прогретый кэш → разрыв → logout → восстановление | старый токен → 401; запись удалена FLUSHDB при переподключении |
evidence/tests.txt |
| 4: недоступность Redis | автотест с redis://127.0.0.1:1; стенд: docker compose stop redis + smoke |
вход, Bearer, logout работают через PostgreSQL; smoke PASS |
evidence/tests.txt, evidence/failures.txt §1 |
| 4: недоступность БД | автотест с недостижимым DATABASE_URL; стенд: docker compose stop postgres |
/health/ready и /chats с токеном → 503 unavailable без деталей; аноним → 401 |
evidence/tests.txt, evidence/failures.txt §2 |
| Собственные тесты | docker compose -f compose.test.yaml run --rm --build tests |
Tests: 68 passed, 68 total |
evidence/tests.txt |
Эксперименты и отказы
EXPLAIN. Гипотеза: с индексом (chat_id, created_at, id) стоимость страницы истории не зависит от её глубины и от размера других чатов. Методика: scripts/explain.sql в одной транзакции создаёт 21 чат (10 000 сообщений в целевом, по 2 000 в остальных, всего 50 000), выполняет ANALYZE и четыре EXPLAIN (ANALYZE, BUFFERS), затем ROLLBACK — данные стенда не меняются. Повтор: docker compose run --rm tools sh -c "docker compose exec -T postgres psql -U messenger -d messenger < scripts/explain.sql".
| Запрос (LIMIT 51) | План | Buffers | Execution Time |
|---|---|---|---|
| Keyset, первая страница | Index Scan messages_chat_id_created_at_id_idx |
4 | 0,05 мс |
| Keyset, после 9000-го сообщения | Index Scan, ROW(created_at, id) > … в Index Cond |
5 | 0,08 мс |
OFFSET 9000 (для сравнения) |
Seq Scan + Sort, Rows Removed by Filter: 40021 |
667 | 5,6 мс |
| Keyset без индекса (для сравнения) | Seq Scan, Rows Removed by Filter: 49021 |
667 | 3,6 мс |
Остальные 21 строка в таблице — синтетические сообщения smoke-прогонов на стенде.
Вывод: keyset по индексу читает одинаковое число страниц на любой глубине; без индекса и с OFFSET читается вся таблица. Ограничения: все данные в shared buffers (горячий кэш), один прогон, абсолютное время на ноутбуке не переносится на другое железо — сравниваются планы и buffers.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
restart.sh: рестарт postgres + redis + api |
данные и прежний токен сохраняются | make test-persistence PASS, started= сменился у всех трёх |
готовность за ~3–4 с; потерь нет |
docker compose stop redis |
запросы идут в PostgreSQL | полный smoke PASS при остановленном Redis | без простоя; потерь нет (Redis — только кэш) |
docker compose restart redis (кэш пуст) |
сессии восстанавливаются из PostgreSQL | smoke PASS, кэш прогревается заново | без простоя |
docker compose stop postgres |
503 без деталей, аноним не пускается |
/health/ready и /chats → 503 unavailable; аноним → 401 |
после start готов за ~3 с; подтверждённые данные на volume |
API с SESSION_TTL_SECONDS=2 |
токен истекает | 200 → через 3 с 401 |
— |
Нагрузочные измерения (RPS, перцентили) в этой работе не проводились: уровень 4 их не требует, трек 5 не заявлен.
Ограничения и следующие шаги
- Durability:
COMMITподтверждается после записи WAL на диск (настройки PostgreSQL по умолчанию,synchronous_commit=on,fsync=on); при отказе диска/хоста без реплики данные теряются — репликации и backup в этой работе нет. - Разрыв связи только у одной реплики API (актуально с lab3): очистка кэша выполняет та реплика, что потеряла связь; реплика с непрерывным соединением может отдавать запись из кэша до её TTL (≤ 60 с). В lab2 реплика одна.
- Порядок при конкурентной записи:
created_at= время начала транзакции, поэтому сообщение может стать видимым позже сообщения с бо́льшимcreated_at; читатель, уже прошедший эту позицию курсором, его пропустит. Для однострочных INSERT окно — миллисекунды; snapshot-изоляция между HTTP-запросами контрактом не требуется. Строгий порядок дал бы последовательный номер в чате (lab3+). - Строки истёкших сессий не удаляются (нет фоновой очистки); на корректность не влияет, таблица растёт.
- Нет rate limiting на
POST /auth/sessions— перебор паролей ограничен только стоимостью Argon2id. - HTTP без TLS — допустимо только для локального стенда с синтетическими данными (TLS — lab7).
- Образ
migrateсодержит dev-зависимости (Prisma CLI) — используется только как one-shot; runtime-образ API без них. - Подтверждено измерением: keyset + индекс (EXPLAIN). Гипотеза, не измерена: выигрыш кэша сессий по latency/числу SQL-запросов под нагрузкой (это трек 5.1).