Files
mtusi2026lab5-fork/REPORT1.md
T
2026-11-07 19:56:48 +03:00

22 KiB
Raw Blame History

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

  • Автор, группа: Алексей Миронов, БВТ2302
  • Целевая оценка: 4 (трек 5 не заявляется)
  • Commit/PR: d26ef6e lab 5 + kafka message broker, mtusi2026/mtusi2026lab5#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) = PK attachment_variants + детерминированный S3-ключ.
  • Kafka: топик attachment-jobs (3 партиции, key = attachment_id, RF=1, min.insync=1, volume kafka_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 контейнера, CPU RLIMIT_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 не проводились.