Files
mtusi2026lab4/REPORT.md
T

9.4 KiB
Raw Blame History

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

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

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

Нужны Docker Engine с Docker Compose v2, shell, GNU Make и Python 3.9+. Версии образов — Node.js 22.16.0-alpine3.22, postgres:15.18-bookworm, haproxy:3.0.11-alpine, rustfs/rustfs:1.0.6.

chmod +x scripts/init-env.sh scripts/restart.sh scripts/stop-one.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/idempotency.py
python3 student-tests/attachments.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose ps --all api-a api-b
docker compose start api-a api-b

После восстановления обеих реплик проверьте сценарий, который останавливает именно загрузившую реплику.

python3 student-tests/attachment_failover.py --action-script scripts/stop-one.sh
docker compose ps --all api-a api-b
docker compose start api-a api-b

Скрипт инициализации создаёт локальный .env со случайными учётными данными PostgreSQL и S3. Сервис migrate применяет SQL, сервис s3-init проверяет бакет и создаёт его при отсутствии. Для ручного повтора используйте docker compose run --rm migrate и docker compose run --rm s3-init. docker compose down сохраняет оба тома. docker compose down -v намеренно удаляет все учебные данные и файлы. Swagger UI доступен через HAProxy по /docs.

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

От lab3 сохранены две API-реплики, HAProxy, PostgreSQL, общие сессии и атомарные повторы отправки. Добавлено приватное S3-хранилище RustFS. Текстовые запросы без вложений сохраняют прежний формат. Ответ Message с lab4 содержит attachment_ids, для прежних сообщений это пустой массив. Запрос с пропущенным полем и запрос с пустым массивом используют тот же хеш, что и текстовый запрос lab3.

Роль Сервис Готовность Данные и доступ
PostgreSQL postgres pg_isready по TCP postgres_data, внутренняя сеть
Миграции migrate Успешный выход после применения трёх миграций SQL выполняется до запуска API
S3 s3 Доступность приватного бакета по подписанному HeadBucket s3_data, внутренний порт 9000
Bootstrap бакета s3-init Успешный выход после HeadBucket Повторный запуск использует существующий бакет
API api-a, api-b /health/ready проверяет миграцию в БД и бакет Внутренний порт 8080 и собственный X-Instance-Id
Балансировщик lb Проверяет /health/ready реплик Единственный порт хоста 127.0.0.1:8080

S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS загружаются из .env. Endpoint http://s3:9000 и регион us-east-1 заданы в Compose. Порт RustFS и его консоль наружу не публикуются.

При загрузке API проверяет Bearer-сессию и членство в чате. Имя используется для отображения. Сервер генерирует случайный ключ объекта, отдельно от ID вложения. HTTP-парсер ограничивает тело 10 MiB. Sharp читает заголовок, сравнивает MIME с форматом и проверяет 40 млн пикселей до полной декодирующей проверки. В S3 отправляются исходные байты. Ответ 201 ready выдаётся после успешной записи оригинала и метаданных с SHA-256. Скачивание проверяет членство и передаёт оригинал потоком через API.

Миграция 003_attachments.sql добавляет attachments и message_attachments. Метаданные лежат в PostgreSQL, содержимое — в RustFS. Два составных внешних ключа гарантируют принадлежность сообщения и вложения тому же чату. Сообщение, связи с файлами и запись ключа идемпотентности фиксируются одной транзакцией.

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

16.11.2026 проверки запущены на локальных процессах Node.js 22.16.0, PostgreSQL 15.18, HAProxy 3.0.11 и RustFS 1.0.6. Hook перезапускал реальные процессы с теми же каталогами данных. Манифест отдельно прошёл docker compose config --quiet (Compose v2.36.2).

Критерий уровня 3 Команда или сценарий Результат
Сохранён API lab3 make test, python3 student-tests/idempotency.py Smoke прошёл. 16 одновременных повторов через две реплики дали одно сообщение
PNG, SHA-256 и доступ к вложению make test Публичный smoke сверил SHA-256 и байты, проверил привязку к сообщению и 404 для постороннего
JPEG, лимиты, MIME и filename python3 student-tests/attachments.py JPEG скачался побайтно. Превышение размера и пикселей дало 413, битый файл и подмена MIME дали 415, опасные имена дали 400
Приватный бакет GET существующего объекта напрямую без S3-подписи RustFS вернул 403
Сохранность после полной остановки make test-persistence с локальным hook HAProxy, обе реплики, PostgreSQL и RustFS перезапущены. Старый токен, сообщение и исходный файл доступны
Отказ реплики make test-failover с локальным hook Остановлена api-b. Первая подтверждённая запись после hook через 0,332 сек. Дублей не обнаружено
Скачивание после остановки загрузившего API python3 student-tests/attachment_failover.py с локальным hook Загрузка через api-a, затем остановка api-a и побайтно совпавшее скачивание через api-b за 0,189 сек
Недоступность S3 Остановка RustFS и запросы к оставшейся API-реплике /health/live — 200, /health/ready — 503. После запуска RustFS бакет снова прошёл инициализацию

Вывод проверок и PID — local-verification.txt.

Ограничения

S3 PUT и запись в PostgreSQL выполняются последовательно. При подтверждённой ошибке SQL API пытается удалить объект. Если исход COMMIT неизвестен или удаление не удалось, объект может остаться в приватном бакете. Сверка объектов и метаданных в фоне не реализована. Используются общие учётные данные учебного S3-сервиса. Доступность системы при отказе единственного PostgreSQL, балансировщика или S3-сервера не обеспечена. Поддерживается синхронная загрузка оригинала PNG/JPEG.