Files

122 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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** не обещаем: одна логическая операция может доставляться и исполняться несколько раз, итоговая запись идемпотентна.