forked from mtusi2026/mtusi2026lab5
75 lines
6.1 KiB
Markdown
75 lines
6.1 KiB
Markdown
# Отчёт — лабораторная 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. При подготовке кода использовалась помощь ИИ для разбора требований и ревью; все решения, команды запуска и результаты проверок воспроизведены локально.
|