26 KiB
Лабораторная 5. Очереди и асинхронная обработка изображений
- Автор: Савин Александр БВТ2303;
- Целевая оценка: 5, выполнены уровни 3 и 4; трек 2 — доказанная идемпотентность pipeline.
Запуск из чистого clone
Нужны Git, Python 3.9+ для публичных HTTP-проверок, Python 3.11+ для локального окружения исследования, Docker Engine с Compose v2. На macOS использована Colima, Linux arm64, 4 vCPU и около 8 GiB RAM. Docker-версии и фактические ресурсы: runtime.json, containers.json. Синтетический HTTP-стенд доступен только на 127.0.0.1:8085.
git clone https://gitea.privcloud.tech/healby/mtusi2026lab5.git
cd mtusi2026lab5
./scripts/bootstrap.sh
./scripts/compose.sh config --quiet
make up
make check
make test
# Полная проверка OpenAPI и генератор графиков:
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-research.txt
make validate PYTHON=.venv/bin/python
# Проверки предыдущих возможностей и вариантов:
make test-extra
# Автоматические crash/retry/version/cleanup-сценарии:
make research
# Эти сценарии управляют сервисами; выполнять последовательно:
python3 tests/lifecycle.py > evidence/lifecycle.json
python3 tests/backpressure.py > evidence/backpressure.json
python3 scripts/container_snapshot.py > evidence/persistence-before.json
make test-persistence ACTION_SCRIPT=scripts/restart.sh > evidence/persistence.txt
python3 scripts/container_snapshot.py > evidence/persistence-after.json
python3 scripts/verify_persistence.py > evidence/persistence-verified.json
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
./scripts/compose.sh start api
python3 scripts/wait_ready.py
python3 scripts/container_snapshot.py > evidence/containers.json
.venv/bin/python scripts/summarize_research.py
python3 scripts/summarize_operations.py
bootstrap.sh создаёт .env с тремя случайными секретами и портом 8085, не перезаписывая существующий файл. .env исключён из Git и Docker build context. Миграции PostgreSQL и создание приватного bucket/ограниченной учётной записи S3 выполняют одноразовые сервисы migrate и s3-init. Повторный запуск безопасен. Зафиксированы PostgreSQL 16.6, Valkey 8.0.2, HAProxy 3.0.5, Python 3.11.11, MinIO/mc по digest; Python-библиотеки — в requirements.txt.
Безопасная остановка сохраняет volumes: make down. Намеренное удаление только учебных данных пятой работы: ./scripts/compose.sh down -v. После удаления volumes старые пользователи, сессии, очередь и файлы восстановить нельзя. Проекты лабораторных 2–4 имеют другие Compose names, порты и volumes.
Архитектура и переход с lab4
flowchart LR
C[Клиент] --> LB[HAProxy]
LB --> A[API ×2]
A --> DB[(PostgreSQL: metadata, jobs, outbox)]
A --> S[(MinIO: staging)]
DB --> P[Publisher]
P --> B[(Valkey Streams + AOF)]
B --> W[Worker]
W --> D[Pillow subprocess]
W --> S3[(MinIO: results/id/version)]
W --> DB
A --> K[(Valkey: кэш сессий)]
Из предыдущих работ сохранены Argon2id-пароли, устойчивые сессии и отзыв, авторизация участников чата, Unicode, keyset-пагинация, атомарная идемпотентность сообщений на 24 часа, две API-реплики и балансировка, проверка файлов, приватный S3 и авторизованная потоковая выдача оригинала. Источник истины для состояния — PostgreSQL; кэш не может подменить сессию/пользователя. Байты хранятся в MinIO.
Объявленный переход: upload 201 ready заменён на 202 queued; метаданные доступны до готовности, content отвечает 409, а queued/processing можно прикрепить к сообщению. Failed прикреплять нельзя. Новая миграция переводит существующие ready/pending-вложения lab4 в очередь, используя старый оригинал как источник; новая установка получает пустые таблицы. Автоматический reconciler из исследовательского трека lab4 заменён подходящей для асинхронной работы очисткой staging; прежний алгоритм нельзя применять к текущим queued jobs.
Границы устойчивости
- API аутентифицирует клиента, проверяет чат/имя/MIME/bytes/пиксели/целостность. Приём идёт небольшими блоками в ограниченный временный spool; это ещё не durable staging.
- Под общей advisory-блокировкой приёма проверяется лимит активных jobs. Полный оригинал записывается в приватный
staging/<UUID>MinIO на persistent volume. - В одной транзакции PostgreSQL создаются attachment, job и outbox. После COMMIT возвращается снимок queued. Падение после S3 до COMMIT может оставить только непринятый orphan; он убирается после retention. Такой запрос не получит подтверждённого 202.
- Publisher читает outbox, выполняет XADD и только затем сохраняет published_at. Ответ XADD при
appendfsync=always— граница подтверждения брокером. Если процесс упал после XADD до COMMIT outbox, публикация повторится. Если упал после COMMIT API до publish, сохранённый outbox будет найден при запуске publisher. - Worker использует consumer group и
XREADGROUP COUNT 1. Краткая транзакция фиксирует processing, attempt и lease. Следующая транзакция блокирует job и attachment, проверяет поколение/попытку и держит блокировки до записи всех S3-эффектов и COMMIT ready. Живой worker не теряет право на эффект только из-за истечения времени lease. - После устойчивого результата worker выполняет XACK, затем XDEL обработанной доставки. При временной ошибке ack допустим только после сохранения нового намерения retry в БД. Необработанная доставка остаётся pending;
XAUTOCLAIMпозволяет её восстановить после остановки consumer.
Staging уже находится в том же MinIO, что и результаты: приём файла включает S3 PUT. Асинхронная граница отделяет resize/encode и публикацию конечного results/ от HTTP, а не устраняет передачу байтов клиентом. Readiness требует PostgreSQL и S3; брокер, worker и необязательный кэш не включены, поскольку 202 можно безопасно принять через staging/outbox и при их остановке.
Варианты, состояния и лимиты
| Вариант | Правила |
|---|---|
| original | Побайтно исходный PNG/JPEG; SHA-256 и размер из upload |
| thumbnail | JPEG, вписан в 256×256, без увеличения, размеры округляются вниз, минимум 1 px |
| crop | JPEG, центральный квадрат 128×128, маленькие допускается увеличивать |
| optimized | WebP, вписан в 1280×1280, без увеличения |
EXIF orientation применяется до геометрии; прозрачность компонуется на белый фон. Метаданные EXIF не переносятся в варианты; оригинал сохраняет исходные байты. Для v1 JPEG quality=85, WebP quality=80; для v2 и следующих JPEG=90, WebP=85. Optimized не обязан быть меньше каждого небольшого оригинала.
В API доступны queued → processing → ready/failed и processing → queued при временной ошибке. Error_code безопасный, без внутренних адресов и traceback. Готовность фиксируется после оригинала и всех трёх вариантов. Content проверяет авторизацию и статус для каждого запроса; redirect или публичная ссылка S3 не используются.
HTTP ограничен 10 MiB, 40 млн пикселей, 30 секундами передачи и 5 секундами простоя; одновременно принимаются два файла на API. Обработка выполняется в отдельном subprocess: 20 секунд на decode/encode, RLIMIT_AS 640 MiB, весь контейнер worker — 768 MiB. Процесс обработки получает минимальное окружение без credentials. Чрезмерно затратное, но формально допустимое по пикселям изображение может получить конечный resource_limit; 40 млн пикселей — защитный максимум, не обещание обработки при любом содержимом и выделенной памяти.
Обычный worker последовательный, prefetch/count=1; число отдельных workers можно увеличить через --scale worker=N. Максимум 100 queued/processing jobs контролируется транзакционно на всех API. При заполнении — 429 до записи нового staging. Это ограничение текущей работы, не общий лимит хранения всей истории файлов.
Retry, failed, replay и cleanup
Временные S3-сбои и timeout повторяются до 5 управляемых попыток: задержка uniform(0.5,1.5) × min(30, 2^(attempt−1)) секунд. Сам broker redelivery не создаёт новую логическую job. Неисправный/отсутствующий staging, invalid_image или resource_limit дают failed; исчерпание временных попыток — retry_exhausted. Registry failed — таблица jobs, а не отдельная очередь с потерянным контекстом. Операторский replay сбрасывает бюджет попыток текущей failed-job, пишет audit и не допускается для ready или отсутствующего staging.
./scripts/compose.sh run --rm --no-deps ops python manage.py failed
./scripts/compose.sh run --rm --no-deps ops python manage.py replay JOB_UUID
./scripts/compose.sh run --rm --no-deps ops python manage.py upgrade ATTACHMENT_UUID
# Очистка: безопасный dry-run по умолчанию:
./scripts/compose.sh run --rm --no-deps ops python janitor.py --once
./scripts/compose.sh run --rm --no-deps ops python janitor.py --once --apply
Lease по умолчанию 30 секунд и не меньше timeout+5. Зависшая processing после смерти worker захватывается заново; старый процесс дополнительно ограничен блокировками и версией. Повторы получают те же ключи (attachment_id, pipeline_version, variant). Старый job не может откатить ready или опубликовать результат поверх новой версии. PUT после аварии может повториться — это идемпотентность эффекта, а не exactly-once доставка.
Janitor запускается раз в минуту и удаляет staging старше суток только после проверки состояния под блокировками. Он сохраняет queued/processing независимо от возраста, удаляет orphan после неудавшегося upload и удерживает failed-источники сутки для replay. Dry-run ничего не меняет, повторный apply идемпотентен. Готовые объекты и старые опубликованные версии автоматически не удаляются. Источник новой версии может ссылаться на готовый original предыдущей версии; такой объект не попадает в staging cleanup.
Где настраивается
Реальные локальные параметры показаны в infra/local.env.example; bootstrap.sh генерирует секреты отдельно. В исходном .env.example заданы логические интерфейсы задания, а не готовая конфигурация этого стенда.
| Переменная/настройка | Реальная реализация |
|---|---|
| APP_PORT, API_REPLICAS | .env → Compose: порт 8085, две API |
| DATABASE_URL_FILE, CACHE_URL_FILE | Используются прямые DATABASE_URL/CACHE_URL в окружении контейнеров; значения собираются Compose из локальных секретов |
| S3_*_FILE | Прямые S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEY в контейнерах; только s3-init получает административные credentials |
| BROKER_URL_FILE | Прямой BROKER_URL=redis://broker:6379/0, внутренняя сеть, порт наружу не опубликован |
| WORKER_CONCURRENCY | Внутри worker фиксировано 1, горизонтальное число задаётся --scale worker=N |
| JOB_MAX_ATTEMPTS | .env, по умолчанию 5 |
| JOB_TIMEOUT_SECONDS, JOB_LEASE_SECONDS | .env, 20 и 30 секунд; минимальный lease=timeout+5 |
| MAX_PENDING_JOBS | .env, 100 на весь проект |
| STAGING_RETENTION_SECONDS | .env, 86400, janitor не допускает меньше 60 секунд |
| MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS | Фиксированные контрактом 10 MiB/40 млн в attachments.py, пиксельный лимит также в transform.py |
| SESSION_TTL_SECONDS | 3600 в Compose, проверяется PostgreSQL, TTL не продлевается рестартом |
Доказательства критериев
| Критерий | Команда/сценарий | Наблюдение | Доказательство |
|---|---|---|---|
| Структура и контракт | make check, make validate PYTHON=.venv/bin/python |
PASS | check, validate |
| Публичный минимум 1–5 | make test |
PASS: 202, сообщение, ready, SHA оригинала, настоящий JPEG thumbnail | smoke |
| Сессии/кэш из lab2 | cache_consistency.py | Подделанный/устаревший кэш отвергнут, logout сохраняет отзыв, 8/8 идентификаций верны | cache |
| Две API и message idempotency | idempotency_concurrent.py | 16 запросов через две реплики → одно сообщение | idempotency |
| Приватный S3, least privilege | private_storage.py | Анонимные list/get 403; admin/посторонний prefix запрещены; console недоступна | private storage |
| Ограничения и авторизация файлов | uploads_negative.py | 21 отрицательный сценарий, включая обрыв HTTP без сохранения частичного файла | negative |
| Worker не нужен для приёма | lifecycle.py | 202 queued, content 409, сообщение принято при остановленном worker | lifecycle |
| Устойчивость API/outbox | lifecycle.py | SIGKILL обеих API после 202 до publish; прежнее вложение завершается | lifecycle |
| Persistence брокера | lifecycle.py | Очередь сохранена после restart broker на прежнем volume | lifecycle |
| Thumbnail/crop/WebP | image_variants.py | EXIF, белый alpha, no-upscale, crop по центру, 1280×640, размеры/hash реальны | variants |
| Разрыв COMMIT/publish и повтор publish | pipeline_faults.py, lifecycle.py | Outbox доставлен после восстановления; повтор не размножает эффект | faults |
| Падение после S3 до ack | drive_job.py + pipeline_faults.py | Exit 86, незавершённая broker delivery восстановлена, четыре объекта | faults |
| Lease после смерти worker | lifecycle.py | Реальное ожидание lease, та же job становится ready на второй попытке | lifecycle |
| Backoff/jitter/failed/replay | pipeline_faults.py | Пять попыток, retry_exhausted, безопасный replay; ready replay отвергнут | faults |
| Время/память subprocess | cleanup_and_limits.py | Реальный timeout на тестовом бюджете 50 мс и MemoryError при 32 MiB классифицированы | limits |
| Staging retention/cleanup | cleanup_and_limits.py | Dry-run/apply/repeat; активный staging сохранён, orphan удалён | cleanup |
| Backpressure и отказ брокера | backpressure.py | 100 приняты без broker, следующий 429, сообщения доступны, все 100 ready после восстановления | backpressure |
| Перезапуск всех сервисов | make test-persistence + snapshots |
Сессия/данные/файл сохранены; StartedAt изменён у всех 10 работающих контейнеров, volumes прежние | persistence, проверка hook |
| Отказ одной API | make test-failover |
Запись восстановлена в допустимый бюджет, подтверждённые сообщения/файл сохранены | failover |
| Уровень 5, трек 2 | make research |
Три повтора crash/duplicates/reorder, новая версия защищена, инварианты выполнены | RESEARCH.md |
Реальный вывод основных команд:
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
PASS: lab5 public API scenario; infrastructure and grading evidence remain separate.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
make check не запускает приложение; сквозные и инфраструктурные доказательства приведены отдельно. Снимки контейнеров намеренно не содержат окружение и credentials.
Исследование уровня 5
Гипотеза: outbox, version fencing и устойчивые ключи S3 сохраняют логический результат при дублировании/изменении порядка/аварии worker. Методика, аппаратные ограничения, размеры файлов и границы выводов изложены в RESEARCH.md. Сценарии включают реальный consumer-group redelivery и отдельные процессы, завершённые os._exit(86).
| Сценарий | Повторы | Среднее, мс | min–max, мс | SD, мс | Объектов текущей версии | Ошибки |
|---|---|---|---|---|---|---|
| Падение до PUT | 3 | 1550.718 | 1321.347–1786.888 | 232.845 | 4 | 0 |
| Падение после PUT | 3 | 1549.527 | 1334.593–1872.025 | 284.404 | 4 | 0 |
| Падение после COMMIT до ack | 3 | 1383.915 | 1275.246–1590.414 | 178.915 | 4 | 0 |
| 8 конкурентных дублей | 3 | 143.795 | 121.12–172.849 | 26.448 | 4 | 0 |
| Старая версия после новой | 3 | 223.21 | 109.191–440.476 | 188.235 | 4 | 0 |
Время таблицы — длительность тестового сценария с запуском процессов; в матрице lease ускорен SQL-командой. Это не время ожидания реального lease и не production latency. Отдельный lifecycle использует реальные часы. Дополнительные результаты автоматически сведены ниже.
Восстановление и ограничения
| Воздействие | Реальное наблюдение | Результат |
|---|---|---|
| Остановка worker, SIGKILL API до publish, restart broker | Длина stream 1 → 1; ready через 3.023 с после запуска worker | PASS, исходник сохранён |
| Смерть worker после PUT, настоящий lease | Ready через 28.923 с; попыток 2 | PASS, без ускорения часов |
| Остановка broker и заполнение очереди | Принято 100; следующий HTTP 429; восстановлено 100 за 24.64 с | PASS, потеряно 0 |
| Перезапуск всего стенда | 10 реальных процессов, прежние volumes и сессия | PASS |
| Отказ API | 114 успешных записей, 2 переходных ошибок; первая успешная запись через 2.171 с | PASS |
| Тайм-аут decode, тестовый бюджет 50 мс | Время сценария 68.024 мс; retry, затем ready | PASS |
| Ограничение адресного пространства, тестовый бюджет 32 MiB | Конечный resource_limit, replay завершился | PASS |
| Staging cleanup, часы +2 дня | Кандидатов 23, повторных 0; активный исходник сохранён | PASS |
Проверка геометрии реальных файлов
| Исходник/сценарий | Thumbnail | Crop | Optimized |
|---|---|---|---|
| small_alpha | 80×40 | 128×128 | 80×40 |
| exif_orientation | 64×256 | 128×128 | 100×400 |
| center_crop | 256×64 | 128×128 | 400×100 |
| large_fit | 256×128 | 128×128 | 1280×640 |
Наблюдаемые retry с jitter
| После попытки | Сохранённая задержка до следующей, с |
|---|---|
| 1 | 1.080882 |
| 2 | 2.447441 |
| 3 | 2.182634 |
| 4 | 8.307950 |
После 5-й временной ошибки зафиксирован retry_exhausted; явный replay завершается ready. При проверке расписания next_at искусственно сдвигается, так что таблица показывает записанные интервалы, а не фактически выжданные паузы.
Raw JSON/CSV и PNG/SVG хранятся в evidence/. График и таблица исследования пересобираются scripts/summarize_research.py, операционные таблицы — scripts/summarize_operations.py; ручные PASS не заменяют assert сценариев.
