# Отчёт — лабораторная 5: очередь и асинхронная обработка изображений **Автор / группа:** Авзалов Артур Марсович / БПИ2301 **Целевая оценка:** 4 **Заявленная оценка:** 4; основной интеграционный набор выполнен на учебном Windows/Docker Desktop стенде (см. результаты и ограничения) **Использование ИИ:** ChatGPT помогал проектировать и реализовать API, outbox, worker, инфраструктуру, тесты и этот отчёт. ## Что перенесено и изменено Сохранён каркас Lab4: две stateless FastAPI-реплики за HAProxy, PostgreSQL, Redis-сессии, S3-совместимый SeaweedFS, авторизация по Bearer, идемпотентность сообщений, пагинация, проверки MIME/ACL и миграции. Публичные `contracts/` и `tests/smoke.py` взяты из **оригинального skeleton Lab5**, не из Lab4. Изменение Lab5: загрузка `POST /api/v1/chats/{id}/attachments?filename=...` отвечает `202` со снимком `status=queued`. Обещание на момент ответа: файл целиком проверен и находится в устойчивом S3 staging, а метаданные вложения, job и запись transactional outbox находятся в **одном коммите PostgreSQL**. Публикация RabbitMQ и обработка — после HTTP-ответа, в отдельных процессах. ## Архитектура ```text HAProxy / \ api1 api2 GET status / content / messages \ / PostgreSQL (attachments, jobs, transactional outbox) | ^ outbox dispatcher worker (RabbitMQ consumer) | ^ RabbitMQ (durable queue, persistent messages, manual ack) | worker child (Pillow transforms, time budget) | SeaweedFS (private S3 bucket) staging/ -> attachments/ + recovery/ + variants/thumbnail,crop,optimized ``` **Единственный источник истины по статусу** — PostgreSQL. В сообщении RabbitMQ только `job_id`, `attachment_id`, `pipeline_version`, `attempt`, дата и тип; байтов, клиентского filename, токенов и S3 credentials там нет. S3 staging не исчезает при перезапуске API/worker/broker. RabbitMQ имеет named volume и durable queue. Pubisher confirm фиксирует приём брокером; consumer ack вызывается после устойчивой фиксации результата в БД либо очередной попытки/failed. Доставка **at least once**, но не exactly-once. ### Разрыв между COMMIT и publish `_admit_upload()` загружает исходник в `staging/{id}/original`, затем в одной транзакции создаёт `attachments(status=queued)`, `processing_jobs` и `job_outbox`. `dispatcher` читает ещё не опубликованные outbox-записи, публикует persistent RabbitMQ message с publisher confirms и только после подтверждения выставляет `published_at`. Если dispatcher падает до publish или после publish до обновления outbox — он повторяет отправку. Повторы безопасны благодаря `processing_jobs` и `attachment_variants` с уникальностью `(attachment_id,pipeline_version,name)`. ### Worker, таймауты и retry Worker имеет ограниченный `prefetch` (по умолчанию 1), одну обработку за раз на процесс, и отдельный subprocess для каждой картинки с таймаутом `JOB_TIMEOUT_SECONDS=60`. Изображения ограничены 10 MiB и 40 млн пикселей; Docker memory limit worker — 768 MiB, CPU 1.0. Для большого формата subprocess может завершиться неуспешно: фиксируется ограниченный retry либо failed, но API не зависает синхронно. Worker захватывает job через строковую блокировку в PostgreSQL и создаёт lease на 105 с при таймауте 60 с. При падении lease истекает, dispatcher повторно ставит job в очередь. При временной ошибке: retry с экспоненциальным backoff + jitter, по умолчанию до пяти попыток. Повреждённый файл — постоянная ошибка `invalid_image`. По исчерпании — `retry_exhausted`. Для failed доступен **только операторский** `python -m app.jobs replay --id ...`, с аудитом в `job_replay_audit`. Job с `status=ready` не перезапускается по старому сообщению. ### Варианты изображений - `original` — неизменённые исходные bytes, первичный ключ `attachments/...`, recovery-копия `recovery/...`. - `thumbnail` — JPEG, вписанный в 256×256 без увеличения; например, fixture 320×200 → 256×160; quality 85. - `crop` — JPEG 128×128, центрированный квадрат с допущенным увеличением; quality 85. - `optimized` — WebP, вписанный в 1280×1280 без увеличения; quality 78, method 4. EXIF orientation применяется через `ImageOps.exif_transpose`; прозрачность накладывается на белый фон; метаданные не передаются при кодировании новых изображений. Контент queued/processing/failed отвечает `409`, готовые варианты — только через авторизованный API и проверку участника чата. ### Безопасная очистка staging После `ready` worker удаляет `staging/` только после успешного commit. Если он умер раньше очистки, dispatcher повторяет безопасную уборку. Не привязанные к БД staging-объекты и staging failed-работ удерживаются не менее 86400 с; по истечении могут быть очищены, после чего replay требует нового staging и будет отклонён. S3 и PostgreSQL **не имеют общей транзакции**; очистка построена консервативно. ## Запуск из чистого clone 1. Создать `.env` из `.env.example` и заменить учебные пароли БД, RabbitMQ и S3 на разные случайные значения. `.env` никогда не включать в Git. 2. Остановить Lab4, если он занимает `127.0.0.1:8080`, без удаления volumes. 3. В PowerShell из корня Lab5: ```powershell $env:PYTHONUTF8 = '1' docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build --wait docker compose --env-file .env ps python scripts/check_contract.py python tests/smoke.py ``` Все зависимости создаются только этим Compose: PostgreSQL 16.10, Redis 7.4.5, RabbitMQ 4.1.8, SeaweedFS 4.53, HAProxy 3.1.7, Python 3.12.10. Для Windows также нужны Docker Desktop, PowerShell, Python 3.9+. **Команды тестов и их результаты приведены ниже в разделе доказательств критериев.** ## Доказательства критериев **Фактически проверено пользователем 14–15 ноября 2026 года на Windows + Docker Desktop.** Команды и результаты ниже взяты из вывода реального запуска; отсутствующие результаты не обозначены PASS. Исправлены две обнаруженные проблемы: лишний `%s` в SQL `publish_result()` и устаревшее ожидание `404` thumbnail/`201` upload в собственных тестах из Lab4. | Критерий | Команда / опыт | Результат | | --- | --- | --- | | Инфраструктура | `docker compose up -d --build --wait`; `docker compose ps` | **PASS**: API1/2, RabbitMQ, PostgreSQL, Redis, SeaweedFS, LB, worker, dispatcher поднялись; health основных сервисов зелёный | | Структура/контракт | `python scripts/check_contract.py` | **PASS**, offline-only | | Модели/limit/cursor | `python tests/own_unit.py` | **PASS** | | API и вариантные файлы | `python tests/smoke.py` после SQL фикса | **PASS**: 202→ready | | Негативные MIME, размеры, ACL, варианты | `python tests/attachments_negative.py` после актуализации ожиданий под Lab5 | **PASS** | | Message idempotency | `python tests/idempotency_parallel.py` | **PASS**: 2 API, 201 replay и 409 для иного тела | | Pillow, isolated | `python -m app.pipeline_selftest` внутри worker-контейнера | **PASS**: PNG→JPEG thumb 256×160, crop 128×128, WebP | | Остановленный worker / рестарт API и RabbitMQ / ready | `python tests/pipeline_resilience.py --scenario paused` | **PASS**: данные, оригинал, 3 варианта доступны после восстановления | | PostgreSQL COMMIT → падение dispatcher до publish | `... --scenario outbox-crash` | **PASS**: exit 78, восстановление из outbox | | Worker после S3 effects, до DB commit/ack | `... --scenario worker-crash` | **PASS**: exit 77, восстановление после lease, 3 варианта | | 10 одновременных загрузок → все ready | `python tests/attachments_concurrent.py --concurrency 10 --output evidence/attachments-concurrent.json` | **PASS**: 10/10 accepted, 10/10 ready, 0 failed; повторный прогон: приём 2.391 s / 4.182 RPS, p50 2218.5 ms, max 2313 ms; все ready через 29.781 s, по 111817 bytes | | Долговечность *уже опубликованного* RabbitMQ сообщения | `python tests/pipeline_extended.py --scenario broker-persistence` | **PASS**: подтверждённая публикация, ready=1 до и после рестарта брокера; dispatcher остановлен | | Permanent failed / manual replay / аудит / запрет replay ready | `python tests/pipeline_extended.py --scenario failed-replay` | **PASS** (15.11): `invalid_image` без retry/вариантов → исправление метаданных → operator replay → `ready`; audit=1, replay `ready` отклонён | | Очистка S3 staging | `python tests/pipeline_extended.py --scenario staging-cleanup` | **PASS**: `ready`, `staging_key=NULL`, staging-объект отсутствует | | Использование памяти контейнеров под нагрузкой | 45-секундная серия `docker stats`, 15 отсчётов на контейнер | **ЗАМЕРЕНО**: наблюдаемый максимум памяти API1 163.10 MiB, API2 157.10 MiB, worker 128.90 MiB; это не peak RSS | | Persistence Lab2/3 на Lab5 | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | **PASS** (15.11): ранее подтверждённые данные, байты вложения и действующая сессия сохранились после выполнения restart hook | | Failover одной FastAPI-реплики | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd` | **PASS** (15.11): 2 экземпляра до отказа, 6 успешных записей, 1 неудачная попытка; первое успешное восстановление за 6.172 s; данные и сессия сохранены | | Восстановление 2 API и повторный smoke | `docker compose ... up -d --no-deps --wait api1 api2`; `python tests/smoke.py`; `docker compose ps` | **PASS** (15.11): обе API healthy, smoke PASS, инфраструктура запущена | `4.182 RPS` — скорость **приёма HTTP 202** во втором прогоне, а не производительность worker; `29.781 s` — время завершения всех 10 задач. Дополнительные прогоны 14–15.11: `broker-persistence`, `staging-cleanup`, `failed-replay`, `persistence` и `failover` — PASS после исправления тестового клиента. Первый прогон `failed-replay` падал из-за ошибки теста, затем перепроверен успешно. Новые проверки `pipeline_extended.py` работают только при `LAB5_ALLOW_FAILURE_TEST=yes`, не стирают volumes и не запускаются автоматически; их нельзя объявлять прошедшими без реального вывода. ### Границы проверки restart/failover `tests/resilience.py` **подавляет stdout/stderr hook** и выводит `Hook scope needs operator evidence`. Прочитанные `scripts/restart.cmd`/`scripts/stop-one.cmd` действительно содержат команды остановки и запуска соответствующих контейнеров; однако сам вывод `PASS` подтверждает **наблюдаемый эффект теста**, а не сам по себе независимую запись событий Docker. Для защиты удобно сохранить `docker compose ps`, показать сами `.cmd` и при необходимости провести повторный прогон с дополнительными логами Docker. Failover не бесшовный: **1 неудачная попытка записи**, восстановление в тесте около **6.172 s**. Сценарий с одним Docker-хостом не доказывает устойчивость к потере хоста. Полный фактический результат последнего прогона: [`evidence/verified_results_2026-11-15.md`](evidence/verified_results_2026-11-15.md). Приведённые результаты — пользовательские логи на Windows; архив v6 подготовлен без повторного запуска Docker в среде сборки. ## Ограничения - **Одиночный broker, S3, PostgreSQL, Redis и HAProxy** являются точками отказа. RabbitMQ volume выдерживает restart при сохранении диска, но не потерю хоста. - Время обработки зависит от Pillow и S3. При нагрузке очередь растёт; учебный admission cap проверяется простым счётчиком, а не атомарным глобальным семафором. - Доставка RabbitMQ at least once, поэтому возможны дубликаты публикаций и обработок, но БД не фиксирует второй набор вариантов. - Worker lease обеспечивает восстановление после смерти; в этом кандидате нет периодического продления lease во время обработки. Время lease сделано больше budget subprocess; на сильно перегруженном узле возможны повторные попытки. - Пакет создан на основе **предыдущего кандидата Lab4**, а не автоматически синхронизирован с последним Git-коммитом пользователя. Перед MR сравнить отличия с собственной Lab4. - Набор тестов на текущем учебном стенде пройден, но не заменяет независимую проверку преподавателем и стресс-/долгосрочное тестирование. Однозначных доказательств устойчивости к отказу физического хоста или exact-once нет. ## Полезные различия для защиты **Publisher confirm** — брокер подтвердил приём persistent сообщения. **Consumer ack** — worker завершил обработку и клиент брокера подтвердил удаление сообщения из очереди. **202** — уже сохранены staging bytes + metadata/job/outbox, но не варианты. **Idempotency key эффекта** — `(attachment_id,pipeline_version,variant)`. **Lease** — ограниченный срок права обработчика на работу; истёкший lease подбирает dispatcher. **Exactly-once** не обещаем: одна логическая операция может доставляться и исполняться несколько раз, итоговая запись идемпотентна.