beave-rs

beave-rs

A lightweight Rust message processing framework built around typed handlers.

cargo add beavers --features kafka

Read the guides docs.rs

Pre-release. The API may change until 0.1.0.

Example

Summarize each article on a Kafka topic with an LLM and publish the summaries to another topic:

use beavers::{
    App, Classify, Result, Utf8,
    adapters::kafka::Kafka,
};

async fn summarize(article: String) -> Result<String> {
    let summary = call_llm(&format!("Summarize: {article}")).await.retry()?;
    Ok(summary)
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let kafka = Kafka::new("localhost:9092");
    let articles = kafka.source::<Utf8, _>("summarizer", ["articles"]);
    let summaries = kafka.sink::<Utf8, _>("summaries");

    App::new()
        .subscribe("summarize", articles, summaries, summarize)
        .run()
        .await?;
    Ok(())
}

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.

Subscriptions

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. The architecture guide describes the contracts each part implements.

An App running three subscriptions: Kafka source to handler to Kafka sink, Pulsar source to handler to HTTP sink, and SQS source to handler to RabbitMQ sink

Adapters and codecs

No Cargo feature is enabled by default. Enable the adapters and codecs the application uses.

Adapters

Codecs

opentelemetry propagates trace context through broker metadata, health serves /livez and /readyz, and testing provides fabricated broker records for handler tests.

Errors

Errors propagated with ? reject the input, which is dead-lettered by default. The handler asks for other outcomes at the call site:

async fn handle(order: Order) -> Result<Output> {
    validate(&order).reject()?; // dead-letter now (same as `?`)
    let user = db.find_user(order.user_id).await.retry()?; // retry, then dead-letter
    Ok(build_output(order, user))
}

.fatal()? stops the subscription. Handling dead letters covers what to do with rejected inputs.

Guides

Configuration, delivery behavior for each broker, testing, monitoring, and local development brokers.

Read the guides