# Resilience Patterns Tutorials

These tutorials guide us through building fault-tolerant applications with higher-kinded-j's resilience patterns.

**Tutorials**: 4 | **Exercises**: 24
<!-- exercises: resilience/Tutorial01_CircuitBreaker resilience/Tutorial02_Saga resilience/Tutorial03_RetryBulkheadResilience resilience/Tutorial04_PathResilience -->

~~~admonish tip title="Where This Fits in the Bigger Picture"
The [One Line, Six Layers](../../hkts/one_line_six_layers.md) anchor uses `Either` short-circuiting to handle a single failure cleanly. This journey covers the patterns we reach for once one failure is not the whole story: retries, timeouts, downstream-protection, multi-step compensations. Reference material lives under [Resilience Patterns](../../resilience/ch_intro.md) in the Effect chapter.
~~~

## Prerequisites

Before starting, we should be comfortable with:
- `VTask` basics (creating, running, composing)
- The Effect Path API (`VTaskPath`, `VStreamPath`)
- Basic error handling (`handleError`, `recover`)

## Tutorial Track

### Tutorial 1: Circuit Breaker

Learn to protect services from cascading failures with the circuit breaker pattern.

**Exercises:**
1. Create a circuit breaker with custom configuration
2. Protect a VTask with the circuit breaker
3. Observe the circuit opening after threshold failures
4. Handle `CircuitOpenException`
5. Use `protectWithFallback` for graceful degradation
6. Monitor circuit breaker metrics

**File:** `Tutorial01_CircuitBreaker.java`

### Tutorial 2: Saga

Learn to coordinate multi-step operations with automatic compensation on failure.

**Exercises:**
1. Create a simple saga with compensation
2. Chain saga steps with dependent data
3. Verify compensation on failure
4. Use `SagaBuilder` for complex workflows
5. Handle saga errors with `runSafe()`

**File:** `Tutorial02_Saga.java`

### Tutorial 3: Retry, Bulkhead & Combined Resilience

Learn VTask-native retry, concurrency limiting, and combining multiple patterns.

**Exercises:**
1. Use `Retry.retryTask` with a `RetryPolicy`
2. Monitor retries with `RetryEvent`
3. Create a `Bulkhead` to limit concurrency
4. Compose patterns with `ResilienceBuilder`
5. Use convenience methods from `Resilience`

**File:** `Tutorial03_RetryBulkheadResilience.java`

### Tutorial 4: Path API Resilience

Learn to use resilience patterns through the fluent Path API.

**Exercises:**
1. `VTaskPath.withRetry()` and `.retry()` convenience
2. `VTaskPath.catching()`, `.asMaybe()`, `.asTry()` typed error wrapping
3. `VTaskPath.withCircuitBreaker()` in a fluent chain
4. `VStreamPath.recover()` and `.onError()` stream error handling
5. `VStreamPath.mapTask()` with per-element retry
6. `VTaskContext` Layer 2 resilience: `.retry()`, `.withCircuitBreaker()`

**File:** `Tutorial04_PathResilience.java`

## Running Tutorials

```bash
# Run tutorial exercises (expected to fail until completed)
./gradlew :hkj-examples:tutorialTest

# Run solutions to verify they work
./gradlew :hkj-examples:test
```

## Solutions

Each tutorial has a corresponding solution file under `hkj-examples/src/test/java/org/higherkindedj/tutorial/solutions/resilience/`. Try to complete the exercises on your own before checking the solutions.

| Tutorial | Solution File |
|----------|--------------|
| `Tutorial01_CircuitBreaker.java` | `solutions/resilience/Tutorial01_CircuitBreaker_Solution.java` |
| `Tutorial02_Saga.java` | `solutions/resilience/Tutorial02_Saga_Solution.java` |
| `Tutorial03_RetryBulkheadResilience.java` | `solutions/resilience/Tutorial03_RetryBulkheadResilience_Solution.java` |
| `Tutorial04_PathResilience.java` | `solutions/resilience/Tutorial04_PathResilience_Solution.java` |

---

**Previous:** [ForPath Parallel](../expression/forpath_parallel_journey.md)
**Next:** [Capstone: One Line, Six Layers Grows Up](../capstone/capstone_journey.md)