8.1 KiB
Отчёт — лабораторная 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 предназначен для локального стенда с синтетическими данными.