Files
mtusi2026lab2/REPORT.md

8.1 KiB
Raw Permalink Blame History

Отчёт — лабораторная 2

  • Автор, группа — Архипов Антон Андреевич, БПИ2304
  • Целевая оценка — «3»
  • Commit/PR — указать после публикации в своём fork.
  • Использованные библиотеки — TypeScript, Express, tsoa, Zod, UUID, Pino, Swagger UI, node-postgres и Node.js crypto. Материалы — README.md, COURSE.md, contracts/README.md и OpenAPI из задания.
  • ИИ использовался для разбора требований, проектирования структуры приложения, проверки соответствия контракту и подготовки отчёта.

Запуск из чистого clone

Нужны Docker Engine с Docker Compose v2, shell, GNU Make и Python 3.9+. Образ API собирается на Node.js 22.16.0-alpine3.22, БД использует postgres:15.18-bookworm. Инициализация создаёт локальный .env со случайным паролем PostgreSQL, повторный запуск скрипта сохраняет текущую конфигурацию.

chmod +x scripts/init-env.sh scripts/restart.sh
./scripts/init-env.sh
docker compose config --quiet
docker compose build migrate
docker compose up -d --no-build --wait
curl -fsS http://localhost:8080/health/ready
make check
make test
python3 student-tests/auth_and_chat.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh

Swagger UI доступен по /docs, схема курса — по /docs/openapi.json. При изменении APP_BIND_PORT укажите соответствующий BASE_URL в командах тестов. Для повторного применения миграций выполните docker compose run --rm migrate.

Короткий TTL проверяется на отдельном запуске API. Срок уже выданной сессии при этом не пересчитывается.

SESSION_TTL_SECONDS=2 docker compose up -d --no-deps --force-recreate --wait api
python3 student-tests/session_expiry.py
docker compose up -d --no-deps --force-recreate --wait api

Штатная остановка — docker compose down. Для намеренного сброса всех учебных данных выполните docker compose down -v.

Архитектура и решения

Локальный клиент обращается к одному API на 127.0.0.1:8080. От первой лабораторной перенесены Express/tsoa-маршруты, сервисы, проверка Zod, единый JSON ошибок, идентификатор запроса, Swagger UI и завершение по SIGTERM. In-memory хранилище заменено PostgreSQL. Регистрация добавляет пароль, вход принимает Basic, защищённые запросы используют Bearer. X-User-Id игнорируется.

Роль Сервис Готовность Данные и доступ
База postgres pg_isready по TCP Именованный том postgres_data и внутренняя сеть Compose
Миграции migrate Успешный выход после применения SQL Подключение к той же БД, запуск перед API
API api /health/ready проверяет БД и наличие миграции Порт процесса 8080, опубликован на loopback

POSTGRES_USER, POSTGRES_DB и POSTGRES_PASSWORD передаются из .env. DB_HOST=postgres задаёт Compose. APP_BIND_PORT, APP_ENV, LOG_LEVEL и SESSION_TTL_SECONDS управляют портом, профилем, логированием и длительностью сессии.

Миграция 001_core.sql создаёт таблицы users, chats, chat_members, messages и sessions. Уникальный индекс по username защищает от повторной регистрации. Внешние ключи связывают участников, отправителей и сессии с их записями. Проверка участников, запись чата и запись членства проходят в одной транзакции. Миграции используют транзакционную advisory-блокировку и сравнивают SHA-256 уже применённого файла.

Пароль хешируется scrypt с отдельной случайной 16-байтовой солью. Токен содержит 32 случайных байта. PostgreSQL хранит его SHA-256, пользователя и абсолютное время окончания сессии. Выход удаляет запись текущего токена. /health/live проверяет процесс. История сортируется по (created_at, id), курсор привязан к конкретному списку, сообщения читаются через PostgreSQL, где есть индекс (chat_id, created_at, id).

Доказательства критериев

Проверки выполнены 16.11.2026. Сборка и HTTP-сценарии запущены с Node.js 22.16.0 и PostgreSQL 15.18 отдельными локальными процессами. Манифест отдельно прошёл docker compose config --quiet (Compose v2.36.2).

Критерий уровня 3 Команда или сценарий Результат
Минимум API и новая аутентификация make test Smoke прошёл, включая список чатов, историю, чужой чат, Basic, Bearer и logout
PostgreSQL, миграции и атомарность чата Повторный запуск мигратора и python3 student-tests/auth_and_chat.py Повторный запуск увидел применённую миграцию. Запросы с ошибочными участниками не оставили чатов
Срок сессии и отзыв Smoke и python3 student-tests/session_expiry.py После logout и после истечения короткого TTL запрос возвращает 401
Сохранность данных и действующего токена make test-persistence с локальным hook API и PostgreSQL сменили PID. До и после перезапуска проверен тот же токен и то же сообщение
Контракт и конфигурация make check, docker compose config --quiet Обе команды завершились успешно

Вывод команд — local-verification.txt.

Эксперименты и отказы

Воздействие Наблюдение
Перезапуск API и PostgreSQL с тем же каталогом данных Сессия и подтверждённое сообщение сохранились
Сессия с TTL 2 секунды Сразу после входа пользователь доступен, после истечения срока API выдаёт 401

Ограничения

Один экземпляр API и один экземпляр PostgreSQL создают паузу при перезапуске. Сессии хранятся только в PostgreSQL. Просроченные строки сессий перестают участвовать в аутентификации и физически сохраняются до обслуживания таблицы. Пагинация не фиксирует снимок данных на несколько запросов. HTTP предназначен для локального стенда с синтетическими данными.