forked from mtusi2026/mtusi2026lab5
122 lines
18 KiB
Markdown
122 lines
18 KiB
Markdown
# Отчёт — лабораторная 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** не обещаем: одна логическая операция может доставляться и исполняться несколько раз, итоговая запись идемпотентна.
|