Every grade 3 item of lab 5 is proven on a stand raised from empty
volumes at fe26938: the public smoke passes with 202 queued and a real
256x160 JPEG thumbnail; the suite runs its six grade 3 scenarios and
eight invariants green, including worker down with both API replicas,
the relay and the broker restarted while the job stays in the queue,
a redelivered finished job that changes nothing, an S3 outage that
recovers on attempt 2 and five transient failures that end in
retry_exhausted; the stand evidence shows the queued job with
delivery mode 2, the job id as message id and exactly the contract
fields, 409 before ready and a clean SIGTERM of the relay and the
worker; persistence restarts all eight services with their volumes,
failover keeps 134 writes without errors, and the lab 4 scenarios,
S3 checks, upload faults and container policy still pass.
The report describes the clean clone start, the processes and the
source of truth, what is stored at the moment of 202, the outbox and
relay, the claim, fencing and ack order of the worker, the retry
policy, the failure windows, the broker topology and permissions, the
roles table and the mapping of .env.example.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
316 lines
44 KiB
Markdown
316 lines
44 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Костылев Артём, БПИ2303
|
||
- Целевая оценка: **5**; трек «5» — **трек 2 «Доказанная идемпотентность pipeline»**
|
||
- Commit/PR: ветка `solution/bpi2303-kostylev`, PR в репозиторий преподавателя
|
||
- Использованные источники, библиотеки и помощь ИИ: FastAPI, gunicorn + uvicorn-worker, dishka и
|
||
dishka-faststream, pydantic, structlog, asyncpg, argon2-cffi, redis-py, aiobotocore/botocore, Pillow,
|
||
FastStream 0.7 (`faststream[rabbit]`) поверх aio-pika, pytest, ruff, ty (версии — `evidence/environment.txt` и
|
||
`uv.lock`); RabbitMQ docs (Reliability Guide, Consumer Acknowledgements and Publisher Confirms, Quorum Queues,
|
||
Dead Lettering, Access Control, Definitions), документация FastStream 0.7 через context7 (ack policy, `Channel`,
|
||
`RabbitQueue(declare=False)`, publisher confirms), Pillow (`ImageOps.exif_transpose`, режимы и альфа-канал),
|
||
Docker Compose (secrets, `depends_on`, healthcheck). Заготовки брокера, compose-фрагмент, хуки и suite
|
||
сценариев — из моей подготовки `.prep/lab5`. Решение перенесено из моей лабы 4 и выполнено с помощью Claude
|
||
Code; код, стенд и отказы проверены прогонами, перечисленными ниже.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker с Compose v2, `make`, системный Python 3.9+ (публичные проверки и сценарии) и `uv` (собственные
|
||
тесты). Образы сторонних сервисов закреплены версией и digest, приложение собирается из исходников.
|
||
|
||
```sh
|
||
git clone <repo> && cd mtusi2026lab5 && git checkout solution/bpi2303-kostylev
|
||
|
||
make secrets # secrets/*: PostgreSQL, Valkey, ключ курсора, root/API/worker-ключи S3, пароли и URL брокера,
|
||
# rabbitmq_users.json с хешами паролей; .env из .env.example (существующее не перезаписывает)
|
||
docker compose --env-file .env config --quiet
|
||
make up # up -d --build --wait: postgres, valkey, s3, broker → migrate, s3-init → api ×2, relay, worker → lb
|
||
make test # публичный smoke через балансировщик, http://localhost:8080
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
make restore # вернуть остановленную реплику и дождаться её в ротации LB
|
||
make suite-preflight && make level3 # сценарии уровня «3» и инварианты → evidence/level3.json
|
||
make pipeline-evidence # worker остановлен: 202, 409, задание в очереди, SIGTERM relay/worker
|
||
make topology # очереди, consumer с prefetch, права, пользователи брокера → evidence/topology.txt
|
||
make worker-stop / make worker-start / make broker-restart / make queues # ручная демонстрация защиты
|
||
|
||
make down # безопасная остановка: контейнеры удаляются, volumes pgdata, valkeydata, s3data, broker-data остаются
|
||
make reset-data # НАМЕРЕННОЕ удаление учебных данных, включая байты вложений и очередь: docker compose down -v
|
||
```
|
||
|
||
`make up` ждёт `healthy` всех долгоживущих сервисов и кода 0 одноразовых `migrate` (миграции под advisory lock)
|
||
и `s3-init` (bucket, анонимный доступ `private`, политики и пользователи API и worker, lifecycle). Топологию
|
||
брокера (vhost, exchanges, quorum-очереди, привязки, политики) и пользователей узел RabbitMQ импортирует из
|
||
`/etc/rabbitmq/definitions.d` на каждой загрузке; повторный `make up`, `restart.sh` и `broker.sh restart` проходят
|
||
без изменений состояния. Наружу публикуются только порты `lb` (`LB_HTTP_PORT` 8080, `LB_STATS_PORT` 8404) и UI
|
||
брокера (`BROKER_MANAGEMENT_PORT` 15672), все на `127.0.0.1`. На машине, где выполнялась работа, параллельно
|
||
работали стенды других лаб, поэтому в локальном `.env` стояли `LB_HTTP_PORT=18085`, `LB_STATS_PORT=25085`,
|
||
`BROKER_MANAGEMENT_PORT=25672`, а проверки запускались с `BASE_URL=http://localhost:18085`. Доказательства уровня
|
||
«3» сняты на стенде, поднятом после `make reset-data` (пустые volumes), на коммите `fe26938`.
|
||
|
||
Собственные проверки и тулчейн:
|
||
|
||
```sh
|
||
make install # uv sync --group dev (Python 3.14 и зависимости из uv.lock)
|
||
make lint # ruff check + ruff format --check (src, student-tests, Python-скрипты стенда) + ty check
|
||
make student-test # собственные тесты; поднимают одноразовые PostgreSQL, Valkey, RustFS и RabbitMQ тех же образов
|
||
make check # офлайн-проверка skeleton
|
||
make validate PYTHON=<venv с requirements-dev.txt>/bin/python # полная валидация OpenAPI и jobs.schema.json
|
||
make stack-evidence / make persistence-evidence / make failover-evidence # как в лабах 3–4
|
||
```
|
||
|
||
**Версии и стенд:** Python 3.14.7 в образе `python:3.14-slim-trixie@sha256:51dafde8…`,
|
||
`rabbitmq:4.1.8-management-alpine@sha256:54ef5ff5…` (RabbitMQ 4.1.8), `rustfs/rustfs:1.0.4@sha256:ed9210d6…`,
|
||
`rustfs/rc:v0.1.36@sha256:ab024bfe…`, `haproxy:3.2.26-alpine@sha256:58938405…`,
|
||
`postgres:17.11-alpine@sha256:266d3c25…`, `valkey/valkey:8.1.11-alpine@sha256:2602ace2…`; FastStream 0.7.8,
|
||
aio-pika 10.2.1, aiormq 7.2.4, dishka-faststream 0.7.0, Pillow 13.0.0; Docker 28.3.2, Compose 2.38.2. Машина —
|
||
Apple M4 Max, 16 CPU, 48 ГБ RAM, macOS 15.1; VM Docker Desktop — 16 CPU, 7.65 ГиБ (`evidence/environment.txt`).
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
┌─ api ×2 (gunicorn) ─ upload: проверка → PUT staging/<id> ──────────────▶ s3: RustFS
|
||
клиент ─HTTP─▶ lb (HAProxy) ─────┤ одна транзакция: attachments(queued) + jobs + outbox + job_events ──▶ postgres
|
||
127.0.0.1:8080 └─ 202 снимок queued; GET метаданных/контента читает PostgreSQL и S3 (источник истины)
|
||
relay ── SELECT outbox … FOR UPDATE SKIP LOCKED ─▶ publish (confirm, mandatory, persistent) ─▶ broker: RabbitMQ
|
||
└─ UPDATE published_at; возврат истёкших аренд; удаление staging у ready quorum attachments.process
|
||
worker ◀── FastStream subscriber, prefetch = WORKER_CONCURRENCY, manual ack ───────────────────────┘ DLX → .dlq
|
||
└─ claim (lease_token) → GET staging → Pillow thumbnail → CopyObject originals/<id>, PUT variants/<id>/1/…
|
||
→ COMMIT (fencing по lease_token, ON CONFLICT DO NOTHING, published_version < v) → ack
|
||
сеть edge: lb, broker (UI на 127.0.0.1) ─── сеть backend (internal): все сервисы
|
||
```
|
||
|
||
**Источник истины.** PostgreSQL — для всего, что знает система о вложении и задании: статус, ключи staging и
|
||
оригинала, опубликованная версия, варианты, попытки, аренда, намерение публикации и журнал переходов. S3 — только
|
||
для байтов (`staging/<id>`, `originals/<id>`, `variants/<id>/<версия>/<имя>-<sha256[:16]>.jpg`). Брокер —
|
||
транспорт и будильник: сообщение несёт только идентификаторы по `jobs.schema.json`, worker берёт ключи хранилища
|
||
из БД. Потерянное сообщение восстанавливается из PostgreSQL (outbox, возврат аренды), лишнее гасится захватом
|
||
задания.
|
||
|
||
**Перенесено из лабы 4 без изменения поведения:** зоны `identity`, `messaging`, `attachments`, порты и адаптеры,
|
||
UoW, шина событий с журналом аудита, ASGI-конвейер, Basic → Bearer, Argon2id, сессии в PostgreSQL с кэшем в
|
||
Valkey, `X-Instance-Id`, `Idempotency-Key`, HAProxy с проверкой готовности, RustFS с приватным bucket, порядок
|
||
проверок upload (лимит тела по маршруту, членство, `filename`, `Content-Type`, слоты, поток со счётчиком,
|
||
проверка изображения по заголовку), компенсация и уборка намерений `pending` по grace period, хуки, сценарии и
|
||
проверки уровня «4» лабы 4. **Изменено:** upload отвечает `202 queued`, оригинал пишется в `staging/`, вместо
|
||
`ready` строка-намерение переходит в `queued` вместе с заданием и outbox; метаданные и `/content` показывают
|
||
статусы и варианты; `messaging` отказывает `409` на `failed`-вложение; новые процессы `relay` и `worker`, сервис
|
||
`broker`, миграция `0004`; `restart.sh` перезапускает ещё брокер, relay и worker; сценарии лабы 4 ждут `ready`.
|
||
|
||
**Процессы и границы зон.** Три процесса из одного образа: `api` (`messenger.main:create_app()`), `relay`
|
||
(`python -m messenger.relay`), `worker` (`python -m messenger.worker`). `relay.py` и `worker.py` — сборки процессов
|
||
рядом с `main.py`; они знают только зону `attachments` и `shared`. Вся логика pipeline — в зоне `attachments`:
|
||
домен заданий (`Job` и его сообщение, `Lease`, `Claim`, `RetryPolicy`, `FailureCode`, `Outcome`, `Variant`, `fit`),
|
||
обработчики `ProcessJob`, `PublishOutbox`, `RecoverExpiredLeases`, `CleanStaging`, порты `JobPublisher`,
|
||
`VariantRenderer`, `Faults`, расширенные `ObjectStorage` и UoW, адаптеры FastStream (`infrastructure/rabbitmq.py`),
|
||
Pillow (`infrastructure/images.py`), PostgreSQL и `FAULT_POINT`, точки входа FastStream-подписчика и циклов relay.
|
||
Ядро `shared/` не импортирует ни веб-фреймворк, ни FastStream, ни aio-pika; dishka-контейнер worker и relay
|
||
собирается из тех же `PlatformProvider` и адаптеров, что у API, через интеграцию `dishka-faststream`. Вопрос
|
||
`messaging` «есть ли среди вложений `failed`» — порт `AttachmentStates` зоны `messaging`, адаптер которого над
|
||
`AttachmentDirectory` собирает `main.py`. Правила проверяет `student-tests/api/test_bounded_contexts.py`.
|
||
|
||
**Схема** (`0004_jobs.sql`, expand): у `attachments` статусы `pending/queued/processing/ready/failed`,
|
||
`staging_key`, `original_key`, `published_version`, `error_code` (CHECK: `invalid_image`, `processing_failed`,
|
||
`retry_exhausted`); `object_key` лабы 4 перенесён в новые колонки и оставлен nullable до contract-миграции. Новые
|
||
таблицы: `attachment_variants` с PK `(attachment_id, pipeline_version, name)` — ключ эффекта — и уникальным
|
||
`object_key`; `jobs` (`UNIQUE (attachment_id, pipeline_version)`, `attempt`, `claims`, `lease_token`,
|
||
`lease_until`, `next_attempt_at`, `last_error`); `outbox` (`payload jsonb`, `available_at`, `published_at`);
|
||
`job_events` (журнал переходов). Частичные индексы: `outbox_pending_idx (available_at, id) WHERE published_at IS
|
||
NULL` — выборка relay, `jobs_lease_idx (lease_until) WHERE status = 'processing'` — истёкшие аренды,
|
||
`attachments_staged_idx (updated_at) WHERE staging_key IS NOT NULL` — уборка staging.
|
||
|
||
**Upload и что сохранено в момент `202`.** Лимиты и проверки лабы 4 не изменились. После проверки изображения:
|
||
`INSERT attachments (pending, staging_key)` и `COMMIT` → `PutObject staging/<id>` → одна транзакция:
|
||
`UPDATE attachments SET status='queued' WHERE status='pending'`, `INSERT jobs (pipeline_version=1, attempt=1)`,
|
||
`INSERT outbox (payload по jobs.schema.json)`, `INSERT job_events ('enqueued')` → `202`. Ответ — снимок объекта
|
||
из памяти (`queued`, `variants=[]`, `error_code=null`), не перечитанный после фиксации. К моменту `202` устойчиво
|
||
сохранены полный проверенный оригинал в S3, метаданные, задание и намерение его публикации. API не строит
|
||
вариантов и не подключается к брокеру: недоступный worker или брокер не влияет на upload.
|
||
|
||
**Outbox и relay.** Раз в `OUTBOX_POLL_SECONDS` (1 с) relay в транзакции берёт до 50 строк `WHERE published_at IS
|
||
NULL AND available_at <= now() ORDER BY available_at, id FOR UPDATE SKIP LOCKED`, публикует каждую через
|
||
`RabbitBroker.publish` (exchange `attachments` без объявления, routing key `attachment.process.v1`,
|
||
`persist=True`, `mandatory=True`, `message_id = job_id`, `type = attachment.process.v1`, тело — ровно `payload`)
|
||
и той же транзакцией ставит `published_at`. Канал открыт с `publisher_confirms=True` и `on_return_raises=True`:
|
||
unroutable-сообщение, `basic.nack` или обрыв соединения — ошибка, строка остаётся неопубликованной и
|
||
повторяется. Publisher confirm — подтверждение брокера, что сообщение записано в quorum queue; обработку он не
|
||
подтверждает. Раз в `SWEEP_INTERVAL_SECONDS` (5 с) relay возвращает задания `processing` с истёкшей арендой
|
||
(`queued`, `attempt + 1`, новая строка outbox, событие `lease_expired`; на пределе попыток — `failed`) и удаляет
|
||
staging-объекты `ready`-вложений (у worker нет права `DeleteObject`).
|
||
|
||
**Worker: захват, фиксация, `ack`.** FastStream `RabbitBroker` (`logger=None`: журнал только через порт `Logger`),
|
||
подписчик на `RabbitQueue("attachments.process", declare=False, quorum)` без привязки к exchange,
|
||
`Channel(prefetch_count=WORKER_CONCURRENCY)`, `AckPolicy.MANUAL`, `graceful_timeout` 5 с. Сообщение не по схеме
|
||
(pydantic-модель с `extra="forbid"`) — `reject(requeue=False)` в DLX. Дальше:
|
||
|
||
1. *Захват* — `UPDATE jobs SET status='processing', lease_token=<новый uuid>, lease_until=now()+JOB_TIMEOUT_SECONDS,
|
||
claims=claims+1 WHERE job_id=$1 AND attachment_id=$2 AND pipeline_version=$3 AND ((status='queued' AND
|
||
next_attempt_at наступил) OR (status='processing' AND lease_until < now()))`, вложение `queued → processing`,
|
||
событие `claimed`. Нет строки — задание уже `done`/`failed`, держится живой арендой или повтор ещё не наступил:
|
||
событие `duplicate_noop` и `ack`. `attempt` из сообщения информационный, захват идёт по `job_id`.
|
||
2. *Побочные эффекты* — чтение `staging/<id>`, thumbnail в потоке, `CopyObject staging → originals/<id>`,
|
||
`PutObject variants/<id>/1/thumbnail-<sha256[:16]>.jpg`. Ключ содержит хеш: повтор с другими байтами не
|
||
перезапишет объект, на который уже ссылается БД.
|
||
3. *Фиксация* — одна транзакция: `UPDATE jobs SET status='done' … WHERE status='processing' AND lease_token=$2`
|
||
(0 строк — аренду перехватили: событие `fenced`, ничего не публикуется); `INSERT attachment_variants … ON
|
||
CONFLICT DO NOTHING`; `UPDATE attachments SET status='ready', published_version=$v, original_key … WHERE
|
||
published_version < $v` (0 строк — опубликована более новая версия: задание `superseded`); событие `done`.
|
||
4. *`ack` — только после `COMMIT`.* Ошибка PostgreSQL до или во время фиксации — `nack(requeue=True)` через 1 с;
|
||
если аренда уже взята, задание вернёт relay по её истечении.
|
||
|
||
**Повторы и финальные ошибки.** Временная ошибка (`Unavailable` от S3 или PostgreSQL, точка `transient_error`)
|
||
возвращает задание и вложение в `queued` (не `failed` — smoke падает на первом `failed`) с тем же `job_id`,
|
||
`attempt + 1`, `next_attempt_at = now + min(60, JOB_BACKOFF_BASE_SECONDS · 2^(attempt−1))` и новой строкой outbox
|
||
с `available_at = next_attempt_at`. После `JOB_MAX_ATTEMPTS` (5) попыток — `failed` с `retry_exhausted`.
|
||
Нечитаемое изображение — сразу `failed` с `invalid_image`, без повторов; непредвиденная ошибка рендера —
|
||
`processing_failed`. В `error_code` — короткий код, в `jobs.last_error` — имя класса ошибки без текста. Все
|
||
переходы — с fencing по `lease_token` и не трогают вложение в `ready`. Jitter и подробная классификация —
|
||
уровень «4».
|
||
|
||
**Thumbnail.** Pillow: `ImageOps.exif_transpose` до расчёта размеров; 16-битные режимы масштабируются в `L`;
|
||
палитра с прозрачностью, `LA`, `RGBA` компонуются на белый фон, прочее — `convert("RGB")`. Размер считается
|
||
целочисленно: при `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, 17×1000 → 4×256, 3000×2 → 256×1, EXIF 6 400×200 →
|
||
128×256 (`student-tests/unit/test_renderer.py`). Рендер — `asyncio.to_thread` под семафором `WORKER_CONCURRENCY`;
|
||
ProcessPool с таймаутом и лимиты памяти — уровень «4».
|
||
|
||
**Чтение.** `GET /attachments/{id}` отдаёт любой статус, кроме внутреннего `pending`, с вариантами опубликованной
|
||
версии одним запросом (`jsonb_agg` по PK вариантов). `/content`: посторонний — `404`; не `ready` — `409 conflict`
|
||
для любого `variant`, включая `original`; `original` — `original_key` с типом оригинала; `thumbnail` — вариант;
|
||
`crop`/`optimized` на уровне «3» — `404`; иное значение `variant` — `400`. Сообщение со ссылкой на `failed` —
|
||
`409`, на `queued`/`processing` — `201`; повтор по `Idempotency-Key` возвращает исходный ответ, даже если
|
||
вложение потом стало `failed`.
|
||
|
||
**Готовность и SIGTERM.** `/health/ready` реплик API зависит только от PostgreSQL, как в лабе 4: брокер развязан
|
||
outbox-ом, а при недоступном S3 upload и скачивание отвечают `503` от приложения, тексты работают. Relay и worker
|
||
проверяются heartbeat-файлом, который обновляется, пока жив цикл событий и брокер отвечает на ping (от PostgreSQL и
|
||
S3 не зависит — иначе worker не стартовал бы при временно недоступном S3). SIGTERM: worker отменяет consumer, ждёт
|
||
задачи до 5 с, закрывает канал (неподтверждённые сообщения возвращаются в очередь); relay завершает циклы и
|
||
закрывает соединение; оба выходят с кодом 0 за 0,5 с (`evidence/pipeline-stand.txt`).
|
||
|
||
**Окна отказа** (`contracts/attachment-states.md`):
|
||
|
||
| Окно | Что лежит после сбоя | Кто восстанавливает | Уровень |
|
||
| --- | --- | --- | --- |
|
||
| после staging, до записи задания | невидимая строка `pending` и объект `staging/` | компенсация сразу; уборка намерений лабы 4 после grace | «3» (из лабы 4) |
|
||
| после `COMMIT`, до publish | строка outbox без `published_at`, очередь пуста | relay после рестарта | «3»; crash-точка — «4» |
|
||
| после publish, до confirm или `published_at` | сообщение в очереди, строка не помечена | relay публикует повторно, дубль гасит захват | «3»; crash-точка — «4» |
|
||
| после записи S3, до `COMMIT` результата | объекты, нет строк вариантов, живая аренда | redelivery после истечения аренды или возврат аренды relay, те же ключи | «3»; crash-точка — «4» |
|
||
| после `COMMIT`, до `ack` | `ready`, сообщение не подтверждено | redelivery видит `done` → `duplicate_noop` и `ack` | «3»; crash-точка — «4» |
|
||
|
||
At-least-once доставки + идемпотентный эффект по ключу `(attachment_id, pipeline_version, variant)` + fencing по
|
||
`lease_token` = один опубликованный результат. Это не exactly-once: окна 3 и 5 дают повторные доставки, их гасит
|
||
эффект, а не брокер.
|
||
|
||
**Топология брокера** (`infra/rabbitmq/definitions.json`, импорт на каждой загрузке): vhost `messenger`
|
||
(`default_queue_type: quorum`); exchange `attachments` (direct) → `attachments.process` (quorum, durable);
|
||
`attachments.dlx` (fanout) → `attachments.process.dlq` (quorum); политика `attachments-process`:
|
||
`dead-letter-exchange=attachments.dlx`, `dead-letter-strategy=at-least-once`, `overflow=reject-publish`,
|
||
`delivery-limit=10`; DLQ — `max-length=100000`. DLX и delivery-limit заданы политикой, поэтому клиенты делают
|
||
только пассивный declare и не получают `PRECONDITION_FAILED`. Права (`evidence/topology.txt`): `messenger-api`
|
||
(relay) — только запись в `attachments`, `messenger-worker` — только чтение `attachments.process`,
|
||
`messenger-ops` — оператор; `guest` нет. В `rabbitmq.conf`: `consumer_timeout` 300 с (больше аренды 60 с),
|
||
`vm_memory_high_watermark` 256 MiB, запрет transient-очередей и global QoS.
|
||
|
||
**Роли и сервисы** (`compose.yaml`; сети `edge` и `backend` с `internal: true`):
|
||
|
||
| Роль | Сервис | Версия / digest | Health / readiness | Volume | Сеть / порт | Credentials |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| load_balancer | `lb` | `haproxy:3.2.26-alpine@sha256:58938405…`, uid 99, `read_only` | `/healthz` :8404; реплики — `GET /health/ready` | нет | `edge` + `backend`; `127.0.0.1:${LB_HTTP_PORT:-8080}`, `127.0.0.1:${LB_STATS_PORT:-8404}` | нет |
|
||
| api ×`API_REPLICAS` | `api` | сборка из `Dockerfile`, uid 10001, `read_only` | `GET /health/ready` (PostgreSQL) | нет | `backend`, без портов | `database_url`, `cache_url`, `cursor_secret`, ключ API S3 через `*_FILE`; брокера нет |
|
||
| broker | `broker` | `rabbitmq:4.1.8-management-alpine@sha256:54ef5ff5…`, uid 100, `hostname: broker`, `read_only`, `cap_drop: ALL` | `rabbitmq-diagnostics -q check_port_connectivity` | `broker-data:/var/lib/rabbitmq` | `backend` + `edge`; AMQP 5672 внутри; UI `127.0.0.1:${BROKER_MANAGEMENT_PORT:-15672}` | definitions с хешами паролей — secret `rabbitmq_users`; пароль оператора — `rabbitmq_ops_password` |
|
||
| outbox relay | `relay` | образ приложения, `python -m messenger.relay`, `init`, `read_only` | heartbeat `/tmp/heartbeat` моложе 30 с | нет | `backend`, без портов | `database_url`, `broker_url` ← `broker_url_api`, ключ API S3 |
|
||
| worker | `worker` | образ приложения, `python -m messenger.worker`, `init`, `read_only` | heartbeat `/tmp/heartbeat` моложе 30 с | нет | `backend`, без портов | `database_url`, `broker_url` ← `broker_url_worker`, ключ worker S3 |
|
||
| postgres | `postgres` | `postgres:17.11-alpine@sha256:266d3c25…`, uid 70 | `pg_isready` | `pgdata` | `backend` | `postgres_password` через `POSTGRES_PASSWORD_FILE` |
|
||
| s3 | `s3` | `rustfs/rustfs:1.0.4@sha256:ed9210d6…`, uid 10001, консоль выключена | `curl /health/ready` | `s3data` | `backend`, :9000 без публикации | root-ключи через `RUSTFS_*_FILE` |
|
||
| bootstrap S3 | `s3-init` | `rustfs/rc:v0.1.36@sha256:ab024bfe…` | код выхода 0 | нет | `backend` | root-ключи, ключи API и worker (создаёт пользователей) |
|
||
| bootstrap схемы | `migrate` | образ приложения, `restart: "no"` | код выхода 0 | нет | `backend` | `database_url` |
|
||
| сессии (кэш) | `valkey` | `valkey/valkey:8.1.11-alpine@sha256:2602ace2…`, uid 999 | `valkey-cli ping` | `valkeydata` (AOF) | `backend` | `valkey.conf` |
|
||
| CLI S3 и нагрузка | `s3-cli` (профиль `tools`), `k6` (профиль `bench`) | как в лабе 4 | нет | нет | `backend` / `edge` | как в лабе 4 |
|
||
|
||
Bootstrap: схема — `migrate` (advisory lock, повтор без изменений); bucket, политики `messenger-api`
|
||
(`infra/s3/api-policy.json`) и `messenger-worker` (`infra/s3/worker-policy.json`: чтение `staging/`, `originals/`,
|
||
`variants/`, запись `originals/` и `variants/`), пользователи и lifecycle — `s3-init` (`--ignore-existing`, повтор
|
||
без изменений, самопроверка политик); топология и пользователи брокера — definitions на загрузке узла
|
||
(идемпотентный импорт; ротация пароля — удалить `secrets/rabbitmq_<роль>_password` и `broker_url_<роль>`,
|
||
`make secrets`, `docker compose up -d broker relay worker`). Лимиты: broker 1/512m, relay 0.5/192m, worker
|
||
2/768m, остальное как в лабе 4; `make limits` проверяет политику секретов, volumes, сетей и портов
|
||
(`evidence/limits.txt`).
|
||
|
||
**Соответствие `.env.example` реальной конфигурации:**
|
||
|
||
| `.env.example` | В решении | Комментарий |
|
||
| --- | --- | --- |
|
||
| `APP_*`, `SESSION_*`, `DATABASE_URL_FILE`, `CACHE_URL_FILE`, `API_REPLICAS`, `IDEMPOTENCY_TTL_SECONDS`, `S3_*`, `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | как в лабе 4 | |
|
||
| `BROKER_URL_FILE=/run/secrets/broker_url` | тот же у `relay` и `worker` | разные secrets: `broker_url_api` и `broker_url_worker`; у API нет |
|
||
| `WORKER_CONCURRENCY=2` | тот же | prefetch канала consumer и параллельные рендеры одного worker |
|
||
| `JOB_MAX_ATTEMPTS=5` | тот же | предел попыток; последняя неудача — `retry_exhausted` |
|
||
| `JOB_TIMEOUT_SECONDS=60` | тот же | аренда захваченного задания; меньше `consumer_timeout` 300 с |
|
||
| `STAGING_RETENTION_SECONDS=86400` | тот же (настройка relay и worker) | на уровне «3» staging `ready`-вложений убирается сразу после публикации; retention `failed` — уровень «4» |
|
||
| — | `BROKER_MANAGEMENT_PORT`, `JOB_BACKOFF_BASE_SECONDS`, `OUTBOX_POLL_SECONDS`, `SWEEP_INTERVAL_SECONDS`, `WORKER_CPUS`, `WORKER_MEMORY`, `PIPELINE_DB_POOL_MAX_SIZE` | UI брокера; база backoff 2 с; опрос outbox 1 с; возврат аренд и уборка staging 5 с; лимиты worker; пул PostgreSQL relay и worker |
|
||
| — | `FAULT_POINT` | только в `infra/compose.faults.yaml` (короткие аренда и backoff, `restart: "no"`), никогда в основном стенде |
|
||
| — | прочие `LB_*`, `API_*`, `PG_*`, `UPLOAD_*`, `S3_*_TIMEOUT_SECONDS`, `MALLOC_MMAP_THRESHOLD_` | как в лабе 4 |
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test BASE_URL=http://localhost:18085` | `PASS: lab5 public API scenario` (upload → `202 queued`, сразу сообщение `text=""` с вложением → `201`, `ready` от bob, оригинал побайтно `image/png`, eve `404`, один вариант `thumbnail` 256×160, настоящий JPEG той же длины и SHA-256, весь минимум lab2–lab4) | `evidence/smoke.txt` |
|
||
| `make check` / `make validate` / `make lint` | `make check`; `make validate` в venv с `requirements-dev.txt`; `make lint` | `PASS: offline skeleton structure…`; `PASS: full OpenAPI 3.1 and JSON Schema validation`; ruff, формат, ty — `All checks passed!` | `evidence/contract-checks.txt` |
|
||
| Собственные тесты | `make student-test` | `390 passed` (15 проверок стенда под маркером `stack` — отдельно): pipeline против PostgreSQL, адаптеры против RabbitMQ и RustFS, рендер, контракт сообщения, архитектура | `evidence/student-tests.txt` |
|
||
| **3.1** `202` только после устойчивого staging и сохранения задания; остановка API после ответа не теряет работу | `make level3` (`worker_down_broker_restart`), `make pipeline-evidence`; тесты `test_attachments.py`, `test_upload_consistency.py`, `test_pipeline.py` | ответ — снимок `queued`, в БД ключ `staging/<id>`, задание и строка outbox; отказ фиксации после записи staging → `503`, нет ни строки, ни задания, ни объекта; после `202` перезапущены обе реплики API и relay — задание одно в очереди и доходит до `ready` | `evidence/level3.json`, `evidence/pipeline-stand.txt`, `evidence/student-tests.txt` |
|
||
| **3.2** Отдельные broker и worker в общем стенде; durable, at-least-once, подтверждение после эффекта | `make topology`; `make pipeline-evidence`; `test_rabbitmq.py` | `attachments.process` и `.dlq` — `quorum`, `durable`, политики применены; один consumer `ack_required=true`, `prefetch_count=2`; сообщение в очереди: `delivery_mode: 2`, `message_id` = `job_id`, тело — ровно 7 полей `jobs.schema.json`; `ack` только после `COMMIT` (ошибка обработки → `nack` → повторная доставка до успеха); сообщение не по схеме → DLQ; учётка worker не может публиковать | `evidence/topology.txt`, `evidence/pipeline-stand.txt`, `evidence/student-tests.txt` |
|
||
| **3.2** Недоступность worker не заставляет API делать resize синхронно | `make pipeline-evidence`, `worker_down_broker_restart` | worker остановлен: upload `202 queued`, `/content` (`original` и `thumbnail`) → `409`, сообщение с вложением `201`, текст и история работают, вложение остаётся `queued`, задание лежит в очереди (`messages_ready=1`) | `evidence/pipeline-stand.txt`, `evidence/level3.json` |
|
||
| **3.3** Состояния `queued/processing/ready/failed`; оригинал неизменен, thumbnail по контракту | `make test`, `smoke_pipeline`, `test_pipeline.py`, `test_renderer.py` | переходы видны в API и `job_events` (`enqueued → claimed → done`); оригинал из `originals/<id>` побайтно равен загруженному; thumbnail 256×160 JPEG, длина и SHA-256 равны метаданным; инвариант `bytes_match_metadata` — PASS | `evidence/smoke.txt`, `evidence/level3.json`, `evidence/student-tests.txt` |
|
||
| **3.4** Ограниченный retry, финальное `failed` с безопасным `error_code` | `retry_exhausted`, `s3_outage_recovers` (`make level3`); `test_pipeline.py` | точка `transient_error`: задание `failed`, `attempt = 5 = JOB_MAX_ATTEMPTS`, `error_code = retry_exhausted`, `/content` и сообщение со ссылкой → `409`; S3 остановлен во время обработки → вложение `queued` с `attempt = 2`, после возврата S3 — `ready`; нечитаемый оригинал → `invalid_image` с `attempt = 1`; следующая попытка отложена на базу backoff; инвариант `bounded_attempts` — PASS | `evidence/level3.json`, `evidence/student-tests.txt` |
|
||
| **3.4** Повтор одной job не создаёт второго набора вариантов | `duplicate_after_ready`; `test_pipeline.py` | копия сообщения после `ready` → `duplicate_noop`, метаданные и строки вариантов до и после равны; две копии одновременно → один `done` и один `duplicate_noop`, одна строка варианта, `claims = 1`; опоздавший держатель аренды → `fenced`, вариантов не добавил; инвариант `single_effect` — PASS | `evidence/level3.json`, `evidence/student-tests.txt` |
|
||
| **3.5** Демонстрация: worker остановлен → upload `202` → сообщение → рестарт API → worker → `ready`; задание переживает рестарт broker с volume | `make level3` (`worker_down_broker_restart`) | хронология с ID без токенов: worker остановлен 22:20:24.58; upload `202 queued` (`01a18499-a689…`); `/content` `409`; сообщение `201` (`01a18499-a698…`); в очереди `[1, 0]`; обе реплики API и relay перезапущены; broker перезапущен с volume — в очереди снова `[1, 0]`; worker запущен 22:20:49.24, `ready` с `thumbnail` 22:20:49.42 | `evidence/level3.json` |
|
||
| **3.5** Минимум lab4: persistence | `make persistence-evidence` | `PASS: persistence …`; `StartedAt` у `lb`, обеих `api`, `relay`, `worker`, `postgres`, `valkey`, `s3`, `broker` новее, контейнеры те же, hostname брокера `broker` | `evidence/persistence.txt` |
|
||
| **3.5** Минимум lab4: failover | `make failover-evidence` | `PASS: failover …`: 2 реплики до отказа, 134 записи, 0 ошибок, первая запись через 2,85 с; цель `db66b246dcf8` в `exited`, в её журнале сигнал, окно readiness `503`, выход; `make restore` вернул реплику | `evidence/failover.txt` |
|
||
| Минимум lab4: download через другую реплику, недоступный S3, приватность, негативный suite, политика | `make scenario SCENARIO=failover-upload`, `SCENARIO=s3-outage`, `make s3-check`, `make upload-faults`, `make limits` | upload принят `db66b246dcf8`, после `ready` и её остановки — скачивание через `6f688eb249b1` за 2,87 с, SHA-256 равен; S3 остановлен: upload и `/content` `503` за 4,5–4,7 с, метаданные, текст и readiness работают; `RESULT: PASS`; 5 проверок стенда, 0 × `5xx`; политика портов, секретов и сетей — PASS | `evidence/failover-upload.json`, `evidence/s3-outage.json`, `evidence/s3-security.txt`, `evidence/upload-faults.txt`, `evidence/limits.txt` |
|
||
| Инварианты suite уровня «3» | `make suite-preflight && make level3` | 6/6 сценариев PASS; `terminal`, `single_effect`, `no_ready_rollback`, `monotonic_publication`, `bytes_match_metadata`, `bounded_attempts`, `no_orphans` (очереди пусты, outbox опубликован, staging `ready` убран, лишних писем в DLQ нет), `no_lost_202` — PASS | `evidence/level3.json` |
|
||
| Все пункты уровня «4» | — | заполняется следующим изменением: crop и optimized, лимиты worker, crash-точки окон 2–5, jitter, DLQ и replay, lease и fencing под внедрённым зависанием, retention staging | — |
|
||
| Трек 2 | — | заполняется изменением трека 2: versioned pipeline, fault-injection suite одной командой, инварианты | — |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Стенд: 2 реплики `api` (1 CPU, 512 MiB), worker 2 CPU / 768 MiB, relay 0.5 CPU / 192 MiB, RabbitMQ 1 CPU /
|
||
512 MiB, RustFS 1 CPU / 512 MiB, PostgreSQL 2 CPU / 1 GiB; Docker Desktop VM 16 CPU, 7.65 ГиБ, параллельно
|
||
работали стенды других лаб. Данные — синтетические пользователи и fixture `sample.png` (111 817 B). Сценарии
|
||
suite идут с `infra/compose.faults.yaml` у relay и worker (аренда 5 с, база backoff 1 с, опрос outbox 0,5 с).
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| Worker остановлен, upload и сообщение | `202 queued`, `409` на `/content`, сообщения работают, задание в очереди | так и есть; `messages_ready=1` | `ready` через 0,2 с после запуска worker; потерь нет |
|
||
| Рестарт обеих реплик API и relay после `202` | задание не теряется и не дублируется | в очереди одна копия до и после | потерь нет |
|
||
| `scripts/broker.sh restart` при остановленном worker | durable сообщение переживает рестарт | `[1, 0]` до и после, имя узла `rabbit@broker` неизменно | брокер healthy за ~9 с; потерь нет |
|
||
| Повторная доставка выполненной job (`rabbitmqadmin publish` той же копии) | no-op с `ack`, результат не меняется | `duplicate_noop`, снимок вариантов равен | — |
|
||
| S3 остановлен во время обработки | временная ошибка, `queued`, повтор | `attempt 2`, статус `queued`; после возврата S3 — `ready` | сценарий 13,8 с; потерь нет |
|
||
| Каждая попытка — временная ошибка (`FAULT_POINT=transient_error`) | ровно 5 попыток, `failed retry_exhausted` | `attempt 5`, `retry_exhausted`, `409` на `/content` и в сообщении | 22,9 с до `failed`; бесконечного повтора нет |
|
||
| Битый PNG (обрезан после IDAT) | `415` на входе или `invalid_image` без повторов | `415` на входе (API проверяет файл до `202`); с подменой staging в тесте — `invalid_image`, `attempt 1` | — |
|
||
| Сообщение не по `jobs.schema.json` | в DLQ, worker жив | DLQ +1, очередь пуста (`test_rabbitmq.py`) | — |
|
||
| Аренда истекла, старый держатель пытается зафиксировать | relay возвращает задание, старый — `fenced` | `queued`, `attempt 2`, затем `ready`; старая фиксация → `fenced`, вариантов не добавила (`test_pipeline.py`) | следующий проход relay (5 с) |
|
||
| Брокер не подтвердил публикацию | строка outbox остаётся | `published_at IS NULL`, после восстановления публикуется (`test_pipeline.py`) | следующий опрос; потерь нет |
|
||
| SIGTERM worker и relay | выход ≤10 с, код 0, unacked в очередь | 0,5 с, код 0 | — |
|
||
| Перезапуск LB, API, relay, worker, PostgreSQL, Valkey, S3, broker с volumes | данные, сессия, вложение и байты на месте | `PASS: persistence …`, все `StartedAt` новее | хук ~11 с; потерь нет |
|
||
| Остановка реплики API под записью | запись ≤10 с, без дублей | 2,85 с, 134 записи, 0 ошибок | ≤3 с; потерь нет |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Один Docker-host: RabbitMQ — один узел quorum-очереди без репликации, PostgreSQL и RustFS — единственные точки
|
||
отказа; это не HA. Отказы — остановка и `SIGKILL` процессов и контейнеров, не сеть и не диск.
|
||
- Это не exactly-once: брокер доставляет повторно (окна 3 и 5, redelivery после рестарта), дубли гасит захват
|
||
задания и ключ эффекта. Publisher confirm подтверждает запись в очередь, consumer ack — устойчивый результат.
|
||
- Relay держит транзакцию outbox на время публикации пачки; при недоступном брокере он каждую секунду ждёт
|
||
таймаут соединения, API это не затрагивает, outbox растёт. LISTEN/NOTIFY не введён: опроса раз в секунду хватает
|
||
бюджету smoke.
|
||
- Ошибка PostgreSQL на захвате возвращает сообщение в очередь; после 10 возвратов оно уходит в DLQ, а задание
|
||
остаётся `queued` с опубликованной строкой outbox — нужна переопубликация (replay, уровень «4»).
|
||
- Аренда без heartbeat: задание дольше `JOB_TIMEOUT_SECONDS` (60 с) relay вернёт и его выполнят повторно, результат
|
||
защищён fencing; продление аренды, ProcessPool с таймаутом и лимиты памяти worker — уровень «4».
|
||
- `object_key` лабы 4 в `attachments` оставлен nullable до contract-миграции.
|
||
- Нестабильность, найденная прогоном: проверка лабы 2 `test_valkey_restart_keeps_cache_and_revocations` один раз
|
||
увидела на 1 ключ меньше после рестарта Valkey (между подсчётами истёк TTL кэшированной сессии); повтор — PASS.
|
||
- Подтверждено прогонами: всё в таблице доказательств уровня «3». Уровень «4» и трек 2 — следующие изменения.
|