9.4 KiB
Отчёт — лабораторная 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.