Files
mtusi2026lab5-fork/REPORT.md
T

18 KiB
Raw Blame History

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

  • Автор и группа — Ситосенко, БВТ2303.
  • Целевая оценка — 5, трек 2 «Доказанная идемпотентность pipeline».
  • Реализация основана на собственном коде lab4. Codex использовался для переноса кода, реализации очереди, подготовки эксперимента и проверки.
  • Источники — Valkey Streams, Valkey AOF, условная запись S3, Pillow.

Запуск

Нужны Docker с Linux-контейнерами, Compose v2 и Python 3.9+ для клиентских проверок. Для сборки нужен доступ к реестру образов, Go modules и PyPI. Команды запуска в PowerShell из корня clone.

python -X utf8 scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 150
$env:BASE_URL = "http://127.0.0.1:8080"
python -X utf8 scripts/check_contract.py
python -X utf8 tests/smoke.py
python -X utf8 student-tests/image_rules.py
python -X utf8 student-tests/pipeline_faults.py

На Unix эквиваленты проверки контракта и публичного smoke — make check и make test. Проверки перезапуска выполняются последовательно на выделенном учебном стенде.

make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
docker compose start api

Bootstrap генерирует локальные секреты и .env при их отсутствии. Миграции 001–005 применяет одноразовый сервис migrate. Старые записи lab4 с исходником в original/<id> читаются по этому ключу с result_version=0. Сервис s3-init создаёт приватный бакет и ограниченные учётные записи. API доступны через HAProxy на 127.0.0.1:8080. APP_PORT задаёт внешний порт. При его изменении задайте тестам соответствующий BASE_URL.

docker compose down останавливает стенд и сохраняет volumes. docker compose down --volumes предназначена для намеренного удаления данных своего учебного проекта после завершения проверок.

Стек использует Go 1.27.3, PostgreSQL 17.6, Valkey 8.1.3, HAProxy 3.2.6, MinIO из фиксированного коммита 9e49d5e7a648, Python 3.13.18 и Pillow 13.0.0. compose.yaml задаёт лимиты сервисов. Worker получает 1 vCPU, 640 MiB памяти, 32 MiB tmpfs и обрабатывает одно задание за раз с prefetch 1. Локальный HTTP используется для синтетических данных.

Архитектура

  1. API проверяет Bearer-сессию, членство в чате, filename, MIME, целостность изображения и лимиты 10 MiB и 40 млн пикселей. Исходные байты и SHA-256 передаются в приватный S3 staging под серверным UUID. Принятие до 202 queued включает завершившийся S3 PUT и commit строки вложения вместе с записью задания в PostgreSQL.
  2. image_jobs служит реестром заданий и transactional outbox. Dispatcher отправляет JSON одним полем job через XADD, затем фиксирует признак публикации. JSON несёт поля schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at по jobs.schema.json. Valkey для очереди имеет собственный volume, AOF с appendfsync always и noeviction.
  3. Worker читает Streams через consumer group, захватывает задание с lease и сверяет ID, версию и номер попытки с PostgreSQL. Истёкшие lease восстанавливает dispatcher. XAUTOCLAIM возвращает потерянные pending delivery. После устойчивого завершения либо записи retry/failed worker подтверждает доставку и удаляет запись из Streams одной командой Lua. Дубли завершённых и устаревших попыток подтверждаются по сохранённому состоянию.
  4. Worker проверяет SHA-256 и длину исходника и запускает ограниченный по времени процесс Pillow. Thumbnail — JPEG качества 85, вписанный в 256×256, с округлением вниз и без увеличения. Crop — JPEG качества 85, центрированный квадрат 128×128. Optimized — WebP качества 80 в v1 и 90 в v2, до 1280×1280 без увеличения. Для вариантов применяется EXIF orientation, прозрачность компонуется на белый фон, а EXIF, ICC и текстовые метаданные удаляются. Исходник сохраняется побайтно.
  5. Эффект привязан к (attachment_id, pipeline_version, variant). S3 PUT с If-None-Match: * исключает повторную запись уже существующего объекта. При 412 сверяются размер, MIME и SHA-256 из метаданных объекта. После записи всех объектов одна транзакция фиксирует результат с проверкой активной версии и lease. GET использует атомарно опубликованную версию. Читатели видят v1 в ходе подготовки v2 и переключаются на v2 после commit.
  6. Невалидное изображение и нарушение целостности считаются постоянными ошибками. Временный отказ возвращает задание в очередь с экспоненциальной задержкой и jitter от 100% до 200% базового интервала, с базой от 1 до 32 секунд. По исчерпании лимита выдаётся retry_exhausted. Dispatcher очищает staging после публикации результата, для failed — после retention, для orphan — после часа и повторной проверки строки под тем же lock, что использует upload.
  7. Разрешения S3 разделены для API и фоновой обработки. API пишет staging и читает опубликованные варианты, фоновая учётная запись может записывать результаты и удалять staging. API сохраняет регистрацию, Argon2id, постоянные сессии Valkey, права чата, keyset-пагинацию и идемпотентность сообщений из lab4. Broker, worker и dispatcher работают независимо от синхронной readiness API, которая проверяет PostgreSQL, Valkey сессий и S3.

JOB_MAX_ATTEMPTS задаёт число попыток за цикл (5 по умолчанию), JOB_TIMEOUT_SECONDS — время обработки (30 секунд). Lease длиннее на 5 секунд. STAGING_RETENTION_SECONDS — срок хранения failed-исходника для replay (86400 секунд). WORKER_CONCURRENCY=1 закрепляет один слот в контейнере. Лимиты байт и пикселей зафиксированы в коде по контракту. Настройки endpoint, region и bucket в Compose относятся к встроенному локальному S3.

Команды оператора доступны через Compose и используют доступ к PostgreSQL.

docker compose run --rm --no-deps dispatcher jobs failed
docker compose run --rm --no-deps dispatcher jobs replay <job-id>
docker compose run --rm --no-deps dispatcher jobs upgrade <attachment-id>

Replay разрешён для текущего failed-задания, пока staging может использоваться. Он сохраняет job_id, увеличивает attempt, начинает новый цикл и добавляет запись в аудит. Для v2 источником служит опубликованный оригинал v1. Upgrade переводит готовый результат v1 на v2 без изменения публичного HTTP API.

Эксперимент

Гипотеза. Подтверждённая загрузка доходит до ready после каждого моделируемого сбоя. Переотправка или переупорядочивание заданий сохраняет по одному набору объектов на версию и оставляет опубликованную v2 неизменной.

Скрипт student-tests/pipeline_faults.py использует синтетический PNG 320×200 и последовательно проводит сценарии на одном стенде. Каждый сценарий получает новый attachment ID. Для сбоя запускается отдельный контейнер нужной роли с failpoint, привязанным к этому ID. Скрипт проверяет код завершения 86 и маркер точки сбоя. Через HTTP, PostgreSQL, Streams и S3 проверяются статусы, попытки, опубликованные версии, размеры, контрольные суммы и время записи объектов. Время в JSON отсчитывается от получения 202 и включает запуск контейнеров и ожидание подтверждений. Это последовательная проверка корректности, без нагрузочного прогона.

Критерий Проверка Доказательство
Публичный контракт и smoke scripts/check_contract.py, tests/smoke.py contract.txt, openapi.txt, smoke.txt
Отправка сообщения с queued-вложением, перезапуск API и broker при остановленном worker Сценарий api_broker_restart_with_worker_stopped, сверка StartedAt, записи Streams и оригинала pipeline.json
Геометрия, EXIF, alpha, форматы и лимиты student-tests/image_rules.py image-rules.txt
COMMIT до XADD и сбой после XADD Сценарии before_publish и after_publish pipeline.json
Lease и сбой до/после записи S3 и после commit до ack before_effect, after_effect, after_commit, проверка pending и LastModified/ETag pipeline.json
Ограниченный retry, failed и операторский replay invalid_image_replay, temporary_replay, проверка backoff и записи аудита pipeline.json
Reorder и поздняя доставка старой версии reorder_and_stale_version, проверка версии и неизменности S3 pipeline.json

Прогон выполнялся в Docker Desktop на Windows, движок Docker 29.3.0, Compose 5.1.0, Linux amd64. Docker VM предоставляла 12 логических CPU и 3,68 GiB памяти. Дополнительного прогрева не было, перед экспериментом прошли smoke и проверка форматов. Для каждого воздействия использовалась одна загрузка и отдельный набор ожидаемых переходов.

Результаты прогона

Воздействие Наблюдение Время сценария
Перезапуск API и брокера Та же запись Streams сохранилась после перезапуска трёх контейнеров. Сообщение было создано с queued-вложением. Исходник и варианты доступны после запуска worker. 39,9 с
Сбой до XADD В Streams было 0 записей. Dispatcher восстановил задание из outbox, после чего загрузка стала ready. 29,0 с
Сбой после XADD Dispatcher опубликовал тот же job_id повторно. Две доставки завершились одним набором вариантов и одной попыткой. 29,0 с
Сбой до записи S3 В S3 результата ещё не было. Истечение lease запустило вторую попытку, вложение стало ready. 60,8 с
Сбой после записи S3 До сбоя был записан оригинал. Вторая попытка сохранила его ETag и LastModified, дописала варианты и опубликовала результат. 88,9 с
Сбой после commit до ack Была pending-доставка при ready. Повтор подтвердил её без дополнительной попытки и перезаписи объекта. 49,0 с
Постоянная ошибка Одна попытка, затем invalid_image. Операторский replay завершился ready с одной записью аудита. 42,2 с
Временная ошибка После 5 попыток получен retry_exhausted. После replay вложение стало ready. 73,7 с
Переупорядочивание и поздний дубль Последовательность версий 2, 1, 2, 1, 2 сохранила один результат на версию и итоговую v2. Проверены контрольные суммы, ETag и LastModified. 62,4 с

Во всех девяти сценариях подтверждённая загрузка дошла до ready. Сырые результаты с ID и длительностью сохранены в pipeline.json. Прогон выполнен с настройками из .env.example и именем проекта mtusi-lab5.

Для сборки Linux amd64 govulncheck не нашёл достижимых уязвимостей в Go-коде. Проверка охватывает Go-пакеты приложения. go-vuln.txt

Публичные persistence и failover прошли с неизменёнными тестами и сессией. Сценарии сохранили подтверждённые сообщения и оригинал вложения. Прогон failover через localhost на Windows дал около 2 с задержки клиента на запрос и исчерпал окно записи. При первом прогоне по IPv4 холодный запуск Argon2id превысил таймаут регистрации. Зачётный прогон через 127.0.0.1 после двух синтетических регистраций и входов дал 115 успешных записей, 4 переходных ошибки и первую успешную запись после остановки через 3,881 с. persistence.txt, failover.txt, до перезапуска, после перезапуска, до остановки реплики, после остановки реплики

Границы

XADD и commit в PostgreSQL — отдельные операции. Подтверждение XADD означает приём брокером. Consumer ack относится к отдельной доставке и может потеряться после успешной фиксации результата. Поэтому Streams доставляет at least once, а единственность эффекта обеспечивают условная запись S3 и проверка состояния в PostgreSQL.

Эксперимент проверяет отказы процессов и рестарт broker с сохранённым volume. Потеря хоста или постоянного хранилища, сетевой split-brain и максимальная пропускная способность за пределами методики. Старые конечные версии сохраняются для чтения и анализа. MinIO CE унаследован из lab4 и ограничен внутренним сегментом и фильтрацией HAProxy. Стенд рассчитан на локальный учебный запуск.