Files
mtusi2026lab5/REPORT.md
T
2026-11-10 07:01:17 +03:00

18 KiB
Raw Blame History

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

Автор: Григорян Илья Мурадович, БПИ2303. Целевая оценка текущего этапа: 4. Обновлено 10.11.2026. Дальнейшая цель — 5; исследовательский трек ещё не выбран. Использована помощь Codex при реализации, проверках и исправлениях. Commit/PR: заполнить после публикации.

Запуск

Нужны Python 3.12, pip, Docker с Compose. Зависимости закреплены в requirements.txt.

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make init
make up
make test

make init создаёт отсутствующие .env и файлы secrets/, сохраняя существующие. Все environment-параметры Compose подставляются из .env; образец — .env.example. Пароли и S3 credentials читаются из файлов secrets, не включаются в задания. API не получает credentials брокера. По умолчанию HTTP доступен на http://localhost:18081. Broker, MinIO и основные PostgreSQL/Redis наружу не открыты.

При обновлении ранее запущенного стенда сначала остановить старые процессы через make down без удаления volumes, затем выполнить make up. Migrate применяет ревизии до a62c950e18b3 перед стартом приложения. Миграции добавляют jobs, варианты, бюджет попыток и аудит replay. Готовые вложения раннего варианта lab5 переобрабатываются для заполнения crop/WebP. При переходе Redis Streams → RabbitMQ миграция повторно публикует queued jobs из PostgreSQL; processing восстанавливаются по истечении lease. Старые процессы обоих брокеров во время перехода должны быть остановлены.

Инфраструктура и устойчивый приём

Компонент Реализация Данные
API две реплики FastAPI, Python 3.12.15 PostgreSQL и Redis сессий
Балансировка nginx 1.28.0 единая HTTP-точка входа
База PostgreSQL 16.10 сообщения, metadata, jobs, outbox, audit
Сессии Redis 7.4.2, AOF always redisdata
Объекты приватный MinIO staging, originals, variants
Брокер RabbitMQ 4.4.0 durable очередь, rabbitmqdata
Publisher отдельный процесс приложения, aio-pika 10.2.2 PostgreSQL → RabbitMQ
Worker отдельный процесс приложения RabbitMQ → MinIO + PostgreSQL
Cleanup отдельный процесс незавершённые upload и terminal staging

Redis используется для сессий. Очередь заданий использует RabbitMQ через AMQP. Очередь durable, сообщения persistent. Publisher ожидает подтверждение брокером приёма сообщения (publisher confirm) и только затем фиксирует published_attempt. При неизвестном результате публикации возможен дубль; намерение остаётся в БД. Подтверждение worker (consumer ack) следует после устойчивого результата или устойчиво сохранённого перехода retry/failed. При разрыве соединения RabbitMQ возвращает неподтверждённые доставки в очередь.

До ответа 202 queued API полностью принимает и проверяет оригинал, сохраняет его в приватный staging и фиксирует attachment/job одной транзакцией PostgreSQL. Job одновременно служит transactional outbox — устойчивым намерением публикации. Worker и broker не входят в синхронный путь upload и readiness API. Остановка worker не заставляет API выполнять resize. При компенсации неоднозначного COMMIT API проверяет БД, чтобы не удалить оригинал уже принятого задания.

Envelope соответствует contracts/jobs.schema.json: job_id, attachment_id, pipeline_version=1, attempt, created_at, schema_version, type и необязательный trace context. Bytes, имена объектов S3, URL и credentials туда не помещаются. Доступ к вложениям проверяется по участию в чате; content до ready возвращает 409. Аутентификация, пагинация, идемпотентность сообщений и ограничения lab4 сохранены.

Изображения и ограничения

Worker повторно сверяет размер и SHA-256 исходника. Original сохраняется без перекодирования. Все варианты создаются в отдельном ограниченном процессе:

Вариант Формат и размеры Параметры
thumbnail JPEG, вписан в 256×256 без увеличения quality=85, белая подложка alpha
crop JPEG, центральный crop 128×128 quality=85; маленькое изображение увеличивается
optimized WebP, вписан в 1280×1280 без увеличения quality=80, method=4, alpha сохраняется

Применяется EXIF orientation; EXIF/ICC/XMP и текстовые metadata не переносятся в варианты. JPEG создаётся из RGB с белой подложкой, WebP — из чистого RGBA. Алгоритмы используют Pillow 13.0.0. Metadata содержит реальные размеры, bytes и SHA-256.

Лимиты: PNG/JPEG, 10 MiB, 40 млн пикселей; JOB_TIMEOUT_SECONDS=60; IMAGE_MEMORY_MIB=768 адресного пространства и IMAGE_CPU_SECONDS=20 CPU на процесс. Контейнер worker: 2 GiB, 2 CPU, tmpfs 128 MiB. Отмена завершает дочерний процесс; S3 adapter дожидается SDK-потока перед освобождением блокировки/компенсацией.

Повторы, идемпотентность и очистка

Состояния: queued → processing → ready; временный отказ возвращает queued, постоянный отказ или исчерпание бюджета переводит failed с безопасным error_code. JOB_MAX_ATTEMPTS=5 на цикл. Номер attempt монотонен, бюджет закреплён в attempt_limit. Для попытки n текущего цикла ceiling=min(JOB_RETRY_MAX_SECONDS, JOB_RETRY_SECONDS × 2^(n−1)); delay равномерно выбирается в [ceiling/2, ceiling]. База — 5 секунд, максимум — 120 секунд. next_attempt_at сохраняется в БД; дубликат не пересчитывает задержку. Последняя причина остаётся в job даже при публичном retry_exhausted. Ошибки изображения/исходника/конфигурации постоянные; timeout, временные ошибки S3/сети и файловой системы повторяются.

Job захватывается с lease_token и JOB_LEASE_SECONDS=90. Publisher восстанавливает истёкший processing в пределах бюджета. Перед PUT worker блокирует строку job, проверяет актуальность token и lease, держит блокировку до записи original, трёх вариантов и COMMIT ready. Reaper пропускает заблокированные строки. Устаревшая попытка не может начать запись. Фиксированные ключи по (attachment_id, pipeline_version, variant) исключают второй набор объектов. Дубль ready подтверждается без обработки и PUT. Это доставка как минимум один раз с идемпотентным эффектом, не exactly-once выполнение.

WORKER_CONCURRENCY=2, отдельный канал каждого consumer, prefetch=1 на канал. Publisher и worker используют init:true: Python не является PID 1, поэтому fault hooks с SIGKILL действительно завершают процесс. SIGTERM отменяет работу без преждевременного ack. Некорректные envelopes отклоняются без сохранения payload.

Queued/processing staging не удаляется. Для ready retention — 86400 секунд; для failed — FAILED_STAGING_RETENTION_SECONDS=604800 (семь суток). Cleanup и replay блокируют одну строку job. Если staging совпадает с готовым original, объект сохраняется. Частичные конечные объекты failed автоматически не удаляются; после replay используются те же ключи.

Реестр failed и операторский replay

Failed registry находится в PostgreSQL. Команды требуют операторского доступа к Docker/credentials стенда; публичного endpoint для replay нет:

docker compose run --rm --no-deps worker python -m app.core.job_admin list-failed
docker compose run --rm --no-deps worker python -m app.core.job_admin show JOB_ID
docker compose run --rm --no-deps worker python -m app.core.job_admin replay JOB_ID --request-id REQUEST_UUID --actor operator --reason dependency_restored
docker compose run --rm --no-deps worker python -m app.core.job_admin history JOB_ID

JOB_ID/REQUEST_UUID заменить настоящими UUID. Reasons: dependency_restored, configuration_fixed, manual_review. Actor — аудиторская метка, не система входа. Replay принимает только failed, сверяет сохранённый исходник по bytes/SHA-256, атомарно записывает аудит и новый ограниченный бюджет. Счётчик attempt не сбрасывается, старые envelopes не запускают новый цикл. Повтор того же request-id с теми же параметрами возвращает already_applied даже после ready; конфликт параметров отклоняется. После неоднозначного ответа повторяют тот же request-id. Готовую job с новым request-id повторить нельзя. После удаления staging replay отклоняется с source_expired; отсутствующий объект даёт source_missing.

Проверки уровня 3 и 4

Полный воспроизводимый прогон на отдельном стенде:

make test-grade4 PYTHON=.venv/bin/python

Цель последовательно запускает контракт/OpenAPI, тестовый стенд, собственные тесты с реальными PostgreSQL/Redis, публичный smoke, идемпотентность через две реплики, persistence/failover, outbox и сценарии worker/replay. Подготовка БД для pytest выполняется только в выделенной базе *_test, Redis — DB15. Публичные tests/ и обязательные contracts/ не изменены.

Отдельные сценарии на уже работающем изолированном стенде:

make test-outbox-recovery BASE_URL=http://localhost:28080
make test-jobs BASE_URL=http://localhost:28080

При выборе своего проекта задать COMPOSE_PROJECT_NAME и соответствующие порты в окружении. Сценарии сверяют BASE_URL с API выбранного Compose-проекта, создают синтетические данные и возвращают штатные worker/publisher в finally. Перезапуски сохраняют volumes. Сброса пользовательских данных нет.

Результаты и сопоставление каждому пункту приведены в evidence/lab5-verification.json; подробные снимки состояний/объектов/retry — в evidence/lab5-jobs.json. Секреты, tokens и исходные broker payload в evidence не записываются.

Фактический результат проверок

Все перечисленные проверки завершились успешно на отдельном проекте mtusi-lab5-verification, HTTP http://localhost:28080, без удаления volumes:

Проверка Результат
Собственные тесты PostgreSQL/Redis/API/миграций/изображений/OS-лимитов 199 passed, без пропусков
Дополнительные timeout и failed retention/SHA-256 2 passed
Контракт, OpenAPI и Compose config PASS
Публичный smoke PASS
24 конкурентных повтора сообщения через две API-реплики PASS
Публичные persistence и failover PASS
SIGKILL publisher после COMMIT до publish 137 → queued → ready; без повторного upload
Остановленный worker, рестарт API/брокера/хранилищ ready того же ID; сообщение RabbitMQ сохранилось с volume
SIGKILL после четырёх PUT до COMMIT processing → ready на попытке 2; тот же набор/checksums объектов
SIGKILL после COMMIT до ack ready-дубль подтверждён без изменения metadata/Last-Modified
Временная ошибка и replay failed после 5 попыток, затем ready; повтор request-id безопасен
Постоянная ошибка и replay failed после 1 попытки, затем ready; новый replay ready отклонён
Конкуренция/подтверждения RabbitMQ после сценариев 2 consumer, prefetch=1; ready=0, unacknowledged=0
Неизменность публичных tests/contracts/README и whitespace PASS

Суммарно выполнен 201 собственный тест двумя прогонами; новые тесты включены в последующие полные запуски make test-grade4. Тесты намеренно меняют только выделенную БД *_test и Redis DB15. API и worker в интеграционных сценариях используют собственную БД тестового Compose-проекта.

Измеренные задержки пяти неудачных попыток: 4.613, 6.837, 17.323, 30.885, 42.633 секунды; все попали в соответствующие интервалы jitter. Задержка последней failed-попытки сохраняется для диагностики, автоматический retry после исчерпания бюджета не выполняется. Ограничение максимума проверено отдельно.

Во время проверки исправлена проблема fault hooks с PID 1 через init:true. Старые собственные проверки lab4 адаптированы к обязательному переходу 202 queued → ready; публичные проверки не изменены. Цель make test-grade4 переведена на lab5 и последовательные сценарии, чтобы рестарты инфраструктуры не пересекались с регрессией БД. RabbitMQ используется как брокер, Redis — для сессий.

Границы результата

Проверки относятся к одному Docker-хосту и рестартам с сохранением volumes. PostgreSQL, RabbitMQ и MinIO не реплицированы; потеря диска/хоста не покрыта. Ожидание в очереди не ограничено; admission control и исследование перегрузки относятся к будущему уровню 5. Pipeline фиксирован на версии 1; изменение алгоритмов требует решения о новой версии/миграции результатов.

Официальные источники: RabbitMQ reliability, publisher confirms и consumer acknowledgements, aio-pika, Pillow ImageOps, Pillow WebP.