#![forbid(unsafe_code)]
#![warn(missing_docs)]
use std::error::Error as StdError;
use std::fmt;
use std::sync::Arc;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TraceStatus {
Passed,
Blocked,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct TraceEntry {
stage: String,
status: TraceStatus,
}
impl TraceEntry {
fn new(stage: String, status: TraceStatus) -> Self {
Self { stage, status }
}
pub fn stage(&self) -> &str {
&self.stage
}
pub const fn status(&self) -> TraceStatus {
self.status
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum StageOutcome<T, E> {
Pass(T),
Block {
value: T,
reason: E,
},
}
impl<T, E> StageOutcome<T, E> {
pub const fn pass(value: T) -> Self {
Self::Pass(value)
}
pub const fn block(value: T, reason: E) -> Self {
Self::Block { value, reason }
}
pub const fn is_pass(&self) -> bool {
matches!(self, Self::Pass(_))
}
pub fn into_value(self) -> T {
match self {
Self::Pass(value) | Self::Block { value, .. } => value,
}
}
}
type StageFn<T, E> = dyn Fn(T) -> StageOutcome<T, E> + Send + Sync + 'static;
pub struct Stage<T, E> {
name: String,
operation: Arc<StageFn<T, E>>,
}
impl<T, E> Clone for Stage<T, E> {
fn clone(&self) -> Self {
Self {
name: self.name.clone(),
operation: Arc::clone(&self.operation),
}
}
}
impl<T, E> fmt::Debug for Stage<T, E> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Stage").field("name", &self.name).finish()
}
}
impl<T: 'static, E: 'static> Stage<T, E> {
pub fn new(
name: impl Into<String>,
operation: impl Fn(T) -> StageOutcome<T, E> + Send + Sync + 'static,
) -> Result<Self, Error> {
let name = valid_name(name.into())?;
Ok(Self {
name,
operation: Arc::new(operation),
})
}
pub fn inspect(
name: impl Into<String>,
inspection: impl Fn(&T) -> Result<(), E> + Send + Sync + 'static,
) -> Result<Self, Error> {
Self::new(name, move |value| match inspection(&value) {
Ok(()) => StageOutcome::Pass(value),
Err(reason) => StageOutcome::Block { value, reason },
})
}
pub fn transform(
name: impl Into<String>,
transformation: impl Fn(T) -> T + Send + Sync + 'static,
) -> Result<Self, Error> {
Self::new(name, move |value| StageOutcome::Pass(transformation(value)))
}
pub fn name(&self) -> &str {
&self.name
}
pub fn apply(&self, value: T) -> StageOutcome<T, E> {
(self.operation)(value)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Passed<T> {
value: T,
trace: Vec<TraceEntry>,
}
impl<T> Passed<T> {
pub const fn value(&self) -> &T {
&self.value
}
pub fn trace(&self) -> &[TraceEntry] {
&self.trace
}
pub fn into_value(self) -> T {
self.value
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Blocked<T, E> {
value: T,
reason: E,
trace: Vec<TraceEntry>,
}
impl<T, E> Blocked<T, E> {
pub const fn value(&self) -> &T {
&self.value
}
pub const fn reason(&self) -> &E {
&self.reason
}
pub fn trace(&self) -> &[TraceEntry] {
&self.trace
}
pub fn blocked_at(&self) -> &str {
self.trace
.last()
.expect("blocked results always contain one trace entry")
.stage()
}
pub fn into_parts(self) -> (T, E) {
(self.value, self.reason)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PassResult<T, E> {
Passed(Passed<T>),
Blocked(Blocked<T, E>),
}
impl<T, E> PassResult<T, E> {
pub const fn is_passed(&self) -> bool {
matches!(self, Self::Passed(_))
}
pub fn trace(&self) -> &[TraceEntry] {
match self {
Self::Passed(value) => value.trace(),
Self::Blocked(value) => value.trace(),
}
}
pub fn into_value(self) -> T {
match self {
Self::Passed(value) => value.into_value(),
Self::Blocked(value) => value.into_parts().0,
}
}
}
#[derive(Debug, Clone)]
pub struct Passage<T, E> {
stages: Vec<Stage<T, E>>,
}
impl<T: 'static, E: 'static> Passage<T, E> {
pub const fn new() -> Self {
Self { stages: Vec::new() }
}
pub fn push(&mut self, stage: Stage<T, E>) -> Result<(), Error> {
if self
.stages
.iter()
.any(|existing| existing.name == stage.name)
{
return Err(Error::DuplicateStage(stage.name));
}
self.stages.push(stage);
Ok(())
}
pub fn with_stage(mut self, stage: Stage<T, E>) -> Result<Self, Error> {
self.push(stage)?;
Ok(self)
}
pub fn stages(&self) -> &[Stage<T, E>] {
&self.stages
}
pub fn run(&self, mut value: T) -> PassResult<T, E> {
let mut trace = Vec::with_capacity(self.stages.len());
for stage in &self.stages {
match stage.apply(value) {
StageOutcome::Pass(next) => {
trace.push(TraceEntry::new(stage.name.clone(), TraceStatus::Passed));
value = next;
}
StageOutcome::Block {
value: blocked,
reason,
} => {
trace.push(TraceEntry::new(stage.name.clone(), TraceStatus::Blocked));
return PassResult::Blocked(Blocked {
value: blocked,
reason,
trace,
});
}
}
}
PassResult::Passed(Passed { value, trace })
}
pub fn run_token(&self, token: PassToken<T>) -> PassResult<T, E> {
self.run(token.redeem())
}
}
impl<T: 'static, E: 'static> Default for Passage<T, E> {
fn default() -> Self {
Self::new()
}
}
#[derive(Debug, PartialEq, Eq, Hash)]
pub struct PassToken<T> {
value: T,
}
impl<T> PassToken<T> {
pub const fn issue(value: T) -> Self {
Self { value }
}
pub fn redeem(self) -> T {
self.value
}
pub fn pass_to<U>(self, handoff: impl FnOnce(T) -> U) -> U {
handoff(self.value)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Error {
EmptyStageName,
DuplicateStage(String),
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::EmptyStageName => f.write_str("stage name cannot be empty"),
Self::DuplicateStage(name) => write!(f, "duplicate stage name: {name}"),
}
}
}
impl StdError for Error {}
fn valid_name(name: String) -> Result<String, Error> {
if name.trim().is_empty() {
Err(Error::EmptyStageName)
} else {
Ok(name)
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicUsize, Ordering};
#[test]
fn value_passes_and_transforms_in_order() {
let passage = Passage::new()
.with_stage(Stage::<String, &str>::transform("trim", |v| v.trim().to_owned()).unwrap())
.unwrap()
.with_stage(Stage::transform("uppercase", |v: String| v.to_uppercase()).unwrap())
.unwrap();
let result = passage.run(" pass ".to_owned());
assert!(result.is_passed());
assert_eq!(result.trace().len(), 2);
assert_eq!(result.into_value(), "PASS");
}
#[test]
fn block_preserves_value_reason_and_trace() {
let passage = Passage::new()
.with_stage(
Stage::inspect("positive", |value: &i32| {
if *value > 0 {
Ok(())
} else {
Err("not positive")
}
})
.unwrap(),
)
.unwrap();
let result = passage.run(-7);
let PassResult::Blocked(blocked) = result else {
panic!("expected block");
};
assert_eq!(*blocked.value(), -7);
assert_eq!(*blocked.reason(), "not positive");
assert_eq!(blocked.blocked_at(), "positive");
assert_eq!(blocked.trace()[0].status(), TraceStatus::Blocked);
}
#[test]
fn stages_after_block_are_not_called() {
let calls = Arc::new(AtomicUsize::new(0));
let later_calls = Arc::clone(&calls);
let passage = Passage::new()
.with_stage(
Stage::new("block", |value| {
StageOutcome::<i32, &str>::block(value, "stop")
})
.unwrap(),
)
.unwrap()
.with_stage(
Stage::transform("later", move |value| {
later_calls.fetch_add(1, Ordering::SeqCst);
value + 1
})
.unwrap(),
)
.unwrap();
assert!(!passage.run(1).is_passed());
assert_eq!(calls.load(Ordering::SeqCst), 0);
}
#[test]
fn empty_passage_is_identity() {
let passage = Passage::<Vec<u8>, ()>::new();
let result = passage.run(vec![1, 2, 3]);
assert!(result.is_passed());
assert!(result.trace().is_empty());
assert_eq!(result.into_value(), [1, 2, 3]);
}
#[test]
fn duplicate_and_empty_stage_names_are_rejected() {
assert!(matches!(
Stage::<i32, ()>::transform(" ", |value| value),
Err(Error::EmptyStageName)
));
let mut passage = Passage::<i32, ()>::new();
passage
.push(Stage::transform("same", |value| value).unwrap())
.unwrap();
assert!(matches!(
passage.push(Stage::transform("same", |value| value).unwrap()),
Err(Error::DuplicateStage(_))
));
}
#[test]
fn custom_stage_can_transform_before_blocking() {
let stage = Stage::new("cap", |value: String| {
let value = value.to_uppercase();
if value.len() <= 4 {
StageOutcome::Pass(value)
} else {
StageOutcome::Block {
value,
reason: "too long",
}
}
})
.unwrap();
let passage = Passage::new().with_stage(stage).unwrap();
let PassResult::Blocked(blocked) = passage.run("passes".to_owned()) else {
panic!("expected block");
};
assert_eq!(blocked.value(), "PASSES");
}
#[test]
fn passage_and_stages_are_cloneable_for_shared_rules() {
let passage = Passage::new()
.with_stage(
Stage::<i32, &str>::inspect("even", |value| {
if value % 2 == 0 { Ok(()) } else { Err("odd") }
})
.unwrap(),
)
.unwrap();
let cloned = passage.clone();
let handle = std::thread::spawn(move || cloned.run(4).is_passed());
assert!(handle.join().unwrap());
assert!(!passage.run(3).is_passed());
}
#[test]
fn pass_token_is_consumed_by_pipeline_or_handoff() {
let passage = Passage::<String, ()>::new();
let result = passage.run_token(PassToken::issue("once".to_owned()));
assert_eq!(result.into_value(), "once");
let length = PassToken::issue("handoff").pass_to(str::len);
assert_eq!(length, 7);
}
}