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>
22 KiB
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_version2 и монотонная публикация как доказательство — трек 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).