Files
mtusi2026lab6/openspec/specs/message-broker/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

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, пока не достигнут предел незавершённых заданий — 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 не изменились