Files
mtusi2026lab2/REPORT.md
T
2026-10-21 15:24:04 +03:00

25 KiB
Raw Blame History

Отчёт — лабораторная 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/prisma 6.1.0, argon2 0.41.1, ioredis 5.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) и строки подключения кладутся в именованный volume secrets, который монтируется 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 (две системы, не атомарно — см. ограничения).

Время и порядок. 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.
  • Отказ 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 автотест с 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: 65 passed, 65 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 в этой работе нет.
  • Logout и кэш не атомарны: если Redis недоступен в момент logout, а затем вернётся со старыми данными (сетевой разрыв без рестарта), отозванный токен может приниматься до 60 с. При рестарте Redis этого нет — он пуст.
  • Порядок при конкурентной записи: 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).