Quick start

The fastest way to a running service is to scaffold one with cargo generate.

Scaffold a project

cargo install cargo-generate
cargo generate --git https://github.com/powersemmi/ruststream templates/memory --name my-service
cd my-service

Scaffolding needs only cargo generate, not the ruststream CLI. templates/memory is the in-memory starter (no external broker); each broker crate ships its own template (for example --git https://github.com/powersemmi/ruststream-nats templates/nats). This writes an idiomatic, multi-file project:

my-service/
├── Cargo.toml
└── src/
    ├── main.rs      # #[ruststream::app] builds the service and mounts the router
    ├── orders.rs    # handlers as #[subscriber] functions (one publishes a reply)
    └── routes.rs    # collects the handlers into a Router

Run it

#[ruststream::app] generates main, so the binary already understands the framework commands:

cargo run -- run                # or: ruststream run, with the CLI installed

cargo run -- run starts a tokio runtime and runs the service until you press ++ctrl+c++ (the ruststream run CLI is a convenience that forwards to it). The scaffold uses the in-memory broker, so it runs with no external dependencies.

Generate the AsyncAPI document

cargo run -- asyncapi gen

This prints the AsyncAPI document as JSON; the output flags (-o, --yaml) and the document itself are covered in the AsyncAPI guide.

What the entry point looks like

src/main.rs

mod orders;
mod routes;

use ruststream::memory::MemoryBroker;
use ruststream::runtime::{AppInfo, RustStream};

#[ruststream::app]
fn app() -> RustStream {
    RustStream::new(AppInfo::new("orders-service", "0.1.0")).with_broker(MemoryBroker::new(), |b| {
        let router = routes::orders();
        b.include_router(router);
    })
}

You write a function that builds the service; the macro turns it into a main that dispatches run and asyncapi gen.

Next

• Understand each piece in the tutorial.
• Learn the handler forms in Subscribers.
• Drive everything from the CLI.