22 KiB
Отчёт - лабораторная 5
- Автор, группа: Алексей Миронов, БВТ2302
- Целевая оценка: 4 (трек 5 не заявляется)
- Commit/PR:
d26ef6elab 5 + kafka message broker, #32 - Источники, библиотеки, помощь ИИ: FastAPI 0.116.1, psycopg 3.2.9, boto3 1.40.20, Pillow 11.3.0, confluent-kafka 2.10.1 (librdkafka), Apache Kafka 3.9.0 (KRaft), PostgreSQL 17.6, Redis 7.4.2, HAProxy 3.2.5, MinIO-совместимый S3. Код lab5 собран на базе lab4; использовалась помощь ИИ
Запуск из чистого clone
Требования: Docker Compose v2, Python 3.9+ для тестов. Секреты - в локальном .env (в git не коммитится; значения синтетические, шаблон - .env.example).
make check
make validate
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build # postgres, redis, s3, kafka -> init/migrate -> api x2, worker, dispatcher, sweeper, haproxy
# дождаться готовности (до ~60 с):
until curl -fs http://localhost:8080/health/ready; do sleep 2; done
make test # публичный smoke
python3 student-tests/level4_failures.py all # сценарии сбоев уровня 4
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
Безопасная остановка: docker compose stop (volumes сохраняются). Намеренное удаление учебных данных: docker compose down -v. Перезапуск всех хранилищ: scripts/restart.sh; остановка одной API-реплики: scripts/stop-one.sh (hostname = X-Instance-Id). Оператор: failed-реестр и replay - docker compose exec worker python scripts/replay_failed.py --list | --job-id <uuid> --reason <text>.
Архитектура и решения
Клиент -> HAProxy -> API x2 --(1) PUT staging/<random> --> S3 (private bucket)
\--(2) ONE TX: attachments(queued) + attachment_jobs + outbox --> PostgreSQL => 202
dispatcher: outbox -> Kafka (acks=all, idempotent producer, delivery report) ; reaper (lease)
worker (consumer group): Kafka message(IDs only) -> claim+lease в PG -> staging -> imgproc (child, limits) -> final S3 -> TX ready -> offset commit
- Источник истины - PostgreSQL (
attachments.status,attachment_jobs,attachment_variants,outbox,job_events). Kafka - транспорт at-least-once: сообщение содержит только ID (jobs.schema.json), без байтов/ключей/URL. - Staging - приватный префикс
staging/того же приватного bucket; honest-граница: staging в S3, файл уже полностью принят и сохранён до 202. Оригинал воркер публикует вattachments/<id>/v1/original, варианты -.../v1/{thumbnail,crop,optimized}. Ключ эффекта(attachment_id, pipeline_version, variant)= PKattachment_variants+ детерминированный S3-ключ. - Kafka: топик
attachment-jobs(3 партиции, key = attachment_id, RF=1, min.insync=1, volumekafka_data). Группаattachment-workers,enable.auto.commit=false. Publisher confirm = delivery report продюсера приacks=all(приём брокером); consumer ack = commit offset после фиксации результата в PG. - Outbox: строка outbox вставляется в ту же транзакцию, что и attachment/job. Relay берёт строки
FOR UPDATE SKIP LOCKED, публикует, ставитpublished_atтолько по delivery report. Падение между COMMIT и publish -> строка осталась, relay доставит позже; между publish и mark -> дубль сообщения (допустим, идемпотентность на потребителе). - Retry: временные ошибки (S3/сеть/timeout/неожиданный код дочернего процесса) ->
queued,next_attempt_at = now + backoff(экспонента 2·2^(n-1), cap 60 с, equal jitter [d/2, d]), задержка реализована отложенной строкой outbox (available_at). Постоянные (invalid_image,image_too_large,image_too_complex,integrity_error,staging_missing) -> сразуfailed.JOB_MAX_ATTEMPTS=5, исчерпание ->retry_exhausted. Каждый failed сохраняется в реестре PostgreSQL (attachment_jobs) и журналеjob_events. - Lease:
lease_until = now + JOB_TIMEOUT(60) + grace(15). Dispatcher возвращаетprocessingс истёкшим lease вqueued(новая попытка) или вfailed. Повторная доставка при живом lease - no-op (конкурентные дубли не запускаются), при готовом/failed - no-op. - Конкурентность/prefetch:
consume(num_messages=WORKER_CONCURRENCY)+ ThreadPool = не более 2 job одновременно;queued.max.messages.kbytes=1024. Лимиты обработки: байты 10 MiB (API, до чтения тела), пиксели 40 млн (из заголовка до декодирования), времяJOB_TIMEOUT_SECONDS(kill дочернего процесса), памятьRLIMIT_AS=IMG_MEMORY_MB(1024 МБ) +mem_limitконтейнера, CPURLIMIT_CPU. - Варианты: thumbnail JPEG q85 (вписан в 256×256, без увеличения, EXIF-orientation применён, alpha на белом; 320×200->256×160); crop JPEG q85, центрированный квадрат 128×128; optimized WebP q80 (вписан в 1280×1280 без увеличения, alpha сохраняется, EXIF/ICC не переносятся). Ready - только когда записаны все три и COMMIT выполнен одной транзакцией.
- Очистка staging: воркер удаляет staging после COMMIT; sweeper (grace 1 ч) удаляет сироты
staging/иattachments/<id>/без строки БД; staging failed-вложений хранитсяSTAGING_RETENTION_SECONDS(24 ч), после чего replay невозможен (нужна повторная загрузка). - Readiness API: PostgreSQL, Redis (сессии), S3. Kafka и worker не критичны: приём работает через outbox.
- Перенесено из lab4 без изменений: пользователи, Argon2id, сессии в Redis, чаты, сообщения, keyset-пагинация, идемпотентность (advisory lock + атомарная запись), HAProxy, bucket/политики s3_init (+
staging/*), sweeper. Изменено: 201->202, статусы и варианты в метаданных, 409 для content не-ready и для прикрепления failed, новые таблицы (миграция 004), сервисы kafka/worker/dispatcher. - Соответствие .env.example:
BROKER_URL_FILE->KAFKA_BOOTSTRAP_SERVERS(без паролей, PLAINTEXT во внутренней сети backend),WORKER_CONCURRENCY,JOB_MAX_ATTEMPTS,JOB_TIMEOUT_SECONDS,STAGING_RETENTION_SECONDS,MAX_*- те же имена. Secrets в_FILE-виде не используются (учебное упрощение lab4: переменные окружения).
| Роль | Сервис | Версия | Health | Volume |
|---|---|---|---|---|
| load_balancer | load_balancer | haproxy 3.2.5-alpine | haproxy -c / backend check /health/ready |
- |
| api | api (2 реплики) | свой образ | /health/ready |
нет (stateless) |
| postgres | postgres | 17.6-alpine | pg_isready | postgres_data |
| sessions | redis | 7.4.2-alpine, AOF | redis-cli ping | redis_data |
| s3 | s3 (+s3_init) | pgsty/silo (MinIO-совм.) | mc ready | s3_data |
| broker | kafka (+kafka_init) | apache/kafka 3.9.0 | kafka-broker-api-versions | kafka_data |
| worker / dispatcher / sweeper | worker, dispatcher, s3_sweeper | свой образ | перезапуск unless-stopped |
- |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Структура проекта и синтаксис Python | make check |
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. |
evidence/evidence.txt |
| OpenAPI 3.1 и JSON Schema | make validate |
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. Контракты прошли валидацию. |
evidence/evidence.txt |
| Корректность конфигурации Compose | docker compose --env-file .env config --quiet |
Команда завершилась без вывода ошибки. | evidence/evidence.txt |
| Готовность приложения | curl -fs http://localhost:8080/health/ready в цикле ожидания |
Получен ответ {"status":"ok"}. |
evidence/evidence.txt |
| Публичный smoke | make test |
PASS: lab5 public API scenario; infrastructure and grading evidence remain separate. |
evidence/evidence.txt |
| 202 и устойчивый приём; worker остановлен -> upload -> рестарт API -> worker -> ready | python3 student-tests/level4_failures.py all - сценарий worker_down |
PASS worker_down; события: accepted,claimed,ready. |
evidence/evidence.txt |
| Crash между COMMIT и publish; восстановление доставки через outbox | python3 student-tests/level4_failures.py all - сценарий commit_publish_gap |
PASS commit_publish_gap; события: accepted,claimed,ready. |
evidence/evidence.txt |
| Crash после записи в S3 до фиксации результата/ack; восстановление по lease | python3 student-tests/level4_failures.py all - сценарий crash_after_s3 |
PASS crash_after_s3; события: accepted,claimed,lease_expired,claimed,ready. Повторный claim после истечения lease завершился ready. |
evidence/evidence.txt |
| Retry при временной недоступности S3 | python3 student-tests/level4_failures.py all - сценарий s3_outage |
PASS s3_outage; события: accepted,claimed,retry_scheduled,claimed,retry_scheduled,claimed,retry_scheduled,claimed,ready. Зафиксированы три планирования повторной попытки, после чего задача завершилась успешно. |
evidence/evidence.txt |
| Реестр failed и операторский replay | python3 student-tests/level4_failures.py all - сценарий replay |
Команда вывела REPLAYED job=... attachment=...; сценарий завершился PASS replay. Последовательность событий: accepted,claimed,failed,replay,claimed,ready. |
evidence/evidence.txt |
| Сохранность данных после перезапуска хранилищ и сохранение существующей сессии | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. Тест подтвердил сохранность проверенных данных и существующей сессии |
evidence/evidence.txt |
| Работа при остановке одной API-реплики | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
Перед воздействием наблюдались 2 экземпляра API; выполнено 88 успешных записей, 2 неуспешные попытки; первое восстановление - 3.153 с. Итог: PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence. |
evidence/evidence.txt |
| Отдельные broker и worker, durable-сообщения, at-least-once, ack только после устойчивого эффекта | Реализованы отдельные сервисы Kafka broker и worker в compose.yaml; Kafka использует persistent volume kafka_data. В src/dispatcher.py producer настроен с acks=all и idempotence, outbox помечается опубликованным только после подтверждения доставки. В src/worker.py автоматический commit offset отключён: сообщение подтверждается только после записи вариантов в S3 и фиксации состояния ready в PostgreSQL. | worker_down, commit_publish_gap, crash_after_s3 - PASS. В crash_after_s3 после lease_expired задача была повторно получена и завершилась состоянием ready. | Реализация подтверждается compose.yaml, src/dispatcher.py, src/worker.py; порядок подтверждения дополнительно проверен fault-injection сценариями. Kafka работает с RF=1: persistent volume обеспечивает сохранение данных при перезапуске, но репликационной защиты от потери единственного брокера нет. |
| Crop 128×128, optimized WebP и ограничения обработки по bytes/pixels/time/memory | В src/imgproc.py реализованы центрированный crop 128×128 JPEG q85 и optimized WebP q80 с ограничением размера 1280×1280; метаданные исходного изображения не переносятся. В src/main.py ограничен размер входного файла (10 MiB): проверяется Content-Length и фактический объём потокового тела; количество пикселей ограничено 40 000 000 до декодирования. В src/worker.py обработка выполняется с ограничением времени 60 секунд. В src/imgproc.py используются RLIMIT_CPU и RLIMIT_AS=1024 MiB; в compose.yaml для worker задан mem_limit: 1g. | Функция check_variants() в student-tests/level4_failures.py проверяет наличие crop 128×128 и WebP (image/webp). Она используется в сценариях worker_down, commit_publish_gap, crash_after_s3, replay, s3_outage; все пять сценариев завершились PASS. | Все преобразования и ограничения обработки реализованы в исходном коде и конфигурации; размеры crop и формат WebP дополнительно проверяются автоматическими сценариями. |
| Lease для зависшего processing, ограниченные concurrency/prefetch и очистка staging | В src/jobs.py задан срок lease на основе JOB_TIMEOUT_SECONDS и LEASE_GRACE_SECONDS (60+15 секунд). В src/dispatcher.py просроченные задачи processing возвращаются в queued с повторной публикацией через outbox. В src/worker.py ограничены параллелизм (WORKER_CONCURRENCY=2) и количество получаемых сообщений (consume(num_messages=CONCURRENCY)); также заданы ограничения Kafka fetch/prefetch. После фиксации ready worker удаляет staging-файл. scripts/s3_sweep.py удаляет осиротевшие staging-объекты после проверки ссылок в PostgreSQL; grace period - 3600 секунд, период запуска - 600 секунд, срок хранения staging для failed - 86400 секунд. | crash_after_s3 - PASS: после lease_expired задача повторно получена (claimed) и завершилась ready. | Восстановление по lease подтверждено fault-injection тестом; ограничения concurrency/prefetch и механизм очистки staging подтверждаются реализацией в src/worker.py, src/jobs.py, src/dispatcher.py, scripts/s3_sweep.py. |
Эксперименты и отказы
Среда проведения экспериментов:
- ОС: Microsoft Windows 11 Pro 10.0.22631 (build 22631).
- CPU: Intel Core i5-8350U, 4 ядра / 8 потоков.
- RAM: 15.9 GB.
- Docker Compose: v2.32.4-desktop.1.
- Docker Client/Engine: 27.5.1; Docker Desktop 4.38.0; контекст
desktop-linux.
Перед функциональными сценариями выполнены make check, make validate и docker compose --env-file .env config --quiet. Первые две команды завершились с PASS; в их выводе отдельно указано, что они не тестируют работающее приложение. Compose config завершился без сообщения об ошибке. После запуска стенда readiness endpoint вернул {"status":"ok"}. Публичный smoke (make test) завершился с PASS.
Сценарии отказов уровня 4
Команда python3 student-tests/level4_failures.py all завершилась успешно для всех пяти сценариев:
| Воздействие | Наблюдаемые события / результат | Вывод |
|---|---|---|
Остановка worker, приём задания и последующий запуск worker (worker_down) |
accepted,claimed,ready; PASS worker_down |
Задание обработано после восстановления worker. |
Разрыв между фиксацией задания в PostgreSQL и публикацией (commit_publish_gap) |
accepted,claimed,ready; PASS commit_publish_gap |
Задание в итоге доставлено и обработано без ручного вмешательства. |
Аварийное завершение после записи в S3 (crash_after_s3) |
accepted,claimed,lease_expired,claimed,ready; PASS crash_after_s3 |
После истечения lease задача была повторно захвачена и завершена. |
Повторный запуск задания из failed-реестра (replay) |
accepted,claimed,failed,replay,claimed,ready; команда вывела REPLAYED; PASS replay |
Failed-задание прошло операторский replay и завершилось успешно. |
Недоступность S3 во время обработки (s3_outage) |
accepted,claimed,retry_scheduled,claimed,retry_scheduled,claimed,retry_scheduled,claimed,ready; PASS s3_outage |
Зафиксированы три запланированные повторные попытки; после восстановления S3 задача завершилась успешно. |
Сохранность данных и отказ API-реплики
| Воздействие | Наблюдаемый результат | Время восстановления / потеря данных |
|---|---|---|
Перезапуск хранилищ: make test-persistence ACTION_SCRIPT=scripts/restart.sh |
PASS: persistence preserved confirmed data and existing session. |
Проверенные подтверждённые данные и существующая сессия сохранены. |
Остановка одной API-реплики: make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
До воздействия наблюдались 2 экземпляра; 88 успешных записей, 2 неуспешные попытки; PASS: failover preserved confirmed data and existing session. |
Первое восстановление - 3.153 с; тест сообщил о сохранении подтверждённых данных и существующей сессии. |
Ограничения и следующие шаги
Один брокер Kafka (RF=1): при потере диска kafka_data сообщения могут быть потеряны; автоматического восстановления потерянного брокерного лога нет. PostgreSQL остаётся источником истины для состояния job, но восстановление доставки после потери самого лога не гарантируется. Лимит памяти - RLIMIT_AS + mem_limit, не cgroup-метрика RSS по job. Валидация изображения (декодирование) при upload выполняется в API (перенос lab4), resize - только в worker. Replay доступен оператору через CLI, не через публичный API (контракт не менялся). Трек 5 не реализован; нагрузочные измерения pipeline не проводились.