225 lines
26 KiB
Markdown
225 lines
26 KiB
Markdown
# Лабораторная 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](evidence/runtime.json), [containers.json](evidence/containers.json). Синтетический HTTP-стенд доступен только на `127.0.0.1:8085`.
|
||
|
||
```sh
|
||
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](requirements.txt).
|
||
|
||
Безопасная остановка сохраняет volumes: `make down`. Намеренное удаление **только учебных данных пятой работы**: `./scripts/compose.sh down -v`. После удаления volumes старые пользователи, сессии, очередь и файлы восстановить нельзя. Проекты лабораторных 2–4 имеют другие Compose names, порты и volumes.
|
||
|
||
## Архитектура и переход с lab4
|
||
|
||
```mermaid
|
||
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.
|
||
|
||
```sh
|
||
./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](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](evidence/check.txt), [validate](evidence/validate.txt) |
|
||
| Публичный минимум 1–5 | `make test` | PASS: 202, сообщение, ready, SHA оригинала, настоящий JPEG thumbnail | [smoke](evidence/smoke.txt) |
|
||
| Сессии/кэш из lab2 | cache_consistency.py | Подделанный/устаревший кэш отвергнут, logout сохраняет отзыв, 8/8 идентификаций верны | [cache](evidence/cache-consistency.txt) |
|
||
| Две API и message idempotency | idempotency_concurrent.py | 16 запросов через две реплики → одно сообщение | [idempotency](evidence/idempotency.json) |
|
||
| Приватный S3, least privilege | private_storage.py | Анонимные list/get 403; admin/посторонний prefix запрещены; console недоступна | [private storage](evidence/private-storage.json) |
|
||
| Ограничения и авторизация файлов | uploads_negative.py | 21 отрицательный сценарий, включая обрыв HTTP без сохранения частичного файла | [negative](evidence/uploads-negative.json) |
|
||
| Worker не нужен для приёма | lifecycle.py | 202 queued, content 409, сообщение принято при остановленном worker | [lifecycle](evidence/lifecycle.json) |
|
||
| Устойчивость API/outbox | lifecycle.py | SIGKILL обеих API после 202 до publish; прежнее вложение завершается | [lifecycle](evidence/lifecycle.json) |
|
||
| Persistence брокера | lifecycle.py | Очередь сохранена после restart broker на прежнем volume | [lifecycle](evidence/lifecycle.json) |
|
||
| Thumbnail/crop/WebP | image_variants.py | EXIF, белый alpha, no-upscale, crop по центру, 1280×640, размеры/hash реальны | [variants](evidence/image-variants.json) |
|
||
| Разрыв COMMIT/publish и повтор publish | pipeline_faults.py, lifecycle.py | Outbox доставлен после восстановления; повтор не размножает эффект | [faults](evidence/pipeline-faults.json) |
|
||
| Падение после S3 до ack | drive_job.py + pipeline_faults.py | Exit 86, незавершённая broker delivery восстановлена, четыре объекта | [faults](evidence/pipeline-faults.json) |
|
||
| Lease после смерти worker | lifecycle.py | Реальное ожидание lease, та же job становится ready на второй попытке | [lifecycle](evidence/lifecycle.json) |
|
||
| Backoff/jitter/failed/replay | pipeline_faults.py | Пять попыток, retry_exhausted, безопасный replay; ready replay отвергнут | [faults](evidence/pipeline-faults.json) |
|
||
| Время/память subprocess | cleanup_and_limits.py | Реальный timeout на тестовом бюджете 50 мс и MemoryError при 32 MiB классифицированы | [limits](evidence/cleanup-and-limits.json) |
|
||
| Staging retention/cleanup | cleanup_and_limits.py | Dry-run/apply/repeat; активный staging сохранён, orphan удалён | [cleanup](evidence/cleanup-and-limits.json) |
|
||
| Backpressure и отказ брокера | backpressure.py | 100 приняты без broker, следующий 429, сообщения доступны, все 100 ready после восстановления | [backpressure](evidence/backpressure.json) |
|
||
| Перезапуск всех сервисов | `make test-persistence` + snapshots | Сессия/данные/файл сохранены; StartedAt изменён у всех 10 работающих контейнеров, volumes прежние | [persistence](evidence/persistence.txt), [проверка hook](evidence/persistence-verified.json) |
|
||
| Отказ одной API | `make test-failover` | Запись восстановлена в допустимый бюджет, подтверждённые сообщения/файл сохранены | [failover](evidence/failover.txt) |
|
||
| Уровень 5, трек 2 | `make research` | Три повтора crash/duplicates/reorder, новая версия защищена, инварианты выполнены | [RESEARCH.md](RESEARCH.md) |
|
||
|
||
Реальный вывод основных команд:
|
||
|
||
```text
|
||
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](RESEARCH.md). Сценарии включают реальный consumer-group redelivery и отдельные процессы, завершённые `os._exit(86)`.
|
||
|
||
<!-- BEGIN RESEARCH RESULTS -->
|
||
|
||
| Сценарий | Повторы | Среднее, мс | 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 |
|
||
|
||

|
||
|
||
<!-- END RESEARCH RESULTS -->
|
||
|
||
Время таблицы — длительность тестового сценария с запуском процессов; в матрице lease ускорен SQL-командой. Это не время ожидания реального lease и не production latency. Отдельный lifecycle использует реальные часы. Дополнительные результаты автоматически сведены ниже.
|
||
|
||
<!-- BEGIN OPERATIONAL RESULTS -->
|
||
|
||
### Восстановление и ограничения
|
||
|
||
| Воздействие | Реальное наблюдение | Результат |
|
||
| --- | --- | --- |
|
||
| Остановка 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 искусственно сдвигается, так что таблица показывает записанные интервалы, а не фактически выжданные паузы.
|
||
|
||
<!-- END OPERATIONAL RESULTS -->
|
||
|
||
Raw JSON/CSV и PNG/SVG хранятся в `evidence/`. График и таблица исследования пересобираются `scripts/summarize_research.py`, операционные таблицы — `scripts/summarize_operations.py`; ручные PASS не заменяют assert сценариев.
|