#![no_std]
#![forbid(unsafe_code)]
#![doc = include_str!("../README.md")]
pub struct Dispatcher<M, W> {
matcher: M,
middleware: W,
}
impl<M, W> Dispatcher<M, W> {
pub const fn new(matcher: M, middleware: W) -> Self {
Self {
matcher,
middleware,
}
}
pub fn dispatch<Item, Input, Output, Error>(
&mut self,
table: &[Item],
input: &Input,
) -> Result<Output, DispatchError<Error>>
where
M: Matcher<Item, Input>,
W: Middleware<Item, Input, Output, Error>,
Item: Handler<Input = Input, Output = Output, Error = Error>,
{
dispatch(self, table, input)
}
pub const fn matcher(&self) -> &M {
&self.matcher
}
pub fn matcher_mut(&mut self) -> &mut M {
&mut self.matcher
}
pub const fn middleware(&self) -> &W {
&self.middleware
}
pub fn middleware_mut(&mut self) -> &mut W {
&mut self.middleware
}
pub fn into_parts(self) -> (M, W) {
(self.matcher, self.middleware)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DispatchError<E> {
NotFound,
Before(E),
Execute(E),
After(E),
}
pub trait Matcher<Item, Input> {
fn matches(&self, item: &Item, input: &Input) -> bool;
}
pub trait Handler {
type Input;
type Output;
type Error;
fn handle(&self, input: &Self::Input) -> Result<Self::Output, Self::Error>;
}
pub trait Middleware<Item, Input, Output, Error> {
fn before(&mut self, item: &Item, input: &Input) -> Result<(), Error>;
fn after(&mut self, item: &Item, input: &Input, output: &mut Output) -> Result<(), Error>;
}
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
pub struct NoopMiddleware;
impl<Item, Input, Output, Error> Middleware<Item, Input, Output, Error> for NoopMiddleware {
fn before(&mut self, _item: &Item, _input: &Input) -> Result<(), Error> {
Ok(())
}
fn after(&mut self, _item: &Item, _input: &Input, _output: &mut Output) -> Result<(), Error> {
Ok(())
}
}
pub fn dispatch<M, W, Item, Input, Output, Error>(
dispatcher: &mut Dispatcher<M, W>,
table: &[Item],
input: &Input,
) -> Result<Output, DispatchError<Error>>
where
M: Matcher<Item, Input>,
W: Middleware<Item, Input, Output, Error>,
Item: Handler<Input = Input, Output = Output, Error = Error>,
{
let item = table
.iter()
.find(|item| dispatcher.matcher.matches(item, input))
.ok_or(DispatchError::NotFound)?;
dispatcher
.middleware
.before(item, input)
.map_err(DispatchError::Before)?;
let mut output = item.handle(input).map_err(DispatchError::Execute)?;
dispatcher
.middleware
.after(item, input, &mut output)
.map_err(DispatchError::After)?;
Ok(output)
}
#[cfg(test)]
mod tests {
use core::cell::Cell;
use super::*;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TestError {
Before,
Execute,
After,
}
struct Rule {
key: u8,
value: u8,
fails: bool,
calls: Cell<u8>,
}
impl Handler for Rule {
type Input = u8;
type Output = u8;
type Error = TestError;
fn handle(&self, _input: &Self::Input) -> Result<Self::Output, Self::Error> {
self.calls.set(self.calls.get() + 1);
if self.fails {
Err(TestError::Execute)
} else {
Ok(self.value)
}
}
}
struct KeyMatcher;
impl Matcher<Rule, u8> for KeyMatcher {
fn matches(&self, item: &Rule, input: &u8) -> bool {
item.key == *input
}
}
#[derive(Default)]
struct TestMiddleware {
fail_before: bool,
fail_after: bool,
before_calls: u8,
after_calls: u8,
}
impl Middleware<Rule, u8, u8, TestError> for TestMiddleware {
fn before(&mut self, _item: &Rule, _input: &u8) -> Result<(), TestError> {
self.before_calls += 1;
if self.fail_before {
Err(TestError::Before)
} else {
Ok(())
}
}
fn after(&mut self, _item: &Rule, _input: &u8, output: &mut u8) -> Result<(), TestError> {
self.after_calls += 1;
if self.fail_after {
Err(TestError::After)
} else {
*output *= 2;
Ok(())
}
}
}
fn rule(key: u8, value: u8) -> Rule {
Rule {
key,
value,
fails: false,
calls: Cell::new(0),
}
}
#[test]
fn dispatches_to_the_first_matching_item() {
let table = [rule(1, 10), rule(1, 20)];
let mut dispatcher = Dispatcher::new(KeyMatcher, TestMiddleware::default());
let output = dispatcher.dispatch(&table, &1).unwrap();
assert_eq!(output, 20);
assert_eq!(table[0].calls.get(), 1);
assert_eq!(table[1].calls.get(), 0);
assert_eq!(dispatcher.middleware().before_calls, 1);
assert_eq!(dispatcher.middleware().after_calls, 1);
}
#[test]
fn returns_not_found_without_running_middleware() {
let table = [rule(1, 10)];
let mut dispatcher = Dispatcher::new(KeyMatcher, TestMiddleware::default());
let result = dispatcher.dispatch(&table, &2);
assert_eq!(result, Err(DispatchError::NotFound));
assert_eq!(dispatcher.middleware().before_calls, 0);
assert_eq!(dispatcher.middleware().after_calls, 0);
}
#[test]
fn stops_when_before_fails() {
let table = [rule(1, 10)];
let middleware = TestMiddleware {
fail_before: true,
..TestMiddleware::default()
};
let mut dispatcher = Dispatcher::new(KeyMatcher, middleware);
let result = dispatcher.dispatch(&table, &1);
assert_eq!(result, Err(DispatchError::Before(TestError::Before)));
assert_eq!(table[0].calls.get(), 0);
assert_eq!(dispatcher.middleware().after_calls, 0);
}
#[test]
fn skips_after_when_handler_fails() {
let mut failing_rule = rule(1, 10);
failing_rule.fails = true;
let table = [failing_rule];
let mut dispatcher = Dispatcher::new(KeyMatcher, TestMiddleware::default());
let result = dispatcher.dispatch(&table, &1);
assert_eq!(result, Err(DispatchError::Execute(TestError::Execute)));
assert_eq!(table[0].calls.get(), 1);
assert_eq!(dispatcher.middleware().after_calls, 0);
}
#[test]
fn reports_after_errors() {
let table = [rule(1, 10)];
let middleware = TestMiddleware {
fail_after: true,
..TestMiddleware::default()
};
let mut dispatcher = Dispatcher::new(KeyMatcher, middleware);
let result = dispatcher.dispatch(&table, &1);
assert_eq!(result, Err(DispatchError::After(TestError::After)));
assert_eq!(table[0].calls.get(), 1);
}
#[test]
fn noop_middleware_requires_no_configuration() {
let table = [rule(1, 10)];
let mut dispatcher = Dispatcher::new(KeyMatcher, NoopMiddleware);
let output = dispatcher.dispatch(&table, &1).unwrap();
assert_eq!(output, 10);
}
}