Files
mtusi2026lab5/REPORT.md
T

9.5 KiB
Raw Blame History

Отчёт по лабораторной работе №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-стенде.