Files
mtusi2026lab5/openspec/changes/add-lab5-async-attachments/design.md
T
ArtyomandClaude Opus 5.5 d9bcc7324b Propose asynchronous attachment processing as an openspec change
Plan grade 3 of lab 5: upload answers 202 queued after the original is
in a private staging prefix and the attachment, its job and an outbox
row are committed in one transaction; a separate relay publishes the
outbox to a RabbitMQ quorum queue with publisher confirms and returns
jobs with an expired lease; a separate worker on FastStream claims a
job under a lease, publishes the original and a 256 px JPEG thumbnail,
commits the result fenced by the lease token and acks only after the
commit, retries transient errors up to JOB_MAX_ATTEMPTS and fails
undecodable images at once. Content answers 409 until ready and a
failed attachment cannot be sent.

The change adds the lab5-attachment-pipeline and lab5-job-delivery
capabilities and deltas to lab4-attachments, lab4-upload-resilience,
lab1-messenger-history and lab3-load-balancing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 00:42:15 +03:00

22 KiB
Raw Blame History

Context

Мотивация — в proposal.md. Решение лабы 4 — три зоны за HAProxy с двумя репликами, PostgreSQL как источник истины, RustFS с приватным bucket, upload со строкой-намерением pending → PutObject → ready, компенсацией и уборкой намерений старше grace period. Контракт 1.5.0 меняет только ответ upload и enum статусов, но вводит формат сообщения брокера (jobs.schema.json) и машину состояний с окнами отказа (attachment-states.md). Брокер, топология, compose-фрагмент, хуки и suite сценариев заранее проверены на заглушке в .prep/lab5 и встраиваются, а не пишутся заново. Пользователь требует FastStream 0.7 поверх aio-pika для consumer и publisher и интеграцию dishka.

Goals / Non-Goals

Goals:

  • 202 ровно тогда, когда оригинал в устойчивом staging и вложение, задание и намерение публикации зафиксированы одной транзакцией; дальше работу не теряет ни остановка API, ни рестарт брокера.
  • PostgreSQL — источник истины состояний; брокер — транспорт и будильник: любое потерянное сообщение восстанавливается из PostgreSQL, любое лишнее гасится идемпотентным эффектом.
  • Ровно один набор вариантов на ключ (attachment_id, pipeline_version, variant), ready не откатывается, ack — только после COMMIT.
  • Зоны по-прежнему не импортируют друг друга, shared/ не знает ни FastStream, ни веб-фреймворка.

Non-Goals:

  • Crop, optimized, ProcessPool с таймаутом и лимиты памяти worker, crash-точки окон 2–5, jitter, DLQ-демонстрация и replay, heartbeat аренды, retention failed — уровень «4».
  • pipeline_version 2 и монотонная публикация как доказательство — трек 2 (условие published_version < v закладывается сразу, потому что без него повтор не идемпотентен).

Decisions

D1. Процессы и границы зон

Три процесса из одного образа: api (gunicorn, messenger.main:create_app()), relay (python -m messenger.relay), worker (python -m messenger.worker). relay.py и worker.py лежат рядом с main.py и migrate.py: это сборки процессов, а не каталог точек входа; они знают только зону attachments и shared. Тест графа импортов разрешает несколько зон только main.py, а сборкам процессов — одну.

Вся новая логика — в зоне attachments:

  • domain/jobs.py — задание Job и его сообщение по jobs.schema.json, аренда Lease, политика повторов RetryPolicy, коды FailureCode, исходы Outcome; domain/variants.py — Variant, геометрия fit (вписать в квадрат, вниз, минимум 1 px).
  • application/ — порты JobPublisher (публикация с подтверждением), VariantRenderer (байты оригинала → варианты), Faults (точки внедрения отказа), расширенные ObjectStorage (read, copy) и AttachmentsUnitOfWork (репозитории jobs, outbox); команды ProcessJob, PublishOutbox, RecoverExpiredLeases, CleanStaging и их обработчики.
  • infrastructure/ — rabbitmq.py (адаптер JobPublisher на RabbitBroker.publish), images.py (адаптер VariantRenderer на Pillow), faults.py (FAULT_POINT), SQL заданий в postgres.py.
  • entrypoints/ — worker.py (FastStream-подписчик, разбор сообщения, ack/reject), relay.py (циклы outbox и уборки), heartbeat.py, PipelineProvider в ioc.py, схема сообщения в schemas.py.

Порт зоны messaging AttachmentStates.unusable(chat_id, ids) отвечает «есть ли среди вложений failed»; адаптер поверх AttachmentDirectory зоны attachments собирает main.py. Получаем: SQL каждой зоны читает свои таблицы, messaging не знает о статусах. Стоит: один лишний запрос при отправке сообщения с вложениями; гонка «вложение стало failed сразу после проверки» допустима — контракт говорит о состоянии на момент запроса.

D2. Схема — миграция 0004_jobs.sql (expand)

ALTER TABLE attachments
    DROP CONSTRAINT attachments_status_check,
    ADD CONSTRAINT attachments_status_check
        CHECK (status IN ('pending', 'queued', 'processing', 'ready', 'failed')),
    ADD COLUMN staging_key text COLLATE "C" UNIQUE,
    ADD COLUMN original_key text COLLATE "C" UNIQUE,
    ADD COLUMN published_version integer NOT NULL DEFAULT 0 CHECK (published_version >= 0),
    ADD COLUMN error_code text CHECK (error_code IN ('invalid_image', 'processing_failed', 'retry_exhausted')),
    ALTER COLUMN object_key DROP NOT NULL;
UPDATE attachments SET original_key = object_key, published_version = 1 WHERE status = 'ready';
UPDATE attachments SET staging_key = object_key WHERE status = 'pending';
CREATE INDEX attachments_staged_idx ON attachments (updated_at) WHERE staging_key IS NOT NULL;

CREATE TABLE attachment_variants (
    attachment_id uuid NOT NULL REFERENCES attachments (id),
    pipeline_version integer NOT NULL CHECK (pipeline_version >= 1),
    name text NOT NULL CHECK (name IN ('thumbnail', 'crop', 'optimized')),
    object_key text COLLATE "C" NOT NULL UNIQUE,
    content_type text NOT NULL CHECK (content_type IN ('image/jpeg', 'image/png', 'image/webp')),
    size_bytes bigint NOT NULL CHECK (size_bytes >= 1),
    width integer NOT NULL CHECK (width >= 1), height integer NOT NULL CHECK (height >= 1),
    sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
    created_at timestamptz NOT NULL,
    PRIMARY KEY (attachment_id, pipeline_version, name));

CREATE TABLE jobs (
    job_id uuid PRIMARY KEY,
    attachment_id uuid NOT NULL REFERENCES attachments (id),
    pipeline_version integer NOT NULL CHECK (pipeline_version >= 1),
    status text NOT NULL CHECK (status IN ('queued', 'processing', 'done', 'failed', 'superseded')),
    attempt integer NOT NULL CHECK (attempt >= 1), claims integer NOT NULL DEFAULT 0,
    lease_token uuid, lease_until timestamptz, next_attempt_at timestamptz, last_error text,
    created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL,
    UNIQUE (attachment_id, pipeline_version));
CREATE INDEX jobs_lease_idx ON jobs (lease_until) WHERE status = 'processing';

CREATE TABLE outbox (
    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    job_id uuid NOT NULL REFERENCES jobs (job_id),
    payload jsonb NOT NULL, available_at timestamptz NOT NULL, published_at timestamptz);
CREATE INDEX outbox_pending_idx ON outbox (available_at, id) WHERE published_at IS NULL;

CREATE TABLE job_events (
    id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    job_id uuid NOT NULL, attachment_id uuid NOT NULL, kind text NOT NULL,
    attempt integer, detail jsonb NOT NULL DEFAULT '{}', at timestamptz NOT NULL DEFAULT now());
CREATE INDEX job_events_attachment_idx ON job_events (attachment_id, id);

Колонки совпадают с tools/schema.reference.sql из .prep/lab5, на которые опирается suite. object_key лабы 4 остаётся nullable до contract-миграции: новые строки его не пишут, старые ready получают original_key и published_version = 1. Индексы: частичный outbox_pending_idx обслуживает выборку relay (Index Scan по (available_at, id) с LIMIT), jobs_lease_idx — поиск истёкших аренд, attachments_staged_idx — уборку staging. Получаем: каждое окно отказа видно в SQL. Стоит: ещё четыре таблицы и одна запись outbox на попытку.

D3. Upload: staging и одна транзакция

Обработчик лабы 4 сохраняется до записи объекта: членство → имя → Content-Type → поток со счётчиком → проверка изображения → строка pending → PutObject staging/<uuid>. Вместо ready агрегат переходит в queued (Attachment.enqueue), и одной транзакцией выполняются: UPDATE attachments SET status = 'queued' WHERE id = $1 AND status = 'pending', INSERT jobs (job_id = uuid7, pipeline_version = 1, attempt = 1, status = 'queued'), INSERT outbox (payload, available_at = now()), INSERT job_events ('enqueued'). После COMMIT ответ 202 строится из объекта в памяти — перечитанное состояние могло бы уже быть processing.

Окно 1 (после staging до записи задания): 202 не отдан; компенсация лабы 4 сразу удаляет объект и строку, а при крахе процесса строку pending с объектом убирает уборка намерений лабы 4 по grace period. Отказ транзакции даёт 503, как в лабе 4.

D4. Outbox и relay

Relay раз в OUTBOX_POLL_SECONDS (1 с) в транзакции выбирает до OUTBOX_BATCH строк WHERE published_at IS NULL AND available_at <= now() ORDER BY available_at, id FOR UPDATE SKIP LOCKED, публикует каждую и помечает published_at = now() той же транзакцией. Публикация — RabbitBroker.publish в exchange attachments (пассивно, без объявления) с routing key attachment.process.v1, persist=True, mandatory=True, message_id = job_id, message_type = attachment.process.v1, content_type = application/json, телом — ровно payload строки. Канал брокера открыт с publisher_confirms=True и on_return_raises=True: возврат unroutable-сообщения и basic.nack — ошибка, строка остаётся неопубликованной, транзакция откатывается.

Окно 2 (после COMMIT, до publish): строка ждёт в outbox и публикуется после рестарта relay. Окно 3 (после publish, до confirm или до published_at): повторная публикация даёт дубль с тем же job_id; его гасит захват (D5). Publisher confirm означает «брокер записал в quorum queue», а не «обработано»: это разные границы, обработку подтверждает только consumer ack.

SKIP LOCKED позволяет держать несколько relay. Держать транзакцию на время публикации допустимо: confirm в локальной сети — миллисекунды, пачка ограничена, idle_in_transaction_session_timeout 10 с. LISTEN/NOTIFY не вводится: опрос раз в секунду укладывается в бюджет smoke 60 с.

D5. Worker: захват, обработка, фиксация, ack

FastStream RabbitBroker с logger=None (журнал — только порт Logger), подписчик на RabbitQueue("attachments.process", declare=False, queue_type=quorum) без exchange (привязку не трогает), Channel(prefetch_count=WORKER_CONCURRENCY), AckPolicy.MANUAL, graceful_timeout 5 с. Обработчик берёт сырые байты сообщения и проверяет их pydantic-моделью с extra="forbid" по jobs.schema.json; невалидное — reject(requeue=False) в DLX. dishka-контейнер подключён через dishka-faststream: worker использует те же PlatformProvider и адаптеры, что API.

Захват:

UPDATE jobs SET status = 'processing', lease_token = $4, lease_until = now() + make_interval(secs => $5),
       claims = claims + 1, updated_at = now()
WHERE job_id = $1 AND attachment_id = $2 AND pipeline_version = $3
  AND ((status = 'queued' AND coalesce(next_attempt_at, '-infinity') <= now())
       OR (status = 'processing' AND lease_until < now()))
RETURNING attempt, created_at;

плюс UPDATE attachments SET status = 'processing' WHERE id = $2 AND status = 'queued' и событие claimed. Нет строки — job уже done/failed/superseded, её держит живая аренда или повтор ещё не наступил: событие duplicate_noop, ack. attempt в сообщении информационный: захват идёт по job_id.

Обработка: прочитать staging_key (или original_key, если staging уже убран), отрисовать варианты в потоке, CopyObject staging → originals/<id>, PutObject variants/<id>/<version>/<name>-<sha256[:16]>.jpg. Ключ варианта содержит хеш: повтор с другими байтами не перезапишет объект, на который ссылается БД.

Фиксация — одна транзакция:

UPDATE jobs SET status = 'done', lease_token = NULL, lease_until = NULL, updated_at = now()
WHERE job_id = $1 AND status = 'processing' AND lease_token = $2;          -- 0 строк → fenced, ROLLBACK
INSERT INTO attachment_variants (...) SELECT ... FROM unnest(...) ON CONFLICT DO NOTHING;
UPDATE attachments SET status = 'ready', published_version = $3, error_code = NULL,
       original_key = $4, updated_at = $5
WHERE id = $6 AND published_version < $3;                                   -- 0 строк → superseded

После COMMIT — ack. Окно 4 (после записи S3 до COMMIT): объекты есть, строк нет; redelivery или истёкшая аренда повторяют ту же работу по тем же ключам. Окно 5 (после COMMIT до ack): redelivery видит done и подтверждает no-op. Ошибка PostgreSQL до или во время фиксации — nack(requeue=True) через секунду; если аренда уже взята, задание вернёт relay по её истечении.

Получаем: at-least-once доставки + идемпотентный эффект = один опубликованный результат; это не exactly-once — дубли доставки есть (окна 3 и 5), их гасит ключ эффекта. Стоит: две транзакции на задание и запись в job_events на каждый переход.

D6. Повторы и финальные ошибки

Временная ошибка (Unavailable от S3 и PostgreSQL, точка transient_error): RetryPolicy(JOB_MAX_ATTEMPTS, JOB_BACKOFF_BASE_SECONDS, cap 60 с) даёт задержку min(cap, base·2^(attempt−1)), пока attempt < JOB_MAX_ATTEMPTS; задание получает queued, attempt + 1, next_attempt_at, новую строку outbox с available_at = next_attempt_at и тем же job_id, вложение — queued (не failed: smoke падает на первом же failed). На последней попытке — failed с retry_exhausted. Постоянная ошибка (Pillow не декодирует, неподдерживаемый режим) — сразу failed с invalid_image, без повторов. Любая непредвиденная ошибка рендера — processing_failed. Все переходы — с fencing по lease_token и только для вложения не в ready. В error_code — короткий код, в jobs.last_error — имя класса ошибки, без текста исключения.

Аренда: JOB_TIMEOUT_SECONDS (60) — больше обработки thumbnail и меньше consumer_timeout брокера (300 с). Relay раз в SWEEP_INTERVAL_SECONDS (5) возвращает processing с lease_until < now() по той же политике (lease_expired), поэтому убитый или остановленный посреди задания worker не оставляет вечный processing. Продление аренды heartbeat-ом и демонстрация fencing — уровень «4».

D7. Thumbnail

Pillow: ImageOps.exif_transpose до расчёта размеров; 16-битные режимы масштабируются в L; палитра с прозрачностью, LA, RGBA компонуются на белый фон; остальное — convert("RGB"). Размер — fit(w, h, 256): при max(w, h) > 256 длинная сторона 256, короткая max(1, short·256 // long), иначе без изменений; Image.thumbnail() не используется, потому что округляет к ближайшему. resize(..., LANCZOS), JPEG quality=85, optimize=True, без EXIF и ICC. Fixture 320×200 → 256×160. Рендер идёт в asyncio.to_thread под семафором WORKER_CONCURRENCY; ProcessPool с таймаутом — уровень «4».

D8. Чтение через API

GET /attachments/{id} отдаёт любой статус, кроме внутреннего pending, с вариантами published_version. /content: посторонний — 404; статус не ready — 409 conflict для любого variant; original — объект original_key с content_type оригинала; thumbnail — вариант опубликованной версии; варианта нет (crop на уровне «3») — 404; неизвестный variant — 400 валидацией параметра. Читается сначала строка и членство, потом S3.

D9. Брокер и стенд

Встраивается .prep/lab5: broker — rabbitmq:4.1.8-management-alpine по digest, hostname: broker (имя узла и каталог данных в volume не меняются при пересоздании), volume broker-data, read-only rootfs, uid 100, лимит 512 MiB; топология без секретов в infra/rabbitmq/definitions.json (vhost messenger, exchange attachments → quorum attachments.process, DLX attachments.dlx → attachments.process.dlq, политика delivery-limit 10, overflow reject-publish), пользователи с хешами паролей — compose secret из scripts/broker-secrets.sh. Права: messenger-api (relay) только пишет в attachments, messenger-worker только читает attachments.process, configure — только у messenger-ops. UI брокера — 127.0.0.1:${BROKER_MANAGEMENT_PORT}. relay и worker — образ приложения, сеть backend, init: true, read-only, heartbeat-файл /tmp/heartbeat (цикл жив и брокер отвечает на ping; от PostgreSQL и S3 не зависит), SIGTERM ≤ 10 с; у worker свой S3-пользователь (чтение staging/, запись originals/ и variants/), у relay — ключ API (удаление staging). У api секрета брокера нет; /health/ready от брокера не зависит, как и от S3 в лабе 4: outbox развязывает приём и брокер.

Хуки: restart.sh останавливает lb, api, relay, worker, перезапускает postgres, valkey, s3, broker и ждёт up --wait. Обвязка: worker.sh (stop/start/kill), broker.sh (restart/queues), pipeline_suite.py с --level 3, infra/compose.faults.yaml (короткие аренда и backoff, restart: "no", FAULT_POINT). Точка transient_error читается при старте worker и только через faults-override.

Risks / Trade-offs

  • Блокировка outbox на время publish → при недоступном брокере relay каждую секунду ждёт таймаут соединения; выборка ограничена пачкой, API не страдает.
  • Удаление staging делает relay, а не worker: у worker нет права DeleteObject, staging живёт на несколько секунд дольше. Если relay упал между удалением объекта и обнулением staging_key, повтор удаления безопасен.
  • Задание с живой арендой после краха worker ждёт до JOB_TIMEOUT_SECONDS + SWEEP_INTERVAL_SECONDS; уменьшение аренды без heartbeat рискует двойной работой (её гасит fencing).
  • Ошибка PostgreSQL на захвате возвращает сообщение в очередь; после 10 возвратов оно уходит в DLQ, а задание остаётся queued с опубликованной строкой outbox. Переопубликация таких заданий — уровень «4» (replay).