pipeline_toolkit/lib.rs
1//! A small toolkit for building linear, async processing pipelines out of
2//! independently testable steps that communicate through a shared,
3//! type-keyed [`Context`].
4//!
5//! Each [`Step`] declares, via [`Step::access`], exactly which types it
6//! reads, writes, or consumes from the [`Context`]. [`PipelineBuilder::build`]
7//! uses those declarations to catch wiring mistakes — a step reading a type
8//! nothing upstream produces — before the pipeline ever runs, and
9//! [`Context`] enforces them again at run time, so a step that reads or
10//! writes something it didn't declare fails fast with
11//! [`PipelineError::AccessViolation`] instead of silently drifting from its
12//! declared contract.
13//!
14//! # Examples
15//!
16//! ```
17//! use pipeline_toolkit::{AccessSpec, Context, Flow, Pipeline, Step, StepError};
18//!
19//! struct LoadName;
20//!
21//! #[async_trait::async_trait]
22//! impl Step<String> for LoadName {
23//! fn name(&self) -> &str {
24//! "load_name"
25//! }
26//!
27//! fn access(&self) -> AccessSpec {
28//! AccessSpec::new().writes::<String>()
29//! }
30//!
31//! async fn run(&self, ctx: &mut Context) -> Result<Flow<String>, StepError> {
32//! ctx.insert("Ada".to_string());
33//! Ok(Flow::Continue)
34//! }
35//! }
36//!
37//! struct Greet;
38//!
39//! #[async_trait::async_trait]
40//! impl Step<String> for Greet {
41//! fn name(&self) -> &str {
42//! "greet"
43//! }
44//!
45//! fn access(&self) -> AccessSpec {
46//! AccessSpec::new().reads::<String>()
47//! }
48//!
49//! async fn run(&self, ctx: &mut Context) -> Result<Flow<String>, StepError> {
50//! let name = ctx.get::<String>().expect("declared as read").clone();
51//! Ok(Flow::Done(format!("Hello, {name}!")))
52//! }
53//! }
54//!
55//! # fn block_on<F: std::future::Future>(fut: F) -> F::Output {
56//! # use std::task::{Context as TaskContext, Poll, Waker};
57//! # let mut fut = std::pin::pin!(fut);
58//! # let mut cx = TaskContext::from_waker(Waker::noop());
59//! # loop {
60//! # if let Poll::Ready(val) = fut.as_mut().poll(&mut cx) {
61//! # return val;
62//! # }
63//! # }
64//! # }
65//! #
66//! let pipeline = Pipeline::<(), String>::builder()
67//! .step(LoadName)
68//! .step(Greet)
69//! .build()?;
70//!
71//! let greeting = block_on(pipeline.run(()))?;
72//! assert_eq!(greeting, "Hello, Ada!");
73//! # Ok::<(), Box<dyn std::error::Error>>(())
74//! ```
75
76#![warn(missing_docs)]
77
78mod branch;
79mod context;
80mod iteration;
81mod pipeline;
82mod step;
83#[cfg(test)]
84mod test_support;
85
86pub use branch::{Arm, ArmBuilder, Branch, BranchBuilder};
87pub use context::{AccessKind, AccessSpec, AccessViolation, Context};
88pub use iteration::{Loop, LoopBuilder};
89pub use pipeline::{BuildError, Pipeline, PipelineBuilder, PipelineError};
90pub use step::{Flow, Step, StepError};