Files
mtusi2026lab5/REPORT.md
T
2026-11-20 18:50:07 +03:00

225 lines
26 KiB
Markdown
Raw 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. Очереди и асинхронная обработка изображений
- Автор: Савин Александр БВТ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 |
![Исследование pipeline](evidence/pipeline-faults.png)
<!-- 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 сценариев.