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
//! Application registration, subscription supervision, and shutdown coordination.
#[cfg(feature = "health")]
use crate::health::HealthServer;
use crate::{
error::{Error, ensure},
health::Health,
shutdown::{CancellationToken, termination_signal},
sink::Sink,
source::Source,
subscription::{IntoHandler, One, Subscription},
};
use std::{collections::HashSet, future::Future, pin::Pin};
use tokio::task::JoinSet;
type Runner = Box<
dyn FnOnce(CancellationToken) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>> + Send,
>;
/// A set of subscriptions that run, fail, and shut down together.
///
/// ```no_run
/// use beavers::{App, IterSource, Json, StdoutSink};
///
/// async fn double(value: u64) -> beavers::Result<u64> {
/// Ok(value * 2)
/// }
///
/// # async fn run() -> Result<(), beavers::Error> {
/// App::new()
/// .subscribe("double", IterSource::new([1, 2, 3]), StdoutSink::<Json<_>>::new(), double)
/// .run()
/// .await
/// # }
/// ```
#[derive(Default)]
pub struct App {
subscriptions: Vec<Runner>,
names: HashSet<String>,
validation: Vec<String>,
health: Health,
#[cfg(feature = "health")]
health_server: Option<HealthServer>,
}
impl App {
/// An application without subscriptions.
pub fn new() -> Self {
Self::default()
}
/// Add a subscription with the default [`SubscriptionConfig`](crate::SubscriptionConfig).
///
/// Use [`subscription`](Self::subscription) to register a configured [`Subscription`].
///
/// The handler takes the received record or its value and returns the sink's
/// output type or a plain value; see [`IntoHandler`] for the accepted shapes.
pub fn subscribe<S, K, H, In, Out>(
self,
name: impl Into<String>,
source: S,
sink: K,
handler: H,
) -> Self
where
S: Source,
H: IntoHandler<S, K, (In, Out, One)>,
K: Sink<H::Output>,
{
self.subscription(Subscription::new(name, source, sink, handler))
}
/// Add a configured subscription.
///
/// Subscription names must be unique. Invalid configuration is reported when the
/// application starts running.
pub fn subscription<S, K, O>(mut self, subscription: Subscription<S, K, O>) -> Self
where
S: Source,
K: Sink<O>,
O: Send + Sync + 'static,
{
if let Err(error) = subscription.validate() {
self.validation.push(error.to_string());
}
// Names label logs, spans, and metrics, so two subscriptions must not share one.
if !self.names.insert(subscription.name().to_owned()) {
self.validation.push(format!(
"duplicate subscription name {:?}",
subscription.name()
));
}
let tracker = self.health.register(subscription.name());
self.subscriptions
.push(Box::new(|token| Box::pin(subscription.run(token, tracker))));
self
}
/// A handle reporting the liveness and readiness of the subscriptions
/// registered so far and of those registered later.
pub fn health(&self) -> Health {
self.health.clone()
}
/// Serves liveness and readiness probes while the application runs.
#[cfg(feature = "health")]
pub fn health_server(mut self, server: HealthServer) -> Self {
self.health_server = Some(server);
self
}
/// Run every subscription until all of them finish or `shutdown` is cancelled.
///
/// A subscription failure cancels `shutdown`, so the others drain and stop; the first
/// failure is returned after every subscription has finished.
pub async fn run_until(self, shutdown: CancellationToken) -> Result<(), Error> {
ensure!(
self.validation.is_empty(),
Error::config,
"{}",
self.validation.join("; ")
);
self.health.start(&shutdown);
#[cfg(feature = "health")]
let health_server = self.health_server.map(|server| {
let stop = CancellationToken::new();
let task = tokio::spawn(server.serve(self.health.clone(), stop.clone()));
(stop, task)
});
let mut subscriptions = JoinSet::new();
for run in self.subscriptions {
subscriptions.spawn(run(shutdown.clone()));
}
let mut failure = None;
while let Some(result) = subscriptions.join_next().await {
if let Err(error) =
result.unwrap_or_else(|error| Err(Error::wrap("subscription task failed", error)))
{
shutdown.cancel();
failure.get_or_insert(error);
}
}
#[cfg(feature = "health")]
if let Some((stop, task)) = health_server {
stop.cancel();
if let Err(error) = task
.await
.unwrap_or_else(|error| Err(Error::wrap("health server task failed", error)))
{
failure.get_or_insert(Error::wrap("health server failed", error));
}
}
match failure {
Some(e) => Err(e),
None => Ok(()),
}
}
/// Run every subscription until all of them finish, one fails, or the process receives
/// SIGINT or SIGTERM.
pub async fn run(self) -> Result<(), Error> {
let token = CancellationToken::new();
let run = self.run_until(token.clone());
tokio::pin!(run);
tokio::select! {
result = &mut run => result,
signal = termination_signal() => { token.cancel(); let result = run.await; signal?; result }
}
}
}