beave-rs
A lightweight Rust message processing framework built around typed handlers.
Each Subscription connects one source, one handler, and one sink. An App
runs any number of subscriptions side by side and shuts them down together.
- Typed handlers — write
async fn(Input) -> Result<Output>; decoding, publishing, and acknowledgement are handled for you. - At-least-once delivery — an input is acknowledged only after its output is published.
- Explicit failure handling — classify errors as retry, reject (dead-letter), or fatal; retries back off.
- Concurrency with ordering — bounded concurrency, per-key ordering, and a worker pool for blocking handlers.
- Pipelines — chain subscriptions through in-process channels with end-to-end acknowledgement.
- Adapters — Kafka, Apache Pulsar, RabbitMQ, Amazon SQS, Google Cloud Pub/Sub, Azure Service Bus, and HTTP; JSON, Avro, Protobuf, MessagePack, and CBOR codecs, with Base64 and gzip or Zstandard compression wrappers.
- Operations — graceful shutdown,
tracingspans,metrics, OpenTelemetry trace propagation, and/livezand/readyzprobes.
beave-rs is pre-release. The API may change until 0.1.0.
Installation
No Cargo feature is enabled by default. Enable the adapters and codecs the application uses:
| Feature | Enables |
|---|---|
kafka |
Kafka source and sink |
pulsar |
Apache Pulsar source and sink |
rabbitmq |
RabbitMQ source and sink |
sqs |
Amazon SQS source and sink |
pubsub |
Google Cloud Pub/Sub source and sink |
servicebus |
Azure Service Bus source and sink |
http |
HTTP source and sink |
avro |
Avro codec |
protobuf |
Protobuf codec |
msgpack |
MessagePack codec |
cbor |
CBOR codec |
base64 |
Base64 wrapper for another codec |
gzip |
Gzip compression wrapper for another codec |
zstd |
Zstandard compression wrapper for another codec |
opentelemetry |
Trace-context propagation through broker metadata |
health |
/livez and /readyz endpoints |
testing |
Fabricated broker records for handler tests |
Quick start
Summarize each article on a Kafka topic with an LLM and publish the summaries to another topic:
use ;
async
async
The handler sees only the decoded value. A transient API failure is retried
with backoff, and each offset is committed after its summary is published.
Sources and sinks built from one Kafka handle share its connection settings,
and its sinks share one producer.
The repository's examples run against local brokers started with Docker Compose, which also provides web consoles for Kafka and Pulsar:
To try the API without a broker, run cargo run --example transform. See
local development brokers for every example, console,
and Cargo alias.
Errors
Errors propagated with ? reject the input, which is dead-lettered by default.
The handler asks for other outcomes at the call site:
async
.fatal()? stops the subscription. See
errors and retries for retry policies
and the error policy.
Documentation
- Documentation index
- Architecture and trait contracts
- Adapters and usage examples
- Codecs and serialization
- Dead-letter handling
- Monitoring and alerting
- Testing handlers
- Runtime behavior, configuration, and limitations
- Design plan and roadmap
- Local development brokers
- Versioning and releases
- API reference on docs.rs
The guides are also published at https://cafeal.github.io/beave-rs/. Each
page's Markdown source is available at the page URL with .html replaced by
.md, and llms.txt lists them
all for language-model tools.
Development
The minimum supported Rust version is 1.94.1. See local development brokers for the local Kafka, Pulsar, RabbitMQ, SQS, Pub/Sub, and Azure Service Bus environment and the live tests, and AGENTS.md for the checks every change must pass.
License
Licensed under the MIT license.
Let application code process events. Let beave-rs manage the flow.