From 0d97014f4c427b2d6f0d972c0d546d60154f2787 Mon Sep 17 00:00:00 2001
From: Bjerg <onbjerg@users.noreply.github.com>
Date: Fri, 14 Oct 2022 13:23:13 +0200
Subject: [PATCH] docs: mermaid diagram for pipeline (#67)

---
 Cargo.lock                          |  1 +
 crates/stages/Cargo.toml            |  1 +
 crates/stages/src/pipeline.rs       | 35 +++++++++++++++++++++++++++++
 crates/stages/src/pipeline/event.rs |  2 +-
 4 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/Cargo.lock b/Cargo.lock
index 587701145..443731d53 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2197,6 +2197,7 @@ dependencies = [
 name = "reth-stages"
 version = "0.1.0"
 dependencies = [
+ "aquamarine",
  "async-trait",
  "reth-db",
  "reth-primitives",
diff --git a/crates/stages/Cargo.toml b/crates/stages/Cargo.toml
index 23872f5a6..92062abe1 100644
--- a/crates/stages/Cargo.toml
+++ b/crates/stages/Cargo.toml
@@ -15,6 +15,7 @@ thiserror = "1.0.37"
 tracing = "0.1.36"
 tracing-futures = "0.2.5"
 tokio = { version = "1.21.2", features = ["sync"] }
+aquamarine = "0.1.12"
 
 [dev-dependencies]
 tokio = { version = "*", features = ["rt", "sync", "macros"] }
diff --git a/crates/stages/src/pipeline.rs b/crates/stages/src/pipeline.rs
index c1de58c0d..5357b0642 100644
--- a/crates/stages/src/pipeline.rs
+++ b/crates/stages/src/pipeline.rs
@@ -17,6 +17,7 @@ use ctrl::*;
 pub use event::*;
 use state::*;
 
+#[cfg_attr(doc, aquamarine::aquamarine)]
 /// A staged sync pipeline.
 ///
 /// The pipeline executes queued [stages][Stage] serially. An external component determines the tip
@@ -27,6 +28,40 @@ use state::*;
 /// After the entire pipeline has been run, it will run again unless asked to stop (see
 /// [Pipeline::set_max_block]).
 ///
+/// ```mermaid
+/// graph TB
+///   Start[Start]
+///   Done[Done]
+///   Error[Error]
+///   subgraph Unwind
+///     StartUnwind(Unwind by unwind priority)
+///     UnwindStage(Unwind stage)
+///     NextStageToUnwind(Next stage)
+///   end
+///   subgraph Single loop
+///     RunLoop(Run loop)
+///     NextStage(Next stage)
+///     LoopDone(Loop done)
+///     subgraph Stage Execution
+///       Execute(Execute stage)
+///     end
+///   end
+///   Start --> RunLoop --> NextStage
+///   NextStage --> |No stages left| LoopDone
+///   NextStage --> |Next stage| Execute
+///   Execute --> |Not done| Execute
+///   Execute --> |Unwind requested| StartUnwind
+///   Execute --> |Done| NextStage
+///   Execute --> |Error| Error
+///   StartUnwind --> NextStageToUnwind
+///   NextStageToUnwind --> |Next stage| UnwindStage
+///   NextStageToUnwind --> |No stages left| RunLoop
+///   UnwindStage --> |Error| Error
+///   UnwindStage --> |Unwound| NextStageToUnwind
+///   LoopDone --> |Target block reached| Done
+///   LoopDone --> |Target block not reached| RunLoop
+/// ```
+///
 /// # Unwinding
 ///
 /// In case of a validation error (as determined by the consensus engine) in one of the stages, the
diff --git a/crates/stages/src/pipeline/event.rs b/crates/stages/src/pipeline/event.rs
index 2aaf26ddf..cd07bb2ce 100644
--- a/crates/stages/src/pipeline/event.rs
+++ b/crates/stages/src/pipeline/event.rs
@@ -4,7 +4,7 @@ use crate::{
 };
 use reth_primitives::BlockNumber;
 
-/// An event emitted by a [Pipeline].
+/// An event emitted by a [Pipeline][crate::Pipeline].
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub enum PipelineEvent {
     /// Emitted when a stage is about to be run.