Skip to main content

pipeline_toolkit/
pipeline.rs

1#[cfg(test)]
2use crate::context::AccessKind;
3use crate::context::{AccessSpec, AccessViolation, Context};
4use crate::step::{Flow, Step, StepError};
5use std::any::TypeId;
6use std::collections::{HashMap, HashSet};
7
8/// Why [`PipelineBuilder::build`] rejected a pipeline.
9///
10/// See [`PipelineBuilder::build`] for a runnable example of the
11/// [`UnsatisfiedRead`](Self::UnsatisfiedRead) case.
12#[derive(Debug, thiserror::Error)]
13pub enum BuildError {
14    /// Two steps — including one placed by
15    /// [`PipelineBuilder::insert_before`]/[`PipelineBuilder::insert_after`] —
16    /// share the same [`Step::name`].
17    #[error("duplicate step name: `{name}`")]
18    DuplicateName {
19        /// The name shared by more than one step.
20        name: String,
21    },
22    /// An [`insert_before`](PipelineBuilder::insert_before)/
23    /// [`insert_after`](PipelineBuilder::insert_after) call named an anchor
24    /// that no step, whether added directly or by another pending insert,
25    /// ever resolves to.
26    #[error("anchor step not found: `{anchor}`")]
27    AnchorNotFound {
28        /// The anchor name that never matched a step.
29        anchor: String,
30    },
31    /// A step declares [`AccessSpec::reads`] for a type that no earlier
32    /// step (or the pipeline's input type) declares writing. Also used for
33    /// an [`Arm`](crate::Arm) step that reads a type an earlier step in the
34    /// same arm has already consumed (via [`AccessSpec::consumes`]) without
35    /// a later step rewriting it — that type is gone for the rest of the
36    /// arm regardless of what's available outside it, so this is caught
37    /// when the arm itself is built rather than deferred to the enclosing
38    /// pipeline.
39    #[error(
40        "step `{step}` reads `{entry}`, but no upstream step (nor the pipeline input) writes it"
41    )]
42    UnsatisfiedRead {
43        /// The step with the unsatisfied read.
44        step: String,
45        /// The [`type_name`](std::any::type_name) of the unwritten entry.
46        entry: &'static str,
47    },
48    /// A [`Branch`](crate::Branch) was built with no arms registered via
49    /// [`BranchBuilder::arm`](crate::BranchBuilder::arm). Such a branch
50    /// would fail every run with
51    /// [`PipelineError::NoMatchingBranch`](crate::PipelineError::NoMatchingBranch)
52    /// regardless of the key its condition function produces, so it's
53    /// rejected at build time instead.
54    #[error("branch `{step}` has no arms")]
55    EmptyBranch {
56        /// The name of the `Branch`.
57        step: String,
58    },
59    /// A [`Loop`](crate::Loop)'s body [`Arm`](crate::Arm) consumes a type via
60    /// [`AccessSpec::consumes`] without a later step in that same body
61    /// rewriting it. A `Loop` body runs more than once, so a type it
62    /// consumed and never rewrote would exist on the first iteration but be
63    /// gone from the second one onward — a failure mode
64    /// [`Arm::build`](crate::ArmBuilder::build)'s single-pass check can't
65    /// see, since it only reasons about one execution of the body.
66    #[error(
67        "loop `{step}` body consumes `{entry}` without rewriting it, which would fail every iteration after the first"
68    )]
69    UnrepeatableConsume {
70        /// The name of the `Loop`.
71        step: String,
72        /// The [`type_name`](std::any::type_name) of the consumed-but-never-rewritten entry.
73        entry: &'static str,
74    },
75}
76
77/// Why [`Pipeline::run`] failed.
78///
79/// See [`Pipeline::run`] for the full list of conditions that produce each
80/// variant.
81#[derive(Debug, thiserror::Error)]
82pub enum PipelineError {
83    /// A step's [`Step::run`] returned `Err`.
84    #[error("step `{step}` failed: {source}")]
85    Step {
86        /// The name of the step that failed.
87        step: String,
88        /// The error the step returned.
89        #[source]
90        source: StepError,
91    },
92    /// A step read, wrote, or consumed a [`Context`] entry its
93    /// [`AccessSpec`] didn't declare. See [`AccessViolation`] for which
94    /// step, which entry, and which kind of access.
95    #[error("step `{}` {} `{}` without declaring it", .0.step, .0.verb(), .0.entry)]
96    AccessViolation(AccessViolation),
97    /// Every step returned [`Flow::Continue`]; none produced a
98    /// [`Flow::Done`] output.
99    #[error("pipeline exhausted: no step produced an outcome")]
100    Exhausted,
101    /// A [`Branch`](crate::Branch) step's condition function produced a key
102    /// that no arm was registered for.
103    #[error("step `{step}` had no matching branch arm")]
104    NoMatchingBranch {
105        /// The name of the `Branch` step.
106        step: String,
107    },
108    /// A [`Loop`](crate::Loop) step ran its body `max_iterations` times
109    /// without its condition function ever returning `false`.
110    #[error("step `{step}` exceeded its max_iterations limit of {max_iterations}")]
111    MaxIterationsExceeded {
112        /// The name of the `Loop` step.
113        step: String,
114        /// The configured iteration limit that was reached.
115        max_iterations: u32,
116    },
117}
118
119/// Wraps a [`PipelineError`] so it can cross a [`Step::run`] boundary intact
120/// even though [`Step::run`] can only return a [`StepError`].
121///
122/// [`Branch`](crate::Branch) uses this both for its own "no arm matched"
123/// case and to re-wrap whatever [`PipelineError`] one of its arms produced
124/// (via [`run_steps`]), so that error surfaces from the outermost
125/// [`Pipeline::run`] as itself — an [`AccessViolation`] or
126/// [`NoMatchingBranch`](PipelineError::NoMatchingBranch) three arms deep
127/// stays that variant, rather than getting flattened into
128/// [`PipelineError::Step`] at every level it passes through.
129#[derive(Debug, thiserror::Error)]
130#[error("{0}")]
131pub(crate) struct NestedPipelineError(pub(crate) PipelineError);
132
133struct Pending<Out> {
134    anchor: String,
135    step: Box<dyn Step<Out>>,
136    after: bool,
137}
138
139/// Incrementally assembles a [`Pipeline`], returned by [`Pipeline::builder`].
140///
141/// `In` is the type steps can read as the pipeline input; `Out` is the type
142/// every [`Step`] in the pipeline shares as its own output type. Chain
143/// [`Self::step`], [`Self::insert_before`], and [`Self::insert_after`]
144/// calls, then finish with [`Self::build`].
145pub struct PipelineBuilder<In, Out> {
146    steps: Vec<Box<dyn Step<Out>>>,
147    pending: Vec<Pending<Out>>,
148    _in: std::marker::PhantomData<fn(In)>,
149}
150
151impl<In: Send + Sync + 'static, Out> PipelineBuilder<In, Out> {
152    /// Appends `step` to the end of the pipeline, after every step added so
153    /// far — though possibly before steps inserted later via
154    /// [`Self::insert_before`]/[`Self::insert_after`] anchored on one of
155    /// those earlier steps.
156    ///
157    /// # Examples
158    ///
159    /// ```
160    /// use pipeline_toolkit::Pipeline;
161    /// # use pipeline_toolkit::{AccessSpec, Context, Flow, Step, StepError};
162    /// #
163    /// # struct NoOp(&'static str);
164    /// # #[async_trait::async_trait]
165    /// # impl Step<()> for NoOp {
166    /// #     fn name(&self) -> &str { self.0 }
167    /// #     fn access(&self) -> AccessSpec { AccessSpec::new() }
168    /// #     async fn run(&self, _ctx: &mut Context) -> Result<Flow<()>, StepError> {
169    /// #         Ok(Flow::Continue)
170    /// #     }
171    /// # }
172    /// let pipeline = Pipeline::<(), ()>::builder()
173    ///     .step(NoOp("a"))
174    ///     .step(NoOp("b"))
175    ///     .build()?;
176    /// assert_eq!(pipeline.step_names(), vec!["a", "b"]);
177    /// # Ok::<(), Box<dyn std::error::Error>>(())
178    /// ```
179    pub fn step(mut self, step: impl Step<Out> + 'static) -> Self {
180        self.steps.push(Box::new(step));
181        self
182    }
183
184    /// Registers `step` to be placed immediately before the step named
185    /// `anchor`, once [`Self::build`] resolves anchors.
186    ///
187    /// `anchor` may itself be a step registered via [`Self::step`] or
188    /// another pending insert — resolution order doesn't matter, only that
189    /// some step eventually resolves to that name, or [`Self::build`]
190    /// returns [`BuildError::AnchorNotFound`]. Repeated calls with the same
191    /// anchor keep steps in registration order, immediately preceding the
192    /// anchor.
193    ///
194    /// # Examples
195    ///
196    /// ```
197    /// # use pipeline_toolkit::{AccessSpec, Context, Flow, Pipeline, Step, StepError};
198    /// #
199    /// # struct NoOp(&'static str);
200    /// # #[async_trait::async_trait]
201    /// # impl Step<()> for NoOp {
202    /// #     fn name(&self) -> &str { self.0 }
203    /// #     fn access(&self) -> AccessSpec { AccessSpec::new() }
204    /// #     async fn run(&self, _ctx: &mut Context) -> Result<Flow<()>, StepError> {
205    /// #         Ok(Flow::Continue)
206    /// #     }
207    /// # }
208    /// let pipeline = Pipeline::<(), ()>::builder()
209    ///     .step(NoOp("a"))
210    ///     .step(NoOp("b"))
211    ///     .insert_before("b", NoOp("x"))
212    ///     .build()?;
213    /// assert_eq!(pipeline.step_names(), vec!["a", "x", "b"]);
214    /// # Ok::<(), Box<dyn std::error::Error>>(())
215    /// ```
216    pub fn insert_before(
217        mut self,
218        anchor: impl Into<String>,
219        step: impl Step<Out> + 'static,
220    ) -> Self {
221        self.pending.push(Pending {
222            anchor: anchor.into(),
223            step: Box::new(step),
224            after: false,
225        });
226        self
227    }
228
229    /// Registers `step` to be placed immediately after the step named
230    /// `anchor`, once [`Self::build`] resolves anchors.
231    ///
232    /// Follows the same anchor-resolution and repeated-call ordering rules
233    /// as [`Self::insert_before`], but places `step` after the anchor
234    /// instead of before it.
235    ///
236    /// # Examples
237    ///
238    /// ```
239    /// # use pipeline_toolkit::{AccessSpec, Context, Flow, Pipeline, Step, StepError};
240    /// #
241    /// # struct NoOp(&'static str);
242    /// # #[async_trait::async_trait]
243    /// # impl Step<()> for NoOp {
244    /// #     fn name(&self) -> &str { self.0 }
245    /// #     fn access(&self) -> AccessSpec { AccessSpec::new() }
246    /// #     async fn run(&self, _ctx: &mut Context) -> Result<Flow<()>, StepError> {
247    /// #         Ok(Flow::Continue)
248    /// #     }
249    /// # }
250    /// let pipeline = Pipeline::<(), ()>::builder()
251    ///     .step(NoOp("a"))
252    ///     .step(NoOp("b"))
253    ///     .insert_after("a", NoOp("x"))
254    ///     .build()?;
255    /// assert_eq!(pipeline.step_names(), vec!["a", "x", "b"]);
256    /// # Ok::<(), Box<dyn std::error::Error>>(())
257    /// ```
258    pub fn insert_after(
259        mut self,
260        anchor: impl Into<String>,
261        step: impl Step<Out> + 'static,
262    ) -> Self {
263        self.pending.push(Pending {
264            anchor: anchor.into(),
265            step: Box::new(step),
266            after: true,
267        });
268        self
269    }
270
271    /// Validates that every declared read is satisfied by an earlier step's
272    /// (or the pipeline input's) declared write, and that a step declaring
273    /// [`AccessSpec::consumes`] is treated as removing the value for
274    /// downstream steps unless it is written again afterward.
275    ///
276    /// This check is static: it reasons about declared access, not what a
277    /// step's `run` actually does. A step that declares
278    /// [`AccessSpec::writes`] but never calls [`Context::insert`] still
279    /// passes validation; a downstream read of that type will simply
280    /// observe `None` at runtime, since [`Context`] accessors return
281    /// `Option` rather than assuming presence.
282    ///
283    /// # Errors
284    ///
285    /// - [`BuildError::AnchorNotFound`] if an
286    ///   [`insert_before`](Self::insert_before)/[`insert_after`](Self::insert_after)
287    ///   anchor never resolves to a step.
288    /// - [`BuildError::DuplicateName`] if two steps share a [`Step::name`].
289    /// - [`BuildError::UnsatisfiedRead`] if a step declares a read that no
290    ///   earlier step (or the pipeline input) declares writing.
291    ///
292    /// # Examples
293    ///
294    /// ```
295    /// use pipeline_toolkit::{AccessSpec, BuildError, Pipeline, Step};
296    /// # use pipeline_toolkit::{Context, Flow, StepError};
297    /// #
298    /// struct Marker;
299    ///
300    /// # struct ReadsMarker;
301    /// # #[async_trait::async_trait]
302    /// # impl Step<()> for ReadsMarker {
303    /// #     fn name(&self) -> &str { "reads_marker" }
304    /// #     fn access(&self) -> AccessSpec { AccessSpec::new().reads::<Marker>() }
305    /// #     async fn run(&self, _ctx: &mut Context) -> Result<Flow<()>, StepError> {
306    /// #         Ok(Flow::Continue)
307    /// #     }
308    /// # }
309    /// // `ReadsMarker` reads `Marker`, but nothing upstream writes it.
310    /// let result = Pipeline::<(), ()>::builder().step(ReadsMarker).build();
311    /// assert!(matches!(
312    ///     result,
313    ///     Err(BuildError::UnsatisfiedRead { step, .. }) if step == "reads_marker"
314    /// ));
315    /// ```
316    pub fn build(mut self) -> Result<Pipeline<In, Out>, BuildError> {
317        // Resolution is a fixed-point over multiple passes rather than a
318        // single left-to-right scan: a pending insert may anchor onto
319        // another pending insert that hasn't been placed into `self.steps`
320        // yet, and which pending resolves first must not depend on which
321        // `insert_before`/`insert_after` call happened to be registered
322        // first.
323        let mut pending = self.pending;
324        // Tracks how many steps have already been placed after a given
325        // anchor, so repeated insert_after("a", ...) calls queue up
326        // following the anchor in registration order — the same order
327        // repeated insert_before("a", ...) calls naturally produce
328        // immediately preceding the anchor (each one is inserted at the
329        // anchor's current position, pushing the anchor itself, and every
330        // step already placed before it, further along).
331        let mut after_offset: HashMap<String, usize> = HashMap::new();
332        while !pending.is_empty() {
333            let mut still_pending = Vec::with_capacity(pending.len());
334            let mut progressed = false;
335            for item in pending {
336                match self.steps.iter().position(|s| s.name() == item.anchor) {
337                    Some(index) => {
338                        progressed = true;
339                        if item.after {
340                            let offset = after_offset.entry(item.anchor).or_insert(0);
341                            *offset += 1;
342                            self.steps.insert(index + *offset, item.step);
343                        } else {
344                            self.steps.insert(index, item.step);
345                        }
346                    }
347                    None => still_pending.push(item),
348                }
349            }
350            if !progressed {
351                return Err(BuildError::AnchorNotFound {
352                    anchor: still_pending[0].anchor.clone(),
353                });
354            }
355            pending = still_pending;
356        }
357
358        // Call each step's name() and access() exactly once here and cache
359        // the result in the compiled Pipeline. Steps are trait objects with
360        // no purity contract on these methods; if run() called them again
361        // instead of reusing what build() validated, a step that returned a
362        // different name or AccessSpec on a later call could make run()
363        // enforce something other than what build() actually checked.
364        let mut names = HashSet::new();
365        let mut compiled = Vec::with_capacity(self.steps.len());
366        for step in self.steps {
367            let name = step.name().to_string();
368            if !names.insert(name.clone()) {
369                return Err(BuildError::DuplicateName { name });
370            }
371            let access = step.access();
372            compiled.push(CompiledStep { name, access, step });
373        }
374
375        let mut written: HashSet<TypeId> = HashSet::from([TypeId::of::<In>()]);
376        for compiled_step in &compiled {
377            // AccessSpec stores reads in a HashMap, whose iteration order is
378            // randomized per-process; if a step has multiple unsatisfied
379            // reads, picking the first one seen here would make the
380            // reported entry vary run to run for identical input. Collect
381            // every unsatisfied read and report the one that sorts first by
382            // type name, which is stable regardless of HashMap iteration
383            // order.
384            let mut unsatisfied: Vec<(TypeId, &'static str)> = compiled_step
385                .access
386                .read_entries()
387                .filter(|(id, _)| !written.contains(id))
388                .collect();
389            unsatisfied.sort_unstable_by_key(|(_, entry)| *entry);
390            if let Some((_, entry)) = unsatisfied.into_iter().next() {
391                return Err(BuildError::UnsatisfiedRead {
392                    step: compiled_step.name.clone(),
393                    entry,
394                });
395            }
396            written.extend(compiled_step.access.write_entries().map(|(id, _)| id));
397            for (id, _) in compiled_step.access.consume_entries() {
398                written.remove(&id);
399            }
400        }
401
402        Ok(Pipeline {
403            steps: compiled,
404            _in: std::marker::PhantomData,
405        })
406    }
407}
408
409/// Prefixes whatever step name is embedded in `err` with `qualifier`.
410///
411/// An error from deep inside a [`Branch`](crate::Branch) arm or a
412/// [`Loop`](crate::Loop) body would otherwise carry only that step's own
413/// bare name — meaningful on its own, but ambiguous once more than one arm,
414/// loop body, or enclosing pipeline can contain a step of the same name.
415/// Qualifying it with the branch/loop it came from keeps
416/// [`PipelineError::Step`]/[`AccessViolation`]/[`PipelineError::NoMatchingBranch`]/
417/// [`PipelineError::MaxIterationsExceeded`] messages locally identifiable at
418/// every level they pass through, without requiring step names to be
419/// globally unique across arms, loop bodies, and pipelines.
420pub(crate) fn qualify_step_name(qualifier: &str, err: PipelineError) -> PipelineError {
421    match err {
422        PipelineError::Step { step, source } => PipelineError::Step {
423            step: format!("{qualifier}/{step}"),
424            source,
425        },
426        PipelineError::AccessViolation(violation) => {
427            PipelineError::AccessViolation(AccessViolation {
428                step: format!("{qualifier}/{}", violation.step),
429                ..violation
430            })
431        }
432        PipelineError::NoMatchingBranch { step } => PipelineError::NoMatchingBranch {
433            step: format!("{qualifier}/{step}"),
434        },
435        PipelineError::MaxIterationsExceeded {
436            step,
437            max_iterations,
438        } => PipelineError::MaxIterationsExceeded {
439            step: format!("{qualifier}/{step}"),
440            max_iterations,
441        },
442        // run_steps only ever returns this from Pipeline::run reaching the
443        // end of a top-level pipeline with every step Continue-ing — never
444        // from the arm/body dispatch this function's callers (Branch::run,
445        // Loop::run) wrap, which report the equivalent "every step
446        // continued" outcome as Ok(Flow::Continue) instead (see
447        // run_steps's doc comment). Exhausted also carries no step name to
448        // qualify in the first place, so silently passing it through here
449        // would be misleading.
450        PipelineError::Exhausted => unreachable!(
451            "Branch's arm dispatch and Loop's body dispatch never produce PipelineError::Exhausted, only Pipeline::run does"
452        ),
453    }
454}
455
456pub(crate) struct CompiledStep<Out> {
457    pub(crate) name: String,
458    pub(crate) access: AccessSpec,
459    pub(crate) step: Box<dyn Step<Out>>,
460}
461
462/// Runs `steps` against `ctx` in order, starting from whatever step is
463/// first, until one returns [`Flow::Done`], returns `Err`, or every step has
464/// run and returned [`Flow::Continue`].
465///
466/// This is the shared execution loop behind both [`Pipeline::run`] and
467/// [`Branch`](crate::Branch)'s arm dispatch. The two differ only in how they
468/// treat exhausting `steps` without a [`Flow::Done`]: [`Pipeline::run`]
469/// treats that as [`PipelineError::Exhausted`], while an arm treats it as a
470/// normal [`Flow::Continue`] back to the branch (see
471/// [`Branch`](crate::Branch) for why) — so this function reports that case
472/// as `Ok(Flow::Continue)` and lets each caller decide.
473///
474/// A step's `Err` is normally wrapped as [`PipelineError::Step`], but a
475/// [`StepError`] wrapping a [`NestedPipelineError`] (as
476/// [`Branch`](crate::Branch) produces) is unwrapped and returned as-is
477/// instead, so a nested arm's own [`PipelineError`] variant propagates
478/// unchanged through every enclosing branch/pipeline.
479pub(crate) async fn run_steps<Out>(
480    steps: &[CompiledStep<Out>],
481    ctx: &mut Context,
482) -> Result<Flow<Out>, PipelineError> {
483    for compiled_step in steps {
484        ctx.set_active(compiled_step.name.clone(), compiled_step.access.clone());
485        let result = compiled_step.step.run(ctx).await;
486        ctx.clear_active();
487        if let Some(v) = ctx.take_violation() {
488            return Err(PipelineError::AccessViolation(v));
489        }
490        match result {
491            Ok(Flow::Continue) => continue,
492            Ok(Flow::Done(out)) => return Ok(Flow::Done(out)),
493            Err(source) => {
494                return match source.downcast::<NestedPipelineError>() {
495                    Ok(NestedPipelineError(err)) => Err(err),
496                    Err(source) => Err(PipelineError::Step {
497                        step: compiled_step.name.clone(),
498                        source,
499                    }),
500                };
501            }
502        }
503    }
504    Ok(Flow::Continue)
505}
506
507/// A validated, immutable sequence of [`Step`]s, built via [`Self::builder`].
508///
509/// Every step's [`name`](Step::name) and [`access`](Step::access) were
510/// already read once during [`PipelineBuilder::build`] and are reused for
511/// the pipeline's lifetime, so [`Self::run`] never calls them again.
512///
513/// See the [crate-level example](crate) for building and running one.
514pub struct Pipeline<In, Out> {
515    steps: Vec<CompiledStep<Out>>,
516    _in: std::marker::PhantomData<fn(In)>,
517}
518
519impl<In, Out> std::fmt::Debug for Pipeline<In, Out> {
520    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
521        f.debug_struct("Pipeline")
522            .field(
523                "steps",
524                &self
525                    .steps
526                    .iter()
527                    .map(|s| s.name.as_str())
528                    .collect::<Vec<_>>(),
529            )
530            .finish()
531    }
532}
533
534impl<In: Send + Sync + 'static, Out> Pipeline<In, Out> {
535    /// Starts building a pipeline whose steps take `In` as input and share
536    /// `Out` as their output type.
537    ///
538    /// # Examples
539    ///
540    /// ```
541    /// use pipeline_toolkit::Pipeline;
542    ///
543    /// let pipeline = Pipeline::<(), i32>::builder().build()?;
544    /// assert!(pipeline.step_names().is_empty());
545    /// # Ok::<(), Box<dyn std::error::Error>>(())
546    /// ```
547    pub fn builder() -> PipelineBuilder<In, Out> {
548        PipelineBuilder {
549            steps: Vec::new(),
550            pending: Vec::new(),
551            _in: std::marker::PhantomData,
552        }
553    }
554
555    /// Runs the pipeline against `input`, executing steps in order until one
556    /// returns [`Flow::Done`].
557    ///
558    /// `input` is inserted into a fresh [`Context`] as the pipeline's `In`
559    /// value before the first step runs.
560    ///
561    /// # Errors
562    ///
563    /// - [`PipelineError::Step`] if a step's [`run`](Step::run) returns
564    ///   `Err`.
565    /// - [`PipelineError::AccessViolation`] if a step reads, writes, or
566    ///   takes a [`Context`] entry its [`AccessSpec`] didn't declare.
567    /// - [`PipelineError::Exhausted`] if every step returns
568    ///   [`Flow::Continue`] and none produces an output.
569    ///
570    /// See the [crate-level example](crate) for a full pipeline that builds
571    /// and runs successfully.
572    pub async fn run(&self, input: In) -> Result<Out, PipelineError> {
573        let mut ctx = Context::new();
574        ctx.insert(input);
575        match run_steps(&self.steps, &mut ctx).await? {
576            Flow::Done(out) => Ok(out),
577            Flow::Continue => Err(PipelineError::Exhausted),
578        }
579    }
580
581    /// Lists the resolved step names in execution order, mainly for
582    /// diagnostics and tests.
583    ///
584    /// # Examples
585    ///
586    /// ```
587    /// use pipeline_toolkit::Pipeline;
588    ///
589    /// let pipeline = Pipeline::<(), ()>::builder().build()?;
590    /// assert!(pipeline.step_names().is_empty());
591    /// # Ok::<(), Box<dyn std::error::Error>>(())
592    /// ```
593    pub fn step_names(&self) -> Vec<&str> {
594        self.steps.iter().map(|s| s.name.as_str()).collect()
595    }
596}
597
598#[cfg(test)]
599mod test {
600    use std::error::Error;
601    use std::sync::Arc;
602    use std::sync::atomic::{AtomicUsize, Ordering};
603
604    use super::*;
605    use crate::test_support::block_on;
606
607    #[test]
608    fn display_formats_duplicate_name() {
609        let err = BuildError::DuplicateName {
610            name: "load".to_string(),
611        };
612        assert_eq!(err.to_string(), "duplicate step name: `load`");
613    }
614
615    #[test]
616    fn display_formats_anchor_not_found() {
617        let err = BuildError::AnchorNotFound {
618            anchor: "load".to_string(),
619        };
620        assert_eq!(err.to_string(), "anchor step not found: `load`");
621    }
622
623    #[test]
624    fn display_formats_unsatisfied_read() {
625        let err = BuildError::UnsatisfiedRead {
626            step: "load".to_string(),
627            entry: "Marker",
628        };
629        assert_eq!(
630            err.to_string(),
631            "step `load` reads `Marker`, but no upstream step (nor the pipeline input) writes it"
632        );
633    }
634
635    #[test]
636    fn display_formats_empty_branch() {
637        let err = BuildError::EmptyBranch {
638            step: "route".to_string(),
639        };
640        assert_eq!(err.to_string(), "branch `route` has no arms");
641    }
642
643    #[test]
644    fn implements_std_error_trait_with_none_source() {
645        let err = BuildError::DuplicateName {
646            name: "load".to_string(),
647        };
648        let as_dyn: &dyn Error = &err;
649        assert!(as_dyn.source().is_none());
650    }
651
652    #[test]
653    fn display_formats_step_variant() {
654        let err = PipelineError::Step {
655            step: "load".to_string(),
656            source: StepError::new("boom"),
657        };
658        assert_eq!(err.to_string(), "step `load` failed: boom");
659    }
660
661    #[test]
662    fn display_formats_access_violation_variant_for_read() {
663        let err = PipelineError::AccessViolation(AccessViolation {
664            step: "load".to_string(),
665            entry: "Marker",
666            kind: AccessKind::Read,
667        });
668        assert_eq!(
669            err.to_string(),
670            "step `load` read `Marker` without declaring it"
671        );
672    }
673
674    #[test]
675    fn display_formats_access_violation_variant_for_write() {
676        let err = PipelineError::AccessViolation(AccessViolation {
677            step: "load".to_string(),
678            entry: "Marker",
679            kind: AccessKind::Write,
680        });
681        assert_eq!(
682            err.to_string(),
683            "step `load` wrote `Marker` without declaring it"
684        );
685    }
686
687    #[test]
688    fn display_formats_exhausted_variant() {
689        let err = PipelineError::Exhausted;
690        assert_eq!(
691            err.to_string(),
692            "pipeline exhausted: no step produced an outcome"
693        );
694    }
695
696    #[test]
697    fn display_formats_no_matching_branch_variant() {
698        let err = PipelineError::NoMatchingBranch {
699            step: "route".to_string(),
700        };
701        assert_eq!(err.to_string(), "step `route` had no matching branch arm");
702    }
703
704    #[test]
705    fn source_returns_some_for_step_variant() {
706        let err = PipelineError::Step {
707            step: "load".to_string(),
708            source: StepError::new("boom"),
709        };
710        let source = err.source().expect("source should be present");
711        assert_eq!(source.to_string(), "boom");
712    }
713
714    #[test]
715    fn source_returns_none_for_access_violation_variant() {
716        let err = PipelineError::AccessViolation(AccessViolation {
717            step: "load".to_string(),
718            entry: "Marker",
719            kind: AccessKind::Read,
720        });
721        assert!(err.source().is_none());
722    }
723
724    #[test]
725    fn source_returns_none_for_exhausted_variant() {
726        let err = PipelineError::Exhausted;
727        assert!(err.source().is_none());
728    }
729
730    struct Input(i32);
731    struct Marker(i32);
732
733    enum Action {
734        Continue,
735        Done(i32),
736        Fail(&'static str),
737        WriteMarker(i32),
738        WriteMarkerThenFail(i32, &'static str),
739        ReadMarkerAsDone,
740        ReadInputAsDone,
741    }
742
743    struct ScriptedStep {
744        name: &'static str,
745        access: AccessSpec,
746        action: Action,
747    }
748
749    #[async_trait::async_trait]
750    impl Step<i32> for ScriptedStep {
751        fn name(&self) -> &str {
752            self.name
753        }
754
755        fn access(&self) -> AccessSpec {
756            self.access.clone()
757        }
758
759        async fn run(&self, ctx: &mut Context) -> Result<Flow<i32>, StepError> {
760            match &self.action {
761                Action::Continue => Ok(Flow::Continue),
762                Action::Done(v) => Ok(Flow::Done(*v)),
763                Action::Fail(msg) => Err(StepError::new(*msg)),
764                Action::WriteMarker(v) => {
765                    ctx.insert(Marker(*v));
766                    Ok(Flow::Continue)
767                }
768                Action::WriteMarkerThenFail(v, msg) => {
769                    ctx.insert(Marker(*v));
770                    Err(StepError::new(*msg))
771                }
772                Action::ReadMarkerAsDone => {
773                    let doubled = ctx.get::<Marker>().map(|m| m.0 * 2).unwrap_or(-1);
774                    Ok(Flow::Done(doubled))
775                }
776                Action::ReadInputAsDone => {
777                    let v = ctx.get::<Input>().map(|i| i.0).unwrap_or(-1);
778                    Ok(Flow::Done(v))
779                }
780            }
781        }
782    }
783
784    struct CountingStep {
785        access_calls: Arc<AtomicUsize>,
786        name_calls: Arc<AtomicUsize>,
787    }
788
789    #[async_trait::async_trait]
790    impl Step<i32> for CountingStep {
791        fn name(&self) -> &str {
792            self.name_calls.fetch_add(1, Ordering::SeqCst);
793            "counting"
794        }
795
796        fn access(&self) -> AccessSpec {
797            self.access_calls.fetch_add(1, Ordering::SeqCst);
798            AccessSpec::new()
799        }
800
801        async fn run(&self, _ctx: &mut Context) -> Result<Flow<i32>, StepError> {
802            Ok(Flow::Done(1))
803        }
804    }
805
806    fn step(name: &'static str, access: AccessSpec) -> ScriptedStep {
807        ScriptedStep {
808            name,
809            access,
810            action: Action::Continue,
811        }
812    }
813
814    fn scripted(name: &'static str, access: AccessSpec, action: Action) -> ScriptedStep {
815        ScriptedStep {
816            name,
817            access,
818            action,
819        }
820    }
821
822    #[test]
823    fn build_preserves_step_call_order_when_no_pending_insertions() {
824        let pipeline = Pipeline::<Input, i32>::builder()
825            .step(step("a", AccessSpec::new()))
826            .step(step("b", AccessSpec::new()))
827            .step(step("c", AccessSpec::new()))
828            .build()
829            .unwrap();
830        assert_eq!(pipeline.step_names(), vec!["a", "b", "c"]);
831    }
832
833    #[test]
834    fn insert_before_places_step_immediately_before_anchor() {
835        let pipeline = Pipeline::<Input, i32>::builder()
836            .step(step("a", AccessSpec::new()))
837            .step(step("b", AccessSpec::new()))
838            .insert_before("b", step("x", AccessSpec::new()))
839            .build()
840            .unwrap();
841        assert_eq!(pipeline.step_names(), vec!["a", "x", "b"]);
842    }
843
844    #[test]
845    fn insert_after_places_step_immediately_after_anchor() {
846        let pipeline = Pipeline::<Input, i32>::builder()
847            .step(step("a", AccessSpec::new()))
848            .step(step("b", AccessSpec::new()))
849            .insert_after("a", step("x", AccessSpec::new()))
850            .build()
851            .unwrap();
852        assert_eq!(pipeline.step_names(), vec!["a", "x", "b"]);
853    }
854
855    #[test]
856    fn repeated_insert_before_on_the_same_anchor_preserves_registration_order() {
857        let pipeline = Pipeline::<Input, i32>::builder()
858            .step(step("a", AccessSpec::new()))
859            .insert_before("a", step("x", AccessSpec::new()))
860            .insert_before("a", step("y", AccessSpec::new()))
861            .build()
862            .unwrap();
863        assert_eq!(pipeline.step_names(), vec!["x", "y", "a"]);
864    }
865
866    #[test]
867    fn repeated_insert_after_on_the_same_anchor_preserves_registration_order() {
868        let pipeline = Pipeline::<Input, i32>::builder()
869            .step(step("a", AccessSpec::new()))
870            .insert_after("a", step("x", AccessSpec::new()))
871            .insert_after("a", step("y", AccessSpec::new()))
872            .build()
873            .unwrap();
874        assert_eq!(pipeline.step_names(), vec!["a", "x", "y"]);
875    }
876
877    #[test]
878    fn pending_insert_can_anchor_onto_a_previously_resolved_pending_step() {
879        let pipeline = Pipeline::<Input, i32>::builder()
880            .step(step("a", AccessSpec::new()))
881            .insert_after("a", step("b", AccessSpec::new()))
882            .insert_before("b", step("c", AccessSpec::new()))
883            .build()
884            .unwrap();
885        assert_eq!(pipeline.step_names(), vec!["a", "c", "b"]);
886    }
887
888    #[test]
889    fn pending_insert_resolution_does_not_depend_on_registration_order() {
890        let pipeline = Pipeline::<Input, i32>::builder()
891            .step(step("a", AccessSpec::new()))
892            .insert_before("b", step("c", AccessSpec::new()))
893            .insert_after("a", step("b", AccessSpec::new()))
894            .build()
895            .unwrap();
896        assert_eq!(pipeline.step_names(), vec!["a", "c", "b"]);
897    }
898
899    #[test]
900    fn builder_creates_pipeline_with_zero_steps_when_none_added() {
901        let pipeline = Pipeline::<Input, i32>::builder().build().unwrap();
902        assert!(pipeline.step_names().is_empty());
903    }
904
905    #[test]
906    fn build_returns_anchor_not_found_when_insert_before_anchor_missing() {
907        let result = Pipeline::<Input, i32>::builder()
908            .insert_before("missing", step("x", AccessSpec::new()))
909            .build();
910        assert!(
911            matches!(result, Err(BuildError::AnchorNotFound { anchor }) if anchor == "missing")
912        );
913    }
914
915    #[test]
916    fn build_returns_anchor_not_found_when_insert_after_anchor_missing() {
917        let result = Pipeline::<Input, i32>::builder()
918            .insert_after("missing", step("x", AccessSpec::new()))
919            .build();
920        assert!(
921            matches!(result, Err(BuildError::AnchorNotFound { anchor }) if anchor == "missing")
922        );
923    }
924
925    #[test]
926    fn build_returns_duplicate_name_when_two_added_steps_share_a_name() {
927        let result = Pipeline::<Input, i32>::builder()
928            .step(step("a", AccessSpec::new()))
929            .step(step("a", AccessSpec::new()))
930            .build();
931        assert!(matches!(result, Err(BuildError::DuplicateName { name }) if name == "a"));
932    }
933
934    #[test]
935    fn build_returns_duplicate_name_when_a_pending_insert_introduces_a_duplicate() {
936        let result = Pipeline::<Input, i32>::builder()
937            .step(step("a", AccessSpec::new()))
938            .step(step("b", AccessSpec::new()))
939            .insert_after("a", step("b", AccessSpec::new()))
940            .build();
941        assert!(matches!(result, Err(BuildError::DuplicateName { name }) if name == "b"));
942    }
943
944    #[test]
945    fn build_succeeds_when_step_reads_the_pipeline_input_type() {
946        let result = Pipeline::<Input, i32>::builder()
947            .step(step("a", AccessSpec::new().reads::<Input>()))
948            .build();
949        assert!(result.is_ok());
950    }
951
952    #[test]
953    fn build_succeeds_when_a_read_is_satisfied_by_an_earlier_steps_write() {
954        let result = Pipeline::<Input, i32>::builder()
955            .step(step("a", AccessSpec::new().writes::<Marker>()))
956            .step(step("b", AccessSpec::new().reads::<Marker>()))
957            .build();
958        assert!(result.is_ok());
959    }
960
961    #[test]
962    fn build_succeeds_when_step_declares_no_access_requirements() {
963        let result = Pipeline::<Input, i32>::builder()
964            .step(step("a", AccessSpec::new()))
965            .build();
966        assert!(result.is_ok());
967    }
968
969    #[test]
970    fn build_returns_unsatisfied_read_when_nothing_writes_the_entry() {
971        let result = Pipeline::<Input, i32>::builder()
972            .step(step("a", AccessSpec::new().reads::<Marker>()))
973            .build();
974        assert!(matches!(
975            result,
976            Err(BuildError::UnsatisfiedRead { step, .. }) if step == "a"
977        ));
978    }
979
980    #[test]
981    fn build_returns_unsatisfied_read_when_a_step_consumes_the_entry_before_a_later_reader() {
982        let result = Pipeline::<Input, i32>::builder()
983            .step(step("a", AccessSpec::new().writes::<Marker>()))
984            .step(step("b", AccessSpec::new().consumes::<Marker>()))
985            .step(step("c", AccessSpec::new().reads::<Marker>()))
986            .build();
987        assert!(matches!(
988            result,
989            Err(BuildError::UnsatisfiedRead { step, .. }) if step == "c"
990        ));
991    }
992
993    #[test]
994    fn build_succeeds_when_a_later_step_rewrites_a_consumed_entry() {
995        let result = Pipeline::<Input, i32>::builder()
996            .step(step("a", AccessSpec::new().writes::<Marker>()))
997            .step(step("b", AccessSpec::new().consumes::<Marker>()))
998            .step(step("c", AccessSpec::new().writes::<Marker>()))
999            .step(step("d", AccessSpec::new().reads::<Marker>()))
1000            .build();
1001        assert!(result.is_ok());
1002    }
1003
1004    #[test]
1005    fn build_succeeds_when_reads_writes_is_used_for_in_place_mutation() {
1006        let result = Pipeline::<Input, i32>::builder()
1007            .step(step("a", AccessSpec::new().writes::<Marker>()))
1008            .step(step("b", AccessSpec::new().reads_writes::<Marker>()))
1009            .step(step("c", AccessSpec::new().reads::<Marker>()))
1010            .build();
1011        assert!(result.is_ok());
1012    }
1013
1014    #[test]
1015    fn build_reports_deterministic_entry_when_step_has_multiple_unsatisfied_reads() {
1016        // Marker and a second unwritten type both go unsatisfied; the
1017        // reported entry must consistently be the one that sorts first by
1018        // type name, regardless of HashMap iteration order.
1019        struct OtherMarker;
1020        let access = AccessSpec::new().reads::<Marker>().reads::<OtherMarker>();
1021        let expected = [
1022            std::any::type_name::<Marker>(),
1023            std::any::type_name::<OtherMarker>(),
1024        ]
1025        .into_iter()
1026        .min()
1027        .unwrap();
1028        for _ in 0..20 {
1029            let result = Pipeline::<Input, i32>::builder()
1030                .step(step("a", access.clone()))
1031                .build();
1032            assert!(matches!(
1033                result,
1034                Err(BuildError::UnsatisfiedRead { entry, .. }) if entry == expected
1035            ));
1036        }
1037    }
1038
1039    #[test]
1040    fn build_returns_unsatisfied_read_when_only_a_later_step_writes_the_entry() {
1041        let result = Pipeline::<Input, i32>::builder()
1042            .step(step("a", AccessSpec::new().reads::<Marker>()))
1043            .step(step("b", AccessSpec::new().writes::<Marker>()))
1044            .build();
1045        assert!(matches!(
1046            result,
1047            Err(BuildError::UnsatisfiedRead { step, .. }) if step == "a"
1048        ));
1049    }
1050
1051    #[test]
1052    fn run_returns_done_value_from_a_single_step() {
1053        let pipeline = Pipeline::<Input, i32>::builder()
1054            .step(scripted("a", AccessSpec::new(), Action::Done(42)))
1055            .build()
1056            .unwrap();
1057        let result = block_on(pipeline.run(Input(0)));
1058        assert!(matches!(result, Ok(42)));
1059    }
1060
1061    #[test]
1062    fn run_continues_to_next_step_when_flow_is_continue() {
1063        let pipeline = Pipeline::<Input, i32>::builder()
1064            .step(scripted("a", AccessSpec::new(), Action::Continue))
1065            .step(scripted("b", AccessSpec::new(), Action::Done(7)))
1066            .build()
1067            .unwrap();
1068        let result = block_on(pipeline.run(Input(0)));
1069        assert!(matches!(result, Ok(7)));
1070    }
1071
1072    #[test]
1073    fn run_provides_pipeline_input_via_context() {
1074        let pipeline = Pipeline::<Input, i32>::builder()
1075            .step(scripted(
1076                "a",
1077                AccessSpec::new().reads::<Input>(),
1078                Action::ReadInputAsDone,
1079            ))
1080            .build()
1081            .unwrap();
1082        let result = block_on(pipeline.run(Input(9)));
1083        assert!(matches!(result, Ok(9)));
1084    }
1085
1086    #[test]
1087    fn run_threads_a_value_written_by_an_earlier_step_to_a_later_step() {
1088        let pipeline = Pipeline::<Input, i32>::builder()
1089            .step(scripted(
1090                "a",
1091                AccessSpec::new().writes::<Marker>(),
1092                Action::WriteMarker(5),
1093            ))
1094            .step(scripted(
1095                "b",
1096                AccessSpec::new().reads::<Marker>(),
1097                Action::ReadMarkerAsDone,
1098            ))
1099            .build()
1100            .unwrap();
1101        let result = block_on(pipeline.run(Input(0)));
1102        assert!(matches!(result, Ok(10)));
1103    }
1104
1105    #[test]
1106    fn run_returns_exhausted_for_pipeline_with_zero_steps() {
1107        let pipeline = Pipeline::<Input, i32>::builder().build().unwrap();
1108        let result = block_on(pipeline.run(Input(0)));
1109        assert!(matches!(result, Err(PipelineError::Exhausted)));
1110    }
1111
1112    #[test]
1113    fn run_returns_step_error_when_a_step_returns_err() {
1114        let pipeline = Pipeline::<Input, i32>::builder()
1115            .step(scripted("a", AccessSpec::new(), Action::Fail("boom")))
1116            .build()
1117            .unwrap();
1118        match block_on(pipeline.run(Input(0))) {
1119            Err(PipelineError::Step { step, source }) => {
1120                assert_eq!(step, "a");
1121                assert_eq!(source.to_string(), "boom");
1122            }
1123            other => panic!("expected Step error, got {other:?}"),
1124        }
1125    }
1126
1127    #[test]
1128    fn run_returns_access_violation_when_step_reads_undeclared_entry() {
1129        let pipeline = Pipeline::<Input, i32>::builder()
1130            .step(scripted("a", AccessSpec::new(), Action::ReadMarkerAsDone))
1131            .build()
1132            .unwrap();
1133        match block_on(pipeline.run(Input(0))) {
1134            Err(PipelineError::AccessViolation(AccessViolation { step, kind, .. })) => {
1135                assert_eq!(step, "a");
1136                assert_eq!(kind, AccessKind::Read);
1137            }
1138            other => panic!("expected AccessViolation, got {other:?}"),
1139        }
1140    }
1141
1142    #[test]
1143    fn run_returns_access_violation_when_step_writes_undeclared_entry() {
1144        let pipeline = Pipeline::<Input, i32>::builder()
1145            .step(scripted("a", AccessSpec::new(), Action::WriteMarker(1)))
1146            .build()
1147            .unwrap();
1148        match block_on(pipeline.run(Input(0))) {
1149            Err(PipelineError::AccessViolation(AccessViolation { step, kind, .. })) => {
1150                assert_eq!(step, "a");
1151                assert_eq!(kind, AccessKind::Write);
1152            }
1153            other => panic!("expected AccessViolation, got {other:?}"),
1154        }
1155    }
1156
1157    #[test]
1158    fn run_returns_access_violation_instead_of_step_error_when_both_occur() {
1159        let pipeline = Pipeline::<Input, i32>::builder()
1160            .step(scripted(
1161                "a",
1162                AccessSpec::new(),
1163                Action::WriteMarkerThenFail(1, "boom"),
1164            ))
1165            .build()
1166            .unwrap();
1167        match block_on(pipeline.run(Input(0))) {
1168            Err(PipelineError::AccessViolation(AccessViolation { step, kind, .. })) => {
1169                assert_eq!(step, "a");
1170                assert_eq!(kind, AccessKind::Write);
1171            }
1172            other => panic!("expected AccessViolation, got {other:?}"),
1173        }
1174    }
1175
1176    #[test]
1177    fn run_never_calls_access_or_name_again_after_build_cached_them() {
1178        let access_calls = Arc::new(AtomicUsize::new(0));
1179        let name_calls = Arc::new(AtomicUsize::new(0));
1180        let pipeline = Pipeline::<Input, i32>::builder()
1181            .step(CountingStep {
1182                access_calls: access_calls.clone(),
1183                name_calls: name_calls.clone(),
1184            })
1185            .build()
1186            .unwrap();
1187        let access_calls_after_build = access_calls.load(Ordering::SeqCst);
1188        let name_calls_after_build = name_calls.load(Ordering::SeqCst);
1189        assert!(access_calls_after_build >= 1);
1190        assert!(name_calls_after_build >= 1);
1191
1192        block_on(pipeline.run(Input(0))).unwrap();
1193        block_on(pipeline.run(Input(0))).unwrap();
1194
1195        assert_eq!(
1196            access_calls.load(Ordering::SeqCst),
1197            access_calls_after_build
1198        );
1199        assert_eq!(name_calls.load(Ordering::SeqCst), name_calls_after_build);
1200    }
1201
1202    #[test]
1203    fn run_returns_exhausted_when_every_step_returns_continue() {
1204        let pipeline = Pipeline::<Input, i32>::builder()
1205            .step(scripted("a", AccessSpec::new(), Action::Continue))
1206            .step(scripted("b", AccessSpec::new(), Action::Continue))
1207            .build()
1208            .unwrap();
1209        let result = block_on(pipeline.run(Input(0)));
1210        assert!(matches!(result, Err(PipelineError::Exhausted)));
1211    }
1212
1213    // ---- run_steps: the shared loop behind Pipeline::run and Branch's arm
1214    // dispatch. Unlike Pipeline::run, exhausting every step as Continue is
1215    // not an error here — see run_steps's doc comment for why.
1216
1217    fn compiled(steps: Vec<ScriptedStep>) -> Vec<CompiledStep<i32>> {
1218        steps
1219            .into_iter()
1220            .map(|s| {
1221                let name = s.name().to_string();
1222                let access = s.access();
1223                CompiledStep {
1224                    name,
1225                    access,
1226                    step: Box::new(s),
1227                }
1228            })
1229            .collect()
1230    }
1231
1232    #[test]
1233    fn run_steps_returns_continue_when_every_step_continues() {
1234        let steps = compiled(vec![
1235            scripted("a", AccessSpec::new(), Action::Continue),
1236            scripted("b", AccessSpec::new(), Action::Continue),
1237        ]);
1238        let mut ctx = Context::new();
1239        let result = block_on(run_steps(&steps, &mut ctx));
1240        assert!(matches!(result, Ok(Flow::Continue)));
1241    }
1242
1243    #[test]
1244    fn run_steps_propagates_done_and_stops_running_further_steps() {
1245        let steps = compiled(vec![
1246            scripted("a", AccessSpec::new(), Action::Continue),
1247            scripted("b", AccessSpec::new(), Action::Done(9)),
1248            scripted("c", AccessSpec::new(), Action::Done(-1)),
1249        ]);
1250        let mut ctx = Context::new();
1251        let result = block_on(run_steps(&steps, &mut ctx));
1252        assert!(matches!(result, Ok(Flow::Done(9))));
1253    }
1254
1255    #[test]
1256    fn run_steps_propagates_err() {
1257        let steps = compiled(vec![scripted("a", AccessSpec::new(), Action::Fail("boom"))]);
1258        let mut ctx = Context::new();
1259        match block_on(run_steps(&steps, &mut ctx)) {
1260            Err(PipelineError::Step { step, source }) => {
1261                assert_eq!(step, "a");
1262                assert_eq!(source.to_string(), "boom");
1263            }
1264            Ok(_) => panic!("expected Step error, got Ok"),
1265            Err(other) => panic!("expected Step error, got {other}"),
1266        }
1267    }
1268}