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

148 lines
10 KiB
Markdown
Raw 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.
# 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 не изменились