[Docs] Add sequence diagrams to fallback, retry, and rate limiter (#1702

) Add diagrams to fallback, retry, and rate limiter.
App-vNext · Oct 18, 2023 · f7d434a · f7d434a
1 parent 940c628
commit f7d434a
Show file tree

Hide file tree

Showing 4 changed files with 237 additions and 10 deletions.
diff --git a/docs/strategies/fallback.md b/docs/strategies/fallback.md
@@ -65,6 +65,45 @@ new ResiliencePipelineBuilder<UserAvatar>()
 | `FallbackAction` | `Null`, **Required**                                                       | Fallback action to be executed.                                                             |
 | `OnFallback`     | `null`                                                                     | Event that is raised when fallback happens.                                                 |
 
+## Diagrams
+
+### Happy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C as Caller
+    participant P as Pipeline
+    participant F as Fallback
+    participant D as DecoratedUserCallback
+
+    C->>P: Calls ExecuteAsync
+    P->>F: Calls ExecuteCore
+    F->>+D: Invokes
+    D->>-F: Returns result
+    F->>P: Returns result
+    P->>C: Returns result
+```
+
+### Unhappy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C as Caller
+    participant P as Pipeline
+    participant F as Fallback
+    participant D as DecoratedUserCallback
+
+    C->>P: Calls ExecuteAsync
+    P->>F: Calls ExecuteCore
+    F->>+D: Invokes
+    D->>-F: Fails
+    F->>F: Falls back to<br/>substitute result
+    F->>P: Returns <br/>substituted result
+    P->>C: Returns <br/>substituted result
+```
+
 ## Patterns
 
 ### Fallback after retries

diff --git a/docs/strategies/rate-limiter.md b/docs/strategies/rate-limiter.md
@@ -74,6 +74,140 @@ catch (RateLimiterRejectedException ex)
 | `DefaultRateLimiterOptions` | `PermitLimit` set to 1000 and `QueueLimit` set to 0. | The options for the default concurrency limiter that will be used when `RateLimiter` is `null`. |
 | `OnRejected`                | `null`                                               | Event that is raised when the execution is rejected by the rate limiter.                        |
 
+## Diagrams
+
+### Rate Limiter
+
+Let's suppose we have a rate limiter strategy with `PermitLimit` : `1` and `Window` : `10 seconds`.
+
+### Rate Limiter: happy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C as Caller
+    participant P as Pipeline
+    participant RL as RateLimiter
+    participant D as DecoratedUserCallback
+
+    C->>P: Calls ExecuteAsync
+    P->>RL: Calls ExecuteCore
+    Note over RL,D: Window start
+    RL->>+D: Invokes
+    D->>-RL: Returns result
+    RL->>P: Returns result
+    P->>C: Returns result
+    Note over C: Several seconds later...
+    Note over RL,D: Window end
+    C->>P: Calls ExecuteAsync
+    P->>RL: Calls ExecuteCore
+    Note over RL,D: Window start
+    RL->>+D: Invokes
+    D->>-RL: Returns result
+    RL->>P: Returns result
+    P->>C: Returns result
+    Note over RL,D: Window end
+```
+
+#### Rate limiter: unhappy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C as Caller
+    participant P as Pipeline
+    participant RL as RateLimiter
+    participant D as DecoratedUserCallback
+
+    C->>P: Calls ExecuteAsync
+    P->>RL: Calls ExecuteCore
+    Note over RL,D: Window start
+    RL->>+D: Invokes
+    D->>-RL: Returns result
+    RL->>P: Returns result
+    P->>C: Returns result
+    Note over C: Few seconds later...
+    C->>P: Calls ExecuteAsync
+    P->>RL: Calls ExecuteCore
+    RL->>RL: Rejects request
+    RL->>P: Throws <br/>RateLimiterRejectedException
+    P->>C: Propagates exception
+    Note over RL,D: Window end
+```
+
+### Concurrency Limiter
+
+Let's suppose we have a concurrency limiter strategy with `PermitLimit` : `1` and `QueueLimit` : `1`.
+
+#### Concurrency limiter: happy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C1 as Caller1
+    actor C2 as Caller2
+    participant P as Pipeline
+    participant CL as ConcurrencyLimiter
+    participant D as DecoratedUserCallback
+
+    par
+    C1->>P: Calls ExecuteAsync
+    and
+    C2->>P: Calls ExecuteAsync
+    end
+
+    P->>CL: Calls ExecuteCore
+    CL->>+D: Invokes (C1)
+    P->>CL: Calls ExecuteCore
+    CL->>CL: Queues request
+
+    D->>-CL: Returns result (C1)
+    CL->>P: Returns result (C1)
+    CL->>+D: Invokes (C2)
+    P->>C1: Returns result
+    D->>-CL: Returns result (C2)
+    CL->>P: Returns result (C2)
+    P->>C2: Returns result
+```
+
+#### Concurrency Limiter: unhappy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C1 as Caller1
+    actor C2 as Caller2
+    actor C3 as Caller3
+    participant P as Pipeline
+    participant CL as ConcurrencyLimiter
+    participant D as DecoratedUserCallback
+
+    par
+    C1->>P: Calls ExecuteAsync
+    and
+    C2->>P: Calls ExecuteAsync
+    and
+    C3->>P: Calls ExecuteAsync
+    end
+
+    P->>CL: Calls ExecuteCore
+    CL->>+D: Invokes (C1)
+    P->>CL: Calls ExecuteCore
+    CL->>CL: Queues request (C2)
+    P->>CL: Calls ExecuteCore
+    CL->>CL: Rejects request (C3)
+    CL->>P: Throws <br/>RateLimiterRejectedException
+    P->>C3: Propagate exception
+
+    D->>-CL: Returns result (C1)
+    CL->>P: Returns result (C1)
+    CL->>+D: Invokes (C2)
+    P->>C1: Returns result
+    D->>-CL: Returns result (C2)
+    CL->>P: Returns result (C2)
+    P->>C2: Returns result
+```
+
 ## Disposal of rate limiters
 
 The `RateLimiter` is a disposable resource. When you explicitly create a `RateLimiter` instance, it's good practice to dispose of it once it's no longer needed. This is usually not an issue when manually creating resilience pipelines using the `ResiliencePipelineBuilder`. However, when dynamic reloads are enabled, failing to dispose of discarded rate limiters can lead to excessive resource consumption. Fortunately, Polly provides a way to dispose of discarded rate limiters, as demonstrated in the example below:

diff --git a/docs/strategies/retry.md b/docs/strategies/retry.md
@@ -104,6 +104,60 @@ new ResiliencePipelineBuilder().AddRetry(new RetryStrategyOptions
 | `OnRetry`          | `null`                                                                     | Action executed when retry occurs.                                                       |
 | `MaxDelay`         | `null`                                                                     | Caps the calculated retry delay to a specified maximum duration.                         |
 
+## Diagrams
+
+Let's suppose we have a retry strategy with `MaxRetryAttempts`: `2`.
+
+### Happy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C as Caller
+    participant P as Pipeline
+    participant R as Retry
+    participant D as DecoratedUserCallback
+
+    C->>P: Calls ExecuteAsync
+    P->>R: Calls ExecuteCore
+    Note over R,D: Initial attempt
+    R->>+D: Invokes
+    D->>-R: Fails
+    R->>R: Sleeps
+    Note over R,D: 1st retry attempt
+    R->>+D: Invokes
+    D->>-R: Returns result
+    R->>P: Returns result
+    P->>C: Returns result
+```
+
+### Unhappy path sequence diagram
+
+```mermaid
+%%{init: {'theme':'dark'}}%%
+sequenceDiagram
+    actor C as Caller
+    participant P as Pipeline
+    participant R as Retry
+    participant D as DecoratedUserCallback
+
+    C->>P: Calls ExecuteAsync
+    P->>R: Calls ExecuteCore
+    Note over R,D: Initial attempt
+    R->>+D: Invokes
+    D->>-R: Fails
+    R->>R: Sleeps
+    Note over R,D: 1st retry attempt
+    R->>+D: Invokes
+    D->>-R: Fails
+    R->>R: Sleeps
+    Note over R,D: 2nd retry attempt
+    R->>+D: Invokes
+    D->>-R: Fails
+    R->>P: Propagates failure
+    P->>C: Propagates failure
+```
+
 ## Patterns
 
 ### Limiting the maximum delay

diff --git a/docs/strategies/timeout.md b/docs/strategies/timeout.md
@@ -88,13 +88,13 @@ sequenceDiagram
     actor C as Caller
     participant P as Pipeline
     participant T as Timeout
-    participant DM as DecoratedMethod
+    participant D as DecoratedUserCallback
 
     C->>P: Calls ExecuteAsync
     P->>T: Calls ExecuteCore
-    T->>+DM: Invokes
-    DM->>DM: Performs <br/>long-running <br/>operation
-    DM->>-T: Returns result
+    T->>+D: Invokes
+    D->>D: Performs <br/>long-running <br/>operation
+    D->>-T: Returns result
     T->>P: Returns result
     P->>C: Returns result
 ```
@@ -107,18 +107,18 @@ sequenceDiagram
     actor C as Caller
     participant P as Pipeline
     participant T as Timeout
-    participant DM as DecoratedMethod
+    participant D as DecoratedUserCallback
 
     C->>P: Calls ExecuteAsync
     P->>T: Calls ExecuteCore
-    T->>+DM: Invokes
+    T->>+D: Invokes
     activate T
-    activate DM
-    DM->>DM: Performs <br/>long-running <br/>operation
+    activate D
+    D->>D: Performs <br/>long-running <br/>operation
     T->T: Times out
     deactivate T
-    T->>DM: Propagates cancellation
-    deactivate DM
+    T->>D: Propagates cancellation
+    deactivate D
     T->>P: Throws <br/>TimeoutRejectedException
     P->>C: Propagates exception
 ```