Files
2026-11-20 18:50:07 +03:00

26 KiB
Raw Permalink Blame History

Лабораторная 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.

Границы устойчивости

  1. API аутентифицирует клиента, проверяет чат/имя/MIME/bytes/пиксели/целостность. Приём идёт небольшими блоками в ограниченный временный spool; это ещё не durable staging.
  2. Под общей advisory-блокировкой приёма проверяется лимит активных jobs. Полный оригинал записывается в приватный staging/<UUID> MinIO на persistent volume.
  3. В одной транзакции PostgreSQL создаются attachment, job и outbox. После COMMIT возвращается снимок queued. Падение после S3 до COMMIT может оставить только непринятый orphan; он убирается после retention. Такой запрос не получит подтверждённого 202.
  4. Publisher читает outbox, выполняет XADD и только затем сохраняет published_at. Ответ XADD при appendfsync=always — граница подтверждения брокером. Если процесс упал после XADD до COMMIT outbox, публикация повторится. Если упал после COMMIT API до publish, сохранённый outbox будет найден при запуске publisher.
  5. Worker использует consumer group и XREADGROUP COUNT 1. Краткая транзакция фиксирует processing, attempt и lease. Следующая транзакция блокирует job и attachment, проверяет поколение/попытку и держит блокировки до записи всех S3-эффектов и COMMIT ready. Живой worker не теряет право на эффект только из-за истечения времени lease.
  6. После устойчивого результата 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

Исследование pipeline

Время таблицы — длительность тестового сценария с запуском процессов; в матрице 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 сценариев.