Перейти к основному содержимому
Открытый код · Apache-2.0 · 100% безопасный Rust

Асинхронные сообщения для Rust на любом брокере

Напишите обработчики #[subscriber] один раз, запускайте их на Kafka, NATS, RabbitMQ и ещё десяти брокерах, а ошибки использования пусть ловит компилятор.

Один обработчик, четырнадцать транспортов

Kafkaruststream-rdkafkaNATSruststream-natsRabbitMQruststream-lapinRedis / Valkeyruststream-fredAMQP 1.0ruststream-amqpGoogle Pub/Subruststream-gcp-pubsubSQS / SNSruststream-sqs-snsPulsarruststream-pulsarMQTT 5ruststream-rumqttcZeroMQruststream-zeromqKinesisruststream-kinesisФайлы / stdioruststream-sea-fileБазы данных SQLruststream-sqlxВ памяти процессаruststream
Один и тот же потребитель, дважды

Пишите обработчик, а не цикл

Обе программы читают заказы из Kafka, декодируют их и печатают номер. Слева клиентом управляют вручную, справа им управляет рантайм.

src/main.rs · rdkafkaВручную
use rdkafka::Message;
use rdkafka::config::ClientConfig;
use rdkafka::consumer::{CommitMode, Consumer, StreamConsumer};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Order {
id: u64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let consumer: StreamConsumer = ClientConfig::new()
.set("bootstrap.servers", "localhost:9092")
.set("group.id", "orders-svc")
.set("enable.auto.commit", "false")
.create()?;
consumer.subscribe(&["orders"])?;

loop {
let msg = tokio::select! {
_ = tokio::signal::ctrl_c() => break,
msg = consumer.recv() => match msg {
Ok(msg) => msg,
Err(err) => {
eprintln!("kafka error: {err}");
continue;
}
},
};
match msg.payload().map(serde_json::from_slice::<Order>) {
Some(Ok(order)) => println!("got order {}", order.id),
Some(Err(err)) => eprintln!("bad payload: {err}"),
None => eprintln!("empty message"),
}
if let Err(err) = consumer.commit_message(&msg, CommitMode::Async) {
eprintln!("commit failed: {err}");
}
}
Ok(())
}
  • Настройки клиента и режим фиксации смещений вручную
  • Декодирование и каждая ветка ошибок вручную
  • Сигналы и остановка вручную
  • И всё это заново для следующей темы и следующего брокера
src/main.rs · ruststream-rdkafka
use ruststream_rdkafka::prelude::*;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Order {
id: u64,
}

#[subscriber("orders")]
async fn handle(order: &Order) -> HandlerOutcome {
println!("got order {}", order.id);
HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> impl App {
RustStream::new(AppInfo::new("orders", "0.1.0")).with_broker(
KafkaBroker::new(["localhost:9092"]).default_group("orders-svc"),
|b| {
b.include(handle);
},
)
}
терминал
$ cargo run -- run
04:24:54.781 INFO ruststream::lifecycle starting service service=orders version=0.1.0 brokers=1 subscribers=1
04:24:54.886 INFO ruststream::lifecycle broker connected broker="ruststream_rdkafka::broker::KafkaBroker"
04:24:57.902 INFO ruststream::dispatch subscriber started subscriber=orders input="kafka_quickstart::Order"
04:24:57.902 INFO ruststream::lifecycle service running subscribers=1
# {"id":1} is published to orders
got order 1
04:25:03.779 INFO ruststream::lifecycle shutdown signal received
04:25:03.886 INFO ruststream::lifecycle service stopped

Настоящий запуск примера kafka_quickstart на локальной Kafka с включённой фичей logging.

  • Декодирует каждое сообщение кодеком, выбранным при сборке
  • Подтверждает каждое сообщение по результату обработчика
  • Останавливается по Ctrl+C или SIGTERM и закрывает брокер
  • Печатает свой AsyncAPI-документ командой asyncapi gen и работает под TestApp без Kafka
Архитектура

Путь сообщения

Доставка идёт от брокера через подписку и кодек к вашему обработчику, а ответ возвращается тем же путём. Каждая часть - тип, который проверяет компилятор.

БрокерПодпискаКодекПромежуточные слоиОбработчикОтветИздательAsyncAPITestApp
ОбработчикАсинхронная функция под #[subscriber]; то, что она возвращает, подтверждает доставку или становится ответом.
  1. БрокерАдаптация библиотеки брокера оборачивает одного клиента и соблюдает контракт, который проверяет набор conformance; ядро не зависит ни от одного брокера.
  2. ПодпискаПодписка называет, что потреблять, и разрешается один раз, при запуске, на подключённом брокере.
  3. КодекКодек превращает содержимое сообщения в тип обработчика: JSON, MessagePack или CBOR выбираются при компиляции, а сырые байты обходятся без кодека.
  4. Промежуточные слоиСлои потребления и публикации оборачивают каждую доставку: журналирование, метрики, трассировку или ваш собственный слой.
  5. ОбработчикАсинхронная функция под #[subscriber]; то, что она возвращает, подтверждает доставку или становится ответом.
  6. ОтветТип ответа выводит Outgoing и объявляет, куда он идёт; рантайм кодирует его и публикует.
  7. ИздательПолитика публикации в паре с подключённым брокером; обработчик публикует и через типизированные слоты Out.
  8. AsyncAPIИз тех же объявлений строится документ AsyncAPI 3.1, поэтому документ не расходится с кодом.
  9. TestAppТест запускает рабочее приложение с брокером внутри процесса и проходит настоящую диспетчеризацию без сервера.
Устройство

Чему фреймворк следует

  • 01

    Ядро без брокера внутри

    Ядро - это трейты и типы. Адаптация библиотеки каждого брокера - отдельный крейт, и соблюдение контракта проверяет набор conformance.

  • 02

    Настройки брокера живут в его адаптации

    Каждая адаптация объявляет свой Config. Обновление клиентской библиотеки меняет эту адаптацию, а не фреймворк.

  • 03

    Ошибка использования не компилируется

    ack(self) поглощает доставку, поэтому второй ack - ошибка компиляции. Вызовы жизненного цикла не по порядку отклоняются так же.

  • 04

    Подписчики - это потоки

    Подписчик - это Stream, поэтому обратное давление идёт вместе с ним. Обработчики рантайм надстраивает поверх.

  • 05

    Обобщённое ядро без dyn в контракте

    Контракт построен на ассоциированных типах и нативном async fn in trait. Типы стирает рантайм и только там, где это нужно сервису.

  • 06

    Возможности, а не раздутый интерфейс

    Пакеты, транзакции, запрос-ответ, разделы и перемотка - отдельные трейты. Брокер реализует те, что поддерживает.

Цена одного сообщения

Ноль выделений памяти на сообщение

Собственный код фреймворка на одно сообщение в установившемся режиме; бенчмарки считают его при каждом изменении. Клиент брокера в эти числа не входит.

  • 1 697инструкцийвыделений памяти: 0

    Получить сообщение и декодировать JSON в структуру

  • 862инструкцийвыделений памяти: 0

    Получить сырые байты, без кодека

  • 1 785инструкцийвыделений памяти: 0

    Получить сообщение через четыре промежуточных слоя

  • 2 051инструкцийвыделений памяти: 0

    Закодировать и опубликовать ответ

Замер: ruststream 0.8.0, 2026-11-01, AMD Ryzen 9 7900X 12-Core Processor. На странице бенчмарков - все сценарии и методика, в том числе пути, которые выделяют память.

Начните с одного обработчика

Создайте сервис из шаблона командой cargo generate за минуту или задайте вопрос документации.

Быстрый старт
examples/quickstart.rs
//! The landing-page example: a one-handler service with no runtime boilerplate.
//!
//! ```text
//! cargo run --example quickstart --features macros,memory,json,logging -- run
//! ```

use ruststream::diagnostics::TracingLogger;
use ruststream::memory::prelude::*;
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Order {
id: u64,
}

#[subscriber("orders")]
async fn handle(order: &Order) -> HandlerOutcome {
tracing::info!(order.id, "got order");
HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> RustStream {
RustStream::new(AppInfo::new("orders", "0.1.0"))
.logger(TracingLogger)
.with_broker(MemoryBroker::new(), |b| b.include(handle))
}

#[ruststream::app] генерирует main со всем шаблонным кодом рантайма: cargo run -- run запускает сервис, а cargo run -- asyncapi gen печатает его AsyncAPI-документ.