Files
mtusi2026lab5/REPORT.md
T
Savelev_Ivan fd501cbf68 fix: продление аренды задач и контроль зависшей обработки
- Добавлен heartbeat для продления lease долгих задач.
- Добавлен общий таймаут с остановкой дерева процессов.
- Сохранена защита от устаревших исполнителей.
- Добавлены тесты и обновлена документация.
2026-11-20 14:00:53 +03:00

31 KiB
Raw Blame History

Отчёт — лабораторная 5

  • Автор, группа: Савельев Иван, БВТ2304.
  • Целевая оценка: 4 — все требования уровней 3 и 4. Исследовательский трек оценки 5 не заявлен.
  • Стенд: Docker Compose; HAProxy, две реплики FastAPI, PostgreSQL, Valkey для сессий, SeaweedFS S3; отдельные Valkey Streams broker, outbox publisher и worker.
  • Commit/PR: после публикации. Evidence содержит source_commit и working_tree=true: проверялось рабочее дерево поверх указанного commit.
  • Использование ИИ: перенос базы, код, проверки и отчёт подготовлены с помощью Codex. Результаты проверок получены реальным запуском Docker, а не предполагаются по коду.

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

Нужны Docker Engine с Compose v2, Python 3.11, Bash и make. Все команды выполняются из корня репозитория. Внешние заранее установленные БД/брокер/S3 не нужны.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make check validate PYTHON=.venv/bin/python
./scripts/start.sh
./scripts/check.sh

start.sh создаёт локальные .env и secrets/, собирает образ, выполняет миграции и bootstrap приватного bucket, поднимает сервисы и ждёт обе API-реплики через LB. Существующие настройки и пароли сохраняются. .env, secrets, виртуальное окружение и runtime data исключены из Git; Docker context содержит только исходники, зависимости и миграции.

API: http://localhost:8080. Если порт занят, задайте HOST_PORT=8081 в .env; HTTP-проверки запускайте с BASE_URL=http://localhost:8081. Compose project mtusi-lab5, образы mtusi-messenger:lab5 и volumes отделены от предыдущих лабораторных. Локальные credentials генерируются заново, файлы из lab4 не копируются.

# Полный автоматический сценарий на отдельном временном project и свободном порту:
./scripts/check-docker.sh

# Обычный стенд, остановка без потери данных:
./scripts/stop.sh
./scripts/start.sh

# Перезапуск всех постоянных процессов и хранилищ с сохранением volumes:
./scripts/restart.sh

# Только для намеренного удаления учебных данных ТЕКУЩЕГО Compose project:
docker compose down --volumes

Полный сценарий создаёт синтетические данные в отдельном lab5-check-<random> и удаляет только его контейнеры/volumes. Пишет evidence/lab5-checks.txt и evidence/lab5-checks.json. Для диагностики сбоя можно явно задать KEEP_TEST_STACK=1; это оставит только неуспешный временный стенд. Основной стенд не затрагивается.

Что перенесено и изменено

Из lab4 сохранены регистрация/Argon2id, Basic-вход и Bearer-сессии в Valkey, ACL чатов и вложений, сообщения и keyset-пагинация, X-Request-Id/X-Instance-Id, общая идемпотентность сообщений, две API-реплики за LB, приватный S3, лимиты загрузки, миграции и эксплуатационные скрипты. Предыдущие отчёты — REPORT.lab2.md, REPORT.lab3.md, REPORT.lab4.md; старые evidence относятся к соответствующим работам.

Объявленный переход API: upload возвращает 202 со снимком queued, а клиент опрашивает GET metadata. Queued/processing уже можно прикрепить к сообщению в том же чате. Для failed новое прикрепление даёт 409. Content любого не-ready вложения даёт 409, отсутствующий вариант ready — 404. Оригинал скачивается побайтно без перекодирования и redirect; API не раскрывает storage keys/credentials. Контракт, README задания и публичные tests не изменялись.

Миграции 001–003 сохранены. Миграция 004 добавляет состояния/metadata вариантов и таблицы jobs, outbox, audit событий. Старые ready-вложения сохраняют свои ключи и читаются после обновления; варианты у старых записей не создаются автоматически. Схема описана в docs/schema.md.

Архитектура и границы устойчивости

Клиент → HAProxy → API ×2 → PostgreSQL: metadata + job + outbox
                        → приватный S3 staging

PostgreSQL outbox → publisher → Valkey Streams (AOF, volume)
                                    ↓ XREADGROUP, prefetch=1
                            worker (2 процесса)
                                    ↓
                          отдельный resize subprocess
                                    ↓
                  S3 original + thumbnail + crop + optimized
                                    ↓
                     PostgreSQL COMMIT ready → broker ACK

cleanup → orphan PUT journal + staging только ready/просроченных failed

PostgreSQL — источник истины для намерения обработки и состояния. Valkey Streams обеспечивает at-least-once доставку. Это отдельный service broker, не Pub/Sub и не тот же экземпляр, что сессии. Stream attachments:v1, группа image-workers, начало чтения 0; topology создаётся идемпотентным XGROUP CREATE MKSTREAM. Сообщения не trim-ятся до ACK. После XACK запись удаляется XDEL в одной broker transaction; используется одна группа.

  1. API принимает все bytes с ограничением размера, проверяет имя, MIME и настоящий PNG/JPEG. Resize/генерация вариантов в API не выполняются.
  2. Перед PUT фиксируется журнал attachment_uploads. Полный проверенный оригинал записывается в S3 attachments/staging/<UUID>. Это тот же приватный S3, но отдельный staging prefix; на этом этапе конечного original/вариантов ещё нет.
  3. Одна транзакция PostgreSQL вставляет queued metadata, job и outbox и удаляет запись журнала. 202 отправляется после PUT и успешного COMMIT. Локальный TemporaryFile нужен только во время HTTP-приёма, устойчивым staging не является.
  4. Отдельный publisher читает due outbox с блокировкой SKIP LOCKED и делает XADD. Broker настроен AOF appendfsync always, volume, noeviction. Успешный XADD подтверждает приём брокером с этой настройкой persistence; это не consumer ACK. После ответа dispatcher отмечает published_at.
  5. Worker захватывает job транзакционно: status=processing, случайный lease_token и deadline. Данные для скачивания берёт из БД, а не из сообщения/filename. Проверяет размер и SHA-256 staging. Записывает original и все три варианта, затем в одной транзакции ставит ready и metadata/checksums. Только после COMMIT подтверждает доставку.

В сообщении только поля jobs.schema.json: schema_version, job_id, type, attachment_id, pipeline_version=1, attempt, created_at. Bytes, URL, credentials, filename и storage key отсутствуют. job_id постоянен при redelivery и managed retry; attempt начинается с 1 и меняется при новой управляемой попытке. Native stream ID — отдельный идентификатор доставки.

Идемпотентность, retry и replay

Ключ эффекта (attachment_id, pipeline_version, variant) реализован детерминированными объектами:

attachments/<UUID>/v1/original
attachments/<UUID>/v1/thumbnail
attachments/<UUID>/v1/crop
attachments/<UUID>/v1/optimized

Число объектов конечного результата — четыре. Дубль queued/processing не захватывает уже арендованную job. Устаревшая попытка не меняет актуальное состояние. Перед PUT и COMMIT worker блокирует строки job/attachment и сверяет lease_token и deadline. При повторе после незавершённого PUT те же детерминированные объекты могут записаться ещё раз, второй набор не создаётся. Дубль ready проверяет полную metadata и размеры объектов через S3 HEAD, затем ACK, не меняя status/updated_at и не выполняя resize. В этой работе поддерживается только pipeline_version=1; трек versioned pipeline на 5 не заявлен.

Временные ошибки S3, resource limit и timeout дают queued с новым due outbox. Backoff: uniform(0.5,1.5) × min(60, JOB_BACKOFF_SECONDS × 2^(attempt-1)); интервал сохраняется в PostgreSQL. Default base=2 s, jitter присутствует. Автоматический бюджет — JOB_MAX_ATTEMPTS=5. При исчерпании — failed/error_code=retry_exhausted; последняя безопасная причина сохраняется в job. Нарушение checksum/размера staging или невалидное изображение — постоянный invalid_image, сразу failed без повторов. Тексты исключений и stack traces не передаются в API/registry.

Publisher также восстанавливает истёкший processing lease: записывает worker_lost и создаёт следующую попытку либо failed при исчерпании бюджета. Это не бесконечный retry. Pending-доставки умершего consumer забираются XAUTOCLAIM после lease timeout. Если recovery уже создал новую попытку, старое сообщение становится obsolete и получает ACK; намерение следующей попытки уже устойчиво сохранено.

Реестр failed и явный replay:

docker compose exec -T worker python -m src.job_admin failed
docker compose exec -T worker python -m src.job_admin replay <job_id>

Replay разрешён только для failed с ещё сохранённым staging. Он сохраняет job_id/ключ эффекта, записывает operator_replay в audit, увеличивает глобальный attempt и выделяет новый ограниченный бюджет из пяти попыток. Ready/queued/processing повторять этой командой нельзя; повтор ready завершается ошибкой без изменения БД/объектов. Глобальный attempt монотонен, поэтому старые сообщения не запускают replay как новую работу. После удаления failed staging replay запрещён: исходник надо загрузить заново. HTTP endpoint управления заданиями не добавлен.

Правила изображений и ограничения ресурсов

  • Оригинал остаётся исходными bytes, MIME, size_bytes и SHA-256 относятся к нему.
  • EXIF orientation применяется к производным изображениям. Прозрачность компонуется на белый; производные RGB, без EXIF/ICC/comment metadata.
  • Thumbnail: JPEG quality=85, вписывание в 256×256 без увеличения, целочисленное округление вниз с минимумом 1 px. Fixture 320×200 → 256×160.
  • Crop: JPEG quality=85, центрированный квадрат 128×128, LANCZOS; маленький исходник может увеличиваться.
  • Optimized: WebP quality=80, method=4; вписывание в 1280×1280 без увеличения. Уменьшение байтов каждого маленького файла не обещается.
  • Загрузка ≤10 MiB и ≤40 млн pixels. Limit проверяется до полной распаковки; Content-Length и фактический поток проверяются независимо. Corrupt/MIME spoof — 415, bytes/pixels overflow — 413. API допускает одну проверяемую загрузку на реплику, таймаут тела 30 s и ожидания слота 20 s.
  • Worker concurrency=2, каждый consumer получает максимум одну доставку за раз. Для заданного Compose memory budget разрешено concurrency 1 или 2.
  • Каждый resize выполняется отдельным subprocess: wall timeout 60 s, CPU limit 60/61 s, address-space limit 640 MiB (RLIMIT_AS). При timeout subprocess убивается; MemoryError/resource termination не убивает основной consumer и проходит bounded retry. Worker container ограничен 1536 MiB, 2 CPU и 96 PID.
  • После исправления 13.11.2026 lease (default 90 s, минимум 15 s) продлевается consumer каждые min(10, lease/3) секунд. Продление проверяет статус, lease_token и срок аренды; истёкшую или чужую аренду не восстанавливает. Исправная задача может выполняться дольше первоначального lease; resize timeout и lease больше не связаны условием lease > timeout.
  • Вся попытка, включая скачивание, resize и публикацию, выполняется отдельным job_runner. Consumer контролирует независимый JOB_TASK_TIMEOUT_SECONDS (default 180 s в Compose, не меньше resize timeout). При превышении убивает дерево runner + resize и фиксирует ограниченный retry. Heartbeat не работает бесконечно для зависшего runner. При потере аренды/ошибке продления дерево также останавливается; ACK без устойчивого результата не отправляется. В Linux runner получает сигнал при смерти consumer и завершает свою группу процессов.
  • Во время финальной транзакции PUT/COMMIT строки удерживаются под fence; heartbeat пропускает занятую блокировку, как и recovery. Общий timeout при этом продолжает действовать.

Если корректное преобразование может занимать 95 s, можно задать JOB_TIMEOUT_SECONDS=120, JOB_LEASE_SECONDS=90, JOB_TASK_TIMEOUT_SECONDS=180: lease будет продлеваться, а отдельные таймауты останутся конечными. Defaults по-прежнему разрешают resize только до 60 s; heartbeat не отменяет этот лимит.

  • S3 операции имеют connect timeout 1 s/read timeout 3 s, SDK retries отключены. PostgreSQL I/O, pool wait и блокировки ограничены. CPU/resize выполняется вне DB-транзакции; транзакция публикации результата включает только fencing, четыре ограниченных PUT и COMMIT.

WORKER_TASK_MEMORY_MB ограничивает адресное пространство процесса, а Compose mem_limit — весь контейнер. Это разные ограничения; поддержка 40 млн pixels не обещает, что любой формат/ориентация уложится в память: превышение ресурсов заканчивается наблюдаемым failed после ограниченного бюджета, а не бесконечной обработкой.

Staging retention и очистка

cleanup запускается раз в 30 s. Журнал orphan PUT старше UPLOAD_CLEANUP_GRACE_SECONDS=3600 очищается под advisory lock: свежая/активная загрузка не удаляется. Crash после staging, но до metadata/job не дал 202; его журнал позволяет удалить orphan без обхода всего bucket.

Staging queued/processing не удаляется независимо от возраста. После безопасного COMMIT ready staging удаляется при ближайшем проходе; конечные четыре объекта сохраняются. Failed staging и частичные конечные объекты хранятся STAGING_RETENTION_SECONDS=86400 после последнего перехода в failed, затем удаляются; metadata, failed registry и audit остаются. Операции DELETE идемпотентны, отметка staging_deleted_at фиксируется после удаления. Cleaner и replay блокируют те же строки, поэтому не удаляют staging текущей replay-работы.

Сервисы, настройки и bootstrap

Роль / service Версия Readiness / persistence / credentials
API / api ×2 Python 3.11.15; FastAPI 0.142.4 non-root UID 10001, health live/ready; 384 MiB/1 CPU на реплику; Docker secrets
БД / postgres PostgreSQL 17.6-bookworm pg_isready, postgres_data; отдельный migrate с checksum/advisory lock
Сессии / valkey Valkey 8.1.3 PING, AOF always, valkey_data, внутренний порт
Брокер / broker Valkey 8.1.3 авторизованный PING, AOF always, broker_data, отдельный пароль через secret
Outbox / publisher тот же собранный Python image restart unless-stopped; DB+broker secrets; topology bootstrap идемпотентен
Worker / worker тот же Python image; Pillow 13.0.0 restart supervisor, 2 consumer-процесса, leases; DB+broker+S3 secrets
S3 / s3 + s3-storage SeaweedFS 3.85 с digest gateway probe + filer HTTP; s3_data; storage только в s3-internal
S3 bootstrap / s3-bootstrap MinIO SDK 7.2.20 root secrets только для создания приватного bucket; повтор безопасен
LB / lb HAProxy 3.2.6-alpine readiness backend; единственный порт 127.0.0.1:8080
Cleanup / cleanup тот же Python image restart unless-stopped, DB+S3 secrets; без broker credentials

Python base image закреплён digest в Dockerfile; S3 image — digest в Compose. Все Python-зависимости закреплены в requirements.txt. Административные интерфейсы S3 и внутренние API/БД/broker ports наружу не опубликованы. S3 application credentials разрешают работу только своего bucket/prefix attachments/*; root используется только bootstrap. API/cleaner не получают broker password. .env.example содержит пути secret-файлов, а не их значения.

Соответствие настроек: APP_HOST/APP_PORT — адрес API внутри контейнера; HOST_PORT — порт LB; APP_ENV — учебная метка. SESSION_STORE=valkey и SESSION_TTL_SECONDS=3600 — общее session storage; CACHE_URL_FILE/DATABASE_URL_FILE — Docker secrets. API_REPLICAS=2; IDEMPOTENCY_TTL_SECONDS≥86400. S3_ENDPOINT/REGION/BUCKET и S3_*_FILE — приватный bucket. MAX_UPLOAD_BYTES/MAX_IMAGE_PIXELS и UPLOAD_CLEANUP_GRACE_SECONDS — приём и orphan cleanup. BROKER_URL_FILE — авторизованный Redis-compatible URL отдельного broker. WORKER_CONCURRENCY, WORKER_TASK_MEMORY_MB, JOB_TIMEOUT_SECONDS, JOB_LEASE_SECONDS, JOB_MAX_ATTEMPTS, JOB_BACKOFF_SECONDS — ограничения/повторы. STAGING_RETENTION_SECONDS — срок хранения failed исходников.

/health/ready API зависит от PostgreSQL, сессий и S3: они нужны синхронному пути. Broker/worker/publisher не являются зависимостями readiness API: при их остановке original+outbox надёжно принимаются, текстовые сообщения работают, resize синхронно не запускается. У фоновых процессов нет HTTP health endpoint; состояние jobs/pending/failed наблюдается через БД, broker и операторскую CLI.

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

Проверено 12.11.2026 до добавления heartbeat: все 17 групп проверок и 39 API regression tests прошли. Docker 29.0.1, aarch64, 10 CPU, 8 217 448 448 bytes RAM Docker VM. Эти evidence относятся к предыдущей реализации.

13.11.2026 после исправления локально прошли 6 проверок python -m unittest discover -s student-tests -p test_task_supervisor.py -v с реальными subprocess: работа дольше первой аренды, общий timeout при продолжающемся heartbeat, потеря аренды, ошибка продления, crash и убийство дочернего процесса. Полный Docker-прогон новой версии не выполнен: Docker Engine на текущей машине недоступен. В lab5_pipeline.py добавлены сценарии 20-секундной работы при lease=15 s без retry и зависания runner с общим timeout=25 s; они требуют повторного ./scripts/check-docker.sh.

Полный воспроизводимый запуск: ./scripts/check-docker.sh. Исходник сценария — student-tests/lab5_pipeline.py. Результаты и реальные job/attachment IDs — evidence/lab5-checks.json, консольный вывод — evidence/lab5-checks.txt. Дополнительное доказательство реального restart обычного стенда с прежними container IDs и volumes — evidence/lab5-restart.json; воспроизводится .venv/bin/python student-tests/verify_restart.py.

Критерий README Команда / ключ проверки evidence Наблюдаемый результат
Сохранён lab4, переход 201→202, smoke make check validate test; public_smoke_and_schema, student_api_regressions Публичный lab5 сценарий и собственные API regression tests
Отдельные broker/worker, persistence, лимиты topology_and_limits Реальные контейнеры/volumes, две API, broker AOF always, worker concurrency=2/prefetch=1
Worker остановлен → 202 → сообщение → рестарты → ready worker_offline_api_broker_restart Тот же attachment/job после рестарта API и broker; 409 до ready; original/три варианта доступны
Original/thumbnail/crop/WebP по контракту image_semantics Bytes/checksums/MIME и реальные размеры; small/alpha/EXIF/floor cases
Outbox, crash COMMIT→publish outbox_crash_before_publish Устойчивое намерение доставляется после автоматического restart publisher
Неопределённый XADD, дубли outbox_crash_after_publish Повтор publish не создаёт второго результата
Crash после side effect до COMMIT/ACK worker_crash_after_objects, worker_crash_before_ack Lease/reclaim восстанавливают работу; четыре canonical объекта; ready дубль — no-op
Retry/backoff/jitter, failed registry, replay bounded_retry_failed_registry_replay 5 автоматических неудач → failed; audit содержит время/попытки; явный replay → ready; ready replay отклонён
Постоянная ошибка permanent_error invalid_image с первой попытки, безопасный код
Ограничение времени и памяти обработки image_subprocess_timeout, image_subprocess_memory Реальное убийство зависшего subprocess и MemoryError при выделении 1 GiB под лимитом 640 MiB; следующий retry завершает тот же job
Безопасная очистка staging staging_cleanup Active staging сохранён; ready/expired failed удалены; replay без исходника запрещён
Broker недоступен broker_offline_outbox API принимает 202 и текст; outbox доставляет после восстановления
Сохранность после всех рестартов make test-persistence; public_persistence Сессия, история и original переживают рестарты с volumes
Отказ API make test-failover; public_api_failover Другая реплика продолжает обслуживать подтверждённые сообщения без дублей

Failpoints включаются только явным ENABLE_FAULT_INJECTION=1 во временном тестовом project; по умолчанию отключены. Файлы управления доступны только через docker exec внутри контейнера, HTTP управления ими нет. before_publish завершает publisher после DB COMMIT намерения до XADD; after_publish — после XADD до фиксации outbox. after_objects завершает job_runner после PUT четырёх объектов до COMMIT ready; before_ack — после COMMIT ready до XACK. Маркеры срабатывания проверяются тестом, поэтому простой быстрый успех без внедрённого сбоя не засчитывается. Отдельный timeout failpoint усыпляет именно ограниченный resize subprocess, не подменяет результат mock-объектом. before_download с delay:20 задерживает корректную попытку, с timeout — имитирует зависание runner до скачивания.

Эксперименты и ограничения

Это проверка критериев на 4; исследование максимального throughput, сравнение concurrency/prefetch и versioned pipeline не выполнялись. Полный сценарий использует concurrency=2/prefetch=1, max_attempts=5; для быстрых fault checks timeout=5 s, lease=15 s, base backoff=0.15 s. Production-подобные default настройки остаются 60/90/2 s в .env.example. Дата, Docker/hardware и лимиты конкретного запуска записаны в evidence. Измерения latency/RSS этой проверки не трактуются как нагрузочный benchmark.

Обработка at-least-once, не exactly-once: XADD и PUT могут повториться, идемпотентен конечный эффект и его публикация. Сбой host/disk с потерей volumes, потеря единственной PostgreSQL/S3 или ручное удаление объектов не покрываются. Backup/replication этих хранилищ в lab5 не добавлялись. Очередь ограничена maxmemory/noeviction broker; outbox и staging во время длительного простоя требуют диска, общей квоты принятой работы эта оценка не требует. Повторы самого HTTP upload могут создать отдельные вложения по контракту.

Первичные источники