Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
148 lines
10 KiB
Markdown
148 lines
10 KiB
Markdown
# 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, пока не достигнут предел незавершённых заданий — `queue-overload`), отправка
|
||
текста, история, метаданные, скачивание готового вложения и `/health/ready` (`health`,
|
||
«Readiness»).
|
||
|
||
После возврата брокера публикация SHALL проходить без перезапуска процесса.
|
||
|
||
#### Scenario: Брокер остановлен при загрузке
|
||
|
||
- **WHEN** брокер остановлен, и участник загружает файл, отправляет текст,
|
||
читает метаданные готового вложения и скачивает его
|
||
- **THEN** загрузка — 202 быстрее секунды, отправка — 201, метаданные и скачивание —
|
||
200, а новое вложение видно по API со `status` `queued`
|
||
|
||
#### 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 не изменились
|