Files
mtusi2026lab5/REPORT.md

294 lines
58 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 5
- Автор, группа: Бабиченко Максим, БВТ2303
- Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не выбран
- Commit/PR: <<ссылка на MR в Gitea после публикации>>
- Использованные источники, библиотеки и помощь ИИ: всё из lab4 (FastAPI, Uvicorn, Pydantic, psycopg 3 и psycopg-pool, argon2-cffi, redis-py, boto3/botocore 1.43.116, Pillow 12.3.0; образы python:3.11.13-slim, postgres:17.11-alpine, redis:7.4.11-alpine, haproxy:3.2.25-alpine, chrislusf/seaweedfs:3.80). Новое: брокер RabbitMQ (образ `rabbitmq:4.1.4-alpine`), клиент pika 1.3.2. Документация: RabbitMQ — Reliability Guide, Consumer Acknowledgements and Publisher Confirms, Quorum Queues (`x-delivery-limit`, at-least-once dead-lettering, `x-overflow=reject-publish`), Definitions import, Access Control (configure/write/read); PostgreSQL `SELECT ... FOR UPDATE SKIP LOCKED`, `LISTEN/NOTIFY`; паттерн transactional outbox; W3C Trace Context (`traceparent`); Pillow (`Image.draft`, `ImageOps.exif_transpose`, параметры JPEG/WebP); `setrlimit(2)`. При написании кода и тестов использовался ИИ-ассистент (Claude); весь код проверен и прогнан мной, объяснить и изменить его могу на защите.
## Запуск из чистого clone
Проверял на Windows, все команды в PowerShell. Python нужен только для тестов (стандартная библиотека; Pillow на хосте не нужен — изображения для тестов генерирует и проверяет пробник внутри контейнера worker). Перед запуском остановить стенд lab4 (`docker compose down` в его папке), иначе занят порт 8080. Имя проекта Compose — `messenger-lab5`, поэтому volumes отдельные от lab4.
```powershell
git clone https://gitea.privcloud.tech/Kalibr/mtusi2026lab5.git
cd mtusi2026lab5
git checkout solution/bvt2303-babichenko
$env:PYTHONUTF8 = "1" # contracts/openapi.json в UTF-8, без этого тесты на Windows падают
Copy-Item .env.example .env
python scripts/init_secrets.py # пароли PostgreSQL/Redis, ключи S3, пользователи RabbitMQ и
# secrets/rabbitmq_definitions.json (папка secrets/ в .gitignore)
docker compose --env-file .env config --quiet
docker compose up -d --build --wait # postgres, s3, rabbitmq -> migrate, s3-init -> api x2, janitor,
# dispatcher, worker -> lb
docker compose ps -a # migrate и s3-init: Exited (0), остальные healthy
python student-tests/collect_evidence.py # все проверки lab1-5 по очереди (~15 мин), вывод в evidence/,
# таблицы замеров — в этот отчёт
```
Отдельные проверки (make на Windows нет, ниже то же самое без make):
| Команда из README | То же в PowerShell |
| --- | --- |
| `make check` | `python scripts/check_contract.py` |
| `make test` | `python tests/smoke.py --base-url http://127.0.0.1:8080` |
| `make test-persistence ACTION_SCRIPT=...` | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080` |
| `make test-failover ACTION_SCRIPT=...` | `python tests/resilience.py --mode failover --action-script scripts/stop-one.cmd --base-url http://127.0.0.1:8080` |
| все сценарии lab5 | `python student-tests/test_jobs.py` |
| один сценарий lab5 | `python student-tests/test_jobs.py worker-down` (список — в начале файла) |
| состояние pipeline | `docker compose exec dispatcher python ops.py status` |
| реестр failed / журнал job | `docker compose exec dispatcher python ops.py failed`, `... ops.py events <job_id>` |
| replay failed / разбор DLQ | `docker compose exec dispatcher python ops.py replay <job_id>`, `... ops.py dlq`, `... ops.py dlq-replay` |
| остановить / запустить worker | `scripts\worker.cmd stop`, `scripts\worker.cmd start` (Linux/macOS: `scripts/worker.sh`) |
После `test-failover` одна реплика остаётся остановленной (так требует тест). Вернуть: `docker compose up -d --wait`.
Bootstrap: миграции — одноразовый сервис `migrate` (теперь и `005_jobs.sql`), bucket — `s3-init`, топология RabbitMQ (exchange, очереди, DLQ, пользователи и права) — декларативный файл `secrets/rabbitmq_definitions.json`, который брокер импортирует при каждом старте (`infra/rabbitmq.conf`). Всё идемпотентно: повторный `docker compose run --rm migrate` / `s3-init` и рестарт `rabbitmq` ничего не ломают. Сервисы не имеют права `configure` в брокере и только проверяют топологию пассивным declare — создать или удалить очередь они не могут.
Остановка без потери данных: `docker compose down` (volumes `pgdata`, `redisdata`, `s3data`, `rabbitmqdata`, `faults` остаются). Безопасная остановка worker: `docker compose stop worker` — SIGTERM, потоки доделывают текущее задание (не дольше `JOB_TIMEOUT_SECONDS`, `stop_grace_period: 70s`), неподтверждённое сообщение брокер доставит снова. Намеренное удаление учебных данных: `docker compose down -v`, затем удалить папку `secrets` и снова `python scripts/init_secrets.py` (новые пароли не подходят к старым volumes, поэтому удаляются вместе).
## Архитектура и решения
```text
Клиент --HTTP--> lb (HAProxy) --> api x2 --+--> postgres: метаданные, attachment_jobs, outbox, job_events,
| варианты (ИСТОЧНИК ИСТИНЫ, volume pgdata)
+--> s3 staging/<hex>: полный проверенный оригинал до 202
+--> redis: сессии
COMMIT(queued + job + outbox) --NOTIFY--> dispatcher --publish+confirm--> rabbitmq
(outbox, (quorum queue attachments.process.v1,
аренды, DLQ attachments.process.v1.dlq,
сверка) volume rabbitmqdata)
|
worker x2 потока <-+ prefetch 1, ручной ack
| claim (аренда + fencing-токен) в postgres
| staging -> imaging.py (дочерний процесс, лимиты)
| PUT attachments/<id>/v1/{original,thumbnail.jpg,crop.jpg,optimized.webp}
| COMMIT ready (+варианты) -> ack -> удалить staging
janitor: брошенные uploading, staging ready/failed по retention, сироты в bucket, старый outbox
```
| Роль | Сервис Compose | Версия | Health / готовность | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| Балансировщик | `lb` | haproxy:3.2.25-alpine | `/lb-health` | нет | edge; `127.0.0.1:8080`, `127.0.0.1:8404` | не нужны |
| API ×2 | `api` | python:3.11.13-slim | `/health/ready` (PostgreSQL + Redis; брокер и S3 не входят) | нет | edge + data | `database_url`, `cache_url`, ключ S3 API. **Доступа к брокеру нет** |
| Брокер | `rabbitmq` | rabbitmq:4.1.4-alpine, `hostname: rabbitmq` | узел запущен и очередь `attachments.process.v1` загружена | `rabbitmqdata` | только data, 5672 не публикуется | `rabbitmq_definitions` (хеши паролей, права) |
| Dispatcher | `dispatcher` (образ приложения) | python:3.11.13-slim | файл-пульс `/tmp/alive` не старше 30 с | `faults` | data | `database_url`, `broker_url_dispatcher` (write только в exchange `attachments`, read только DLQ) |
| Worker | `worker` (образ приложения), 2 потока | python:3.11.13-slim | файл-пульс | `faults`; `/tmp` — tmpfs 256 MiB | data | `database_url`, `broker_url_worker` (read только основной очереди, write нет), ключ S3 API |
| Janitor | `janitor` (образ приложения) | python:3.11.13-slim | файл-пульс `/tmp/alive` (обновляется перед проходом и каждые 10 с между проходами) | нет | data | как в lab4: `database_url`, ключ S3 API |
| S3, s3-init, migrate, postgres, redis | как в lab4 | | | | | |
Почему RabbitMQ: durable quorum-очередь (Raft-журнал на диске, fsync до подтверждения издателю), publisher confirms, ручной ack, `x-delivery-limit` и dead-lettering «at-least-once» — ровно те границы, о которых спрашивают на защите. Почему dispatcher, а не publish из API: API фиксирует вложение, задание и строку outbox **одной транзакцией** и сразу отвечает 202; брокер в этом пути не участвует, поэтому его недоступность не мешает приёму, а API не нужны его пароли.
Что перенесено из lab4 без изменений по смыслу: пользователи, сессии в Redis, чаты, сообщения, идемпотентность, балансировка, приём и потоковая проверка файла (лимиты bytes/пикселей до распаковки, MIME по содержимому), приватный bucket и ограниченный ключ, janitor.
Что изменено в lab5:
- Новые файлы: `pipeline.py` (формат сообщения, outbox, переходы состояний, replay), `broker.py` (RabbitMQ, publisher confirms), `dispatcher.py`, `worker.py`, `imaging.py` (варианты, отдельный процесс), `faults.py` (учебное внедрение сбоев), `ops.py` (операторские команды), `migrations/005_jobs.sql`, `infra/rabbitmq.conf`.
- `attachments.py` / `db.py`: исходник пишется в `staging/<hex>`, затем одной транзакцией `state=queued` + `attachment_jobs` + `outbox` + `NOTIFY`; ответ `202` (переход 201 → 202 из COURSE.md). GET отдаёт `queued/processing/ready/failed`, варианты текущей версии pipeline. Сообщение можно создать с queued/processing-вложением, с failed — 409.
- `main.py`: `variant=original|thumbnail|crop|optimized`; для не-ready — 409, отсутствующий вариант ready — 404.
- `janitor.py`: очистка staging после безопасной фиксации и по retention для failed; сироты под `attachments/<id>/...`; очистка опубликованного outbox.
- `compose.yaml`: сервисы `rabbitmq`, `dispatcher`, `worker`, volumes `rabbitmqdata`, `faults`, три новых секрета; `scripts/init_secrets.py` генерирует пользователей RabbitMQ и definitions; restart-hook перезапускает ещё `rabbitmq`, `dispatcher`, `worker`.
- `.env.example`: в skeleton стояли `SESSION_STORE=postgres`, `S3_ENDPOINT=http://s3:9000` и `BROKER_URL_FILE=/run/secrets/broker_url`, с которыми API этого решения не стартует (сессии в Redis с lab2, S3 — SeaweedFS на 8333, у API нет брокера). Значения приведены к реальной конфигурации, добавлены переменные lab5.
- Тесты lab4: хелпер `upload()` ждёт `202`, затем опрашивает GET до `ready` — проверки «файл скачивается побайтно» сохранены; `test_consistency` имитирует падение в `enqueue_upload` вместо `finish_upload`.
### Задание, сообщение и состояния
Сообщение брокера — ровно `contracts/jobs.schema.json`: `schema_version`, `job_id`, `type=attachment.process.v1`, `attachment_id`, `pipeline_version=1`, `attempt`, `created_at`, `traceparent`. Ни байтов, ни URL, ни ключей S3, ни имени файла: worker берёт `source_key`, размер и SHA-256 из PostgreSQL. `traceparent` дублируется в native header AMQP; `message_id = <job_id>:<attempt>`; `delivery_mode=2` (persistent). Worker строго проверяет сообщение по схеме (лишние поля, типы, форматы) — не прошедшее уходит в DLQ.
Таблицы (`005_jobs.sql`): `attachment_jobs` (одна строка на `(attachment_id, pipeline_version)`, `job_id` не меняется при повторах; `attempt`, `max_attempts`, `available_at`, `lease_token`/`lease_owner`/`lease_until`, `error_code`, `last_error`, `replays`), `attachment_variants` с **первичным ключом `(attachment_id, pipeline_version, name)`** — это и есть ключ эффекта из контракта, второй набор вариантов физически не вставится, `outbox`, `job_events` (журнал: created, claimed, retry_scheduled, lease_expired, duplicate_ignored, stale_result_rejected, ready, failed, replayed, staging_expired). CHECK-ограничения: `ready ⇔ object_key`, `failed ⇔ error_code`, `processing ⇔ lease`, до ready исходник обязан быть в staging.
| Переход | Где | Что устойчиво сохранено |
| --- | --- | --- |
| нет → queued | API: PUT в staging, затем одна транзакция | исходник в `staging/<hex>` (SHA-256 сверяет S3 при PUT), строка вложения, job, outbox |
| queued → processing | worker `claim` под `FOR UPDATE` | attempt, новый `lease_token`, `lease_until = now()+15 с`, событие claimed |
| processing → queued | временная ошибка / истёкшая аренда | причина (код), `available_at = now()+backoff`, новая строка outbox |
| processing → ready | worker после PUT всех объектов | варианты + оригинал + ready одним COMMIT, **только если `lease_token` ещё наш** |
| processing → failed | постоянная ошибка или попытки исчерпаны | `error_code`, запись в журнале, исходник хранится 24 ч для replay |
| failed → queued | `ops.py replay` | событие replayed (audit), новая попытка того же job_id через outbox |
Повторная доставка ready/failed — no-op с ack (событие `duplicate_ignored`). Устаревшее сообщение прежней попытки (job ещё ждёт backoff) — ack без работы: своё сообщение придёт из outbox. Ready никогда не откатывается: `finish_ready` обновляет только `state='processing'` и не перезаписывает более новую `pipeline_version`.
### Где граница «202»
К моменту ответа 202 сохранено: полный проверенный оригинал в S3 (staging — приватный prefix того же bucket, persistent volume `s3data`; это честная граница: оригинал уже в S3, worker «публикует» его копией в конечный prefix `attachments/<id>/v1/original`), строка вложения `queued`, задание и сообщение в outbox — всё в одной COMMIT PostgreSQL (`synchronous_commit=on`). Брокер на этот момент может ещё ничего не знать — это нормально: строку outbox опубликует dispatcher. Перезапуск/падение API после ответа не теряет работу.
### Transactional outbox и окна отказа
Dispatcher просыпается по `NOTIFY outbox` (сразу после COMMIT в API) или раз в 1 с, берёт строки `published_at IS NULL AND available_at <= now()` под `FOR UPDATE SKIP LOCKED`, публикует в канал с publisher confirms (`mandatory=True`: непривязанное сообщение — ошибка, nack при переполнении очереди — ошибка) и только после confirm ставит `published_at`.
| Окно | Что происходит | Проверка |
| --- | --- | --- |
| после staging, до записи задания | клиент получил 503/обрыв, 202 не было; строка `uploading` невидима, janitor удалит объект и строку после grace | `test_consistency.py crash` (lab4, теперь с `enqueue_upload`) |
| после COMMIT, до publish | строка outbox не отмечена, после рестарта dispatcher публикует её | `test_jobs.py outbox-crash` (`dispatcher_crash_before_publish`) |
| после publish, до confirm / после confirm, до отметки | сообщение опубликовано, а отметки нет → публикуется ещё раз → дубль, worker видит ready и делает ack | `test_jobs.py outbox-crash` (`dispatcher_crash_after_confirm`) |
| после записи S3, до COMMIT результата | ack не отправлен, брокер доставляет снова; живая аренда → no-op; аренда истекает → новая попытка пишет **те же ключи** | `test_jobs.py crash-after-put` |
| после COMMIT результата, до ack | повторная доставка видит ready → ack, второго набора нет; staging доочищает janitor | `test_jobs.py crash-after-commit`, `staging` |
Дополнительная страховка: раз в 30 с dispatcher ищет `queued`-задания старше `JOB_RECONCILE_SECONDS=120` без сообщения в полёте (например, сообщение ушло в DLQ после `x-delivery-limit`, пока PostgreSQL был недоступен) и публикует заново. Дубль безопасен, потеря — нет.
**Publisher confirm и consumer ack — разные границы:** confirm значит «брокер принял сообщение и записал в quorum-журнал» (граница dispatcher → broker, после неё можно отметить outbox); ack значит «worker устойчиво выполнил эффект — объекты в S3 и COMMIT в PostgreSQL» (граница broker → worker, после неё брокер удаляет сообщение). At-least-once + идемпотентный эффект — это не exactly-once доставка: дубли сообщений происходят (и видны в журнале как `duplicate_ignored`), но не дают второго эффекта.
### Повторы, аренда, DLQ, replay
- Попытки: `JOB_MAX_ATTEMPTS=5`. Backoff «equal jitter»: `потолок = min(60, 2·2^(n-1))`, задержка = половина потолка + случайная половина: 1–2 с, 2–4 с, 4–8 с, 8–16 с. Задержка реализована через `available_at` строки outbox, а не через sleep в worker: поток не занят ожиданием.
- Постоянные ошибки (сразу failed, без повторов): `invalid_image`, `image_too_large`, `resource_limit` (не хватило памяти под RLIMIT_AS), `source_missing`, `source_corrupted` (staging не совпал по SHA-256 с принятым). Временные (повтор): `storage_unavailable`, `processing_timeout`, `processing_failed`/`processing_killed`, ошибки PostgreSQL. После последней попытки — `failed/retry_exhausted`. Наружу в `error_code` уходит только финальный код, без деталей.
- Аренда: `JOB_LEASE_SECONDS=15`, отдельный поток продлевает её каждые 5 с, пока идёт работа. **Долго работающий worker** продлевает аренду (проверено: зависание imaging 60 с — ни одного `lease_expired`), его ограничивает жёсткий `JOB_TIMEOUT_SECONDS=60`. **Зависший/умерший** перестаёт продлевать → через 15 с dispatcher возвращает job в queued (попытка засчитана) или worker сам перехватывает её при повторной доставке. Если «воскресший» исполнитель всё же дойдёт до COMMIT, fencing-проверка `lease_token` отклонит его результат (`stale_result_rejected`) — два неконтролируемых дубля не фиксируются. Его PUT в S3 перезаписал бы те же ключи теми же байтами (Pillow детерминирован), поэтому опасности для опубликованных объектов нет.
- RabbitMQ `consumer_timeout = 300 с`: канал, который не прислал ack дольше, закрывается брокером — последняя страховка от вечного зависания.
- DLQ `attachments.process.v1.dlq` (classic durable) получает: сообщения не по схеме, неизвестный `job_id`, превышение `x-delivery-limit=20` (бесконечный nack при недоступной БД). Реестр failed — `attachment_jobs` со `status='failed'` + `job_events` (`ops.py failed`, `ops.py events`).
- Replay (`ops.py replay <job_id>`): только для `failed` с исходником в staging; та же job получает новую попытку и ещё 5 попыток, событие `replayed`; ready/queued/processing не трогаются («повторить» ≠ исполнить дубль успешной job). `ops.py dlq-replay`: для валидных сообщений DLQ решает по строке job в PostgreSQL (failed → replay, ready → удалить как no-op, queued/processing → удалить, работу ведёт outbox); невалидные и неизвестные остаются в DLQ.
### Варианты изображения (pipeline_version = 1)
| Вариант | Формат | Правило | Параметры |
| --- | --- | --- | --- |
| thumbnail | JPEG | вписан в 256×256, без увеличения, размеры вниз (минимум 1 px); 320×200 → 256×160 | quality 85, `optimize=True`, LANCZOS |
| crop | JPEG | центрированный квадрат 128×128 (маленькие увеличиваются) | quality 85, `optimize=True` |
| optimized | WebP | вписан в 1280×1280 без увеличения; прозрачность сохраняется | quality 80, method 4 |
Во всех вариантах применяется EXIF orientation (1–8, как `ImageOps.exif_transpose`), альфа для JPEG компонуется на белый, EXIF/XMP/комментарии **не записываются** — в `save()` передаётся только ICC-профиль (цвет). Оригинал хранится побайтно как загружен (его EXIF не трогается — это требование контракта). Размер варианта считается от размеров исходника после поворота, а не от промежуточной копии. Большой JPEG декодируется сразу в уменьшенном масштабе (`draft`), сначала уменьшение до ≤1280, потом поворот. Не обещаю, что optimized меньше маленького исходника.
### Лимиты worker
- Bytes: API не принимает больше 10 MiB (413); worker скачивает staging не дальше `MAX_UPLOAD_BYTES` и сверяет размер и SHA-256 с метаданными.
- Пиксели: API проверяет по заголовку до распаковки (413); worker повторно — `Image.MAX_IMAGE_PIXELS` и явная проверка `w·h ≤ 40 000 000` (защита в глубину, `image_too_large`).
- Память: обработка идёт в дочернем процессе `imaging.py`, который **до импорта Pillow** ставит себе `RLIMIT_AS = WORKER_MEMORY_LIMIT_MB` (512 MiB), `RLIMIT_CPU`, `RLIMIT_FSIZE = 64 MiB`. Не хватило памяти → `MemoryError` → `resource_limit`, worker и его соединение с брокером живы. Контейнер worker: 2 CPU / 1536 MiB ≥ 2 потока × 512 MiB + сам worker + tmpfs.
- Время: worker убивает дочерний процесс по `JOB_TIMEOUT_SECONDS=60` (`processing_timeout`, временная ошибка).
- Конкуренция: `WORKER_CONCURRENCY=2` потока, у каждого своё соединение и `prefetch_count=1` → одновременно не больше 2 заданий на контейнер, остальное ждёт в очереди; очередь ограничена `x-max-length=100000` с `reject-publish` (переполнение — nack издателю, строка outbox ждёт, не потеря).
### Очистка staging
Worker удаляет `staging/<hex>` сразу после COMMIT ready и ack. Если не успел (упал, S3 недоступен) — janitor удаляет исходник ready-вложения, обновлённого больше 60 с назад. Исходник failed хранится `STAGING_RETENTION_SECONDS=86400` (для replay), потом удаляется с событием `staging_expired`. queued/processing janitor не трогает никогда. Объекты под `attachments/<id>/` удаляются, только если вложения нет, оно ready и ключ не входит в опубликованный набор, или оно failed и исходник уже удалён по retention (replay невозможен — конечное состояние). Повторная проверка и DELETE выполняются в одной транзакции под `FOR SHARE` на строке вложения: replay (`FOR UPDATE`) и worker ждут её завершения.
### Соответствие `.env.example`
| Переменная | Что делает в этом решении |
| --- | --- |
| APP_*, SESSION_*, DATABASE_URL_FILE, CACHE_URL_FILE, API_REPLICAS, S3_*, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS, пулы и таймауты | как в lab4 |
| IDEMPOTENCY_TTL_SECONDS | не используется: ключ хранится вместе с сообщением бессрочно (не меньше 24 ч) |
| BROKER_URL_FILE | пусто для api/janitor (брокера у них нет); compose задаёт свой файл dispatcher (`broker_url_dispatcher`) и worker (`broker_url_worker`) |
| WORKER_CONCURRENCY, WORKER_PREFETCH | 2 потока-потребителя, prefetch 1 на поток |
| JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, JOB_LEASE_SECONDS | 5 попыток, 60 с на обработку изображения, аренда 15 с |
| JOB_BACKOFF_BASE_SECONDS, JOB_BACKOFF_MAX_SECONDS | 2 с и 60 с (equal jitter) |
| WORKER_MEMORY_LIMIT_MB | RLIMIT_AS процесса обработки, 512 MiB |
| STAGING_RETENTION_SECONDS | сколько хранится исходник failed-вложения для replay, 86400 с |
| PIPELINE_VERSION | 1 (версионирование нескольких pipeline — трек 5, не заявлен) |
| FAULT_INJECTION | учебные точки сбоев, на стенде включены по умолчанию (срабатывают только по файлу в volume `faults`, доступном лишь worker/dispatcher); `FAULT_INJECTION=0` — выключить |
## Доказательства критериев
`python student-tests/collect_evidence.py` создаёт `evidence/*.txt` (вывод тестов как есть, с датой, commit и кодом выхода) и `evidence/summary.md`. Сценарии lab5 — `student-tests/test_jobs.py`, сбои внедряются через `faults.py` (файл в volume `faults` → процесс в нужной точке делает `os._exit(137)`, как SIGKILL/OOM, или временную ошибку). Каждый сценарий проверяет инвариант «ровно 3 строки вариантов и ровно 4 объекта под `attachments/<id>/v1/`, SHA-256 совпадают».
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `python tests/smoke.py` | PASS: публичный сценарий lab5 через балансировщик (202 → ready); размеры вариантов (thumbnail 256×160 для 320×200) — в jobs-variants.txt | smoke.txt |
| Контракт и публичные тесты не изменены | `python scripts/check_contract.py`; `git diff` по `contracts/`, `tests/` | PASS; не менялись | check.txt |
| 3: минимум lab4 сохранён (201 → 202) | `test_attachments.py`, `test_api.py`, `test_race.py`, `test_idempotency.py`, `test_balancing.py`, публичные persistence/failover | все PASS; upload ждёт 202 и затем ready | attachments.txt, student-tests.txt, race.txt, idempotency.txt, balancing.txt, persistence.txt, failover.txt |
| 3: 202 только после устойчивого staging и задания; остановка API после ответа не теряет работу | `test_jobs.py worker-down` | staging-объект есть до 202; job и outbox в БД; после рестарта api и rabbitmq тот же job_id → ready | jobs-recovery.txt |
| 3: отдельные broker и worker, durable, at-least-once, ack после эффекта, API не делает resize | `check_stack.py`, `test_jobs.py worker-down`, `broker-down` | rabbitmq/worker/dispatcher — отдельные сервисы; при остановленном worker вложение остаётся queued (API не обрабатывает); без брокера 202 и /health/ready 200 | stack.txt, jobs-recovery.txt |
| 3: queued/processing/ready/failed в API; оригинал неизменен; thumbnail по контракту | `test_jobs.py variants`, smoke | оригинал побайтно; 320×200 → 256×160; content 409 для queued и failed | jobs-variants.txt |
| 3: ограниченный retry, failed с безопасным error_code, повтор не создаёт второго набора | `test_jobs.py retry`, `exhausted-replay`, все сценарии сбоев | 5 попыток → `retry_exhausted`; в каждом сценарии ровно один набор | jobs-retry.txt, jobs-crash.txt |
| 3: демонстрация worker off → 202 → сообщение → рестарт API → worker → ready; брокер с volume не теряет задание | `test_jobs.py worker-down` | сообщение с вложением 201, другие сообщения работают, после `restart rabbitmq` в очереди 1 сообщение, затем ready и thumbnail | jobs-recovery.txt |
| 4: crop 128×128 и optimized WebP, параметры описаны | `test_jobs.py variants` | 6 исходников (PNG/JPEG, EXIF orientation 6, alpha, 40×30, 3000×2000, 5000×2): размеры по правилам, EXIF/XMP в вариантах 0, alpha на белом | jobs-variants.txt |
| 4: лимиты по bytes, пикселям, времени и памяти worker | `test_jobs.py limits` | 10 MiB+ → 413; 40 Мпикс PNG — пик RSS дочернего процесса 227 MiB при RLIMIT 512 MiB; лимит пикселей в worker — exit 4; «бомба памяти» → `resource_limit`; зависание → убито через 60 с, затем ready | jobs-limits.txt |
| 4: outbox, crash между COMMIT и publish, восстановление без ручного задания | `test_jobs.py outbox-crash` | dispatcher убит до publish → после рестарта тот же job опубликован и ready (attempt 1); убит после confirm → дубль, `duplicate_ignored`, один набор | jobs-outbox.txt |
| 4: backoff с jitter; постоянные/временные ошибки; DLQ/реестр failed; безопасный replay | `test_jobs.py retry exhausted-replay permanent dlq` | задержки в диапазонах 1–2 и 2–4 с; `invalid_image` — failed с attempt 1; replay → ready; replay ready — отказ без изменений; невалидное сообщение и неизвестный job → DLQ, dlq-replay их не исполняет | jobs-retry.txt |
| 4: остановка worker после записи объекта до ack; повтор завершает тот же результат | `test_jobs.py crash-after-put`, `crash-after-commit` | после PUT: аренда истекла, attempt 2 перезаписал те же ключи, 4 объекта; после COMMIT: redelivery → no-op ack, очередь пуста | jobs-crash.txt |
| 4: timeout/lease для зависшего processing | `test_jobs.py lease`, `limits` | зависший не продлевает аренду → через ~15 с job возвращена и выполнена другим потоком, поздний результат отклонён fencing; живой долгий — аренда продлевается | jobs-crash.txt, jobs-limits.txt |
| 4: ограниченная конкуренция/prefetch | `test_jobs.py concurrency` | 2 consumer, `prefetch_count=1`, ручной ack; из 8 накопленных заданий в processing одновременно ровно 2 | jobs-concurrency.txt |
| 4: очистка staging после безопасной фиксации | `test_jobs.py worker-down`, `staging` | staging удалён worker'ом после COMMIT; после crash до очистки — janitor | jobs-recovery.txt, jobs-crash.txt |
| Исправлено по ревью: гонка janitor и replay | `test_janitor_replay.py` | на старом коде janitor удалял crop.jpg после replay (503), теперь все 4 файла 200; после истечения retention остатки удаляются, replay отказывает | evidence/jobs-janitor-replay.txt |
| Выбранный трек 5 | — | не выбран | — |
**Где проверено сейчас.** Все строки таблицы выше подтверждены на Docker-стенде из этого репозитория (Windows 10, Docker Desktop, Compose 2.35, образы из `compose.yaml`, 2 реплики API за балансировщиком): 24.10.2026 один полный прогон `python student-tests/collect_evidence.py` — все 26 шагов PASS, сводка в `evidence/summary.md`, вывод каждого шага в `evidence/*.txt`, таблицы замеров ниже взяты из того же прогона. Перед ним на том же стенде отдельно прошли `docker compose up -d --build --wait` (migrate и s3-init — Exited (0), остальные healthy), `python tests/smoke.py` и `python student-tests/test_jobs.py worker-down`. Ранний прогон процессами без Docker (PostgreSQL 16, RabbitMQ 3.12, SeaweedFS 3.80, Redis) сохранён в `evidence/native-sandbox/` для сравнения.
Что исправлено по итогам первого запуска в Docker (без Docker эти места не проявлялись): путь к definitions в `infra/rabbitmq.conf` (Compose монтирует секрет как `/run/secrets/rabbitmq_definitions`, без `.json`, — брокер не стартовал); у janitor появился healthcheck по файлу-пульсу (с `healthcheck: disable: true` команда `up --wait` завершалась ошибкой); в тестах — пробник `test_jobs.py` запускается одноразовым контейнером worker, когда сам worker остановлен, `upload_memory.py` ждёт 202 вместо 201 из lab4, а сценарий `staging` проверяет результат очистки независимо от того, какой проход janitor её сделал.
## Эксперименты и отказы
Гипотезы:
1. Принятая (202) работа не теряется ни при каком одиночном отказе процесса (API, dispatcher, worker, broker) в любом из окон контракта, а повторная доставка не создаёт второго эффекта.
2. Память worker ограничена независимо от входа: худший допустимый вход (PNG 8000×5000) помещается в RLIMIT_AS 512 MiB, а вход сверх лимита ломает только свою попытку, не процесс worker.
Методика: каждый сценарий `test_jobs.py` взводит одну точку сбоя (`faults.py`), загружает синтетический файл через балансировщик, ждёт конечного состояния через публичный GET и проверяет журнал `job_events`, строки outbox, глубину очередей (`rabbitmqctl list_queues`) и объекты в bucket (пробник в контейнере worker). Пик памяти обработки — `ru_maxrss` дочернего процесса `imaging.py` (`getrusage(RUSAGE_CHILDREN)`).
<!-- measurements:begin -->
Машина: Windows 10, AMD64 Family 26 Model 68 Stepping 0, AuthenticAMD; Docker VM: 16 CPU, 15.2 GiB RAM; клиент Python 3.11.1; дата прогона 2026-10-24, commit 276dbda + uncommitted changes. Лимиты контейнеров: api 1 CPU / 512 MiB каждая, postgres, s3 (SeaweedFS) и rabbitmq по 1 CPU / 512 MiB, redis и lb по 0,5 CPU / 128 MiB, janitor 0,25 CPU / 192 MiB, dispatcher 0,25 CPU / 128 MiB, worker 2 CPU / 1536 MiB.
Публичный тест отказа (`make test-failover`, 15 с записи во время остановки реплики):
| Прогон | Остановлена реплика | Реплик до отказа | Успешных записей | Неудачных попыток (повторены с тем же ключом) | Первая запись после hook, с |
| --- | --- | --- | --- | --- | --- |
| 1 | 5aa14958c864 | 2 | 123 | 0 | 4.406 |
| 2 | b9ad6d33d190 | 2 | 125 | 0 | 4.188 |
Одновременные загрузки (`student-tests/upload_memory.py`, перед каждым сценарием реплики перезапускаются, лимит api 512 MiB / 1 CPU). Пик RSS — VmHWM процесса API; cgroup — память контейнера, включая page cache временных файлов:
| Сценарий | Одновременно | Объём, MiB | Время, с (p50 / max) | Реплика: загрузок | RSS до, MiB | Пик RSS, MiB | Рост, MiB | Пик cgroup, MiB |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 10 x ~9.5 MiB PNG (noise) | 10 | 94.9 | 1.45 / 1.56 | 5aa14958c864: 5 | 96.0 | 109.7 | 13.7 | 149.6 |
| | | | | b9ad6d33d190: 5 | 94.5 | 108.9 | 14.4 | 142.1 |
| 10 x 40 Mpx PNG (8000x5000 RGB) | 10 | 1.1 | 1.04 / 1.31 | 5aa14958c864: 5 | 96.6 | 97.6 | 1.0 | 89.6 |
| | | | | b9ad6d33d190: 5 | 96.2 | 98.6 | 2.3 | 88.9 |
| 20 mixed: large + 40 Mpx + JPEG | 20 | 133.2 | 4.96 / 5.2 | 5aa14958c864: 10 | 94.7 | 114.9 | 20.3 | 155.4 |
| | | | | b9ad6d33d190: 10 | 97.0 | 121.8 | 24.8 | 176.9 |
Один PNG 8000x5000 RGB внутри контейнера api, дополнительный пик RSS: наивно (тело целиком в памяти + полное декодирование Pillow) 161 MiB, потоковая проверка 0 MiB. 10 таких наивных загрузок одновременно не поместились бы в 512 MiB.
Публичный генератор нагрузки (`tests/load.py`, closed loop, concurrency 4, 30 с, 2 реплики): 243.885 успешных POST/с, ошибок 0 (доля 0.0), задержка успешных p50 16.0 мс, p95 32.0 мс, p99 32.0 мс.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| публичный `make test-failover` для каждой реплики | запись продолжается не позже 10 с, подтверждённые сообщения на месте, дублей нет | PASS 2 раз(а), неудачных попыток: 0, 0 | первая запись после hook через 4.406, 4.188 с (hook ждёт остановки ~4 с); потерь нет |
| перезапуск всего стенда (`restart` hook: postgres, redis, s3, api, janitor, lb) | данные, файл и прежний токен живы | PASS, те же контейнеры с новым временем старта | 58.5 с до готовности; потерь нет |
| `docker compose stop s3` (SeaweedFS остановлен) | загрузка и скачивание -> 503, метаданные, сообщения и /health/ready работают | upload 503 за 19922 мс, download 503, остальное 200/201 | после start файлы на месте; uploading-строку убрал janitor; потерь нет |
| `docker compose pause s3` (SeaweedFS завис) | то же, но через таймауты S3-клиента | upload 503 за 14860 мс (2 попытки x 5 с + откат 2 с) | после unpause файлы на месте; потерь нет |
| падение между PUT в S3 и COMMIT в БД (код API в контейнере, finish_upload падает) | вложение не видно, janitor не трогает его до конца grace period, потом удаляет объект и строку | GET/прикрепление -> 404; janitor: свежая строка сохранена, dry-run только отчёт, затем удалено | мусора не осталось; повторный проход ничего не делает |
| обрыв загрузки клиентом (9 МБ заявлено, отправлено 0,2 и 3 МБ) | ничего не сохраняется | строк и объектов не прибавилось, временных файлов 0 | мгновенно |
| worker остановлен, upload, рестарт rabbitmq и api с volumes, start worker | 202 queued, сообщение с вложением 201, content 409; после рестартов job в очереди; тот же job_id -> ready | worker started -> same job 9ab3ca59-e6f4-4f6e-928b-7163577d6139 ready, thumbnail downloadable; staging object deleted | потерь нет; staging удалён после COMMIT |
| rabbitmq остановлен во время upload | 202 и /health/ready 200 без брокера; строка outbox ждёт; после start публикуется | rabbitmq started -> dispatcher published the pending row -> ready | потерь нет |
| crash dispatcher между COMMIT задания и publish | строка outbox не отмечена -> публикуется после рестарта процесса | dispatcher killed between COMMIT and publish; restarted by policy, outbox re-published -> job 9d62ceee-578c-46df-9916-1a7c4c6d8318 ready, attempt 1, no manual action | без ручного действия |
| crash dispatcher после confirm, до отметки outbox | дубль сообщения, worker распознаёт по состоянию job | dispatcher killed after publisher confirm, before marking outbox -> message published twice; worker: ['created', 'claimed', 'ready', 'duplicate_ignored'] -> one result set | один набор вариантов |
| crash worker после PUT в S3, до COMMIT и ack | повтор после истечения аренды перезаписывает те же ключи | worker killed after S3 PUT (before COMMIT and ack): redelivery saw a live lease (no-op), lease expired after 15 s, attempt 2 rewrote the same keys -> one set; events ['created', 'claimed', 'duplicate_ignored', 'lease_expired', 'claimed', 'ready'] | один набор, 4 объекта |
| crash worker после COMMIT, до ack | redelivery ready-задачи -> no-op ack | worker killed after COMMIT, before ack: broker redelivered, worker acked as no-op (1:duplicate_ignored:status=ready); queue empty (0 ready, 0 unacked) | очередь пуста, дублей нет |
| worker завис (не продлевает аренду) | dispatcher возвращает job, другой поток завершает; поздний результат отклонён fencing | frozen attempt 1 stopped renewing; lease expired, recovered by dispatcher, attempt 2 ready after 17 s; frozen attempt woke up -> stale_result_rejected; events ['created', 'claimed', 'lease_expired', 'claimed', 'ready', 'stale_result_rejected'] | ready не откатан |
| зависание обработки изображения | процесс убит по JOB_TIMEOUT_SECONDS, временная ошибка, аренда продлевалась | imaging hang -> killed after 60 s (processing_timeout, temporary), lease renewed meanwhile (no lease_expired), attempt 2 ready after 63 s | повтор -> ready |
| нехватка памяти в процессе обработки (RLIMIT_AS) | failed/resource_limit, worker жив | memory bomb in the imaging process -> failed/resource_limit after attempt 1; worker itself survived | постоянная ошибка, без повторов |
| 2 временные ошибки S3 | backoff с jitter, затем ready | 2 x storage_unavailable -> retries after 1.00 s and 3.30 s (equal jitter: 1..2 s, 2..4 s), attempt 3 ready | - |
| 5 временных ошибок подряд | failed/retry_exhausted, реестр failed, content 409 | 5 temporary errors -> failed/retry_exhausted (public error_code), content 409, attach 409, listed by ops.py failed (replayable) | replay оператора |
| replay failed и повторный replay ready | тот же job_id -> ready; повтор отклонён | ops replay -> same job_id f7e15ba3-2d82-414f-8d88-3038061dbc51 attempt 6 ready; second replay refused: "job is ready, replay is only for failed jobs" | дубля нет |
| невалидное сообщение и неизвестный job_id | reject -> DLQ, dlq-replay не исполняет | schema-invalid message and unknown job_id -> reject -> DLQ (3 message(s)); dlq-replay kept them: ['unknown job', 'invalid message is kept for analysis'] | сообщения сохранены |
| 8 заданий в очереди, старт worker | WORKER_CONCURRENCY=2, prefetch 1 | 2 consumers, prefetch_count 1, manual ack; 8 queued 3000x2000 JPEG drained in 2.4 s after worker start, peak processing 2 of 8 (6 samples) | - |
<!-- measurements:end -->
Результаты прогона на нативном стенде (`evidence/native-sandbox/`, 1 API-реплика без балансировщика):
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| worker остановлен, upload, рестарт rabbitmq и api с volumes, start worker | 202 queued, сообщение с вложением 201, content 409; после рестартов job в очереди; тот же job_id -> ready | worker started -> same job d62da8f8-b127-4141-95c3-8f691c39bb72 ready, thumbnail downloadable; staging object deleted | потерь нет; staging удалён после COMMIT |
| rabbitmq остановлен во время upload | 202 и /health/ready 200 без брокера; строка outbox ждёт; после start публикуется | rabbitmq started -> dispatcher published the pending row -> ready | потерь нет |
| crash dispatcher между COMMIT задания и publish | строка outbox не отмечена -> публикуется после рестарта процесса | dispatcher killed between COMMIT and publish; restarted by policy, outbox re-published -> job 21f39e5f-676b-43a2-92ca-532e1a932fb0 ready, attempt 1, no manual action | без ручного действия |
| crash dispatcher после confirm, до отметки outbox | дубль сообщения, worker распознаёт по состоянию job | dispatcher killed after publisher confirm, before marking outbox -> message published twice; worker: ['created', 'claimed', 'ready', 'duplicate_ignored'] -> one result set | один набор вариантов |
| crash worker после PUT в S3, до COMMIT и ack | повтор после истечения аренды перезаписывает те же ключи | worker killed after S3 PUT (before COMMIT and ack): redelivery saw a live lease (no-op), lease expired after 15 s, attempt 2 rewrote the same keys -> one set; events ['created', 'claimed', 'duplicate_ignored', 'lease_expired', 'claimed', 'ready'] | один набор, 4 объекта |
| crash worker после COMMIT, до ack | redelivery ready-задачи -> no-op ack | worker killed after COMMIT, before ack: broker redelivered, worker acked as no-op (1:duplicate_ignored:status=ready); queue empty (0 ready, 0 unacked) | очередь пуста, дублей нет |
| worker завис (не продлевает аренду) | dispatcher возвращает job, другой поток завершает; поздний результат отклонён fencing | frozen attempt 1 stopped renewing; lease expired, recovered by dispatcher, attempt 2 ready after 17 s; frozen attempt woke up -> stale_result_rejected; events ['created', 'claimed', 'lease_expired', 'claimed', 'ready', 'stale_result_rejected'] | ready не откатан |
| зависание обработки изображения | процесс убит по JOB_TIMEOUT_SECONDS, временная ошибка, аренда продлевалась | imaging hang -> killed after 60 s (processing_timeout, temporary), lease renewed meanwhile (no lease_expired), attempt 2 ready after 63 s | повтор -> ready |
| нехватка памяти в процессе обработки (RLIMIT_AS) | failed/resource_limit, worker жив | memory bomb in the imaging process -> failed/resource_limit after attempt 1; worker itself survived | постоянная ошибка, без повторов |
| 2 временные ошибки S3 | backoff с jitter, затем ready | 2 x storage_unavailable -> retries after 1.40 s and 2.40 s (equal jitter: 1..2 s, 2..4 s), attempt 3 ready | - |
| 5 временных ошибок подряд | failed/retry_exhausted, реестр failed, content 409 | 5 temporary errors -> failed/retry_exhausted (public error_code), content 409, attach 409, listed by ops.py failed (replayable) | replay оператора |
| replay failed и повторный replay ready | тот же job_id -> ready; повтор отклонён | ops replay -> same job_id 43d09c9b-f72f-4918-91d1-3407fbb12848 attempt 6 ready; second replay refused: "job is ready, replay is only for failed jobs" | дубля нет |
| невалидное сообщение и неизвестный job_id | reject -> DLQ, dlq-replay не исполняет | schema-invalid message and unknown job_id -> reject -> DLQ (3 message(s)); dlq-replay kept them: ['unknown job', 'invalid message is kept for analysis'] | сообщения сохранены |
| 8 заданий в очереди, старт worker | WORKER_CONCURRENCY=2, prefetch 1 | 2 consumers, prefetch_count 1, manual ack; 8 queued 3000x2000 JPEG drained in 2.9 s after worker start, peak processing 2 of 8 (16 samples) | - |
## Ограничения и следующие шаги
- Выдерживается: падение/рестарт любого одного процесса (api, dispatcher, worker, rabbitmq, postgres с volume) в любом окне отказа из контракта; недоступность брокера при приёме; зависание и нехватка памяти в обработке изображения; временные ошибки S3.
- Не выдерживается: потеря volume `pgdata` (источник истины) или `s3data` — нужен бэкап; один узел RabbitMQ (quorum-очередь из одного члена — durability есть, отказоустойчивости узла нет); при недоступном PostgreSQL новые загрузки и обработка останавливаются (это осознанно: без источника истины нельзя ни принять, ни зафиксировать).
- Учебные упрощения: worker использует тот же ограниченный S3-ключ, что и API (права только на свой bucket; отдельный ключ worker — следующий шаг); точки внедрения сбоев включены на стенде (`FAULT_INJECTION=1`), в эксплуатации выключаются; replay — CLI в контейнере dispatcher, а не API с авторизацией оператора.
- Подтверждено измерением: память обработки ограничена, конкуренция равна `WORKER_CONCURRENCY`, отказы не дают потерь и дублей эффекта. Гипотеза без измерения: пропускная способность pipeline под перегрузкой и выбор concurrency/prefetch — это трек 5.1, не заявлен.
## Ответы на вопросы защиты (кратко)
- **Publisher confirm vs consumer ack.** Confirm — брокер принял и сохранил сообщение (после него dispatcher отмечает outbox). Ack — worker устойчиво выполнил эффект (объекты в S3 + COMMIT ready); до ack сообщение остаётся у брокера и будет доставлено снова.
- **Что сохранено в момент 202.** Полный проверенный оригинал в S3-prefix `staging/`, строка вложения `queued`, задание `attachment_jobs` и сообщение в `outbox` — одной транзакцией PostgreSQL. Брокер может ещё ничего не знать.
- **Почему повторная доставка нормальна и где ключ идемпотентности.** At-least-once: ack может потеряться после эффекта, dispatcher может опубликовать дважды. Ключ — `job_id` (одна логическая работа) и ключ эффекта `(attachment_id, pipeline_version, variant)`: первичный ключ `attachment_variants` и детерминированные ключи S3 `attachments/<id>/v<N>/<variant>`; состояние job в PostgreSQL решает, работать или подтвердить как no-op.
- **Зависший vs долго работающий.** Живой продлевает аренду каждые 5 с из отдельного потока, его ограничивает только `JOB_TIMEOUT_SECONDS`. Зависший/умерший перестаёт продлевать — через 15 с job перехватывают; если он «оживёт», fencing по `lease_token` не даст зафиксировать результат.