Files
mtusi2026lab5/REPORT.md
T
2026-11-20 22:48:28 +03:00

75 lines
6.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 5
- Автор, группа: Гусак Дмитрий, БПИ2303
- Целевая оценка: 4
- Трек 5: не заявлен
## Что реализовано
Сохранен минимум лабораторных 1–4: регистрация и Basic/Bearer-аутентификация, PostgreSQL, Redis-сессии, HAProxy, idempotency для сообщений, MinIO и ACL чата.
В этой работе загрузка изображения стала асинхронной. API сначала потоково принимает файл во временный файл, проверяет MIME/signature, декодирование, размер (10 MiB) и число пикселей (40 млн), затем кладёт оригинал в приватный staging-prefix MinIO и одной транзакцией PostgreSQL сохраняет `attachments` и `attachment_jobs`. Только после этого отвечает `202 queued`.
`OutboxPublisher` регулярно публикует в Redis Stream только `job_id`, тип и версию схемы. Отдельный контейнер `worker` читает durable stream с consumer group, получает staging-объект, создаёт конечный original, JPEG thumbnail 256×256 fit без увеличения, JPEG crop 128×128 и WebP optimized до 1280 px. В PostgreSQL записываются варианты с размерами, MIME и SHA-256, затем attachment переводится в `ready`, а staging удаляется.
Повторная доставка безопасна: job имеет уникальный `job_id`, варианты имеют первичный ключ `(attachment_id, name)`, записи используют `ON CONFLICT DO NOTHING`, а object keys детерминированы. Есть lease 30 секунд, ограничение пяти попыток, exponential backoff с jitter, безопасные `temporary_error`/`retry_exhausted` и восстановление outbox-записей после разрыва между COMMIT и publish. Redis работает с AOF `everysec`, PostgreSQL и MinIO — с именованными volumes.
Для финального failed-состояния предусмотрен явный операторский replay без создания новой attachment: `ATTACHMENT_ID=... scripts/replay-failed.sh`. Он переводит только `failed` job обратно в `queued`, после чего outbox публикует тот же `job_id`.
## Запуск из чистого clone
Нужны Docker Desktop, Java 21/Gradle Wrapper и Python 3.9+. Секреты не коммитятся:
```sh
cp .env.example .env
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
# вставить результат в CURSOR_SECRET в .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2
```
Ожидать успешного healthcheck у `api` и `lb`, затем использовать порт `APP_PORT` (по умолчанию 8080). Остановка без удаления данных:
```sh
docker compose --env-file .env stop
```
Намеренное удаление учебных данных (не выполнять для обычной остановки):
```sh
docker compose --env-file .env down -v
```
## Проверки
```sh
make check
make test BASE_URL=http://localhost:8080
make test-grade4 BASE_URL=http://localhost:8080
make validate
```
Фактически проверено на локальном стенде с `APP_PORT=8084`:
```text
make check PASS: offline skeleton structure...
make test BASE_URL=http://localhost:8084
PASS: lab5 public API scenario; infrastructure and grading evidence remain separate.
make test-grade4 BASE_URL=http://localhost:8084
PASS: grade-4 async attachment pipeline; queue, worker, crop, WebP and idempotent metadata verified.
make test-persistence ACTION_SCRIPT=./scripts/restart.sh BASE_URL=http://localhost:8084
PASS: persistence preserved confirmed data and existing session.
make test-failover ACTION_SCRIPT=./scripts/stop-one.sh BASE_URL=http://localhost:8084
PASS: failover preserved confirmed data and existing session.
```
Публичный smoke проверяет `202 queued`, связь queued-вложения с сообщением, переход в `ready`, оригинал и thumbnail. Собственный `student-tests/lab5_grade4.py` дополнительно проверяет crop, WebP-сигнатуру, фактические JPEG-размеры, SHA-256 всех вариантов и стабильность повторного GET. Отказ worker воспроизводится так: `docker compose stop worker`, выполнить upload (получить 202 и 409 на content), затем `docker compose start worker` и дождаться `ready`; данные не теряются.
## Ограничения
Это учебный single-process worker с Redis consumer group и bounded polling; production-масштабирование требует отдельной настройки числа consumers, мониторинга lag/DLQ и janitor для очень старых staging-объектов. WebP-библиотека `webp4j` содержит native backend для Linux x64/ARM64; при смене платформы образ должен соответствовать архитектуре. Exactly-once доставка не заявляется: гарантируется at-least-once и идемпотентный эффект.
## Источники и ИИ
Использованы README/контракты лаборатории, официальная документация Redis Streams, Spring Boot scheduling/JDBC и MinIO S3 API. При подготовке кода использовалась помощь ИИ для разбора требований и ревью; все решения, команды запуска и результаты проверок воспроизведены локально.