Files
mtusi2026lab2/evidence/level3-4-verification.md
2026-10-10 02:13:35 +03:00

24 KiB
Raw Permalink Blame History

Журнал проверок уровня 3/4

Индекс всех доказательств — README.md; сводка решения — ../REPORT.md; методика и числа трека 1 — track1-cache-consistency.md.

Запись по командам, на которых основано заявление об оценке 5 (уровень 4 плюс трек 1). Все пункты выполнены на локальном Compose-стенде; значения ниже скопированы из наблюдавшегося вывода, а не выведены из кода.

Окружение: Node 25.7.0 (node:25.7.0-slim), postgres:16.4-alpine, redis:7.4.2-alpine, Python 3.14.7, Linux x86_64. Тома postgres-data и redis-data между проверками сохраняются.

1. Структура репозитория и контракт

$ make check
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.

$ make validate
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.

2. Сборка приложения и unit-тесты

$ (cd app && npm run build)
nest build  -> PASS

$ (cd app && npm test)
Test Files  5 passed (5)
Tests      13 passed (13)

$ (cd app && npx tsc --noEmit)
PASS (диагностик нет)

Что покрыто unit-тестами: снапшот метрик/процентили/ограничение буфера, изоляция страниц кэша, cursor-scope lock, деградация кэша при недоступности Redis, дельты счётчиков.

3. Compose-стенд и миграции

$ docker compose --env-file .env config --quiet
PASS

$ docker compose --env-file .env up -d --build
postgres  Up (healthy)
redis     Up (healthy)
migrate   Exited (0)
api       Up (healthy)

$ curl -fsS http://localhost:8080/health/ready
{"status":"ok"}

$ docker compose exec -T postgres psql -U messenger -d messenger -c 'SELECT version FROM schema_migrations ORDER BY version;'
001_initial.sql
002_timestamp_precision.sql

Повторные up/restart снова запускают сервис миграций, но без дублирования данных и без сидов: применённые версии записаны в schema_migrations и пропускаются, а сам SQL миграций идемпотентен (CREATE TABLE IF NOT EXISTS, ALTER COLUMN TYPE).

4. Публичный приёмочный сценарий

$ make test BASE_URL=http://localhost:8080
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.

Сценарий покрывает health, регистрацию с паролем, Basic-вход, Bearer-идентичность, видимость чатов, пагинацию сообщений, 401 без сессии, 401 для Basic на бизнес-endpoint, отсутствие подмены владельца через X-User-Id, а также logout и повторное использование токена.

5. Сохранность после полного перезапуска

$ chmod +x scripts/restart.sh
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.

Хук — это docker compose --env-file .env restart postgres redis api и затем up -d --no-recreate --no-deps --wait; он не удаляет тома, не выполняет сиды и не вызывает FLUSHALL. Тест держит токен только в памяти и после перезапуска читает им то же сообщение.

6. Чёрно-белый интеграционный набор против реальных PostgreSQL и Redis

$ (cd app && API_BASE_URL=http://localhost:8080 \
    DATABASE_URL=postgresql://messenger:<password>@<pg-container>:5432/messenger \
    REDIS_URL=redis://<redis-container>:6379 \
    npx vitest run --config ./vitest.config.e2e.ts)
Test Files  1 passed (1)
Tests       9 passed | 1 skipped (10)

Покрыто: challenge для Basic/Bearer с точными значениями WWW-Authenticate, некорректный Basic, запрет тела при создании сессии, пароль с Unicode и двоеточием, гонка дублирующейся регистрации, подмена X-User-Id, повторное использование токена после logout, чужой чат скрыт (404), неизвестные и дублирующиеся участники, пробельный текст и подмена отправителя, read-after-write через вторую сессию, сломанный JSON, некорректные cursor/limit (включая несуществующую календарную дату), границы длин в Unicode code points для пароля, display_name, title и текста сообщения, keyset-пагинация без повторов.

Набор читает API_BASE_URL, потому что Vitest сам устанавливает process.env.BASE_URL в значение Vite base (/). Порты PostgreSQL и Redis наружу не публикуются, поэтому оператор передаёт адреса контейнеров.

7. Истечение сессии при коротком TTL

$ sed -i 's/^SESSION_TTL_SECONDS=.*/SESSION_TTL_SECONDS=2/' .env
$ docker compose up -d api
$ (cd app && API_BASE_URL=http://localhost:8080 ... SESSION_TTL_SECONDS=2 npx vitest run --config ./vitest.config.e2e.ts)
Test Files  1 passed (1)
Tests       10 passed (10)

Кейс истечения: регистрация, вход, ожидание 2,3 с, ожидание 401 unauthorized с Bearer-challenge. Работают и TTL Redis, и сериализованный expires_at. После проверки TTL возвращён в 3600.

8. Гонка одинакового username

statuses: [201, 409]
rows in users for that username: 1
constraint: CREATE UNIQUE INDEX users_username_key ON public.users USING btree (username)

Два одновременных POST /api/v1/users с одинаковым username: ровно один 201, проигравший получает 409 (ошибка PostgreSQL 23505 маппится в ConflictException), а не 500. Уникальность обеспечивает unique-индекс базы, а не предварительный SELECT, который был бы подвержен гонке. Интеграционный тест дополнительно проверяет, что в таблице ровно одна строка.

9. Атомарность создания чата (rollback)

chat with unknown member -> 400
rows left after rollback -> 0

POST /api/v1/chats с неизвестным участником падает на валидации внутри транзакции: ни строки в chats, ни строк в chat_members не остаётся.

10. Отказы зависимостей

Остановлен Redis (docker compose stop redis):

/health/ready                -> 503
GET /users/me (валидный токен) -> 503      # анонимный доступ не выдаётся
после `docker compose start redis` -> /health/ready 200

Остановлен PostgreSQL (docker compose stop postgres):

/health/ready                -> 503
GET /users/me (валидный токен) -> 503
состояние процесса            -> контейнер api остался Up (падения нет)
после `docker compose start postgres` -> /health/ready 200, тот же токен -> 200

Здесь найден и исправлен реальный дефект: idle-клиент пула эмитил error на пул, Node считал это необработанным исключением, и процесс API завершался. Теперь DatabaseClient регистрирует pool.on('error') (счётчик database.pool_error + warn в лог), а ошибки доступности БД маппятся в ограниченную 503 в ApiExceptionFilter вместо 500.

Тот же сценарий автоматизирован: make test-dependencies (или E2E_DEPENDENCY_FAULTS=1 npm run test:dependencies из app/) сам останавливает и поднимает контейнеры Compose-стенда и проверяет для обоих хранилищ, что /health/live остаётся 200, /health/ready и бизнес-запросы дают ограниченную 503 unavailable с request_id, равным X-Request-Id, в теле ошибки нет утечки деталей драйвера/SQL/стека, запрос без сессии остаётся 401 (отказ не делает анонимного вызывающего доверенным), а после старта зависимости работают прежняя сессия, подтверждённое сообщение и новая запись.

$ make test-dependencies
 Test Files  1 passed (1)
      Tests  2 passed (2)
   Duration  40.09s

Первая версия этого теста сразу нашла дефект: POST /api/v1/users при остановленном PostgreSQL отвечал 500, потому что часть ошибок node-postgres не несёт поля code («Connection terminated unexpectedly», «timeout exceeded when trying to connect»). Фильтр теперь распознаёт и такие сообщения, а неожиданные исключения логируются на сервере (в ответе остаётся только internal_error).

Путь деградации кэша (Redis недоступен → ответ из PostgreSQL, счётчик cache_fallback) подтверждён unit-тестами, а не этим экспериментом: при остановленном Redis бизнес-запрос останавливается раньше, на session guard, и по дизайну получает 503, поэтому до слоя кэша не доходит.

11. План запроса истории

$ docker compose exec -T postgres psql -U messenger -d messenger -f - < /tmp/track1-explain.sql
=== Запрос A: первая страница истории ===
 Limit  (cost=0.28..112.30 rows=51 width=77) (actual time=0.020..0.028 rows=51 loops=1)
   ->  Index Scan using messages_chat_created_id_idx on messages  (actual rows=51)
 Execution Time: 0.040 ms
=== Запрос B: продолжение по keyset-cursor ===
 Limit  (cost=0.28..8.30 rows=1 width=77) (actual time=0.008..0.014 rows=51 loops=1)
   ->  Index Scan using messages_chat_created_id_idx on messages  (actual rows=51)
         Index Cond: ((chat_id = ...) AND (ROW(created_at, id) > ROW(...)))
 Execution Time: 0.048 ms

Для снятия планов в один чат вставлено 10 000 синтетических сообщений, после захвата они удалены (DELETE 10000). Полный файл с текстом анализируемых запросов и подготовкой данных: evidence/track1-explain.md.

12. Endpoint метрик

$ curl -H "Authorization: Bearer $METRICS_TOKEN" http://localhost:8080/internal/metrics
observed counters: cache_miss, chats.findForUser, chats.listForUser, health.database,
  messages.history, messages.version, redis.del, redis.get, redis.ping, redis.set,
  redis.unlock, request_count, session_del, session_get, session_set,
  users.findById, users.findByUsername, users.insert
latency: {count: 25, sample_count: 25, p50: 2.82, p95: 50.71, p99: 52.74, max: 52.74}

Без корректного METRICS_TOKEN endpoint отдаёт 401; в ответе нет токенов, кредов, тел запросов и SQL-текста.

Тот же путь проверен ручным клиентом Bruno (bruno/README.md): из корня коллекции bru run -r --env-var metricsToken=<METRICS_TOKEN> дал 29 запросов и 58 проверок без падений (регистрация трёх пользователей, три Basic-сессии, чат, сообщения с пагинацией, метрики и негативные сценарии). baseUrl и пароль подставляются на уровне коллекции (bruno/collection.bru), поэтому вводить адрес в каждой ручке не требуется; без реального токена метрик два запроса к /internal/* возвращают 401 — это ожидаемо. Прогон вскрыл расхождение: POST /internal/metrics/reset отвечал 201 (дефолт Nest для POST), хотя это действие, а не создание ресурса; добавлен @HttpCode(HttpStatus.OK), теперь 200.

13. Дефекты, найденные этим аудитом и исправленные

Дефект Симптом Исправление
Отсутствовали DI-импорты зависимостей CurrentUserGuard контейнер API Exited (1) с UnknownDependenciesException ChatsModule/MessagesModule импортируют RedisModule, MetricsModule; UsersModule их реэкспортирует
Микросекунды PostgreSQL против миллисекунд JavaScript вторая страница истории повторяла последнее сообщение (make test падал) миграция 002_timestamp_precision.sql → timestamptz(3)
Regex курсора требовал строго version 4 валидные курсоры отклонялись как 400 invalid_request regex принимает любую корректную форму UUID плюс строгий RFC 3339 UTC timestamp
Необработанное событие error пула процесс API умирал при недоступности PostgreSQL обработчик pool.on('error') (счётчик database.pool_error + warn), отказ маппится в 503
«Тихие» блоки catch деградация кэша и зависимостей была невидима счётчики (cache_fallback, cache_write_error, cache_unlock_error, cache_lock_timeout, cache_corrupt_entry, database.pool_error, database.rollback_error, redis.error) + warn-логи
Мёртвое состояние lastError, getLastError(), isReady() заполнялось и нигде не читалось удалено; листенеры пишут лог и счётчик
POST /internal/metrics/reset отвечал 201 действие возвращало статус создания ресурса (нашлось прогоном коллекции Bruno) добавлен @HttpCode(HttpStatus.OK), теперь 200
Курсор с несуществующей датой (2026-02-31) отвечал 500 Date.parse молча переносил дату на 3 марта, значение доходило до SQL и Postgres отклонял его формат проверяется регулярным выражением, календарь — date-fns parseISO + isValid; невозможные даты и 24:00:00 дают 400 invalid_request (unit-тесты cursor.spec.ts, e2e-кейс, bruno/negative/invalid-calendar-cursor.bru)
Длины строк мерились в UTF-16-единицах @Length считает UTF-16: пароль из 11 эмодзи (22 единицы) проходил проверку «12+», а текст из 4000 эмодзи (8000 единиц) отклонялся как слишком длинный собственный декоратор @CodePointLength (app/src/common/validation/code-point-length.ts) считает code points; применён к display_name, password, title, тексту сообщения; дублирующая проверка в UsersService удалена; unit-тесты границ + HTTP-кейс в app/test/app.e2e-spec.ts
Пароль из 12 пробелов принимался (201) проверялась только длина, хотя контракт требует непустые по непробельным символам обязательные строки в CreateUserDTO добавлен @Matches(/\S/u); e2e-кейс отклоняет пробельный пароль, короткий пароль и пробельное display_name, при этом Unicode-пароль с двоеточием по-прежнему принимается
POST /api/v1/users при отказе PostgreSQL отвечал 500 часть ошибок node-postgres приходит без code, поэтому фильтр не относил их к отказу зависимости (нашёл автоматический тест make test-dependencies) фильтр распознаёт тексты «Connection terminated unexpectedly»/«timeout exceeded when trying to connect» и логирует неожиданные исключения серверно
nest build не копировал .sql-миграции в dist/ локальный запуск node dist/database/migration.runner.js упал бы: каталога миграций в dist/ нет, работал только Docker за счёт отдельного COPY в nest-cli.json добавлен assets: database/migrations/*.sql → dist, лишний COPY из Dockerfile убран; проверено docker run --rm --entrypoint ls mtusi-messenger:lab2 dist/database/migrations и повторным запуском runner (exit 0)

14. Инвентарь артефактов

Артефакт Назначение
evidence/track1-cache-consistency.md подробный отчёт по треку 1 с таблицами по повторностям
evidence/track1-raw/naive.json сырой прогон naive (в Git не попадает)
evidence/track1-raw/protected.json сырой прогон protected (в Git не попадает)
evidence/track1-raw/redis-restart.json сырая проверка рестарта Redis (в Git не попадает)
evidence/track1-explain.md запросы и EXPLAIN (ANALYZE, BUFFERS)
bruno/README.md коллекция ручных запросов (Bruno) ко всем эндпоинтам
app/test/app.e2e-spec.ts black-box набор против запущенного API (реальные PG/Redis)
app/test/dependency-failures.e2e-spec.ts автоматическая проверка отказов Redis/PostgreSQL (make test-dependencies)
app/src/common/http/cursor.spec.ts unit-тесты разбора курсора (формат, календарь, scope)
app/src/common/validation/code-point-length.ts декоратор проверки длины в Unicode code points
app/src/common/validation/code-point-length.spec.ts unit-тесты границ декоратора по code points
REPORT.md основной отчёт: архитектура, решения, команды, результаты

Хеши сырых артефактов перечислены в evidence/track1-cache-consistency.md §8.