Files
mtusi2026lab6/PIPELINE.md
T

15 KiB
Raw Blame History

Основа ЛР6: асинхронный pipeline из ЛР5

Ответ на первый вопрос преподавателя

«Я перенёс свой мессенджер с приватным S3 и вынес преобразование изображений в отдельный worker. API проверяет доступ, формат и лимиты, сохраняет полный оригинал в S3 staging, затем в одной транзакции PostgreSQL создаёт queued-вложение и durable job/outbox. Только после COMMIT возвращает 202. Dispatcher публикует служебное сообщение в Valkey Streams, worker читает его через consumer group. Worker публикует неизменённый оригинал, thumbnail JPEG, crop JPEG и optimized WebP, затем атомарно переводит метаданные в ready. XACK выполняется после устойчивого результата или сохранённого решения о retry/failed.

Я проверил окна аварий, конечные повторы и явный replay. Для исследования сделал две версии pipeline и fencing результата: ключи объектов включают версию, а COMMIT проверяет текущую версию и lease token. Даже реально продолжившийся старый worker не перезаписывает новый результат. Доставка остаётся at least once; идемпотентен эффект, а не сеть».

Общая схема

flowchart LR
 C[Клиент] --> LB[HAProxy]
 LB --> A[API × 2]
 A --> S[S3 staging]
 A --> D[(PostgreSQL: attachment + job/outbox)]
 D --> P[Dispatcher]
 P --> B[(Valkey Streams + AOF)]
 B --> W[Worker: bounded concurrency]
 W --> F[S3 final: original + 3 variants]
 W --> D
 C -->|poll metadata / download with ACL| LB
sequenceDiagram
 participant A as API
 participant S as S3
 participant D as PostgreSQL
 participant P as Dispatcher
 participant B as Streams
 participant W as Worker
 A->>S: PUT staging/full original
 A->>D: COMMIT queued + job
 A-->>A: 202 queued snapshot
 P->>D: read durable unpublished job
 P->>B: XADD (AOF fsync always)
 P->>D: mark published
 B->>W: XREADGROUP
 W->>D: claim, attempt, lease token
 W->>S: PUT versioned original/variants
 W->>D: fenced COMMIT ready
 W->>B: XACK, then XDEL

202 не означает, что worker уже завершил работу. Файл всё равно полностью проходит по сети до API и сохраняется до ответа. Staging уже находится в S3, поэтому worker читает его и отдельно публикует final objects; это не перенос из памяти API в S3.

Четыре вопроса из README

Чем publisher confirm отличается от consumer ack? Publisher confirm подтверждает приём публикации брокером, consumer ack — устойчивую обработку получателем. В нашем Valkey Streams нет отдельного RabbitMQ confirm-протокола: успешный XADD при appendfsync always — граница приёма persistent брокером, XACK убирает доставку из pending. Между этими границами worker ещё может упасть. Дополнительно намерение хранится в PostgreSQL и повторно публикуется outbox.

Что именно уже сохранено в момент 202? Полные проверенные bytes в приватном staging/<UUID>; в PostgreSQL — метаданные queued и запись job в одной committed-транзакции. Публикация в broker может ещё не произойти. Именно outbox позволяет честно принять работу, пока broker недоступен. Нельзя отвечать 202 после одного запуска goroutine или записи файла в ephemeral disk API.

Почему повторная доставка нормальна и где ключ идемпотентности job? При разрыве соединения невозможно всегда знать, получил ли broker XACK или producer ответ XADD. Поэтому допускаем повтор. Логическая job определяется job_id, эффект — (attachment_id, pipeline_version, variant). Ключи S3 детерминированы внутри версии, метаданные fenced по версии и lease token; ready/stale delivery — no-op. В таблице UNIQUE (attachment_id,pipeline_version). Это не exactly-once доставка.

Как отличить зависший worker от долго работающего и не запустить два неконтролируемых дубля? Работа имеет persisted lease 45s и уникальный token; pipeline budget 30s, transform subprocess 20s. После истечения lease работу можно захватить снова, но старый token больше не вправе опубликовать SQL-результат. XAUTOCLAIM/redispatch используют 60s. Ограничены concurrency и чтение Count=1 на consumer. Одни часы/heartbeat без fencing не запрещают старому процессу продолжить запись после паузы. Наши разные версии пишут в разные prefixes; одинаковая версия с тем же immutable исходником и закреплёнными параметрами даёт тот же эффект. При смене алгоритма нужна новая pipeline version.

Состояния

stateDiagram-v2
 [*] --> queued: durable stage + DB COMMIT
 queued --> processing: claim + lease token
 processing --> ready: all objects + fenced COMMIT
 processing --> queued: transient error + persisted backoff
 processing --> failed: permanent error / 5 attempts
 processing --> queued: expired lease after crash
 failed --> queued: explicit audited replay

Нельзя выдавать content queued/processing/failed: 409. Можно создать сообщение с queued/processing вложением своего чата. Failed прикреплять нельзя: 409. Чужой chat/attachment остаётся 404. Сессия и членство проверяются до доступа к файлу; приватный bucket и случайный UUID не заменяют ACL.

Окна аварии

Где остановились Что осталось Как восстанавливаемся
После staging до SQL COMMIT journal/orphan, клиент не получил 202 grace cleanup; автоматического подтверждения клиенту нет
После COMMIT до XADD durable queued + job dispatcher читает outbox
После XADD до mark published возможны два сообщения оба указывают на одну job; идемпотентный эффект
После claim до PUT processing + lease reclaim/redispatch после дедлайна
После PUT до result COMMIT final objects, статус processing повтор с теми же versioned keys, fenced COMMIT
После ready COMMIT до XACK готовый результат + pending delivery ready no-op, XACK
Старый v1 продолжился после v2 старые ключи и старый lease v2 prefix не затрагивается; SQL проверяет version/token

S3 не является участником SQL-транзакции. ROLLBACK не отменяет PUT. Не удаляем bytes при неопределённом COMMIT: SQL мог уже зафиксироваться. Staging удаляется только после ready COMMIT, при сбое уборки его найдёт housekeeping.

Изображения и ресурсы

API: bytes ≤10 MiB, PNG/JPEG MIME и полная decode-валидация, ≤40 млн pixels до полной распаковки, filename не путь. В очереди нет bytes, URL, credentials. Worker получает storage key из доверенной БД, проверяет размер и SHA-256 исходника. Transform идёт отдельным процессом: 20s deadline, группа дочерних процессов убивается вместе. Temp directory удаляется; после SIGKILL ephemeral temp остаётся только в container layer до его удаления и не служит источником истины.

EXIF orientation применяется до resize; alpha компонуется на белый фон. Thumbnail вписывается в 256×256 без увеличения, размеры округляются вниз, минимум 1px. 320×200 → 256×160. Crop — центрированный квадрат 128×128, допускает увеличение. Optimized — WebP ≤1280×1280 без увеличения. JPEG/WebP quality v1 = 85/80, v2 = 90/82; перекодирование убирает EXIF. Оригинал остаётся побайтно исходным. WebP маленького файла может оказаться больше исходника.

По умолчанию 1 worker slot, CPU=1, RAM limit=1024MiB, Go memory limit=768MiB. Это реальная декодированная память, не постоянные несколько kilobytes «streaming». Concurrency 1–4 настраивается, при увеличении нужно отдельно выбирать RAM. Prefetch соответствует Count=1 на каждый consumer. Admission атомарно ограничивает незавершённые jobs 1000, затем 429 + Retry-After. Broker memory 192MiB/noeviction внутри container 256MiB: при заполнении XADD откажет, outbox остаётся в БД. Это не неограниченная очередь.

Retry, DLQ и уборка

Временная S3/сетевая ошибка → queued, следующий запуск через 2^attempt seconds + jitter [0,1)s. Всего 5 попыток. Повреждённый/несовпавший checksum исходник → failed invalid_image. Исчерпание → retry_exhausted. failed_jobs — SQL-реестр финальных ошибок (эквивалент DLQ), pipeline_audit хранит claims/errors/operator replay. Replay не разрешён для ready и требует доступного исходника.

Housekeeping проходит каждый час, собирает только staging после 24h grace. Текущие queued/processing защищены всегда; redundant ready staging можно удалить, failed source хранится не меньше 7 days. Metadata и final objects не удаляются этим сборщиком. Старые final versions сохраняются; их GC здесь не реализован. Volume не backup; один broker/MinIO/PostgreSQL/host остаются SPOF.

Что показать руками

  1. make test: 202 → ready, download original и thumbnail.
  2. Остановить worker, загрузить файл, увидеть queued и 409 content; текстовые сообщения продолжаются при доступных PG/S3.
  3. Запустить worker, получить ready той же записи.
  4. pipeline.py: реальные границы аварий и дубли; version_fence.py: живой старый v1 после v2.
  5. retry_backpressure.py: 5 ошибок, финальное failed, явный replay и 429 при заполненном admission ledger.
  6. Найти SQL claim/lease/token и S3 originals/<id>/v<version>/... в коде, объяснить COMMIT и XACK.

Вопросы посложнее

  • Почему не local queue в API? Она теряется с процессом, не общая для реплик и не даёт durable handoff.
  • Можно ли retry upload POST? Обязательный контракт не даёт upload idempotency: повтор может создать новое вложение. Сообщения защищены отдельным Idempotency-Key.
  • Почему DB — источник истины очереди? Broker переносит доставку, DB связывает job, версию, состояние, lease и outbox в одной транзакции.
  • Что если пропадёт весь broker volume? DB намерения сохраняются; незавершённые опубликованные jobs переиздаются через 60s. Это восстановление доставок, не HA broker.
  • Зачем XDEL после XACK? Одна consumer group, завершённый delivery больше не нужен; stream не растёт от уже обработанных сообщений. Не удаляем pending до ACK.
  • Почему не просто MAXLEN stream? Можно обрезать ещё не прочитанные/pending jobs. Мы ограничиваем приём и память, а не теряем незавершённые записи при trim.
  • Что если POST вернул timeout после COMMIT? Клиент не знает исхода. Job не теряется, но новый upload может стать вторым объектом; нельзя обещать exactly-once приём HTTP без отдельного ключа.
  • Почему 60s recovery не нарушает smoke? Smoke задаёт 60s для свободного исправного worker, не SLA восстановления аварии. Наблюдённая crash recovery около 60s обусловлена выбранной политикой reclaim.

Финальная обработка учитывает JPEG APP1 и PNG eXIf orientation перед resize. Только явный invalid-image exit65 считается permanent; crash/kill/deadline encoder проходит bounded retry. Проверка текущего кода — evidence/race-final.txt.