Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] Add sequence diagrams to hedging #1706

Merged
merged 2 commits into from
Oct 19, 2023
Merged

[Docs] Add sequence diagrams to hedging #1706

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a95439
Add sequence diagrams to hedging
Oct 19, 2023
7882c03
Updates hedging diagrams based on feedbacks
Oct 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
294 changes: 294 additions & 0 deletions docs/strategies/hedging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,68 @@ When the `Delay` property is set to a value greater than zero, the hedging strat
- The final result is the result of fastest successful execution.
- If all executions fail, the final result will be the first failure encountered.

#### Latency: happy path sequence diagram

The hedging strategy does not trigger because the response arrives faster than the threshold.

```mermaid
sequenceDiagram
autonumber
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
Note over H: Wait start

activate H
H->>+HUC: Invokes
HUC-->>HUC: Processes request
HUC->>-H: Returns result
deactivate H

Note over H: Wait end
H->>P: Returns result
P->>C: Returns result
```

#### Latency: unhappy path sequence diagram

The hedging strategy triggers because the response arrives slower than the threshold.

```mermaid
sequenceDiagram
autonumber
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant D as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
Note over H: Wait start

activate H
activate D
H->>D: Invokes (R1)
D-->>D: Processes R1<br/> slowly ...
Note over H: Wait end

H->>D: Invokes (R2)
activate D
D-->>D: Processes R2<br/> quickly
D->>H: Returns result (R2)
deactivate D
H->>D: Propagates cancellation (R1)
deactivate H

deactivate D
H->>P: Returns result (R2)
P->>C: Returns result (R2)
```

### Fallback mode

In fallback mode, the `Delay` value should be less than `TimeSpan.Zero`. This mode allows only a single execution to proceed at a given time.
Expand All @@ -96,6 +158,64 @@ In fallback mode, the `Delay` value should be less than `TimeSpan.Zero`. This mo
- The final result will be the first successful execution.
- If all executions fail, the final result will be the first failure encountered.

#### Fallback: happy path sequence diagram

The hedging strategy triggers because the first attempt fails. It succeeds because the retry attempts do not exceed the `MaxHedgedAttempts`.

```mermaid
sequenceDiagram
autonumber
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
activate H

H->>+HUC: Invokes (R1)
HUC-->>HUC: Processes R1
HUC->>-H: Fails (R1)

H->>+HUC: Invokes (R2)
HUC-->>HUC: Processes R2
HUC->>-H: Returns result (R2)

deactivate H
H->>P: Returns result (R2)
P->>C: Returns result (R2)
```

#### Fallback: unhappy path sequence diagram

The hedging strategy triggers because the first attempt fails. It fails because all retry attempts failed as well.

```mermaid
sequenceDiagram
autonumber
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
activate H

H->>+HUC: Invokes (R1)
HUC-->>HUC: Processes R1
HUC->>-H: Fails (R1)

H->>+HUC: Invokes (R2)
HUC-->>HUC: Processes R2
HUC->>-H: Fails (R2)

deactivate H
H->>P: Propagates failure (R1)
P->>C: Propagates failure (R1)
```

### Parallel mode

The hedging strategy operates in parallel mode when the `Delay` property is set to `TimeSpan.Zero`. In this mode, all executions are initiated simultaneously, and the strategy waits for the fastest completion.
Expand All @@ -107,6 +227,76 @@ The hedging strategy operates in parallel mode when the `Delay` property is set
- The final result will be the fastest successful execution.
- If all executions fail, the final result will be the first failure encountered.

#### Parallel: happy path sequence diagram

The hedging strategy triggers because the `Delay` is set to zero. It succeeds because one of the requests succeeds.

```mermaid
sequenceDiagram
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
activate H

par
H->>HUC: Invokes (R1)
activate HUC

and
H->>+HUC: Invokes (R2)

end

HUC-->>HUC: Processes R1<br/> slowly ...
HUC-->>HUC: Processes R2<br/> quickly ...
HUC->>-H: Returns result (R2)

H->>HUC: Propagates cancellation (R1)
deactivate HUC

deactivate H
H->>P: Returns result (R2)
P->>C: Returns result (R2)
```

#### Parallel: unhappy path sequence diagram

The hedging strategy triggers because the `Delay` is set to zero. It succeeds because one of the requests succeeds.

```mermaid
sequenceDiagram
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
activate H

par
H->>HUC: Invokes (R1)
activate HUC

and
H->>+HUC: Invokes (R2)

end

HUC-->>HUC: Processes R1
HUC-->>HUC: Processes R2
HUC->>-H: Fails (R2)
HUC->>-H: Fails (R1)

deactivate H
H->>P: Propagates failure (R2)
P->>C: Propagates failure (R2)
```

### Dynamic mode

In dynamic mode, you have the flexibility to control how the hedging strategy behaves during each execution. This control is achieved through the `DelayGenerator` property.
Expand Down Expand Up @@ -147,6 +337,110 @@ With this configuration, the hedging strategy:
- Initiates a maximum of `4` executions. This includes initial action and an additional 3 attempts.
- Allows the first two executions to proceed in parallel, while the third and fourth executions follow the fallback mode.
peter-csala marked this conversation as resolved.
Show resolved Hide resolved

#### Dynamic: happy path sequence diagram

The hedging strategy triggers and switches between modes due to the usage of `DelayGenerator`. It succeeds because the last request succeeds.

```mermaid
sequenceDiagram
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant DG as DelayGenerator
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
activate H

Note over H: Parallel mode
par
H->>DG: Gets delay
DG->>H: 1 second
H->>HUC: Invokes (R1)
activate HUC
and
H ->> DG: Gets delay
DG ->> H: 2 seconds
H->>+HUC: Invokes (R2)
end

HUC-->>HUC: Processes R1
HUC-->>HUC: Processes R2
HUC->>-H: Fails (R2)
HUC->>-H: Fails (R1)

Note over H: Fallback mode

H->>DG: Gets delay
DG->>H: Infinite
H->>+HUC: Invokes (R3)
HUC-->>HUC: Processes R3
HUC->>-H: Fails (R3)

H->>DG: Gets delay
DG->>H: Infinite
H->>+HUC: Invokes (R4)
HUC-->>HUC: Processes R4
HUC->>-H: Returns result (R4)

deactivate H
H->>P: Returns result (R4)
P->>C: Returns result (R4)
```

#### Dynamic: unhappy path sequence diagram

The hedging strategy triggers and switches between modes due to the usage of `DelayGenerator`. It fails because all requests fail.

```mermaid
sequenceDiagram
actor C as Caller
participant P as Pipeline
participant H as Hedging
participant DG as DelayGenerator
participant HUC as HedgedUserCallback

C->>P: Calls ExecuteAsync
P->>H: Calls ExecuteCore
activate H

Note over H: Parallel mode
par
H->>DG: Gets delay
DG->>H: 1 second
H->>HUC: Invokes (R1)
activate HUC
and
H->>DG: Gets delay
DG->>H: 2 seconds
H->>+HUC: Invokes (R2)
end

HUC-->>HUC: Processes R1
HUC-->>HUC: Processes R2
HUC->>-H: Fails (R2)
HUC->>-H: Fails (R1)

Note over H: Fallback mode

H->>DG: Gets delay
DG->>H: Infinite
H->>+HUC: Invokes (R3)
HUC-->>HUC: Processes R3
HUC->>-H: Fails (R3)

H -> DG: Gets delay
DG->>H: Infinite
H->>+HUC: Invokes (R4)
HUC-->>HUC: Processes R4
HUC->>-H: Fails (R4)

deactivate H
H->>P: Propagates failure (R3)
P->>C: Propagates failure (R3)
```

## Action generator

The hedging options include an `ActionGenerator` property, allowing you to customize the actions executed during hedging. By default, the `ActionGenerator` returns the original callback passed to the strategy. The original callback also includes any logic introduced by subsequent resilience strategies. For more advanced scenarios, the `ActionGenerator` can be used to return entirely new hedged actions, as demonstrated in the example below:
Expand Down