Асинхронные сообщения для 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, декодируют их и печатают номер. Слева клиентом управляют вручную, справа им управляет рантайм.
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(())
}
- Настройки клиента и режим фиксации смещений вручную
- Декодирование и каждая ветка ошибок вручную
- Сигналы и остановка вручную
- И всё это заново для следующей темы и следующего брокера
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
Путь сообщения
Доставка идёт от брокера через подписку и кодек к вашему обработчику, а ответ возвращается тем же путём. Каждая часть - тип, который проверяет компилятор.
- БрокерАдаптация библиотеки брокера оборачивает одного клиента и соблюдает контракт, который проверяет набор conformance; ядро не зависит ни от одного брокера.
- ПодпискаПодписка называет, что потреблять, и разрешается один раз, при запуске, на подключённом брокере.
- КодекКодек превращает содержимое сообщения в тип обработчика: JSON, MessagePack или CBOR выбираются при компиляции, а сырые байты обходятся без кодека.
- Промежуточные слоиСлои потребления и публикации оборачивают каждую доставку: журналирование, метрики, трассировку или ваш собственный слой.
- ОбработчикАсинхронная функция под #[subscriber]; то, что она возвращает, подтверждает доставку или становится ответом.
- ОтветТип ответа выводит Outgoing и объявляет, куда он идёт; рантайм кодирует его и публикует.
- ИздательПолитика публикации в паре с подключённым брокером; обработчик публикует и через типизированные слоты Out.
- AsyncAPIИз тех же объявлений строится документ AsyncAPI 3.1, поэтому документ не расходится с кодом.
- 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 за минуту или задайте вопрос документации.
- Макросы
- Вручную
//! 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))
}
//! The landing-page example written without the `macros` feature: the handler is a named type
//! with an `impl Handle`, mounted with the `subscriber` constructor, and `main` is the one
//! `#[ruststream::app]` would generate.
//!
//! ```text
//! cargo run --example manual_quickstart --no-default-features --features memory,json,logging -- run
//! ```
use ruststream::diagnostics::TracingLogger;
use std::future::ready;
use std::process::ExitCode;
use ruststream::memory::prelude::*;
use ruststream::runtime::cli::run_main;
use serde::Deserialize;
#[derive(Debug, Deserialize, schemars::JsonSchema)]
struct Order {
id: u64,
}
/// The handler: `#[subscriber("orders")]` generates this type and this impl. Every axis of the
/// form - the reply, the injections, the broker context, the application state - is a defaulted
/// parameter of `Handle`, so a plain body names none of them.
struct Receive;
impl Handle<Order> for Receive {
fn handle(
&self,
order: &Order,
_outs: &(),
_ctx: &mut Context<'_>,
) -> impl Future<Output = Result<(), HandlerOutcome>> {
tracing::info!(order.id, "got order");
ready(Ok(()))
}
}
fn app() -> RustStream {
RustStream::new(AppInfo::new("orders", "0.1.0"))
.logger(TracingLogger)
.with_broker(MemoryBroker::new(), |b| {
b.include(subscriber("orders", Receive).build())
})
}
fn main() -> ExitCode {
run_main(app)
}
#[ruststream::app] генерирует main со всем шаблонным кодом рантайма: cargo run -- run запускает сервис, а cargo run -- asyncapi gen печатает его AsyncAPI-документ.
Установка
Подключение крейта и выбор фич.
Быстрый старт
Сервис из шаблона одной командой
cargo generate.Учебник
Первый сервис шаг за шагом.
Брокеры
In-memory брокер и адаптации библиотек остальных брокеров.
Авторам брокеров
Как написать адаптацию библиотеки брокера: контракт и проверки conformance.
Тестирование
Тесты обработчиков внутри процесса, без сервера.
HTTP-фреймворки
Сервис рядом с axum и транзакционный outbox.
AsyncAPI
Документ, который сервис строит из собственных объявлений.
Справочник API
Все типы на docs.rs.
Бенчмарки
Цена кода и каждый брокер против своего клиента без фреймворка.