Перейти к содержанию

NATS JetStream: stream, consumer и producer

Требования применяются к прикладному контракту stream, consumer и producer NATS JetStream. Уровни обязательности определены в корневом README.md.

INT-NATS-002. Контракт stream и consumer

Уровень: MUST

Применяется к: JetStream stream или consumer, используемым проектом

Проект должен версионировать закрытый перечень subjects и прикладные ожидания от JetStream: требуемый режим хранения и replay, filter subjects, acknowledgement policy, максимальное время обработки, семантику повторов и поведение после их исчерпания.

Точные определения broker-side consumers и параметры AckWait или BackOff, MaxDeliver и MaxAckPending MAY принадлежать и применяться владельцем NATS-платформы. Микросервис не обязан хранить или создавать эти ресурсы. При платформенном владении проект должен ссылаться на управляемую конфигурацию и проверять перед release, что её фактические значения совместимы с прикладными тайм-аутами, идемпотентностью и пропускной способностью. Достижение MaxDeliver должно иметь определённый наблюдаемый результат. Изоляция и replay по INT-EVT-009 MAY использоваться, но не являются обязательными.

Обоснование

Defaults JetStream влияют на потерю, повтор, пропускную способность и объём данных.

Проверка

  • review subjects, прикладных ожиданий и ссылки на управляемую NATS configuration;
  • сопоставление AckWait/BackOff, MaxDeliver и MaxAckPending с timeout, идемпотентностью и ёмкостью микросервиса;
  • тест redelivery, исчерпания попыток и terminal delivery result;
  • тест восстановления позиции и drain consumer.

Исключения

Микросервис MAY владеть JetStream consumer и его параметрами, если это явно определено границей ответственности; при этом применяются те же проверки совместимости.

INT-NATS-007. Подтверждённая публикация JetStream

Уровень: MUST

Применяется к: producer, публикующему сообщение в JetStream

Producer должен считать публикацию успешной только после положительного подтверждения сохранения от JetStream. До первой попытки producer должен назначить сообщению стабильный прикладной идентификатор. При timeout, разрыве соединения или другом неопределённом результате повтор должен передавать исходное сообщение с тем же идентификатором.

Если включена deduplication JetStream, стабильный идентификатор должен передаваться в Nats-Msg-Id; для события по INT-EVT-001 его значение должно быть равно event.id. Duplicate window должно покрывать максимальный срок повторной публикации, объявленный producer. При отключённой deduplication или повторе за пределами её окна consumer должен безопасно обрабатывать дубликат.

Обоснование

Отправка bytes без publish acknowledgement не доказывает сохранение, а новый идентификатор при неопределённом результате превращает безопасный повтор в новое сообщение.

Проверка

  • тест положительного и отрицательного publish acknowledgement;
  • тест timeout и reconnect после фактически сохранённой публикации;
  • повтор с тем же прикладным идентификатором и, при включённой deduplication, с тем же Nats-Msg-Id;
  • повтор до и после границы duplicate window;
  • сопоставление окна повторной публикации и настройки deduplication.

Исключения

Core NATS publish регулируется допустимой потерей по INT-NATS-001 и не обязан получать подтверждение сохранения.