diff --git a/DEFENSE_CHEATSHEET.md b/DEFENSE_CHEATSHEET.md deleted file mode 100644 index ce2c316e..00000000 --- a/DEFENSE_CHEATSHEET.md +++ /dev/null @@ -1,95 +0,0 @@ -# Лабораторная 5: шпаргалка для защиты - -## Что сделано - -Из четвёртой работы сохранены пользователи, сессии, чаты, сообщения, две API-реплики, PostgreSQL и приватный MinIO. В пятой работе загрузка возвращает **202 queued**, а обработку выполняет отдельный worker через устойчивую очередь. - -- **Уровень 3:** staging, broker, worker, состояния queued/processing/ready/failed, оригинал и thumbnail, ограниченные попытки, восстановление после рестарта. -- **Уровень 4:** crop и WebP, transactional outbox, retry с backoff/jitter, реестр failed и replay, lease и защита от дублей, очистка staging. -- **Уровень 5, трек 2:** версии обработки и автоматические аварийные сценарии: дубли, изменение порядка, падения до/после записи результата и устаревшее задание после новой версии. - -## Как идёт загрузка - -1. Клиент передаёт все байты в API. API проверяет сессию, участие в чате, размер и формат. -2. API записывает оригинал в приватный `staging/` в MinIO. -3. В одной транзакции PostgreSQL создаются вложение, job и outbox. Только после COMMIT возвращается 202. -4. Publisher читает outbox и выполняет XADD в Valkey Streams. -5. Worker получает ID задания, читает доверенные параметры из БД и исходник из staging. -6. В отдельном процессе Pillow создаёт варианты. Оригинал остаётся побайтно неизменным. -7. Worker записывает четыре объекта в `results//v/`, затем одной транзакцией публикует ready и метаданные вариантов. -8. После COMMIT выполняется consumer ack. Клиент узнаёт готовность через GET метаданных. - -## Кто за что отвечает и где настроить - -| Компонент | Задача | Где смотреть | -| --- | --- | --- | -| Docker Compose | Запускает отдельные процессы и постоянные volumes | `compose.yaml` | -| HAProxy | Распределяет запросы между двумя API | `infra/haproxy.cfg` | -| API | Авторизация, приём и проверка файла, staging и job | `app.py`, `attachments.py` | -| PostgreSQL | Источник истины: пользователи, сообщения, статусы, версии, jobs/outbox/audit | `migrations/004_pipeline.sql` | -| MinIO | Приватные байты исходников и вариантов | `infra/init-s3.sh`, `infra/api-policy.json` | -| Valkey для кэша | Ускоряет сессии; корректность проверяется по PostgreSQL | сервис `valkey`, `app.py` | -| Valkey для очереди | Streams, consumer groups, pending и ack, AOF | отдельный сервис `broker` | -| Publisher | Восстанавливает публикацию задания из БД в брокер | `publisher.py` | -| Worker | Получает и обрабатывает задания | `worker.py` | -| Pillow subprocess | Ограниченная по времени и памяти обработка | `transform.py` | -| Janitor | Удаляет старые staging-объекты, сохраняя текущую работу | `janitor.py` | -| CLI оператора | Список failed, replay, новая версия | `manage.py` | - -Основные значения задаются в `.env` и используются `compose.yaml`: `API_REPLICAS=2`, `JOB_MAX_ATTEMPTS=5`, `JOB_TIMEOUT_SECONDS=20`, `JOB_LEASE_SECONDS=30`, `MAX_PENDING_JOBS=100`, `STAGING_RETENTION_SECONDS=86400`. Worker последовательный: одна задача и prefetch/count=1. Для нескольких workers можно использовать `scripts/compose.sh up -d --scale worker=2`; каждый получает собственный consumer ID. Результаты исследования относятся к одному обычному worker. - -Лимиты HTTP: 10 MiB, 40 миллионов пикселей, 30 секунд передачи, 5 секунд простоя, два принимаемых файла на API. Они находятся в `attachments.py`. Worker имеет лимит контейнера 768 MiB, дочерний обработчик — 640 MiB адресного пространства. Это разные ограничения, оба могут остановить слишком затратную обработку. - -## Что сказать на защите - -«В этой работе я отделил приём изображения от его обработки. API сохраняет полный оригинал в устойчивый S3 staging, а метаданные, задание и outbox фиксирует одной транзакцией PostgreSQL. После этого возвращает 202, даже если worker или брокер временно недоступны. - -Publisher доставляет задание в Valkey Streams с постоянным AOF. Worker делает thumbnail, центральный crop и WebP в отдельном процессе. Ready публикуется только после записи всех объектов, а ack отправляется после COMMIT. - -Повторная доставка допустима. Ключ результата состоит из attachment ID, версии pipeline и имени варианта. Блокировки БД и проверка версии защищают от одновременных дублей и старых заданий. Есть пять попыток с backoff и jitter, конечный failed, операторский replay и восстановление зависшего processing по lease. - -В исследовании я автоматически завершал worker до записи, после S3 и после COMMIT, доставлял дубли и старую версию после новой. Проверки подтвердили сохранность принятых задач и отсутствие дополнительных наборов вариантов. Это идемпотентные эффекты при at-least-once доставке». - -## Возможные вопросы - -**Зачем очередь?** Чтобы тяжёлая обработка не занимала HTTP-запрос, а временная остановка worker не теряла принятую работу. - -**202 означает готовность?** Нет. Приняты все байты, сохранены staging и намерение обработки. Готовность — только `status=ready`. - -**Почему не отправить файл в брокер?** Большие сообщения расходуют память и журнал брокера. Он передаёт только ID и служебные поля; байты находятся в S3. - -**Зачем outbox?** PostgreSQL и брокер не имеют общей транзакции. Если API упал после COMMIT, publisher позже найдёт сохранённое намерение и опубликует его. - -**Что если publish прошёл, а запись published_at не сохранилась?** Будет повторная публикация. Она безопасна благодаря идемпотентности worker. - -**Publisher confirm и consumer ack — одно и то же?** Нет. Подтверждение публикации означает приём брокером, ack — устойчивое завершение обработки потребителем. Здесь используется ответ XADD при AOF appendfsync=always, а consumer ack — XACK. - -**Почему не exactly once?** Одно сообщение может прийти несколько раз. Гарантируется один логический опубликованный результат, а не единственная доставка или единственный физический PUT. - -**Как защищены дубли?** Уникальная job на attachment/version, блокировка строки job, состояние ready, проверка версии и устойчивые ключи S3. После ready дубль ничего не меняет. - -**Что если worker упал после PUT до ack?** Доставка остаётся pending. После lease работа повторяется с тем же ключом. Если COMMIT ready уже был — повтор становится no-op. - -**Lease может истечь у работающего worker?** Да. Одного времени недостаточно: транзакционная блокировка строки не даёт другому worker одновременно публиковать эффект. Обработка изображения дополнительно ограничена тайм-аутом subprocess. - -**Что такое backoff и jitter?** Пауза между попытками растёт, а случайный множитель разводит повторы по времени, чтобы не создавать одновременную волну запросов. - -**Какие ошибки повторяются?** Тайм-ауты и временные ошибки S3. Непригодный или повреждённый исходник и превышение памяти становятся failed. После пяти временных ошибок — retry_exhausted. - -**Как повторить failed?** Через CLI `manage.py replay `. Нужен сохранённый исходник и текущая версия; ready повторять нельзя. Действие записывается в audit. - -**Как защищена новая версия?** В БД хранится текущая версия, а ключи объектов содержат `/v1/`, `/v2/`. Старый job не может опубликовать метаданные новой версии. - -**Чем отличаются v1 и v2?** Для v1 JPEG quality=85, WebP=80; для v2 и следующих JPEG=90, WebP=85. Изменяются производные варианты, оригинал сохраняется. - -**Когда удаляется staging?** После суток, если вложение больше не queued/processing. Failed-исходник также хранится сутки для replay. В тесте очистки часы janitor искусственно сдвигаются на два дня. - -**Что при переполнении?** В БД глобально ограничены 100 queued/processing jobs. Следующая загрузка получает 429 до записи нового staging. Обычные сообщения продолжают работать. - -**Почему два Valkey?** Кэш сессий и очередь имеют разные роли и независимые volumes. Очередь не должна зависеть от очистки кэша. - -**Зачем Docker volumes?** Контейнер можно пересоздать, сохранив данные PostgreSQL, MinIO и брокера. Volume не является резервной копией и не защищает от потери диска. - -**Что доказано экспериментом?** Проверенные аварийные сценарии на одном локальном стенде. Потеря диска, отказы нескольких узлов и production SLA не исследовались. - -Подробные команды и реальные результаты: [REPORT.md](REPORT.md), [RESEARCH.md](RESEARCH.md).