pipeline-toolkit 0.2.0

A small toolkit for building linear, async processing pipelines out of independently testable steps that communicate through a shared, type-keyed Context.
Documentation
use crate::{AccessSpec, Context};

/// What a [`Step`] wants the [`Pipeline`](crate::Pipeline) to do next.
///
/// # Examples
///
/// ```
/// use pipeline_toolkit::Flow;
///
/// let flow: Flow<i32> = Flow::Done(42);
/// assert!(matches!(flow, Flow::Done(42)));
/// ```
pub enum Flow<Out> {
    /// Move on to the next step, unchanged.
    Continue,
    /// Stop the pipeline and produce this as its output.
    Done(Out),
}

/// The error type returned by [`Step::run`].
///
/// Wraps any `Send + Sync` [`std::error::Error`], so a step can propagate
/// whatever failure it produces (I/O, parsing, a domain error) through
/// [`Self::new`]'s `impl Into<Box<dyn Error>>` bound.
///
/// # Examples
///
/// ```
/// use pipeline_toolkit::StepError;
///
/// let err = StepError::new("failed to load config");
/// assert_eq!(err.to_string(), "failed to load config");
/// ```
#[derive(Debug, thiserror::Error)]
#[error("{source}")]
pub struct StepError {
    source: Box<dyn std::error::Error + Send + Sync>,
}

impl StepError {
    /// Wraps `source` as a [`StepError`].
    ///
    /// # Examples
    ///
    /// ```
    /// use pipeline_toolkit::StepError;
    ///
    /// #[derive(Debug, thiserror::Error)]
    /// #[error("connection refused")]
    /// struct ConnectError;
    ///
    /// let err = StepError::new(ConnectError);
    /// assert_eq!(err.to_string(), "connection refused");
    /// ```
    pub fn new(source: impl Into<Box<dyn std::error::Error + Send + Sync>>) -> Self {
        Self {
            source: source.into(),
        }
    }

    /// Consumes this error, returning the wrapped source downcast to `E` if
    /// it was one, or the original [`StepError`] back otherwise.
    ///
    /// Used internally by [`Branch`](crate::Branch) to smuggle a full
    /// [`PipelineError`](crate::PipelineError) across [`Step::run`]'s fixed
    /// `StepError` return type, so a nested arm's
    /// [`AccessViolation`](crate::AccessViolation)/`NoMatchingBranch`
    /// surfaces from [`Pipeline::run`](crate::Pipeline::run) as itself
    /// rather than wrapped in an outer [`PipelineError::Step`](crate::PipelineError::Step).
    pub(crate) fn downcast<E: std::error::Error + Send + Sync + 'static>(self) -> Result<E, Self> {
        match self.source.downcast::<E>() {
            Ok(boxed) => Ok(*boxed),
            Err(source) => Err(Self { source }),
        }
    }
}

/// A single unit of work in a [`Pipeline`](crate::Pipeline).
///
/// A step reads and writes typed values from the shared [`Context`] rather
/// than taking or returning them directly, which is what lets
/// [`PipelineBuilder`](crate::PipelineBuilder) wire arbitrary steps together
/// and validate the wiring without knowing their concrete types.
/// [`Self::access`] is the declaration
/// [`PipelineBuilder::build`](crate::PipelineBuilder::build) and [`Context`]
/// check that declaration against: a step's [`Self::run`] must not read,
/// write, or take a type it didn't declare, or
/// [`Pipeline::run`](crate::Pipeline::run) fails with
/// [`PipelineError::AccessViolation`](crate::PipelineError::AccessViolation).
///
/// # Examples
///
/// ```
/// use pipeline_toolkit::{AccessSpec, Context, Flow, Step, StepError};
///
/// struct Double;
///
/// #[async_trait::async_trait]
/// impl Step<i32> for Double {
///     fn name(&self) -> &str {
///         "double"
///     }
///
///     fn access(&self) -> AccessSpec {
///         AccessSpec::new().reads::<i32>()
///     }
///
///     async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
///         let value = *ctx.get::<i32>().expect("declared as read");
///         Ok(Flow::Done(value * 2))
///     }
/// }
/// ```
///
/// See the [crate-level example](crate) for wiring a step like this into a
/// running pipeline.
#[async_trait::async_trait]
pub trait Step<Out>: Send + Sync {
    /// Must consistently return the same value for the lifetime of the
    /// step. [`PipelineBuilder::build`](crate::PipelineBuilder::build) calls
    /// this once and reuses the result for the rest of the pipeline's life
    /// instead of calling it again at run time.
    fn name(&self) -> &str;

    /// Must consistently return an equivalent [`AccessSpec`] for the
    /// lifetime of the step, for the same reason as [`Self::name`].
    fn access(&self) -> AccessSpec;

    /// Performs this step's work against the shared context.
    ///
    /// Returning [`Flow::Continue`] hands off to the next step;
    /// [`Flow::Done`] stops the pipeline and produces that value as its
    /// output.
    ///
    /// # Errors
    ///
    /// Returns a [`StepError`] wrapping whatever domain-specific failure
    /// prevented this step from completing.
    async fn run(&self, ctx: &mut Context) -> Result<Flow<Out>, StepError>;
}

#[cfg(test)]
mod test {
    use std::error::Error;
    use std::fmt::Display;

    use super::*;
    use crate::test_support::block_on;

    #[derive(Debug)]
    struct DummyError(String);

    impl Display for DummyError {
        fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
            write!(f, "{}", self.0)
        }
    }

    impl Error for DummyError {}

    #[test]
    fn new_wraps_source_error_accessible_via_source_downcast() {
        let err = StepError::new(DummyError("boom".to_string()));
        let source = err.source().expect("source should be present");
        let dummy = source
            .downcast_ref::<DummyError>()
            .expect("source should downcast to DummyError");
        assert_eq!(dummy.0, "boom");
    }

    #[test]
    fn display_delegates_to_source_display() {
        let err = StepError::new(DummyError("boom".to_string()));
        assert_eq!(err.to_string(), "boom");
    }

    #[test]
    fn new_accepts_str_via_into() {
        let err = StepError::new("boom");
        assert_eq!(err.to_string(), "boom");
    }

    #[test]
    fn new_accepts_string_via_into() {
        let err = StepError::new(String::from("boom"));
        assert_eq!(err.to_string(), "boom");
    }

    #[test]
    fn implements_std_error_trait_with_some_source() {
        let err = StepError::new("boom");
        let as_dyn: &dyn Error = &err;
        assert!(as_dyn.source().is_some());
    }

    #[test]
    fn new_accepts_empty_string_message() {
        let err = StepError::new("");
        assert_eq!(err.to_string(), "");
    }

    struct Marker(i32);

    enum Outcome {
        Continue,
        Done(i32),
        Err(&'static str),
        InsertMarker(i32),
    }

    struct TestStep {
        name: &'static str,
        access: AccessSpec,
        outcome: Outcome,
    }

    #[async_trait::async_trait]
    impl Step<i32> for TestStep {
        fn name(&self) -> &str {
            self.name
        }

        fn access(&self) -> AccessSpec {
            self.access.clone()
        }

        async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
            match &self.outcome {
                Outcome::Continue => Ok(Flow::Continue),
                Outcome::Done(v) => Ok(Flow::Done(*v)),
                Outcome::Err(msg) => Err(StepError::new(*msg)),
                Outcome::InsertMarker(v) => {
                    ctx.insert(Marker(*v));
                    Ok(Flow::Continue)
                }
            }
        }
    }

    #[test]
    fn step_name_returns_configured_name() {
        let step = TestStep {
            name: "load",
            access: AccessSpec::new(),
            outcome: Outcome::Continue,
        };
        assert_eq!(step.name(), "load");
    }

    #[test]
    fn step_access_returns_configured_spec() {
        let step = TestStep {
            name: "load",
            access: AccessSpec::new().reads::<Marker>(),
            outcome: Outcome::Continue,
        };
        assert!(step.access().can_read(std::any::TypeId::of::<Marker>()));
    }

    #[test]
    fn step_run_returns_continue_variant() {
        let step = TestStep {
            name: "s",
            access: AccessSpec::new(),
            outcome: Outcome::Continue,
        };
        let mut ctx = Context::new();
        let result = block_on(step.run(&mut ctx));
        assert!(matches!(result, Ok(Flow::Continue)));
    }

    #[test]
    fn step_run_returns_done_variant_with_value() {
        let step = TestStep {
            name: "s",
            access: AccessSpec::new(),
            outcome: Outcome::Done(42),
        };
        let mut ctx = Context::new();
        let result = block_on(step.run(&mut ctx));
        assert!(matches!(result, Ok(Flow::Done(42))));
    }

    #[test]
    fn step_run_propagates_err_variant() {
        let step = TestStep {
            name: "s",
            access: AccessSpec::new(),
            outcome: Outcome::Err("boom"),
        };
        let mut ctx = Context::new();
        match block_on(step.run(&mut ctx)) {
            Err(err) => assert_eq!(err.to_string(), "boom"),
            Ok(_) => panic!("expected Err"),
        }
    }

    #[test]
    fn step_run_receives_context_and_can_read_write_it() {
        let step = TestStep {
            name: "s",
            access: AccessSpec::new(),
            outcome: Outcome::InsertMarker(7),
        };
        let mut ctx = Context::new();
        block_on(step.run(&mut ctx)).unwrap();
        assert_eq!(ctx.get::<Marker>().map(|m| m.0), Some(7));
    }

    #[test]
    fn step_trait_object_is_usable_as_dyn_step() {
        let step: Box<dyn Step<i32>> = Box::new(TestStep {
            name: "boxed",
            access: AccessSpec::new(),
            outcome: Outcome::Done(1),
        });
        assert_eq!(step.name(), "boxed");
        let mut ctx = Context::new();
        let result = block_on(step.run(&mut ctx));
        assert!(matches!(result, Ok(Flow::Done(1))));
    }
}