Files
mtusi2026lab5/REPORT.md
T
2026-10-26 18:05:06 +03:00

35 KiB
Raw Blame History

Лабораторная 5 — очередь и обработка изображений

  • Автор: Максим Шептунов, БВТ2301.
  • Целевая оценка: 5, трек 2 — «Доказанная идемпотентность pipeline».
  • Skeleton lab5: 276dbdad8a34da4c5b57fbf1879ca169b581d75b.
  • Заявленная основа подготовленного решения: собственная lab4, commit 16709c91b3e06028b10d72095fb1e5d2bacbc5ef; соответствие этому commit отдельно не перепроверялось.
  • Проверка: 26 октября 2026, WSL2 Ubuntu 22.04 / Docker Desktop. Факты окружения: evidence/local_environment.json.
  • Помощь ИИ: подготовка реализации и собственных проверок
  • Основные библиотеки: FastAPI 0.115.12, Uvicorn 0.34.2, Psycopg 3.2.9, redis-py 5.2.1, Pillow 12.0.0, boto3 1.40.18, argon2-cffi 23.1.0; полный фактический список — evidence/runtime_versions.json.

README задания, обязательный контракт и публичные tests сохранены. Отдельного файла миграции решения нет: перенос и переход API описаны здесь. Результаты ниже взяты из текущих логов WSL; прежняя облачная проверка не считается Docker-прогоном.

Запуск из чистого clone

Нужны Docker Desktop/Engine с Compose v2/BuildKit, Linux amd64, Python 3.10+ на хосте. В Windows используется WSL2 Ubuntu. Порт 8080 должен быть свободен; при занятом порте сначала нужно установить владельца. При текущем запуске других работающих контейнеров не было. Для сборки нужен доступ к Docker Hub, PyPI и GitHub Releases.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt -r requirements-experiment.txt
chmod +x scripts/*.sh
make setup
make start
make ready
make check
make validate
make test
make student-checks
make test-files
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
bash scripts/restore-api.sh
make ready
make test-file-failover
make test-dependencies
make test-expiry
make experiment
make ready
make test

Безопасная остановка с сохранением данных: make stop. Намеренное удаление учебных данных текущего проекта: docker compose down -v; эта команда не применяется в проверках сохранности.

setup.sh создаёт .env и случайные secrets в .secrets. Повторный setup не меняет существующие пароли. Папка имеет права 700; файлы для UID10001 — 644 внутри закрытой папки. Пароль PostgreSQL, MinIO root и broker password — 600. API не получает root credentials и broker URL. В Git и build context secrets не входят.

Все роли приложения собираются в один локальный image mtusi2026lab5-app:1. База — Python 3.12.10 slim-bookworm. PostgreSQL 16.9 bookworm; cache и broker — Redis 7.4.3 bookworm; HAProxy 3.0.11 bookworm. MinIO RELEASE.2025-04-22T22-12-26Z и mc RELEASE.2025-04-16T18-13-26Z скачиваются из официальных GitHub Releases в infra/s3.Dockerfile; закреплённые SHA-256 проверяются во время сборки.

После старта работают db, cache, broker, s3, две api, lb, dispatcher, worker и reconciler. migrate и s3-bootstrap завершаются с кодом 0 — это нормально. Общий start.sh не использует Compose --wait, поскольку у фоновых процессов нет HTTP healthcheck. Две готовые API отдельно ожидаются через LB. Readiness API проверяет PG и S3; отсутствие worker не запрещает durable приём. Сам прогресс pipeline проверяется smoke, статусами job и отдельными сценариями.

Лимиты: каждая API 1 CPU/512 MiB; worker 1 CPU/768 MiB; PG и S3 по 1 CPU/512 MiB; broker 0.5 CPU/256 MiB; dispatcher и reconciler по 0.5 CPU/256 MiB; cache/LB по 0.5 CPU/128 MiB. Фактические значения сохраняются через inspect. Docker-логи ограничены: 5 MiB × 2 файла на контейнер.

Перенос и архитектура

Перенесены пользователи, Argon2id, PostgreSQL-сессии, Redis-кеш профиля, чаты, сообщения, keyset-пагинация, общая идемпотентность, две API, HAProxy и приватный MinIO. Сохранены проверка типов cursor (400 invalid_request), выбор реально работающего контейнера вместо жёсткого индекса и исправление общего --wait. Исследования масштабирования lab3 и сверки lab4 повторно не требуются.

Изменён объявленный переход lab4 → lab5: upload возвращает 202 queued, а готовность определяется GET метаданных. Все bytes по-прежнему передаются в HTTP. Сообщение может ссылаться на queued/processing; failed прикреплять нельзя (409). Content для queued/processing/failed — 409. Для ready доступны original, thumbnail, crop, optimized; неизвестный вариант — 404. ACL чата проверяется при каждом запросе метаданных и содержимого. Публичный ответ не раскрывает S3 keys.

Роли и источник истины:

  • API принимает ограниченный файл и фиксирует намерение. SQL — источник сессий, метаданных, статусов, версий, attempts и outbox.
  • Отдельный persistent Redis Streams — broker. Cache профилей остаётся другим сервисом Redis: сброс кеша не затрагивает очередь.
  • Dispatcher публикует outbox и восстанавливает брошенные leases.
  • Worker забирает задания consumer group, обрабатывает изображение в дочернем процессе и публикует результат.
  • Reconciler в этой лабораторной выполняет безопасную очистку staging.
  • MinIO хранит staging, неизменённые оригиналы и готовые варианты.

Наружу опубликован только LB 127.0.0.1:8080. Консоль MinIO выключена и привязана к loopback контейнера. Ограниченный S3-пользователь общий для API/worker: операции разрешены только в originals/, variants/, staging/ указанного bucket; нет IAM и создания bucket. Broker защищён отдельным паролем, публичного порта нет.

Что сохранено к моменту 202

  1. API потоково пишет максимум 10485760 bytes во временный файл. Проверяет MIME, filename, структуру PNG/JPEG и максимум 40000000 pixels до полного декодирования. Для JPEG проверяется наличие EOI. Считаются SHA-256 и transport Content-MD5.
  2. Под блокировкой UUID вложения сохраняет полный исходник в S3 staging.
  3. Одной SQL-транзакцией создаёт attachment queued, job и outbox. Общая admission блокировка ограничивает число queued/processing заданиями MAX_PENDING_JOBS.
  4. После COMMIT возвращает снимок queued, даже если worker уже успел завершиться.

API не делает resize и полное декодирование пикселей. Нераспознаваемый формат/ очевидное повреждение/MIME mismatch — 415, лимиты bytes/pixels — 413, опасное имя — 400. Повреждение, обнаруженное только при полном декодировании, становится failed с безопасным кодом worker. Временный файл API не является durable staging. При неопределённом COMMIT staging немедленно не удаляется.

Broker, outbox и подтверждения

Broker использует Redis Streams consumer group image-workers, AOF и appendfsync always, persistent volume, maxmemory-policy noeviction. XADD отвечает producer после записи по выбранной AOF-политике. Если publish прошёл, но dispatcher умер до фиксации published_at, он может отправить дубль. Если умер до publish, незавершённый outbox будет опубликован после восстановления.

Carrier соответствует contracts/jobs.schema.json: schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at. Нет bytes, credentials, URL или клиентского пути. Worker сверяет job с доверенными metadata в PG. Некорректный carrier попадает в broker_rejections с hash/кодом, без исходного тела.

XACK выполняется после ready/устойчивого terminal no-op либо после фиксации следующей попытки в outbox/окончательного failed. Pending после смерти consumer забирается через XAUTOCLAIM. Publisher acknowledgement и consumer ack относятся к разным границам; доставка остаётся at least once.

Обработка, ограничения и варианты

Исходник скачивается из staging с ограничением bytes и проверкой SHA-256. Затем отдельный процесс Pillow полностью декодирует изображение, применяет EXIF orientation, ограничивает pixels и адресное пространство до 512 MiB. Родитель ограничивает время job (по умолчанию 30 s), включая проверяемые этапы download, преобразования и PUT. Синхронный вызов S3 может закончиться позже deadline на величину своего сетевого timeout (connect/read 2/5 s; Docker DNS timeout 1 s, attempts 1).

На worker по умолчанию concurrency=1 и prefetch=1 на consumer. API допускает четыре ограниченных upload на процесс; сверх очереди MAX_PENDING_JOBS=1000 новые приёмы получают 503. Значения 1..4 concurrency доступны, но увеличение требует отдельного бюджета RAM и измерений; в исследовании используется 1.

Worker публикует неизменённый original и три варианта:

Вариант Формат и правила
thumbnail JPEG, вписан в 256×256, без увеличения, размеры округляются вниз
crop JPEG, центрированный квадрат 128×128, маленькие изображения увеличиваются
optimized WebP, вписан в 1280×1280, без увеличения

Alpha компонуется на белый. EXIF/ICC/XMP в вариантах не сохраняются. Качество JPEG/WebP — 82 для pipeline v1 и 86 для v2; WebP method=4, JPEG optimize=true. Original не перекодируется. WebP не обязан быть меньше каждого маленького PNG. Ready фиксируется только после оригинала и всех трёх вариантов, вместе с их размерами/checksums и внутренними keys.

Lease, retry, failed и replay

Worker держит PostgreSQL session advisory lock на attachment UUID. При захвате фиксирует processing, очередную attempt, lease token и deadline. Dispatcher возвращает истёкший processing в очередь только если общий lock свободен. Lease=15 s может истечь во время корректной длинной обработки; активный lock защищает её. Зависшая обработка ограничена job timeout и лимитами процесса.

Одна попытка не равна одному broker redelivery: устаревшие attempts и дубли завершённых jobs подтверждаются без повторной обработки. По умолчанию максимум 5 управляемых попыток. Для временных сетевых/хранилищных ошибок — exponential backoff с jitter, базовая пауза до 10 s + 0..0.5 s. Невалидный исходник, отсутствие staging и неверные S3 credentials — постоянные ошибки. После исчерпания временных попыток error_code=retry_exhausted. Текст SDK/stack trace наружу не выдаётся.

DLQ реализована как устойчивый реестр jobs со status=failed плюс job_events. Команды выполняются оператором внутри контейнера; публичного admin endpoint нет:

docker compose exec -T dispatcher python -m src.jobs failed
docker compose exec -T dispatcher python -m src.jobs inspect JOB_UUID
docker compose exec -T dispatcher python -m src.jobs replay JOB_UUID
docker compose exec -T dispatcher python -m src.jobs version ATTACHMENT_UUID 2

Replay разрешён только для текущей failed job при доступном staging. Job ID и effect key сохраняются; номер attempt растёт, новый бюджет начинается после явного replay. Уже ready → noop; старая версия не активируется replay-командой. Версия повышается только отдельной операторской командой.

Версии и идемпотентность эффекта

Ключ эффекта — (attachment_id, pipeline_version, variant). В PG уникальна пара attachment/version; S3 keys детерминированы и включают version. Повтор может ещё раз выполнить PUT в тот же key, но не создаёт дополнительные variants.

Перед processing проверяется current_job_id/version; перед публикацией — ещё lease token и условный UPDATE текущей версии. Общий lock сериализует изменения. Старая job после появления v2 становится no-op и не откатывает ready в processing. Вторая версия действительно меняет настройки encoder, а не только название.

Это не exactly-once доставка: XADD/получение/PUT могут повториться. Проверяется однократная публикация устойчивого результата одной job и отсутствие перезаписи текущего результата старой версией.

Очистка и retention

После ready staging удаляется; отдельная сверка каждые 60 s повторяет очистку, если worker умер после COMMIT. Failed/superseded staging и объекты без job хранятся 86400 s. Перед удалением повторно проверяются PG, реальный LastModified и общий lock; queued/processing не удаляются. Dry-run по умолчанию:

make cleanup
docker compose run --rm --no-deps reconciler python -m src.cleanup --apply

Предыдущие опубликованные версии original/variants оставлены для аудита; их автоматический GC не заявляется. Старые lab4 ready-оригиналы сохраняются миграцией; варианты для них можно создать командой новой версии. Переносится реализация, старые Docker volumes между разными проектами автоматически не подключаются.

Доказательства критериев

Структура и OpenAPI проверены отдельно от работающего HTTP-приложения. Ниже результаты текущего последовательного прогона. Полный трек 2 завершён: status=PASS, checks=39; финальный HTTP smoke прошёл после серии и дополнительного отказа второй API.

Критерий Команда Наблюдение моего стенда Evidence
Структура/OpenAPI make check; make validate PASS: структура, ссылки, синтаксис и OpenAPI 3.1 local_check.txt, local_validate.txt
Обязательный lab5 API make test PASS: публичный сквозной HTTP-сценарий local_smoke.txt, local_final_smoke.txt
Минимум предыдущих работ, SQL/cursor/ключи make student-checks PASS: гонки регистрации, 100 сообщений от 10 клиентов, cursor, idempotency и SQL rollback local_student_checks.txt, idempotency.json
Отрицательные файлы, ACL и сообщение с вложением make test-files PASS: MIME/filename/bytes/pixels, ACL, повтор сообщения local_files.txt
Реальные thumbnail/crop/WebP, EXIF/alpha/маленький файл make test-files PASS: реальные форматы, размеры, белый фон, EXIF orientation, отсутствие увеличения local_files.txt
Перезапуск всех хранилищ и прежняя сессия make test-persistence PASS: подтверждённые данные, original и старая сессия сохранены; 4 хранилища перезапущены local_persistence.txt, containers_before_retry.json, containers_after_restart.json, persistence_scope.json
Отказ одной API и original через другую make test-failover; make test-file-failover PASS: 114 подтверждённых записей, 3 неудачные попытки, восстановление 2.581 s; original через другую API local_failover.txt, local_file_failover.txt, attachment_failover.json
Redis/PG outage, expiry make test-dependencies; make test-expiry PASS: fallback без cache, PG → 503 и восстановление прежних данных/сессии; TTL=2 s → отказ истёкшей сессии dependencies.json, local_dependencies.txt, local_expiry.txt
Worker stop, queued message, API/broker restart make experiment PASS ×3: 202 при выключенном worker, queued message, прежние stream IDs и ready после рестартов pipeline_raw.json: accepted_restart_broker_api
Outbox COMMIT/publish и publish/mark crash make experiment PASS ×3 для каждого окна: outbox доставил прежнюю job после реального crash dispatcher pipeline_raw.json: before_publish, after_publish
Crash до/после S3 и до ack, lease recovery make experiment PASS ×3 для каждого окна: до ready — 2 попытки; после COMMIT ready — 1 попытка pipeline_raw.json: before_effect, after_original, after_effects, after_commit
Дубли и схема carrier make experiment PASS ×3: по 16 дублей, неизменные metadata/bytes, неверный carrier отклонён pipeline_raw.json: duplicates_and_invalid_carrier
Reorder и stale после новой версии make experiment PASS ×3 для каждого случая: v2 сохранена, v1 не меняет текущие bytes/metadata pipeline_raw.json: reorder_new_before_old, stale_after_new_ready
Постоянная ошибка и безопасный replay make experiment PASS ×3: staging_missing → явный replay той же job → ready; replay ready = noop pipeline_raw.json: permanent_failure_replay
Физический S3 outage, пять попыток, failed/replay make experiment PASS ×3: retry_exhausted после 5 попыток; replay → ready на 6-й попытке pipeline_raw.json: bounded_retry_and_replay
Retention, fresh/active и приватность make experiment PASS ×3: старый orphan удалён, fresh/queued сохранены, anonymous GET=403 pipeline_raw.json: staging_retention_and_privacy

Фактическое окружение и найденная ошибка

Intel Core i5-1240P; WSL видит 16 CPU. Docker Server 26.1.1, Compose 2.27.0-desktop.2; Docker видит 16 CPU и 8 187 711 488 bytes RAM. Хостовый Python 3.10.12, runtime контейнера 3.12.10. Фактические runtime/библиотеки/image IDs и mounts — runtime_versions.json. Broker подтверждён с AOF=1, appendonly=yes, appendfsync=always и noeviction (broker_runtime.json). Лимиты контейнеров сохранены в containers_before_retry.json и containers_after_restart.json; факт перезапуска db/cache/s3/broker — в persistence_scope.json.

Первый persistence выявил дефект infra/broker-entrypoint.sh: после первого запуска /tmp/broker.conf принадлежал redis; повторная root redirection в sticky /tmp блокировалась Linux protected_regular («Permission denied»). Конфиг перенесён в /run/broker/broker.conf внутри root-owned каталога. AOF, Redis-настройки и volume сохранены. После исправления persistence прошёл. Неудачные логи сохранены в local_persistence_failed_initial.txt, local_restart_diagnostic.txt, broker_restart_diagnostic.txt; успешный повтор — local_restart_fixed.txt и local_persistence.txt. Попытка запустить persistence до восстановления остановленного стенда также сохранена отдельно: local_persistence_failed_stopped_stack.txt.

Перед переносом рабочий Git был чист от tracked-изменений; существовали только пользовательские AGENTS.md и CODEX_HANDOFF.md. Сохранены они и .git. Решение распаковано из incoming/mtusi2026lab5_solution.zip; добавлено 47 файлов, изменены .dockerignore, .gitignore, Makefile и REPORT.md, 32 файла совпали. Сравнение — import_comparison.json. Текущий upstream HEAD совпал со skeleton. Контракты, публичные tests, README и COURSE не изменены. Старые лабы и volumes не удалялись; commit/push/MR не выполнялись.

Эксперимент на 5

Гипотеза: durable staging/outbox, consumer group, versioned keys и проверка версии при COMMIT позволяют пережить дубли, reorder и crashes без потери подтверждённой работы и публикации старого результата поверх нового.

make experiment выполняет 13 случаев по три раза — 39 проверок. Для каждого создаются новые синтетические пользователи/чат/attachment/job; fixture 320×200. Worker concurrency=1, prefetch=1, максимум 5 попыток; остальные лимиты выше. Настройки, версии Docker/Compose, actual containers/limits фиксируются в pipeline_environment.json. В research серии не измеряется предельный throughput.

Fault injection — адресные одноразовые checkpoints для конкретного job UUID. Они выключены при обычном ALLOW_FAULT_INJECTION=0. Скрипт временно пересоздаёт worker/dispatcher с флагом 1. После устойчивой отметки checkpoint выполняется os._exit: нет finally и ack, процесс реально умирает, Docker restart:on-failure возвращает его. В evidence сохраняются fired_at, events, aliases/RestartCount и состояния контейнеров. После эксперимента флаг возвращается в 0.

Проверки не создают вручную новое задание для исправления outbox: accepted job должна восстановиться сама. Для дубликатов/reorder намеренно публикуются повторные carrier уже существующих jobs. Поздний v1 проверяется после готового v2. При S3 outage сервис физически остановлен; после failed возвращается S3, оператор явно запускает replay той же job.

Для каждого ready проверяются original/checksum, три варианта/checksums, ровно четыре key текущей версии, один ready event на job, очистка staging. В duplicate/stale случаях сравнивается весь публичный Attachment до/после: ID, updated_at, variants и checksums не должны измениться. При broker restart проверяются те же опубликованные stream IDs после восстановления volume.

Raw: evidence/pipeline_raw.json; сводка: pipeline_summary.json. Каждый случай содержит длительность сценария с управляющими действиями Docker, attempts, job events/outbox и результат инвариантов. queued_to_ready_seconds считается между SQL-временем создания job и публикации ready, включая намеренные остановки. Эти времена не являются чистой стоимостью resize или production SLA. При незавершённом/ошибочном запуске summary не остаётся старым PASS.

Реальные результаты 26.10.2026

Полная команда: make experiment (repeats=3). Итог: PASS, 39/39, все 13 случаев завершились по три раза. Сумма длительностей сценариев — 1947.325 s (32.46 min); это последовательный эксперимент с управлением Docker и намеренными остановками, включая backoff и lease. Fixture — PNG 320×200, 111817 bytes, SHA-256 99ea7533c441f79cd630d15ce4d58d1ec4e06f6f0efb3b77a5c088305cd1bd75. Рабочая конфигурация: concurrency=1, prefetch=1, lease=15 s, timeout=30 s, максимум 5 попыток до явного replay. Отдельный прогрев и нагрузочный профиль не применялись: это проверка корректности при отказах, не измерение предельного throughput. RPS и p95/p99 resize в этом треке не измерялись.

Сценарий Итог Медиана полного сценария, s Attempts итоговой job
accepted_restart_broker_api 3/3 PASS 62.692 1
before_publish 3/3 PASS 45.890 1
after_publish 3/3 PASS 44.544 1
before_effect 3/3 PASS 45.350 2
after_original 3/3 PASS 43.115 2
after_effects 3/3 PASS 46.272 2
after_commit 3/3 PASS 36.306 1
duplicates_and_invalid_carrier 3/3 PASS 36.795 1
reorder_new_before_old 3/3 PASS 57.728 1
stale_after_new_ready 3/3 PASS 54.823 1
permanent_failure_replay 3/3 PASS 56.230 2
bounded_retry_and_replay 3/3 PASS 75.655 6
staging_retention_and_privacy 3/3 PASS 37.404 1

Время сценария включает создание данных, Docker stop/recreate/start, ожидание готовности и проверки. queued_to_ready_seconds в raw — отдельное SQL-время от создания job до ready; оно также включает намеренные простои. Эти результаты не являются SLA и не сравнивают производительность компьютеров.

Во всех ready snapshot проверены побайтный original и его checksum, checksums трёх вариантов, ровно четыре key текущей версии и один ready event на job. Во всех девяти случаях crash worker до ready (3 окна ×3) job завершилась на второй попытке; после COMMIT ready во всех трёх повторах осталась одна попытка. В каждом bounded_retry_and_replay зафиксирован failed после ровно пяти попыток и ready той же job после операторского replay на шестой. Без replay бесконечных попыток не было. В каждом duplicate-сценарии доставлено и подтверждено 16 дублей (48 суммарно); весь публичный Attachment и bytes остались прежними. Во всех шести проверках reorder/stale current_version=2; настройки v2 действительно изменили bytes вариантов относительно v1. Это согласуется с гипотезой в пределах проверенных окон сбоев; потери диска или целого host эксперимент не моделирует.

После эксперимента выполнены make ready и make test, затем дополнительный публичный failover именно mtusi2026lab5-api-2: 110 подтверждённых записей, 4 неудачные попытки, first_recovery_seconds=2.521. Первый публичный failover и file failover останавливали api-1: 114 подтверждённых записей/3 неудачные попытки/2.581 s; original скачан другой API за 2.386 s, failed_attempts=0. Дополнительные доказательства: local_failover_additional_1.txt, api_failover_additional_1.json, attachment_failover.json. После восстановления повторно прошли ready и публичный smoke. Две API и все фоновые службы работают; migrate и s3-bootstrap завершены с code=0. Fault injection у worker/dispatcher/reconciler выключен (все флаги 0); факты — runtime_versions.json, containers_final.json. Host и container pip check не нашли конфликтов зависимостей.

Аудит: обязательные contracts/, tests/, README и COURSE совпали с Git HEAD и исходным решением; git diff --check прошёл. Проверка evidence и неигнорируемых файлов на фактические значения локальных secrets и поля токенов — final_audit.json. Секреты, .env и .venv остались локальными. Commit/push/MR не выполнялись.

Ограничения и источники

Один host, LB, PG, S3 и broker остаются SPOF. Проверяются перезапуски с сохранением volumes, не потеря диска. Физически потерянный исходник нужен из внешней копии. AOF/persistent volume не заменяют резервную копию и репликацию.

Stream, outbox и job_events автоматически не обрезаются; для длительной работы нужен retention с учётом PEL и аудита. Broker ограничен 192 MiB/noeviction: при невозможности XADD outbox сохраняется, затем MAX_PENDING_JOBS ограничивает новые приёмы. Для прерванного до 202 HTTP-приёма гарантии задания нет; staging без намерения очищается по retention. Дубликат upload может создать новый attachment.

Поддерживаются pipeline версии 1 и 2. Параметры качества закреплены версией кода; их нельзя произвольно менять под прежним номером pipeline. Переключение версии явное и доступно только оператору. Горизонтальное масштабирование worker требует общего PG/broker/S3 и отдельного бюджета CPU/RAM; исследование concurrency/prefetch трек 1 не заявляется.

Источники: README/COURSE/OpenAPI/jobs.schema/attachment-states lab5, собственная lab4; Redis Streams, XAUTOCLAIM, Redis AOF, PostgreSQL locks, Pillow ImageOps, MinIO release.