9.5 KiB
Отчёт по лабораторной работе №5
- Автор, группа: Борзов Никита, БВТ2304
- Целевая оценка: 4
- Основа: проект ЛР4 с сохранением PostgreSQL, Redis-сессий, MinIO, Nginx, четырёх API-реплик, авторизации, идемпотентности и сценариев отказа
- Новая задача: принять изображение отдельно от его фоновой обработки
Запуск из чистого clone
Нужны Docker Desktop с Compose v2 и Python 3.9+. Все образы имеют фиксированные версии или digest. Локальные пароли находятся только в .env; .env.example содержит учебные значения для изолированного стенда.
cp .env.example .env
docker compose config --quiet
docker compose build
docker compose up -d --wait
make check
make validate PYTHON=.venv/bin/python
make test BASE_URL=http://localhost:8080
Без OpenAPI-проверки достаточно make check и make test. Для полной валидации сначала создаётся окружение:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
Сервисы Compose:
| Роль | Сервис | Данные/порты |
|---|---|---|
| API | api-1 ... api-4 |
общий код приложения, порты доступны только внутри сети |
| Балансировщик | lb |
единственный внешний localhost:8080 |
| База | postgres |
postgres_data volume |
| Сессии/кэш | redis |
redis_data volume, AOF |
| Broker | broker |
Redis Streams, broker_data volume, AOF |
| Файлы | minio |
приватный S3 bucket, s3_data volume |
| Обработка | worker |
отдельный процесс, resize и фиксация результата |
minio-init и migrate являются одноразовыми bootstrap-сервисами. API-реплики не публикуются наружу. docker compose down сохраняет volumes, а docker compose down -v намеренно удаляет учебные данные.
Поток загрузки
В ЛР4 upload возвращал 201 ready. В ЛР5 endpoint возвращает 202 queued, потому что обработка вынесена из API:
клиент -> Nginx -> API
| проверка и S3 staging
| PostgreSQL: attachment + outbox job
v
Redis Streams broker -> worker
| original
| thumbnail 256x256
| crop 128x128
| optimized WebP
v
S3 final prefix + PostgreSQL metadata
До ответа 202 проверенный оригинал записывается в приватный prefix staging/, а в одной транзакции PostgreSQL создаются строка вложения и запись attachment_jobs. В broker передаются только UUID и служебные поля job; байты, credentials и клиентский filename в сообщение не попадают.
Клиент читает GET /api/v1/attachments/{id} и ждёт status=ready. До готовности download возвращает 409. После готовности original отдаётся побайтно, а варианты доступны через ?variant=thumbnail, crop или optimized.
Worker применяет EXIF orientation, ограничивает число пикселей и создаёт варианты без EXIF. Thumbnail вписывается в 256×256 без увеличения маленького изображения; fixture 320×200 даёт 256×160. Crop — центрированный JPEG 128×128. Optimized — WebP, вписанный в 1280×1280, качество 82.
Надёжность и уровень 4
Redis Streams работает как отдельный durable broker с AOF и volume. Доставка at-least-once: worker подтверждает сообщение только после устойчивой фиксации результата. Повторная job использует тот же job_id, а ключи объектов и (attachment_id, pipeline_version, variant) делают обработку идемпотентной. Для уже готового вложения повтор является no-op.
Transactional outbox закрывает разрыв между PostgreSQL и broker. API сначала коммитит staging, metadata и attachment_jobs. Worker отдельным циклом публикует неподтверждённые outbox-записи. Если worker остановлен после commit, запись остаётся в PostgreSQL и публикуется после восстановления; ручное создание нового задания не требуется.
У processing есть lease 30 секунд. После смерти worker просроченный lease переводит вложение обратно в queued, а тот же job снова появляется в outbox. Временные ошибки получают ограниченные повторы до 5 попыток с exponential backoff и jitter. Постоянная ошибка изображения становится failed с безопасным error_code; для явного операторского повтора используется:
docker compose exec worker python scripts/replay_failed.py ATTACHMENT_UUID
Варианты записываются с ON CONFLICT по имени, поэтому повторная доставка не создаёт второй набор вариантов и старая job не перезаписывает новый результат.
Для проверки окна «результат уже записан, но ack ещё не отправлен» worker поддерживает локальный тестовый ACK_DELAY_SECONDS; в обычном .env он равен нулю и не влияет на обработку.
Проверки и наблюдаемые результаты
| Сценарий | Команда | Результат |
|---|---|---|
| Контракт и синтаксис | make check |
PASS |
| OpenAPI и JSON Schema | make validate PYTHON=.venv/bin/python |
PASS |
| Публичный сценарий | make test BASE_URL=http://localhost:8080 |
PASS: lab5 public API scenario |
| MIME/размер/доступ | python3 student-tests/attachments.py |
PASS; 415/413/404 |
| Все варианты | python3 student-tests/variants.py |
thumbnail, crop и optimized PASS |
| Идемпотентность сообщений | python3 student-tests/idempotency.py |
один Message ID при 8 повторах |
| 10 конкурентных upload | python3 student-tests/upload_load.py |
все 10 получили 202 |
| Worker остановлен | python3 student-tests/worker_recovery.py |
upload 202 сохраняется и после старта worker становится ready |
| Outbox | python3 student-tests/outbox_recovery.py |
commit-задание переживает остановку worker и доходит до ready |
| Crash после результата до ack | python3 student-tests/worker_ack_recovery.py |
redelivery оставляет один набор вариантов |
| Persistence | make test-persistence BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/restart.sh |
данные, сессия и вложение сохранены |
| API failover | make test-failover BASE_URL=http://localhost:8080 ACTION_SCRIPT=scripts/stop-one.sh |
записи продолжаются через другие реплики |
Во время локальной проверки было получено: smoke PASS, observed_instances_before=4, failed_attempts=0, recovery около 1 секунды, все варианты прошли проверку checksum и MIME.
Ограничения
Один PostgreSQL, один Redis-сервис сессий, один Redis broker, один MinIO и один Nginx остаются единичными точками отказа. Стенд проверяет отказ worker, повторную доставку, сохранность volumes и отказ одной API-реплики; потеря Docker-host и удаление volumes в модель не входят. Redis Streams использует at-least-once доставку, поэтому exactly-once доставка не заявляется: ровно один эффект достигается идемпотентной записью результата.
Все пользователи и изображения синтетические. ИИ использовался как помощник при разборе skeleton и подготовке кода; команды и результаты проверены на локальном Compose-стенде.