RustStream

RustStream is an async messaging framework for Rust: a broker-agnostic core of traits and a router runtime, plus codecs, AsyncAPI generation, Prometheus metrics, and a conformance harness for broker authors.

Two architectural commitments shape the framework:

1. A real interface for third-party brokers. The core holds only traits and types, with zero broker dependencies. Each broker is an independent crate, and the contract is checked by the conformance harness.
2. Broker-specific config stays in broker crates. The core carries no broker-specific config or defaults. Each broker crate owns its own Config, so an upstream change hits one broker crate, not the framework.

//! The landing-page example: a one-handler service with no runtime boilerplate.
//!
//! ```text
//! cargo run --example quickstart --features macros,memory,json -- run
//! ```

use ruststream::memory::MemoryBroker;
use ruststream::runtime::{AppInfo, HandlerResult, RustStream};
use ruststream::subscriber;
use serde::Deserialize;

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

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

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

#[ruststream::app] generates main, so cargo run -- run starts the service and cargo run -- asyncapi gen prints its AsyncAPI document - no runtime boilerplate.

Design principles

• Fully async, tokio-based. No blocking APIs in the public surface.
• Generic core, no dyn in the contract. Associated types and native async fn in trait; object-safe erasure lives in consumers (the Python bindings), not the core.
• Subscribers are Streams, not callbacks. Back-pressure for free; the callback DX is built on top in the runtime.
• Ack consumes self. You cannot ack twice - the compiler enforces it.
• Capability traits for optional features (BatchSubscriber, TransactionalPublisher, RequestReply, Partitioned) - never forced into the mandatory interface.

Where to go next

• Installation - features and crate setup.
• Quick start - scaffold a service with the CLI.
• Tutorial - build a service step by step.
• Testing - test handlers in-process, no server needed.
• Brokers - the in-memory broker and NATS.
• Broker authors - implement the contract and pass conformance.

Scope of this repository

This site documents ruststream-rs, the pure-Rust core (no PyO3, no concrete brokers). Concrete brokers (NATS, Kafka, RabbitMQ, Redis, MQTT) live in their own crates and pull ruststream from crates.io. The Python bindings live in the ruststream-py repository.

The Rust API reference is published on docs.rs - see API reference.