24 KiB
Отчёт — лабораторная 5
Исправление по ревью: целостность PNG
В src/messenger/image_check.py добавлен проход по структуре PNG: полные
заголовки, данные и CRC каждого блока, обязательный завершающий IEND нулевой
длины с корректным CRC. Проверка выполняется до S3 staging и создания задания.
Pillow verify/load сохранены для проверки формата, размеров и декодирования:
сами по себе они допускают усечение CRC блока IEND.
CRC считается потоково блоками до 64 KiB без выделения памяти по недоверенной
длине блока. Неполный или повреждённый PNG возвращает HTTP 415.
Регрессия покрывает удаление последних 1–12 байт PNG, повреждение CRC IEND,
ошибочный CRC дополнительного блока и непустой IEND. HTTP-тест также проверяет,
что после отказов корректный PNG принимается и достигает ready.
Вывод повторного прогона: evidence/png-integrity-offline.txt,
evidence/png-integrity-unit.txt, evidence/png-integrity-smoke.txt,
evidence/png-integrity-tests.txt.
- Автор / группа: Черников Дмитрий, БВТ2304.
- Целевая оценка: 4 — обязательные требования на 3 и все пункты на 4. Треки на 5 не заявляются.
- Ветка:
solution/bvt2304-chernikov, создана от официального skeletonmtusi2026/mtusi2026lab5:main, базовый commit276dbda. Commit решения/PR указывается после публикации в личный fork. - Основа — собственная лабораторная 4, включая клиентский таймаут PostgreSQL 3 с из исправления по ревью. При разработке использовался Codex (OpenAI).
Запуск из чистого clone
Нужны Docker Desktop с Compose и Python 3.9+ для HTTP-тестов. Команды выполняются из корня mtusi2026lab5. Сервер и worker используют Python 3.14.7 внутри образа. Точные версии и хеши библиотек находятся в requirements.txt: psycopg 3.3.6, psycopg-pool 3.3.3, valkey 6.1.1, argon2-cffi 25.1.0, boto3 1.43.123, Pillow 13.0.0.
python scripts/init_secrets.py
Copy-Item .env.example .env
docker compose config --quiet
docker compose up -d --build --wait
docker compose ps -a
python -X utf8 scripts/verify.py
python -X utf8 scripts/lab5_checks.py
В Linux используйте python3, вместо Copy-Item — cp .env.example .env. -X utf8 нужен публичным скриптам в Windows. make необязателен; make check, make test, make student-test, make checks соответствуют прямым командам Python.
API: http://127.0.0.1:8080; HAProxy stats: http://127.0.0.1:8404. Если lab4 уже использует эти порты, остановите её стенд либо задайте другие APP_PUBLISHED_PORT / LB_STATS_PORT и передайте тестам --base-url. Проект Compose mtusi-lab5 имеет собственные volumes и secrets.
init_secrets.py создаёт случайные пароли только при отсутствии файлов. Не удаляйте secrets/, сохраняя старые volumes: пароли PostgreSQL не меняются вместе с новым локальным файлом. .env и secrets/ не входят в Git или build context.
| Сервис | Роль и версия | Persistence / готовность |
|---|---|---|
| api ×2 | Python 3.14.7, собственный образ lab5 | без постоянного локального состояния; readiness PostgreSQL + session Valkey + S3 |
| lb | HAProxy 3.4.5 | round-robin, readiness API, наружу только 127.0.0.1 |
| postgres | PostgreSQL 18.6 | pgdata, pg_isready; метаданные, jobs, outbox, leases, audit |
| valkey | Valkey 9.0.6 | valkeydata, AOF appendfsync always; только сессии |
| s3 | SeaweedFS 3.85 | s3data, включая filer index; приватный bucket |
| broker | отдельный Valkey 9.0.6 Streams | brokerdata, AOF appendfsync always, noeviction; не Pub/Sub |
| dispatcher | отдельный Python-процесс | восстанавливает и публикует PostgreSQL outbox |
| worker | отдельный Python-процесс | bounded decode/resize; default concurrency=1, prefetch=1 |
| migrate / bucket | одноразовые сервисы | идемпотентные миграции и создание приватного bucket до запуска |
| jobs / cleanup | операторские команды, профиль tools | failed/replay/audit и безопасная очистка |
Все внешние образы закреплены тегом и digest, включая брокер. Worker и dispatcher используют тот же собранный из исходников образ, но отдельные процессы. Критичные зависимости проверяются API; worker/broker не входят в readiness API, потому что durable outbox позволяет принять работу во время их недоступности. Ошибки публикации видны в логах dispatcher, состояние задач — оператору в БД/CLI.
Для учебного S3 master volume size ограничен 100 MiB, volume.max=20: дефолтный рост SeaweedFS по 7 томов должен помещаться в одном узле. Это исправляет обнаруженный на новом volume отказ первого PUT при capacity=5; сетевые таймауты приложения ради этого не увеличивались.
Остановка без потери данных: docker compose stop или docker compose down. docker compose down -v намеренно удаляет все учебные данные lab5, включая broker и S3. Не используйте её в проверках отказов.
Что изменилось относительно lab4
Сохранены пользователи, Bearer-сессии, ACL чатов, идемпотентность сообщений, keyset pagination, две API-реплики, PostgreSQL, Valkey и приватное S3. Публичные tests/ и contracts/ не изменены. Устойчивый исходник теперь сначала записывается в staging/<UUID>, а API возвращает 202 со снимком queued; клиент опрашивает GET метаданных. Worker публикует оригинал и варианты, затем атомарно переводит attachment в ready.
HTTP upload -> API -> S3 staging (все bytes)
-> PostgreSQL: attachment queued + job + outbox (один COMMIT)
|
dispatcher -> durable Valkey Stream
|
worker
|
PostgreSQL ready + 3 variant metadata <- конечный S3
API проверяет сессию, чат, filename, MIME, bytes и пиксели. До 202 все байты уже приняты, проверены и находятся в устойчивом S3, а задание и намерение публикации — в PostgreSQL. Локальный /tmp служит только ограниченным временным буфером. API не делает resize и не исполняет работу worker даже при его остановке. В сообщениях брокера только поля jobs.schema.json; bytes, credentials, внутренние URL и клиентские пути не передаются.
Upload и DB намерение фиксируются через Repository.save_attachment / Jobs.save_upload. PUT staging выполняется перед INSERT/COMMIT. Неопределённая ошибка между PUT и DB может оставить orphan; старая очистка lab4 дополнена защитой staging и variants. После успешного 202 задача уже восстановима без API-процесса.
Миграция 0005_async_attachments.sql добавляет status, error_code, staging, attachment_jobs, attachment_outbox, attachment_variants, job_audit и одноразовые операторские fault hooks. При применении поверх lab4 существующие оригиналы становятся staging для нового pipeline; объект, чей staging key совпадает с final key, не удаляется.
Outbox, повторы и подтверждения
Dispatcher арендует строки outbox, публикует XADD и только после успешного ответа отмечает published. COMMIT upload и INSERT outbox атомарны. Если процесс умер после COMMIT до publish, строка остаётся и публикуется после запуска. Если XADD прошёл, но ответ/mark потерян, допустима повторная доставка с тем же job_id. Это at least once, а не exactly once.
Брокер хранит stream и Pending Entries List в AOF с fsync каждой записи. XREADGROUP отдаёт по одной записи на поток; XACK выполняется после устойчивого ready либо после COMMIT решения о retry/failed. XAUTOCLAIM возвращает pending сообщения умершего consumer. Приложение не использует NOACK или обычный Pub/Sub. Stream автоматически не обрезается, чтобы не удалить ещё не подтверждённую работу; рост истории — эксплуатационное ограничение учебного стенда.
PostgreSQL — источник истины о логической работе. Claim блокирует job и выдаёт lease_token, увеличивает attempt. Только текущая неистёкшая аренда может зафиксировать результат: token, attempt и pipeline_version проверяются при записи и перед завершением транзакции. После гибели worker processing восстанавливается в queued или failed по исчерпанию бюджета. Новый outbox записывается в той же транзакции, что и retry/recovery. Устаревший worker не может перевести ready обратно в processing.
Финальные object keys детерминированы: originals/<UUID> и variants/<UUID>/v1/{thumbnail.jpg,crop.jpg,optimized.webp}. Уникальность метаданных — (attachment_id,pipeline_version,name). Повтор пишет тот же логический набор, ready-доставка подтверждается без повторной обработки. Доступных pipeline несколько не реализовано: используется только версия 1, без исследования трека 5.
Изображения и ограничения
| Вариант | Правило |
|---|---|
| original | исходные bytes и MIME; SHA-256 совпадает с upload |
| thumbnail | JPEG quality85, fit256×256, без увеличения, округление вниз минимум1px |
| crop | JPEG quality85, центральный квадрат128×128; маленький исходник может увеличиваться |
| optimized | WebP quality80/method4, fit1280×1280 без увеличения |
EXIF orientation применяется до resize/crop. Прозрачность компонуется на белый. Варианты не содержат исходных EXIF/ICC/XMP; оригинал неизменен. WebP не обязан быть меньше любого маленького PNG/JPEG.
Вход: PNG/JPEG ≤10 MiB и ≤40M pixels. API и worker независимо ограничивают bytes; worker сверяет размер и SHA-256 со staging metadata из БД. Декодирование выполняется отдельным процессом с wall timeout JOB_TIMEOUT_SECONDS=10, RLIMIT_AS IMAGE_MEMORY_MIB=768, CPU/размером выходных файлов и ограниченным tmpfs128MiB. Worker по умолчанию один поток, контейнер1GiB/1CPU; процесс API512MiB. Увеличивать concurrency без согласованного увеличения памяти/tmpfs нельзя.
S3 connect/read timeout — 1/3 с; PostgreSQL client I/O timeout — 3 с, отдельный таймаут пула — 3 с. Lease45с больше штатного бюджета ограниченной обработки. Если lease истёк, fenced commit не публикует устаревший результат; следующий запуск повторяет детерминированные эффекты.
Retry, failed registry и replay
JOB_MAX_ATTEMPTS=5. Постоянные ошибки (invalid_image, image_too_large, integrity mismatch) завершаются failed сразу. Временные ошибки хранилищ повторяются с exponential backoff + equal jitter: cap=min(JOB_RETRY_MAX_SECONDS, JOB_RETRY_BASE_SECONDS*2^(run_attempt-1)), delay в [cap/2,cap]. Defaults base1с/max30с. Причина и available_at сохраняются; после исчерпания — retry_exhausted.
Реестр failed находится в PostgreSQL, доступен отдельной операторской командой:
docker compose --profile tools run --rm jobs failed
docker compose --profile tools run --rm jobs show JOB_UUID
docker compose --profile tools run --rm jobs replay ATTACHMENT_UUID --actor Chernikov --reason "Причина исправлена"
Replay разрешён только для failed при сохранённом staging; сохраняет job_id, сбрасывает ограниченный бюджет run_attempts, монотонно продолжает attempt и пишет audit. Replay уже ready — записанный в audit no-op. Задача не превращается в неконтролируемый дубль. Публичного административного endpoint нет; jobs CLI не раскрывает токены и object keys.
Очистка и credentials
Worker удаляет staging только после COMMIT ready. При сбое DELETE или смерти процесса pending_cleanup остаётся в БД; maintenance повторяет операцию. Ready не зависит от успешности удаления staging. Queued/processing staging всегда защищён от очистки.
Failed-исходники сохраняются минимум24ч для диагностики/replay. Операторская cleanup при истечении retention сначала фиксирует tombstone под attachment row lock (replay после этого запрещён), затем делает идемпотентный S3 DELETE. Сбой между этими шагами оставляет безопасный повтор удаления. Неучтённые объекты очищаются только после grace≥1ч. Учтённые вложения, ещё не прикреплённые к сообщениям, автоматически не удаляются: такого пользовательского lifecycle в контракте нет.
docker compose --profile tools run --rm cleanup
docker compose --profile tools run --rm cleanup --apply
Оператор запускает cleanup по расписанию, например раз в час. STAGING_RETENTION_SECONDS задаёт retention (default86400), --failed-retention-seconds позволяет явно его переопределить; значение меньше24ч запрещено. Автоматическое удаление failed в worker не включено.
API и worker имеют отдельные S3 identity, bootstrap/cleanup — административные. API не получает credentials брокера. S3/broker/БД и порты API-реплик не опубликованы. В SeaweedFS выбранная bucket-scoped Write включает PUT/DELETE; более узкий запрет DELETE у этой identity не заявляется. Внутренняя Compose-сеть доверенная, удалённый доступ требует TLS.
Проверки и доказательства
Стандартный прогон: python -X utf8 scripts/verify.py; сбои: python -X utf8 scripts/lab5_checks.py или verify с --faults. Проверки сбоев сами меняют состояние сервисов и восстанавливают их в finally; volumes не удаляются, tokens остаются только в памяти.
| Критерий | Сценарий / файл |
|---|---|
| Публичный контракт и 202→ready | tests/smoke.py, evidence/smoke.txt |
| Негативные файлы, ACL, queued сообщения, варианты | student-tests, evidence/tests.txt |
| Изображения: EXIF/alpha/размеры/bytes/лимиты | unit-tests/test_image_process.py, evidence/unit.txt |
| Worker остановлен, рестарт API/broker, та же работа ready | lab5_checks --only durability |
| Crash после COMMIT до publish | lab5_checks --only outbox |
| Недоступность broker при приёме 202 | lab5_checks --only broker_outage |
| Повтор ready-задачи и безопасный replay ready | lab5_checks --only redelivery |
| Crash после S3 до COMMIT/ack | lab5_checks --only crash |
| Зависший processing и lease recovery | lab5_checks --only lease |
| Backoff+jitter, 5 попыток, failed/replay | lab5_checks --only retries permanent |
| Очистка staging после ready, защита pending | lab5_checks --only staging |
| Перезапуск всех хранилищ | tests/resilience.py --mode persistence, evidence/persistence.txt |
| Переключение API | tests/resilience.py --mode failover, evidence/failover.txt |
Фактический прогон 11.11.2026: Windows, Docker Engine 29.8.1 / Compose 5.5.1, Linux containers. Docker VM: 22 CPU и 16 464 109 568 байт RAM. Лимиты каждого сервиса перечислены в Compose и подтверждены snapshot.
| Проверка | Наблюдение | Доказательство |
|---|---|---|
| Offline и публичный smoke | PASS, 202 queued → ready; оригинал и JPEG256×160 проверены | evidence/offline.txt, smoke.txt |
| Собственные HTTP-тесты | 98/98 PASS за 38,587 с | evidence/tests.txt |
| Unit pipeline/ack/retry | 13/13 PASS за 1,124 с | evidence/unit.txt |
| Все 10 отказных сценариев | PASS, реальные stop/restart/kill; новые job вручную для восстановления не создавались | evidence/lab5-checks.txt |
| Убит worker после всех 4 S3 PUT до ready/ack | processing, staging сохранён, 3 объекта вариантов ещё без metadata; та же job стала ready на попытке 2 | evidence/lab5-checks.txt, crash |
| Истёкший processing | попытка 2 той же job ready; старый lease не может finish или fail | evidence/lab5-checks.txt, lease |
| Jitter | первые задержки 0,5774478 с и 1,0739815 с; соответствуют интервалам [0,5;1] и [1;2], available_at сохранён | evidence/lab5-checks.txt, retries |
| Исчерпание/replay | run_attempts=5 → retry_exhausted; явный replay → тот же job_id, attempt=6 ready; следующий replay no-op | evidence/lab5-checks.txt |
| Общий restart | старый токен, сообщение, metadata и original сохранены | evidence/persistence.txt |
| Failover API | 2 реплики до отказа, 119 успешных записей, 0 ошибок, восстановление записи через 4,5 с | evidence/failover.txt |
| Приостановка PostgreSQL | прямой readiness ограничен клиентским таймаутом, query/COMMIT/ROLLBACK закрывают соединение, тот же пул восстанавливается | evidence/postgres-pause.txt |
Измерения — короткие функциональные прогоны, не исследование производительности. Нагрузочного сравнения concurrency/prefetch и throughput нет, трек5 не заявлен. Проверка удаления failed staging после реальных24ч не ожидалась сутки; алгоритм проверен по блокировкам/tombstone, а автоматическая очистка ready staging и защита queued подтверждены отдельным сценарием. Полный список реальных состояний контейнеров, закреплённых образов, лимитов и volumes — в evidence/stack.json.
Ограничения
Один хост, по одному PostgreSQL, S3 и брокеру: отказ узла/диска не выдерживается. Сигналы/API-process restart выдерживаются при сохранённых volumes. Выбранная очередь не ограничивает admission количеством pending job; backpressure и сравнение настроек concurrency относятся к незаявленному треку5. Нет exactly-once доставки, распределённых транзакций S3/БД/брокера и нескольких обновляемых pipeline. При неопределённом COMMIT сообщения повторяются с тем же Idempotency-Key; upload сам по себе не идемпотентен.
Источники и использование ИИ
- README, COURSE, contracts и tests текущего skeleton; собственная реализация lab4.
- Valkey Streams, XREADGROUP, XAUTOCLAIM, XACK.
- Pillow ImageOps, Image file formats.
- psycopg 3.3.6, Docker Compose services.
- Codex (OpenAI): помощь в реализации, проверках и подготовке отчёта.