ruststream 0.5.0

Async messaging framework for Rust: broker-agnostic traits, router, codecs, and a conformance harness for broker authors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

# Installation

RustStream ships as a single crate, `ruststream`, whose surface is gated behind additive cargo
features. Add it to your `Cargo.toml`:

```toml
[dependencies]
ruststream = { version = "0.4", features = ["macros", "memory", "json"] }
serde = { version = "1", features = ["derive"] }
```

`serde` is a direct dependency of your service because your message types derive `Deserialize` /
`Serialize`.

!!! note "Edition and MSRV"
    RustStream targets **edition 2024** and a minimum supported Rust version of **1.85** (native
    `async fn in trait`). Set `edition = "2024"` in your `Cargo.toml`. CI builds the crate on
    every stable toolchain from 1.85 up to current stable, so any floor in that range works.
    Broker crates may require a newer toolchain than the core when their underlying clients do;
    check the broker crate's own `rust-version`.

## Features

The core traits, the `RustStream` application object, the `Router`, middleware, and dispatch are
always compiled. Everything else is an additive, opt-in feature.

| Feature | Pulls in | What it gives you |
|---|---|---|
| `json` *(default)* | serde_json | `JsonCodec` |
| `msgpack` | rmp-serde | `MsgpackCodec` |
| `cbor` | ciborium | `CborCodec` |
| `memory` | - | `MemoryBroker`, the in-memory reference broker |
| `macros` | ruststream-macros | `#[subscriber]`, `#[ruststream::app]`, `#[derive(Message)]` |
| `asyncapi` | schemars, serde_norway | AsyncAPI generation and the HTML viewer |
| `metrics` | prometheus | Prometheus middleware and exporter |
| `logging` | tracing-subscriber | `ruststream::logging`, a colored console logger ([Logging](../guides/logging.md)) |
| `conformance` | - | the broker-author conformance harness |
| `cli` | clap, anyhow | the `ruststream` binary |

Codec features are mutually compatible; enable as many as you need (see
[Codecs](../guides/codecs.md)). To drop the bundled JSON codec
(for a broker crate that only needs the trait surface and runtime), disable defaults:

```toml
[dependencies]
ruststream = { version = "0.4", default-features = false }
```

## The CLI

The `ruststream` binary ships with the crate behind the `cli` feature. Install it to drive `cargo`
with the framework's subcommands (`run`, `asyncapi gen`):

```bash
cargo install ruststream --features cli
```

Scaffolding a new project is `cargo generate` against a template (no `ruststream` install required):

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

See the [CLI guide](../guides/cli.md) and the [template contract](../guides/templates.md), or jump
straight to the [quick start](quickstart.md).

## Concrete brokers

The `memory` broker is for local development and tests. For production, depend on a broker crate,
which re-exports what it needs from `ruststream`. Each broker is versioned and released
independently, so its own documentation carries the exact dependency line (including the current
version and the `testing` feature for handler tests) alongside its `Config` and capabilities.

The available brokers are listed under [Brokers](../brokers/index.md); follow the link there to each
broker's documentation for installation. To write one yourself, see
[Broker authors](../broker-authors/index.md).