26 KiB
Отчёт — лабораторная 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(statusqueued, 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). StagingfailedхранитсяSTAGING_RETENTION_SECONDS(24 ч) ради replay. Stagingqueued/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: это допустимо только для локального стенда.