mod dispatch;
mod envelope;
mod queue;
mod signing;
pub use signing::{InvalidSigningSecret, SigningSecret};
#[cfg(test)]
mod tests;
use std::{
collections::BTreeSet,
hash::Hash,
sync::{
Arc,
atomic::{AtomicU64, AtomicUsize, Ordering},
},
time::Duration,
};
use tokio::sync::mpsc;
use crate::outbound::{BearerToken, Endpoint, HttpClient};
pub use envelope::{CONTENT_TYPE, Envelope, RenderError, Renderer};
use queue::Queue;
pub trait Subject: Clone + Eq + Hash + Send + Sync + 'static {
fn as_str(&self) -> &str;
}
pub trait Kind: Copy + Eq + Ord + Hash + std::fmt::Display + Send + Sync + 'static {}
impl<T> Kind for T where T: Copy + Eq + Ord + Hash + std::fmt::Display + Send + Sync + 'static {}
pub trait Occurrence: Send + 'static {
type Subject: Subject;
type Kind: Kind;
const TYPE_PREFIX: &'static str;
fn kind(&self) -> Self::Kind;
fn subject(&self) -> Self::Subject;
fn data(&self) -> serde_json::Value;
}
pub trait HookObserver<K: Kind>: Send + Sync + 'static {
fn event_dropped(&self, _hook: &str, _event: &str, _kind: K, _loss: Loss, _detail: &str) {}
fn events_abandoned(&self, _hook: &str, _dropped: usize) {}
fn delivery_outcomes_unknown(&self, _hook: &str, _count: usize) {}
fn event_unrenderable(&self, _reason: &str) {}
}
#[derive(Clone, Copy, Debug, Default)]
pub struct IgnoreHookEvents;
impl<K: Kind> HookObserver<K> for IgnoreHookEvents {}
#[derive(Clone, derive_more::Debug)]
pub struct HookConfig<K> {
pub name: Arc<str>,
pub endpoint: Endpoint,
pub events: BTreeSet<K>,
pub queue_capacity: usize,
pub maximum_in_flight: usize,
pub maximum_attempts: u32,
#[debug(skip)]
pub bearer: Option<BearerToken>,
pub signing_secret: Option<SigningSecret>,
#[debug(skip)]
pub client: Option<HttpClient>,
}
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[error("hook `{hook}`: {reason}")]
pub struct ConfigError {
pub hook: Arc<str>,
pub reason: &'static str,
}
impl<K> HookConfig<K> {
pub fn validate(&self) -> Result<(), ConfigError> {
let reason = if self.events.is_empty() {
Some("subscribes to no events")
} else if self.queue_capacity == 0 {
Some("queue capacity must be nonzero")
} else if self.queue_capacity > tokio::sync::Semaphore::MAX_PERMITS {
Some("queue capacity exceeds the channel limit")
} else if self.maximum_in_flight == 0 {
Some("maximum in-flight requests must be nonzero")
} else if self.maximum_attempts == 0 {
Some("maximum attempts must be nonzero")
} else {
None
};
match reason {
Some(reason) => Err(ConfigError {
hook: self.name.clone(),
reason,
}),
None => Ok(()),
}
}
}
#[derive(Clone, Debug)]
pub struct HooksConfig<K> {
pub source: String,
pub schema_version: u32,
pub drain_timeout: Duration,
pub hooks: Vec<HookConfig<K>>,
}
impl<K> HooksConfig<K> {
pub fn new(source: impl Into<String>) -> Self {
Self {
source: source.into(),
schema_version: 1,
drain_timeout: Duration::from_secs(5),
hooks: Vec::new(),
}
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, derive_more::Display)]
#[display("{}", self.as_str())]
pub enum Loss {
Ingress,
Overflow,
Rejected,
Exhausted,
Shutdown,
}
impl Loss {
pub fn as_str(self) -> &'static str {
match self {
Self::Ingress => "ingress",
Self::Overflow => "overflow",
Self::Rejected => "rejected",
Self::Exhausted => "exhausted",
Self::Shutdown => "shutdown",
}
}
}
#[derive(Debug, Default)]
pub struct HookMeters {
delivered: AtomicU64,
retried: AtomicU64,
ingress: AtomicU64,
overflow: AtomicU64,
rejected: AtomicU64,
exhausted: AtomicU64,
shutdown: AtomicU64,
outcome_unknown_shutdown: AtomicU64,
filtered: AtomicU64,
ingress_depth: AtomicUsize,
queue_depth: AtomicUsize,
in_flight: AtomicUsize,
}
impl HookMeters {
fn record_loss(&self, loss: Loss) {
match loss {
Loss::Ingress => &self.ingress,
Loss::Overflow => &self.overflow,
Loss::Rejected => &self.rejected,
Loss::Exhausted => &self.exhausted,
Loss::Shutdown => &self.shutdown,
}
.fetch_add(1, Ordering::Relaxed);
}
pub fn snapshot(&self) -> HookSnapshot {
HookSnapshot {
delivered: self.delivered.load(Ordering::Relaxed),
retried: self.retried.load(Ordering::Relaxed),
ingress: self.ingress.load(Ordering::Relaxed),
overflow: self.overflow.load(Ordering::Relaxed),
rejected: self.rejected.load(Ordering::Relaxed),
exhausted: self.exhausted.load(Ordering::Relaxed),
shutdown: self.shutdown.load(Ordering::Relaxed),
outcome_unknown_shutdown: self.outcome_unknown_shutdown.load(Ordering::Relaxed),
filtered: self.filtered.load(Ordering::Relaxed),
ingress_depth: self.ingress_depth.load(Ordering::Relaxed),
ingress_capacity: 0,
queue_depth: self.queue_depth.load(Ordering::Relaxed),
queue_capacity: 0,
in_flight: self.in_flight.load(Ordering::Relaxed),
}
}
}
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct HookSnapshot {
pub delivered: u64,
pub retried: u64,
pub ingress: u64,
pub overflow: u64,
pub rejected: u64,
pub exhausted: u64,
pub shutdown: u64,
pub outcome_unknown_shutdown: u64,
pub filtered: u64,
pub ingress_depth: usize,
pub ingress_capacity: usize,
pub queue_depth: usize,
pub queue_capacity: usize,
pub in_flight: usize,
}
#[derive(Debug)]
struct Shared<E: Occurrence> {
config: HookConfig<E::Kind>,
ingress: mpsc::Sender<Envelope<E::Subject, E::Kind>>,
meters: HookMeters,
}
struct Dispatcher<E: Occurrence> {
shared: Arc<Shared<E>>,
ingress: mpsc::Receiver<Envelope<E::Subject, E::Kind>>,
}
#[derive(derive_more::Debug)]
pub struct Hooks<E: Occurrence> {
renderer: Renderer<E>,
shared: Arc<Vec<Arc<Shared<E>>>>,
#[debug(skip)]
observer: Arc<dyn HookObserver<E::Kind>>,
}
impl<E: Occurrence> Clone for Hooks<E> {
fn clone(&self) -> Self {
Self {
renderer: self.renderer.clone(),
shared: Arc::clone(&self.shared),
observer: Arc::clone(&self.observer),
}
}
}
impl<E: Occurrence> Hooks<E> {
pub fn deliver(&self, event: &E) {
if self.shared.is_empty() {
return;
}
let kind = event.kind();
if !self
.shared
.iter()
.any(|hook| hook.config.events.contains(&kind))
{
for hook in self.shared.iter() {
hook.meters.filtered.fetch_add(1, Ordering::Relaxed);
}
return;
}
let envelope = match self.renderer.render(event) {
Ok(envelope) => envelope,
Err(error) => {
self.observer.event_unrenderable(&error.to_string());
return;
}
};
for hook in self.shared.iter() {
if !hook.config.events.contains(&kind) {
hook.meters.filtered.fetch_add(1, Ordering::Relaxed);
continue;
}
hook.meters.ingress_depth.fetch_add(1, Ordering::Relaxed);
if hook.ingress.try_send(envelope.clone()).is_err() {
hook.meters.ingress_depth.fetch_sub(1, Ordering::Relaxed);
hook.meters.record_loss(Loss::Ingress);
}
}
}
pub fn snapshots(&self) -> Vec<(Arc<str>, HookSnapshot)> {
self.shared
.iter()
.map(|hook| {
let mut snapshot = hook.meters.snapshot();
snapshot.ingress_capacity = hook.config.queue_capacity;
snapshot.queue_capacity = hook.config.queue_capacity;
(Arc::clone(&hook.config.name), snapshot)
})
.collect()
}
}
pub struct Dispatchers<E: Occurrence> {
hooks: Vec<Dispatcher<E>>,
client: HttpClient,
drain_timeout: Duration,
observer: Arc<dyn HookObserver<E::Kind>>,
}
pub fn build<E: Occurrence>(
config: HooksConfig<E::Kind>,
client: HttpClient,
observer: Arc<dyn HookObserver<E::Kind>>,
) -> Result<(Hooks<E>, Dispatchers<E>), ConfigError> {
let mut names = BTreeSet::new();
for hook in &config.hooks {
hook.validate()?;
if !names.insert(hook.name.clone()) {
return Err(ConfigError {
hook: hook.name.clone(),
reason: "duplicate destination name",
});
}
}
let dispatchers: Vec<Dispatcher<E>> = config
.hooks
.into_iter()
.map(|hook| {
let (ingress, receiver) = mpsc::channel(hook.queue_capacity);
let shared = Arc::new(Shared {
ingress,
config: hook,
meters: HookMeters::default(),
});
Dispatcher {
shared,
ingress: receiver,
}
})
.collect();
let shared: Vec<Arc<Shared<E>>> = dispatchers
.iter()
.map(|dispatcher| Arc::clone(&dispatcher.shared))
.collect();
Ok((
Hooks {
renderer: Renderer::new(config.source, config.schema_version),
shared: Arc::new(shared),
observer: Arc::clone(&observer),
},
Dispatchers {
hooks: dispatchers,
client,
drain_timeout: config.drain_timeout,
observer,
},
))
}