Контракты событий¶
Требования применяются к событиям, передаваемым через внешний message broker.
Уровни обязательности определены в корневом README.md.
INT-EVT-001. Версионируемая схема¶
Уровень: MUST
Применяется к: каждому публикуемому событию
Событие должно иметь машинно-проверяемую версионируемую схему в GitLab и
стабильные поля event.id, event.name, event.schema_version, timestamp и
producer.id. timestamp должен содержать время возникновения события в
формате RFC 3339, а event.schema_version — положительное целое число.
Отсутствующее значение должно отличаться от пустого, нулевого или фиктивного.
Ненормативная
event-envelope.schema.json
проецирует только общую часть конверта; структура payload определяется
версией схемы конкретного события.
Обоснование¶
Явная схема является контрактом независимо развёртываемых producer и consumer.
Проверка¶
- schema validation producer и consumer;
- contract-тест обязательных полей;
- сопоставление версии схемы с release.
Исключения¶
Не допускаются для межпроцессного события.
INT-EVT-002. Совместимость схемы¶
Уровень: MUST
Применяется к: изменению действующей версии события
Добавление должно быть обратно совместимым и необязательным для существующего consumer. Удаление, переименование, изменение типа или смысла поля и сужение допустимых значений требует новой версии и плана миграции потребителей.
Добавление значения enum совместимо только для enum, который схема заранее объявляет расширяемым и для которого consumer имеет определённый fallback.
Обоснование¶
В очереди и у потребителей одновременно существуют разные версии события.
Проверка¶
- automated schema compatibility check;
- consumer contract tests старой и новой версии;
- проверка плана прекращения старой версии.
Исключения¶
Исправление схемы до первой публикации production не считается изменением опубликованного контракта.
INT-EVT-003. Семантика доставки¶
Уровень: MUST
Применяется к: producer и consumer внешнего message broker
Контракт должен исходить из возможности повторной доставки, задержки и
нарушения порядка, если выбранный broker и его конфигурация не гарантируют
иное. Consumer должен соблюдать BE-JOB-001–BE-JOB-007. Имена destination,
subscription и применимые параметры маршрутизации должны быть объявлены в
управляемой конфигурации.
Обоснование¶
Broker не превращает доставку в exactly-once бизнес-эффект.
Проверка¶
- integration-тест дубликата, перестановки и redelivery;
- review broker topology и retention;
- тест restart consumer.
Исключения¶
На более сильную гарантию доставки или порядка MAY полагаться только конфигурация, закреплённая контрактом и подтверждённая integration-тестом.
INT-EVT-004. Корреляция и защита данных¶
Уровень: MUST
Применяется к: metadata и payload события
Контекст трассы должен распространяться по OBS-TRACE-004. correlation_id
должен сохранять смысл бизнес-операции; фиктивные идентификаторы запрещены.
Payload и headers не должны содержать секреты или персональные данные сверх
утверждённого контракта классификации.
Обоснование¶
Единая корреляция связывает обработку, а минимизация ограничивает утечку.
Проверка¶
- сквозной тест trace producer–consumer;
- schema и security review payload;
- тест отсутствующего контекста.
Исключения¶
Не допускаются для секретов.
INT-EVT-005. Атомарная публикация изменения¶
Уровень: MUST
Применяется к: событию, сообщающему об изменении транзакционных данных
Изменение данных и запись о предназначенном к публикации событии должны фиксироваться одной локальной транзакцией. Проект может использовать transactional outbox, Change Data Capture (CDC) или иной механизм, при котором crash до и после commit не приводит к потере события. Прямой вызов broker внутри транзакции не должен считаться атомарной публикацией.
Publisher не должен отмечать запись опубликованной или удалять её до
положительного подтверждения broker для требуемой durability. При timeout,
потере соединения или неопределённом результате публикация должна повторяться
с тем же event.id; downstream consumer должен безопасно принимать такой
дубликат по BE-JOB-002.
Обоснование¶
Локальная транзакционная запись исключает разрыв между commit данных и публикацией. Подтверждение broker предотвращает потерю записи между отправкой и фиксацией доставки, не обещая exactly-once.
Проверка¶
- integration-тест crash до и после commit;
- тест crash до и после подтверждения broker;
- тест timeout с неопределённым результатом публикации;
- сверка транзакционных записей с событиями;
- тест повторной доставки выбранного механизма.
Исключения¶
Не допускаются для события, обязательного для согласованности.
INT-EVT-008. Backpressure producer¶
Уровень: MUST
Применяется к: прикладной очереди между producer и broker client
Очередь, число параллельных публикаций и время ожидания должны иметь конечные границы. При заполнении producer должен вернуть определённую ошибку, применить контрактно допустимое объединение либо остановить приём новой работы; молчаливое удаление обязательного события запрещено.
Обоснование¶
Недоступный broker не должен превращать память процесса в неограниченную очередь.
Проверка¶
- integration-тест медленного и недоступного broker;
- нагрузочный тест заполнения очереди;
- contract-тест результата вызывающей операции.
Исключения¶
Best-effort событие может отбрасываться только при явно объявленной семантике и не должно использоваться для восстановления бизнес-состояния.
INT-EVT-009. Контракт dead-letter и replay¶
Уровень: SHOULD
Применяется к: сообщениям, исчерпавшим политику повторной обработки
Проекту следует использовать dead-letter isolation и управляемый replay, если сообщение после исчерпания повторов может быть исправлено, расследовано или повторно обработано. Записи следует сохранять исходные bytes или их разрешённую ссылку, contract version, идентификатор, число попыток и стабильный код причины. При replay следует снова применять schema validation и deduplication, сохранять исходный идентификатор и не обходить актуальную авторизацию обработчика.
Обоснование¶
Ручное копирование payload создаёт новое событие и обходит гарантии consumer.
Проверка¶
- тест создания записи каждого класса причины;
- replay одного события дважды;
- тест несовместимой или невалидной версии.
Исключения¶
Проект MAY не создавать DLQ. В этом случае конечное поведение после исчерпания повторов должно быть явно определено и наблюдаемо; потеря обязательной работы не может считаться успешной обработкой.
INT-EVT-010. Минимальные полномочия клиента¶
Уровень: MUST
Применяется к: конфигурации identity producer и consumer в проекте
Producer должен запрашивать только публикацию разрешённых subjects или
exchanges, consumer — только чтение и подтверждение назначенных streams или
queues. Общий credential producer и consumer и wildcard-доступ вне закрытого
перечня контракта запрещены. Значения credentials регулируются
SEC-SCRT-001, SEC-SCRT-002 и SEC-SCRT-005.
Обоснование¶
Разделение конфигурации предотвращает превращение дефекта consumer в несанкционированную публикацию.
Проверка¶
- integration-тест отказа запрещённой операции с test identities;
- review permission manifest;
- проверка отсутствия общего secret input.
Исключения¶
Изолированный локальный broker может использовать синтетическую общую identity, если тест полномочий отдельно выполняется с production-equivalent policy.
INT-EVT-011. Владение topology и subscription¶
Уровень: MUST
Применяется к: destination, stream, queue, subscription и consumer group внешнего message broker
Для каждого объекта topology должны быть определены владелец, назначение, создающий deployment-процесс, правила изменения и удаления. Каждый логический consumer должен иметь отдельную subscription или consumer group; несколько экземпляров MAY совместно использовать её только как конкурирующие экземпляры одного обработчика с одинаковым контрактом.
Разные бизнес-обработчики не должны разделять очередь так, что получение сообщения одним из них скрывает его от другого. Изменение routing, retention или числа partition должно поставляться как версионируемое изменение с проверкой существующих producer и consumer.
Обоснование¶
Неявное владение topology создаёт потерю сообщений при конкуренции разных потребителей и неконтролируемые инфраструктурные изменения.
Проверка¶
- сопоставление topology manifest с владельцами и deployment;
- integration-тест доставки каждому логическому consumer;
- review изменения routing, retention и partition.
Исключения¶
Временная subscription диагностического инструмента MAY создаваться отдельно, если она не подтверждает и не удаляет сообщения production-consumer.
INT-EVT-012. Backlog, retention и восстановление¶
Уровень: MUST
Применяется к: асинхронному каналу, потеря или задержка которого влияет на обязательный бизнес-результат
Проект должен определить максимальные размер сообщения, допустимый возраст необработанного сообщения, ожидаемую и пиковую скорость, срок retention и предел backlog. Retention должен покрывать согласованное время обнаружения и восстановления consumer либо проект должен иметь другой проверяемый механизм восстановления.
Наблюдаемые сигналы должны показывать возраст старейшего сообщения, lag или эквивалентный backlog, скорость поступления и обработки, ошибки и повторы, а при наличии dead-letter — его объём. Превышение согласованных пределов должно создавать операционное оповещение.
Обоснование¶
Работающий broker не гарантирует своевременный бизнес-результат; backlog может расти до потери по retention или исчерпания квоты.
Проверка¶
- нагрузочный тест пиковой скорости и восстановления после остановки consumer;
- проверка retention относительно времени обнаружения и восстановления;
- тест alerts для lag и возраста, а при наличии dead-letter — для его объёма.
Исключения¶
Для явно best-effort события MAY не задаваться восстановление, но конечные размер, retention и ресурсные пределы остаются обязательными.
INT-EVT-013. Устаревшие события и версия состояния¶
Уровень: MUST
Применяется к: consumer, строящему изменяемое состояние из событий, которые могут доставляться повторно или не по порядку
Событие должно содержать монотонную версию агрегата, sequence для ключа или иной проверяемый признак актуальности. Consumer должен атомарно сравнивать его с применённой версией и не должен заменять более новое состояние устаревшим событием.
Пропуск обязательной версии должен обнаруживаться и приводить к изоляции, повторному чтению источника истины или другому определённому восстановлению. Время события само по себе не должно считаться гарантией порядка.
Обоснование¶
Deduplication устраняет повтор одного ID, но не предотвращает откат состояния поздно доставленным событием с другим ID.
Проверка¶
- тест перестановки двух версий одного ключа;
- тест дубликата, пропуска версии и конкурентного применения;
- проверка атомарности сравнения и записи версии.
Исключения¶
Признак версии не требуется consumer, который не строит изменяемое состояние и для которого порядок событий не влияет на контрактный результат.
INT-EVT-014. Сверка критичной асинхронной проекции¶
Уровень: MUST
Применяется к: асинхронно построенной проекции, расхождение которой нарушает финансовый результат, права доступа, обязательный аудит или другой критичный контракт
Проект должен иметь повторяемую сверку проекции с источником истины. Сверка должна обнаруживать отсутствующие и лишние объекты, дубликаты, расхождение версии и обязательных агрегатов. Для каждого класса расхождения должны быть заданы допустимый предел, максимальный период обнаружения и владелец реакции.
Исправление должно быть идемпотентным, сохранять audit исходного и целевого
состояния и проходить обычные проверки версии по INT-EVT-013. Автоматическое
исправление не должно обходить авторизацию или маскировать неизвестный класс
расхождения.
Обоснование¶
Outbox, deduplication и replay уменьшают вероятность потери, но не обнаруживают ошибочную topology, операционное удаление или дефект обработчика после подтверждения сообщения.
Проверка¶
- контролируемый пропуск, дубликат и устаревшая версия;
- повторный запуск исправления;
- проверка alert и audit при превышении допустимого предела.
Исключения¶
Полностью воспроизводимая некритичная проекция MAY пересоздаваться целиком, если срок пересоздания проверен и соответствует её SLO.