Crate ruststream

Expand description

Rust core of the RustStream messaging framework: broker-agnostic traits, message types, codecs, router runtime, and a conformance harness for broker authors.

§A service

A handler is an async fn over a decoded payload. The application object mounts it on a broker, and the attribute writes the main:

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

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

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

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

cargo run -- run starts it. The broker here is the in-process one; a real broker is a crate of its own with the same shape, and its prelude replaces memory::prelude.

§Where things are

runtime: everything a service is made of. Subscribers and what a handler may take, replies and Out slots, routers, the per-delivery context and the shared state, typed headers, lifecycle hooks, middleware, failure policies, running beside another server.
codec: how payload bytes become values and back, where a codec is chosen, and the byte lanes that need none.
memory: the in-process broker, a real broker and the reference implementation.
testing: testing the service’s own app, in process or against a running broker.
asyncapi: the generated document. metrics, logging, otel: observability.
runtime::cli: the generated entry point and the ruststream command.
conformance: the contract suite a broker crate runs against itself.

The broker crates document their own descriptors and publish policies. Installation, the tutorial and the list of brokers are on the site: https://powersemmi.github.io/ruststream/.

§Cargo features

The core traits, the runtime::RustStream application object, middleware, and dispatch are always present. The rest is additive and opt-in. Codec features are mutually compatible and enable only the deserializers you need.

json (default): codec::JsonCodec.
msgpack: codec::MsgpackCodec.
cbor: codec::CborCodec.
memory: memory::MemoryBroker, an in-process broker usable in applications, prototypes and tests.
macros: the #[subscriber], #[ruststream::app], #[derive(Outgoing)] and #[derive(MessageInfo)] macros.
asyncapi: AsyncAPI document generation and the HTML viewer.
metrics: Prometheus metrics middleware and exporter.
logging: colored, RUST_LOG-driven console logging via tracing-subscriber (logging::init). The generated cli run command installs it automatically.
otel: OpenTelemetry SDK integration: OTLP export for traces and metrics via otel::OtelBuilder::init, plus per-handler dispatch metrics middleware and W3C trace-context propagation (otel::propagation).
conformance: the conformance::harness contract suite, per-capability suites in conformance::capabilities, the in-process transport held to the server in conformance::in_process, the checks of what a message carries in conformance::message_shape, and broker-agnostic conformance::helpers for application tests. Generic over any broker’s testing::TestableBroker, so it pulls in no concrete broker (enable memory too to run it against memory::MemoryBroker).
testing: the testing::TestApp harness, which runs the service’s production app in process or against running brokers.
cli: the ruststream binary (run, asyncapi gen, new).
poll-diagnostics: every subscription samples the time its handler spends in poll and warns when a handler computes on the app’s runtime (runtime::PollDiagnostics).

Disable defaults (default-features = false) to drop the bundled JSON codec; the core traits, runtime, and dispatch remain. Add back only what you need.

§Getting the imports

prelude carries what a service writes every time (the application object, the handler surface, the extractor parameters, the macros): use ruststream::prelude::*;. The broker and the codec stay explicit, since those are the choices a service makes for itself.

Re-exports§

pub use runtime::RustStream;
pub use runtime::OutSlot;
pub use schemars;

Modules§

asyncapi: AsyncAPI 3.1 document generation from a RustStream service.
codec: Pluggable serialization codecs.
conformance: Conformance harness for broker authors.
logging: Colorful, environment-driven console logging built on tracing_subscriber.
memory: In-process broker: the bus, and what it keeps of what went over it.
metrics: Prometheus metrics for consume and publish paths.
otel: OpenTelemetry integration (otel feature): W3C trace-context propagation, OTLP export, and per-handler dispatch metrics.
prelude: The imports a service writes every time, in one glob.
runtime: The application object, the handler surface, and dispatch.
testing: Application testing support, behind the testing feature.

Macros§

nonzero: Builds a NonZero integer from a literal, rejecting zero at compile time.
register_testable_broker: Registers a production broker type with the test harness, so TestApp runs every broker of that type in process.

Structs§

AddressedCopies: The copy path of a subscription whose retries this process publishes, to a destination the descriptor knows: a subject, a topic, a queue, a stream key.
AppId: The service’s own identifier, which AsyncAPI requires to be a URI.
BrokerMoves: The copy path of a subscription whose deliveries the broker moves itself.
Buffered: A SubscriptionSource adapter that buffers the wrapped source’s subscriber into a BatchSubscriber.
BufferedSubscriber: The subscriber Buffered opens: the wrapped source’s subscriber plus client-side batching.
Bytes: The shared byte buffer the message path hands around: a payload, a header value taken with HeaderMap::get_shared.
BytesMut: The buffer the crate’s byte-producing surfaces speak: what a Codec returns, what a Serialized value writes into, and the payload a publisher that declared Take is handed.
CallerName: The destination form of a type declaring no name: the call site names the destination.
Contact: Who to contact about the service.
ExternalDocs: A pointer at documentation kept outside the generated document.
FixedName: The destination form of a type declaring one literal name: the name is fixed, so the publish builder resolves the destination without asking the call site.
HeaderMap: Case-insensitive map of broker-message headers.
Lend: The declaration of a transport that reads the payload and keeps nothing: it is handed &[u8].
License: The licence the service is published under.
Name: The default SubscriptionSource: subscribe by name string via the Subscribe capability.
NameTemplate: The destination form of a type declaring a name template: the call site binds every placeholder through the setters generated from it, and the name is rendered per publish.
NamedCopies: The copy path of a subscription whose retries this process publishes but cannot address: a wildcard subject, an MQTT filter, a Pulsar pattern, a list of topics.
NoHeaders: The header contract of a message that carries no typed headers.
OutgoingMessage: A message ready to be published: a borrowed destination, a payload in the form its publisher declared, and the header map the publish filled.
PairError: The error of PublishPolicy::pair: whatever the broker reported while bringing a publisher alive, type-erased.
RawMessage: An owned snapshot of a message as it travels through the framework.
RedeliveryAddress: The name a deferred redelivery of one subscription is published to.
RetryDeclaration: What one registration declared about its retries: how many attempts a delivery gets, and where it goes when they run out.
SecurityScheme: How clients authenticate to an AsyncAPI server, per the AsyncAPI security scheme types.
ServerSpec: How to reach a broker, for the servers section of an AsyncAPI document.
StartAt: A source decorator opening the subscription at a chosen position instead of the broker’s default.
Tag: A group label: on the service, on a server, on an operation.
Take: The declaration of a transport whose client keeps the payload: it is handed a BytesMut of its own.
Unnamed: The stand-in a definition carries while its subscription has no name yet.
WithHeaders: The header contract of a message whose headers are the typed struct H.

Enums§

AckError: Errors returned by IncomingMessage::ack and IncomingMessage::nack.
ApiKeyLocation: Where an apiKey scheme carries the key, per AsyncAPI.
AppIdError: Why a string is not an AppId.
DeclareRetryError: Errors returned by Subscribe::declare_retry, where a registration mounted by a bare subscription name declares how its deliveries retry.
DeserializeHeadersError: Error of the crate-internal to_typed parse: the header map does not satisfy the typed contract.
HttpApiKeyLocation: Where an httpApiKey scheme carries the key, per AsyncAPI.
SerializeHeadersError: Error of HeaderMap::insert_typed: the value does not fit the flat header-map shape.

Traits§

BatchSubscriber: A subscriber that delivers messages in batches.
Broker: An unconnected broker: configuration captured, no I/O performed yet.
BuildBatchContext: Builds a batch handler’s context value from the batch’s first delivery.
BuildContext: Builds a handler’s per-delivery context value from the broker message.
ConnectedBroker: A connected broker: the typed witness of a live connection.
ContextField: A Field-style key that also names its context type and yields an owned value.
CopyPath: Who publishes the copies a subscription’s retries are made of, and who names where they go.
DefaultPublish: A connected broker that names its plain publish policy, so the runtime can build a default reply publisher when a reply("dest") handler is included without an explicit one.
DescribeServer: A broker that describes itself as an AsyncAPI server.
DestinationForm: The closed set of destination forms: FixedName, NameTemplate and CallerName.
Field: A compile-time key reading one typed field out of Src.
FieldMut: A Field key middleware can also write, for per-delivery scratch values.
FromName: A subscription kind identified by a name and nothing else.
HeadersContract: The closed set of header contract shapes: NoHeaders and WithHeaders<H>.
IncomingMessage: A message delivered by a Subscriber.
MessageHeaders: Declares a message type’s typed header contract.
MessageInfo: Metadata about a message type, used to name and describe it in an AsyncAPI document.
OutgoingDestination: Declares where a message type is sent.
OwnedTransactions: A publisher that opens caller-owned, client-buffered transactions.
Partitioned: Messages or publishers that carry a routing key for broker-side partitioning.
PayloadForm: How a transport consumes the payload of a publish: Lend where it reads the bytes, Take where its client keeps them.
Positioned: A delivered message that knows its own position in the broker’s replayable log.
PublishPolicy: The declaration half of a publisher: pure policy, no connection, no publish surface.
Publisher: A producer that sends messages into the broker.
RedeliveryAddressed: A subscription descriptor that knows where a publish reaches it again.
RequestReply: A publisher that supports synchronous request / reply messaging.
Seekable: A subscriber whose position in a replayable log can be moved.
Seeker: A clonable handle that repositions one subscription, minted by Seekable::seeker.
Subscribe: A connected broker whose subscriptions are fully determined by a name string.
Subscriber: A consumer attached to one or more broker names.
SubscriptionSource: A description of one subscription, resolved against a connected broker at startup.
Transaction: A client-buffered transaction that owns its buffer, opened by OwnedTransactions::transaction.
TransactionalPublisher: A publisher that supports broker-side transactions.

Type Aliases§

Connected: Shorthand for a broker’s connected form, so bounds read S: SubscriptionSource<Connected<B>> instead of spelling the associated type projection.
OutgoingFor: The message a publisher of form Form is handed: OutgoingMessage over that form’s payload.
Str: The owned string of the message path: a destination name, a header key.

Attribute Macros§

app: Attribute macro that generates a main entry point from a RustStream builder function.
subscriber: Attribute macro that turns an async fn into a mountable subscriber definition.

Derive Macros§

Deserialized: Derive macro for a self-deserializing input type (Deserialized): a newtype or single-field struct over &'a [u8] gains the construction and the Input spelling; the batch spelling (&[Frame<'_>]) follows from it.
FromRef: Derive macro that implements FromRef for each field of an application state, so handlers can inject any field with State<T>.
MessageInfo: Derive macro for MessageInfo metadata (type name + doc description).
OutMessages: Derive macro for a declared message set: an enum whose variants each wrap one message model, named as the third Out argument (Out<impl Publisher, Marker, SendSet>). The enum is a type-level declaration and is never constructed.
OutSlot: Derive macro that makes a unit struct a slot marker (OutSlot) for Out<impl Publisher, Marker> handler parameters.
Outgoing: Derive macro declaring everything a message type says about being sent: its destination (OutgoingDestination) and its optional header contract (MessageHeaders), plus the MessageInfo metadata the generated document reads.
Serialized: Derive macro for a self-serialized outgoing type (Serialized): a newtype or single-field struct over a byte buffer gains the bytes accessor and the wire spellings that route it onto the serialized wire (MessageWire for a typed publish, ReplyShape for the reply position).