Move publishing out of the upload path: a relay process publishes queued jobs with confirms. Add lease and attempt fencing, backoff with jitter, a per-job render process with CPU and memory limits, crop and optimized variants, the failed registry with audited replay, and staging cleanup. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
10 KiB
message-broker Specification
Purpose
Брокер сообщений стенда с лабы 5: запуск и закрепление сервера, устойчивая очередь заданий, подтверждение публикации, сохранность при рестарте и клиент в приложении.
Requirements
Requirement: Брокер в стенде
Рабочий стенд compose SHALL включать один брокер RabbitMQ 4. Его образ SHALL быть закреплён тегом с версией и digest индекса. Данные брокера SHALL храниться в именованном volume, а имя узла SHALL быть постоянным: иначе пересозданный контейнер не нашёл бы свои данные в том же volume.
Сервису SHALL быть заданы healthcheck, перезапуск после сбоя, лимиты CPU и
памяти и срок остановки, за который брокер завершается сам. Предел памяти
брокера SHALL быть задан явно меньше лимита контейнера: определить лимит
контейнера сам брокер не может и иначе был бы завершён ядром, а не сдерживал
бы публикацию. Порт AMQP SHALL публиковаться только на 127.0.0.1 хоста, для
запуска в консоли; другие порты брокера MUST NOT публиковаться.
Брокер создаёт учётную запись приложения из .env при первом старте на пустом
volume. Пользователя с паролем по умолчанию MUST NOT быть.
Scenario: Сервис брокера запущен
- WHEN в свежем clone выполнен
make run_docker - THEN контейнер брокера
healthy, его образ указан тегом с версией и digest, данные лежат в именованном volume проекта, аdocker portпоказывает только порт AMQP на127.0.0.1
Scenario: Предел памяти брокера
- WHEN брокер запущен с лимитом контейнера 512 МБ
- THEN его предел памяти меньше лимита контейнера, а не вычислен от памяти ВМ Docker
Scenario: Остановка брокера
- WHEN выполняется
docker compose stopброкера - THEN контейнер завершается с кодом 0 раньше срока остановки
Requirement: Устойчивая очередь заданий
Задания SHALL идти через устойчивую (durable) очередь постоянными (persistent) сообщениями. Имя очереди SHALL содержать имя базы PostgreSQL процесса: так прогон на временной базе не смешивается с рабочим, как объекты S3 и ключи кэша. Очередь SHALL существовать к первой публикации, даже если worker ни разу не запускался: её объявляет и relay, и потребитель, повторное объявление безопасно.
Scenario: Очередь и сообщения устойчивы
- WHEN участник загрузил файл при остановленном worker, и relay опубликовал его задание
- THEN очередь в брокере
durable, в ней одно сообщение с постоянной доставкой, а прочитанное без подтверждения сообщение возвращается в очередь
Scenario: Очереди разных баз разделены
- WHEN на рабочем стенде выполняется прогон на временной базе
- THEN его задания идут через очередь с именем временной базы, worker рабочего стенда их не получает, а после прогона этой очереди нет
Requirement: Подтверждение публикации
Relay SHALL считать сообщение принятым только после подтверждения брокера
(publisher confirm). Сообщение, которое брокеру некуда направить, отказ брокера,
обрыв соединения и истечение [broker] publish_timeout_seconds SHALL быть
ошибкой публикации: время подтверждения у задания не записывается, намерение остаётся в
PostgreSQL, и следующий проход публикует его снова. Исход публикации по сроку неизвестен,
поэтому сообщение может дойти дважды (job-outbox, «Relay публикует намерения»).
Отдельный вызов публикации MUST NOT зависать дольше этого срока.
Брокер не критичен для обязательного пути и для приёма файлов: без него SHALL работать
загрузка (202), отправка текста, история, метаданные, скачивание готового вложения и
/health/ready (health, «Readiness»).
После возврата брокера публикация SHALL проходить без перезапуска процесса.
Scenario: Брокер остановлен при загрузке
- WHEN брокер остановлен, и участник загружает файл, отправляет текст, читает метаданные готового вложения и скачивает его
- THEN загрузка — 202 быстрее секунды, отправка — 201, метаданные и скачивание —
200, а новое вложение видно по API со
statusqueued
Scenario: Брокер завис
- WHEN контейнер брокера заморожен (
docker pause), и участник загружает файл - THEN ответ 202 быстрее секунды, а после разморозки вложение становится
readyс одним набором вариантов, даже если сообщение, дошедшее после разморозки, опубликовано ещё раз
Scenario: Брокер вернулся
- WHEN брокер снова запущен, а relay и worker не перезапускались
- THEN вложение, принятое без брокера, и следующая загрузка становятся
ready
Scenario: Очередь удалена
- WHEN worker остановлен, очередь заданий удалена мимо приложения, участник дважды загружает файл, а затем worker запущен
- THEN обе загрузки — 202, очередь объявлена заново, и оба вложения становятся
ready
Requirement: Данные брокера переживают рестарт
Очередь и подтверждённые сообщения SHALL переживать перезапуск брокера и всего стенда с сохранённым volume, принудительное завершение процесса брокера и пересоздание контейнера на том же volume. Сообщение, подтверждённое издателю и ещё не подтверждённое потребителем, MUST NOT теряться.
Scenario: Подтверждённые сообщения после KILL
- WHEN worker остановлен, брокер подтвердил несколько сообщений и сразу завершён сигналом KILL
- THEN после его запуска в очереди столько же сообщений, сколько было подтверждено
Scenario: Пересоздание контейнера
- WHEN worker остановлен, в очереди есть сообщения, и контейнер брокера
пересоздан (
docker compose up --force-recreate) на том же volume - THEN очередь и сообщения на месте
Requirement: Клиент брокера в приложении
Relay и worker SHALL обращаться к брокеру с настройками секции [broker]. Реплики API MUST
NOT к нему обращаться. Соединение SHALL открываться при первом вызове, а не при старте: без
брокера процесс стартует. При остановке сервиса клиент SHALL закрываться. Потерянное
соединение SHALL восстанавливаться следующим вызовом, с паузой между попытками, без
перезапуска процесса. Пароль брокера MUST NOT попадать в журнал.
Scenario: Старт без брокера
- WHEN реплика API, relay и worker запускаются при остановленном брокере
- THEN реплика становится готовой и принимает файл (202), relay и worker пишут в журнал об
отказе брокера и не завершаются, а после запуска брокера вложение становится
ready
Scenario: Рестарт брокера при работающем worker
- WHEN брокер перезапущен, а relay и worker в это время работают
- THEN worker без перезапуска снова получает задания: новая загрузка становится
ready, а счётчики перезапусков контейнеров relay и worker не изменились