Files
mtusi2026lab5-fork/REPORT.md
T

26 KiB
Raw Blame History

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

  • Автор, группа: Березин Герман / БВТ2304
  • Целевая оценка: 4
  • Commit/PR: после публикации
  • Использованные источники, библиотеки и помощь ИИ: Go 1.26, pgx, go-redis (клиент Valkey Streams), minio-go v7, golang.org/x/image/draw (ресемплинг), github.com/gen2brain/webp (libwebp, транспилированный в Go), github.com/rwcarlsen/goexif (EXIF orientation); PostgreSQL 17, Valkey 8.1, SeaweedFS, HAProxy 3.0; документация RabbitMQ reliability и Redis Streams из README; код lab4 перенесён за основу; ИИ-ассистент использован при разработке

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

Требуются Docker 29 с Compose v2 и Python 3.9+. Для tests/variants.py нужен Pillow (проверяет реальные пиксели JPEG/WebP).

cp .env.example .env
sh scripts/mksecrets.sh
docker compose --env-file .env up -d --build --wait
make check && make test

Порядок старта: postgres, valkey, broker, s3 → migrate → s3-init → api × 2, worker, janitor → lb. Публичный адрес: http://localhost:8080. После первого старта S3 запись становится доступна через 10–30 s.

Остановка без потери данных: docker compose --env-file .env stop. Намеренное удаление учебных данных: docker compose --env-file .env down -v.

Операторские команды:

docker compose --env-file .env stop worker
docker compose --env-file .env up -d --no-deps worker
docker compose --env-file .env run --rm --no-deps worker failed
docker compose --env-file .env run --rm --no-deps worker replay <attachment_id>

Проверки (стенд запущен):

make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 tests/variants.py
python3 tests/queue_recovery.py
python3 tests/faults.py
python3 tests/worker_load.py --output evidence/worker-load.json
python3 tests/attachments.py
python3 tests/s3_checks.py
python3 tests/upload_memory.py --output evidence/upload-memory.json
python3 tests/idempotency.py
python3 tests/session_revocation.py
python3 tests/scenario.py --mode failover-each --output evidence/failover-each.json
python3 tests/scenario.py --mode rolling --output evidence/rolling.json

После make test-failover реплику возвращают командой docker compose --env-file .env up -d --wait api. faults.py, queue_recovery.py, worker_load.py сами останавливают и пересоздают worker/api/broker/s3 и возвращают их в исходное состояние.

Архитектура и решения

клиент → HAProxy → api ×2 ──(1) S3 staging/<id>
                       └──(2) PostgreSQL: attachments(queued) + jobs + outbox — одна транзакция → 202
api: outbox relay ──XADD──→ broker (Valkey Stream attachments.jobs, group workers)
worker ──XREADGROUP──→ claim (lease) → S3 attachments/<id>/... → COMMIT ready → XACK
Роль Сервис Образ Готовность Volume Сеть Credentials
api ×2 api собирается из исходников (mtusi-messenger:lab5) /health/ready (PostgreSQL) нет backend, storage secrets: database_url, cache_url, broker_url, S3-ключи API
worker worker тот же образ, команда worker нет HTTP, healthcheck отключён нет backend, storage database_url, broker_url, S3-ключи API
postgres postgres postgres:17-alpine@sha256:b0f9560a… pg_isready pg_data backend postgres_password
broker broker valkey/valkey:8.1-alpine@sha256:081c2f5c… valkey-cli ping с паролем broker_data backend broker.conf (requirepass)
s3 s3 chrislusf/seaweedfs@sha256:c2658820… /dir/assign выдаёт fid s3_data storage s3_config.json
load_balancer lb haproxy:3.0-alpine@sha256:cf3af0fa… проверки /health/ready бэкендов нет backend, 127.0.0.1:8080 нет
Valkey (сессии проверяются только в PostgreSQL) valkey valkey/valkey:8.1-alpine valkey-cli ping valkey_data backend нет

Bootstrap: migrate применяет migrations/*.sql под advisory lock, повторный запуск пропускает применённые. s3-init создаёт bucket, если его нет. Consumer group workers создают API (перед первой публикацией) и worker при старте (XGROUP CREATE … 0 MKSTREAM, ошибка BUSYGROUP игнорируется).

  • Брокер. Valkey Streams в отдельном сервисе broker с appendonly yes, appendfsync always, noeviction. Доставка at least once: сообщение остаётся в pending (PEL) до XACK. Publisher confirm: ответ на XADD приходит после записи в AOF с fsync. Consumer ack: XACK после COMMIT результата в PostgreSQL. В сообщении только поля jobs.schema.json (поле job — JSON с schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at), без bytes, URL и credentials.
  • Что сохранено к 202. Полный проверенный оригинал лежит в приватном S3-prefix staging/<attachment_id> (тот же bucket, volume s3_data). Одной транзакцией сохранены строки attachments (status queued, staging_key, sha256, размер), jobs (attempt 1) и outbox. Проверки на приёме те же, что в lab4: 413/415/400/404, хвост и заголовок изображения, не более 40 млн пикселей.
  • Transactional outbox. В каждой API-реплике работает relay: select … from outbox where published_at is null and available_at <= now() for update skip locked, затем XADD и published_at = now() в той же транзакции. Падение между COMMIT и publish оставляет неопубликованную строку, её публикует любая живая реплика. Падение после XADD до COMMIT пометки даёт повторную публикацию: это дубль, worker обработает его как no-op.
  • Worker. Отдельный процесс (messenger worker), WORKER_CONCURRENCY=2 потребителя, у каждого COUNT 1: prefetch 1, не больше двух задач одновременно. При старте потребитель дочитывает свои pending-сообщения (XREADGROUP … 0), каждые 15 s забирает зависшие чужие (XAUTOCLAIM с min-idle = lease).
  • Ключ идемпотентности. Логическая работа — jobs.id (job_id), он один на вложение и не меняется при redelivery. Ключ эффекта — (attachment_id, pipeline_version, name): первичный ключ attachment_variants, вставка через on conflict do update. S3-ключи детерминированы: attachments/<id>/original, attachments/<id>/v1/{thumbnail.jpg,crop.jpg,optimized.webp}. Повтор перезаписывает те же объекты и не создаёт второго набора.
  • Захват и lease. update jobs set status='processing', lease_owner, lease_until = now() + lease where status='queued' and next_attempt_at <= now(). Сообщение для задачи в любом другом состоянии подтверждается без работы (job delivery skipped), поэтому повторная доставка ready-задачи — no-op. Lease = JOB_TIMEOUT_SECONDS + 15 s. Фиксация результата и перевод в retry/failed выполняются только при совпадении lease_owner и attempt. Worker, потерявший lease, не перезапишет состояние (lease lost, result discarded).
  • Зависший или долгий. Задача ограничена контекстом JOB_TIMEOUT_SECONDS (60 s), поэтому живой worker не может законно работать дольше lease. Каждые 5 s reaper в worker переводит задачи с истёкшим lease в queued со следующей попыткой или в failed. Новый захват получает новый attempt. Старый процесс не сможет зафиксировать результат из-за fencing. Запись тех же детерминированных объектов безвредна.
  • Retry. Временные ошибки (S3, PostgreSQL, timeout, истёкший lease) дают queued с attempt+1, новой строкой outbox с available_at = now() + delay и записью причины в jobs.last_error. Задержка d = min(JOB_BACKOFF_BASE_MS·2^(n−1), JOB_BACKOFF_MAX_MS) выбирается случайно в [d/2, d] (equal jitter). Всего JOB_MAX_ATTEMPTS = 5 попыток, затем failed с retry_exhausted. Постоянные ошибки сразу дают failed без повторов: invalid_image (файл не декодируется, превышен лимит пикселей), processing_failed (staging отсутствует или не совпадает sha256/размер).
  • Реестр failed и replay. Реестр — jobs со статусом failed (worker failed выводит attachment_id, attempt, error_code, last_error). worker replay <attachment_id> переводит в queued только задачу в failed: даёт новый бюджет из JOB_MAX_ATTEMPTS попыток, пишет аудит в job_replays и строку outbox. Для ready/queued/processing результат skipped_<status>, дубля нет.
  • Варианты. Все варианты строятся из пикселей и кодируются заново, поэтому EXIF и прочие метаданные не копируются. EXIF orientation (JPEG) применяется, alpha компонуется на белый, ресемплинг Catmull-Rom. Изображения больше 2560 px сначала уменьшаются вдвое блоком 2×2, чтобы ограничить промежуточный буфер. Итоговые размеры считаются от исходных.
    • thumbnail: JPEG q=85, вписан в 256×256, без увеличения, размеры округляются вниз, минимум 1 px; fixture 320×200 → 256×160.
    • crop: JPEG q=85, центральный квадрат, 128×128, маленькие исходники увеличиваются.
    • optimized: WebP lossy, quality 80, method 4, вписан в 1280×1280 без увеличения. Уменьшение каждого маленького файла не обещается.
  • Состояния API. POST upload → 202 queued. GET метаданных возвращает queued / processing / ready / failed. Для ready в variants три записи с размерами и sha256 реального файла. /content для не-ready → 409. variant= с неизвестным именем → 400. Отсутствующий вариант ready-объекта → 404. Прикрепить failed-вложение к сообщению → 409, queued/processing можно. Ready ставится одной транзакцией после записи оригинала и всех трёх вариантов.
  • Staging. Удаляется worker'ом после COMMIT ready. Если удаление не прошло, janitor удаляет staging ready-вложений и staging без строки (старше CLEANUP_GRACE_SECONDS). Staging failed хранится STAGING_RETENTION_SECONDS (24 ч) ради replay. Staging queued/processing не удаляется.
  • Критичные зависимости. /health/ready проверяет только PostgreSQL. Брокер не нужен синхронному пути: при его недоступности загрузки принимаются, задания копятся в outbox. Upload и download требуют S3 (иначе 503).
  • Внедрение отказов. FAULT_POINT по умолчанию пуст. В тестах через API_FAULT_POINT=after_commit (выход процесса после COMMIT, до ответа и publish) и WORKER_FAULT_POINT=after_store|before_ack (выход после записи в S3 до COMMIT / после COMMIT до ack).
  • Перенесено из lab4 без изменения смысла: сессии, идемпотентность сообщений, HAProxy, приватный bucket и отдельные ключи, janitor (дополнен очисткой staging), лимиты загрузки. Изменено: upload 201 → 202, attachments.object_key заполняется worker'ом, добавлена миграция 0004_jobs.sql.

Окна отказа

Окно Что происходит Восстановление
после staging до записи задания объект в staging/ без строки, клиент получает 503 или обрыв janitor удаляет его после grace period
после COMMIT до publish строка outbox не опубликована relay любой API-реплики публикует; проверено (faults.py, 1)
после publish до confirm/пометки сообщение в stream, строка outbox не помечена повторная публикация → дубль → no-op при захвате
после записи S3 до COMMIT результата задача processing, объекты записаны lease истекает → reaper → попытка 2 перезаписывает те же ключи; проверено (faults.py, 2)
после COMMIT результата до ack ready, сообщение в PEL после рестарта worker дочитывает pending → no-op → ack; проверено (faults.py, 3)

Соответствие .env.example

Переменная Где используется
API_REPLICAS deploy.replicas сервиса api
S3_REGION, S3_BUCKET api, worker, janitor, s3-init, генерация прав в mksecrets.sh
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS api (приём) и worker (повторная проверка)
WORKER_CONCURRENCY число потребителей worker
JOB_MAX_ATTEMPTS api записывает в jobs.max_attempts, replay выдаёт новый бюджет
JOB_TIMEOUT_SECONDS таймаут задачи, lease = значение + 15 s
JOB_BACKOFF_BASE_MS, JOB_BACKOFF_MAX_MS backoff повторов
STAGING_RETENTION_SECONDS хранение staging failed-вложений (janitor)
CLEANUP_GRACE_SECONDS, CLEANUP_INTERVAL_SECONDS janitor
BROKER_URL_FILE, DATABASE_URL_FILE, S3_*_FILE задаются в compose как пути к secrets

Лимиты worker

Ограничение Значение
Bytes размер staging должен совпасть с метаданными; чтение не более MAX_UPLOAD_BYTES, sha256 сверяется
Пиксели image.DecodeConfig до декодирования, не более MAX_IMAGE_PIXELS (40 млн), иначе invalid_image
Время JOB_TIMEOUT_SECONDS на задачу (S3, БД, проверки между этапами)
Память 2 задачи одновременно, GOMEMLIMIT=600MiB, лимит контейнера 768 MiB, CPU 1.0
Конкуренция WORKER_CONCURRENCY=2, prefetch (COUNT) 1 на потребителя

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

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke (202 → ready, оригинал, настоящий JPEG 256×160) make check && make test PASS evidence/smoke.txt
Отозванная сессия не воскресает после перезапуска Valkey tests/session_revocation.py Valkey остановлен → logout 204 → Valkey запущен → прежний токен 401 evidence/session-revocation.txt
Минимум lab4 сохранён (валидация, доступ, приватный bucket, отказ S3, идемпотентность) tests/attachments.py, tests/s3_checks.py, tests/idempotency.py PASS: 413/415/400/404, анонимный доступ 403, 503 при остановленном S3 evidence/attachments.txt, evidence/s3-checks.txt, evidence/idempotency.txt
Restart всех stores с volumes make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; перезапущены postgres, valkey, broker, s3, api, lb, janitor, worker (состояния до/после в файле) evidence/persistence.txt
Failover каждой API-реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh PASS для api-1 и api-2, 0–1 неуспешная попытка, восстановление 3.5 s evidence/failover-1.txt, evidence/failover-2.txt
Worker остановлен → upload 202 → сообщение → content 409 → рестарт broker и API → worker запущен → ready tests/queue_recovery.py задача есть в stream до и после рестарта broker, статус queued без worker, после старта ready, attempt 1, 3 варианта evidence/queue-recovery.txt
Повторная доставка не размножает варианты tests/queue_recovery.py (ручной XADD дубля) job delivery skipped, ack, updated_at не изменился, 3 варианта evidence/queue-recovery.txt
Thumbnail, crop 128×128, optimized WebP, качество/метаданные tests/variants.py размеры и форматы по реальным байтам, sha256 совпадает, без увеличения, alpha → белый, EXIF orientation 6 применена, EXIF в вариантах нет evidence/variants.txt
Crash между COMMIT и publish tests/faults.py, сценарий 1 API упал после COMMIT (202 не получен), outbox опубликован другой репликой, ready attempt 1 evidence/faults.txt
Остановка worker после записи объекта до COMMIT, timeout/lease tests/faults.py, сценарий 2 lease истёк, reaper вернул в очередь, ready attempt 2, вариантов 3 evidence/faults.txt
Остановка worker после COMMIT до ack tests/faults.py, сценарий 3 после рестарта pending доставлен повторно, no-op, attempt 1, PEL пуст evidence/faults.txt
Backoff с jitter, ограниченный retry, failed, replay tests/faults.py, сценарий 4 S3 остановлен: 4 повтора с задержками 931/1284/2760/7484 мс (окна [d/2, d]), retry_exhausted, задача в реестре, content и прикрепление → 409; replay → ready, повторный replay → skipped_ready, аудит 1 строка evidence/faults.txt
Постоянная ошибка без повторов tests/faults.py, сценарий 5 PNG с повреждённым IDAT (проходит проверку API) → invalid_image на попытке 1 evidence/faults.txt
Ограничение конкуренции, памяти и времени worker tests/worker_load.py 6 изображений по 39.9 млн пикселей + 20 малых: одновременно не более 2 processing, пик RSS 617 MiB при лимите 768 MiB, без OOM; при JOB_TIMEOUT_SECONDS=1 — context deadline exceeded, 5 попыток, retry_exhausted evidence/worker-load.json
Очистка staging после безопасной фиксации tests/s3_checks.py staging ready-вложения удалён, staging queued-задачи сохранён janitor'ом, staging без строки удалён evidence/s3-checks.txt
Память API при загрузках tests/upload_memory.py 12 потоков × 3 файла по 9.3 MiB, 36/36 → 202, пик api 119 / 100 MiB при лимите 192 evidence/upload-memory.json
Отказ реплики и rolling update под нагрузкой tests/scenario.py см. эксперименты evidence/failover-each.json, evidence/rolling.json

Эксперименты и отказы

Стенд: один хост, Docker 29.9.2, Compose 5.6.1, лимиты контейнеров как выше. Нагрузка сообщений — 8 потоков, closed-loop, повтор с тем же ключом. Нагрузка worker — 6 PNG 6320×6320 (116 545 байт, однотонные: проверка лимита пикселей, а не сети) и 20 копий fixture.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Worker остановлен, upload 202, работа ждёт queued, content 409, текст работает после старта worker ready, потерь нет
Restart broker и API с volumes при остановленном worker задача не теряется job_id в stream до и после потерь нет
Падение API после COMMIT задача не теряется без ручного вмешательства outbox опубликован живой репликой ready в пределах секунд, потерь нет
Падение worker после записи S3 повтор того же результата ready с attempt 2 после истечения lease 25 s (тест с JOB_TIMEOUT_SECONDS=10) ≈ lease + 5 s, дублей нет
Падение worker после COMMIT повторная доставка = no-op skipped, ack сразу после рестарта
S3 недоступен для worker ограниченные повторы, failed 5 попыток за ≈ 13 s, retry_exhausted, replay → ready после replay, потерь нет
6×40 Мп + 20 малых не более 2 задач одновременно, память в лимите все ready за 13.1 s, пик RSS 617 MiB / 768 без OOM и рестартов
Остановка каждой API-реплики под нагрузкой запись продолжается 2 и 0 неуспешных попыток, RPS 439 / 447 против 524 до отказа возврат реплики около 6.5 s
Rolling update без простоя 4 неуспешные попытки, RPS 615 старые реплики не отвечают

Первая версия без предварительного уменьшения упиралась в лимит 512 MiB (RSS 780 MiB при двух 40-Мп задачах). Причина — промежуточный буфер Catmull-Rom размером ширина_цели × высота_источника × 32 байта. После уменьшения блоком 2×2 пик стал около 600 MiB, а время двух таких задач сократилось с 11 до 4.6 s.

Ограничения и следующие шаги

  • Декодирование и ресемплинг одного этапа нельзя прервать: timeout проверяется между этапами и на S3/БД-операциях. Длительность этапа ограничена лимитом пикселей (около 2 s на 40 Мп).
  • Broker, PostgreSQL, S3 и HAProxy — единичные экземпляры. appendfsync always надёжнее, но медленнее everysec. Stream не обрезается (XTRIM не реализован), он растёт на одну запись на попытку.
  • Relay работает только в API: если остановлены обе реплики API, принятые задания ждут в outbox. Задержка relay до 300 ms.
  • Имена потребителей привязаны к hostname контейнера: после пересоздания worker старые pending переходят к новым через XAUTOCLAIM только после lease (75 s), а старые consumer'ы остаются в группе.
  • EXIF orientation читается только у JPEG; eXIf-чанк PNG не учитывается.
  • pipeline_version фиксирован (1). Версионирование нескольких pipeline (трек 5) не делалось.
  • Replay — операторская CLI-команда без HTTP API. last_error хранит внутренний текст ошибки только в БД и наружу не выдаётся.
  • WebP кодируется транспилированным libwebp (без CGo): медленнее нативного, но без системных библиотек.
  • Секреты лежат в ./secrets вне Git. Для чтения процессом с UID 10001 у них права 644: это допустимо только для локального стенда.