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
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
//! Typed message processing with explicit delivery and shutdown semantics.
//!
//! Application code is a typed `Input → Output` [`Handler`]. The framework owns everything
//! around it: receiving from a [`Source`], decoding, retries, concurrency, ordering,
//! publishing to a [`Sink`], acknowledgement, dead letters, and graceful shutdown.
//!
//! ```text
//! App
//! ├── Subscription: Kafka source → handler → Kafka sink
//! ├── Subscription: Pulsar source → handler → HTTP sink
//! └── Subscription: SQS source → handler → RabbitMQ sink
//! ```
//!
//! 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.
//!
//! # Quick start
//!
//! Summarize each article on a Kafka topic with an LLM and publish the summaries to
//! another topic. The handler sees only the decoded value; a transient API failure is
//! retried, and each offset is committed after its summary is published.
//!
//! ```no_run
//! # #[cfg(feature = "kafka")]
//! # mod example {
//! use beavers::{
//! App, Classify, Utf8,
//! adapters::kafka::Kafka,
//! };
//!
//! async fn summarize(article: String) -> beavers::Result<String> {
//! let summary = call_llm(&format!("Summarize: {article}")).await.retry()?;
//! Ok(summary)
//! }
//!
//! #[tokio::main]
//! async fn main() -> Result<(), beavers::Error> {
//! 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
//! }
//! # async fn call_llm(prompt: &str) -> Result<String, std::io::Error> {
//! # Ok(prompt.to_owned())
//! # }
//! # }
//! # fn main() {}
//! ```
//!
//! # Concepts
//!
//! - A [`Source`] receives deliveries; each delivery ([`SourceMessage`]) owns its
//! acknowledgement and is acknowledged only after its outputs are published.
//! - A [`Handler`] turns a decoded input into an output, or into zero or many outputs with
//! [`Emit`]. Its errors are classified with [`HandlerError`] and [`Classify`].
//! - A [`Sink`] prepares an output once and publishes it, with retries.
//! - A [`Subscription`] connects one source, handler, and sink with [`Middleware`], a
//! dead-letter sink, an [`ErrorPolicy`], and a [`SubscriptionConfig`].
//! - An [`App`] runs subscriptions together and shuts them down on SIGINT or SIGTERM.
//! - [`Decoder`] and [`Encoder`] implementations such as [`Json`] convert payloads.
//!
//! Delivery is at least once. Duplicates are possible after a failure or a broker
//! rebalance; Kafka-to-Kafka subscriptions can use [`TransactionalSink`] instead.
//!
//! # Cargo features
//!
//! | Feature | Enables |
//! |---|---|
//! | `kafka` | Kafka source and sink in `adapters::kafka` |
//! | `pulsar` | Apache Pulsar source and sink in `adapters::pulsar` |
//! | `rabbitmq` | RabbitMQ source and sink in `adapters::rabbitmq` |
//! | `sqs` | Amazon SQS source and sink in `adapters::sqs` |
//! | `pubsub` | Google Cloud Pub/Sub source and sink in `adapters::pubsub` |
//! | `servicebus` | Azure Service Bus source and sink in `adapters::servicebus` |
//! | `http` | HTTP source and sink in `adapters::http` |
//! | `avro` | The `Avro` codec |
//! | `protobuf` | The `Protobuf` codec |
//! | `msgpack` | The `MessagePack` codec |
//! | `cbor` | The `Cbor` codec |
//! | `base64` | The `Base64` codec wrapper |
//! | `gzip` | The `Gzip` compression wrapper |
//! | `zstd` | The `Zstd` compression wrapper |
//! | `opentelemetry` | Trace-context propagation with `TraceContext` |
//! | `health` | `/livez` and `/readyz` endpoints in [`health`] |
//! | `testing` | Fabricated broker records for handler tests in `testing` |
//!
//! No feature is enabled by default.
//!
//! # Guides
//!
//! - [Runtime behavior and configuration](https://github.com/cafeal/beave-rs/blob/main/docs/runtime.md)
//! - [Adapters and delivery semantics](https://github.com/cafeal/beave-rs/blob/main/docs/adapters.md)
//! - [Codecs](https://github.com/cafeal/beave-rs/blob/main/docs/codecs.md)
//! - [Architecture and trait contracts](https://github.com/cafeal/beave-rs/blob/main/docs/architecture.md)
//! - [Testing](https://github.com/cafeal/beave-rs/blob/main/docs/testing.md)
//! - [Versioning and releases](https://github.com/cafeal/beave-rs/blob/main/docs/releasing.md)
pub use ;
pub use App;
pub use ;
pub use Base64;
pub use Cbor;
pub use Gzip;
pub use MessagePack;
pub use Protobuf;
pub use Zstd;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use Health;
pub use ;
pub use ;
pub use PropagationCarrier;
pub use ;
pub use CancellationToken;
pub use ;
pub use ;
pub use ;
pub use TraceContext;
pub use ;
pub use ;