# EonaCat.SmartRetry

[![NuGet](https://img.shields.io/nuget/v/EonaCat.SmartRetry)](https://www.nuget.org/packages/EonaCat.SmartRetry)

`EonaCat.SmartRetry` is a powerful and flexible .NET library for building resilient applications. 

It provides **retry policies**, **circuit breakers**, **fallbacks**, **jittered backoff**, **async/sync support**, and more

---

## Features

- Retry on **exceptions** or **result conditions**  
- Configurable **retry count** and **max retry duration**  
- **Exponential**, **linear**, or **custom backoff** strategies  
- **Jitter** support to prevent thundering herd  
- **Circuit breaker** with open, half-open, and closed states  
- **Sync and async fallback actions**  
- Retry **with cancellation tokens**  
- Logging and async callbacks for retries and circuit breaker events  
- Thread-safe for **multi-threaded operations**  
- Named policies for reusable resilience configurations  

---

## Installation

Install via NuGet:

```bash
dotnet add package EonaCat.SmartRetry
```

Or via Package Manager:
```csharp
Install-Package EonaCat.SmartRetry
```

# Usage Examples
## Basic Retry with Fallback

```csharp
using EonaCat.SmartRetry;

var policy = SmartRetryPolicy.Policy()
    .Handle<TimeoutException>()
    .Retry(3)
    .WithExponentialBackoff(1, 2)
    .WithFallbackAsync(async () =>
    {
        Console.WriteLine("Executing fallback...");
        await Task.Delay(50);

        // fallback value
        return 42; 
    });

int result = await policy.ExecuteAsync<int>(async () =>
{
    Console.WriteLine("Attempting operation...");
    await Task.Delay(50);
    throw new TimeoutException("Simulated failure");
});

// Outputs: 42
Console.WriteLine($"Result: {result}"); 
```


## Retry with Circuit Breaker, Jitter, and Logging

```csharp
var policy = SmartRetryPolicy.Policy()
    .Handle<TimeoutException>()
    .Retry(5)
    .WithExponentialBackoff(1, 2)
    .WithJitter(0.2)
    .WithCircuitBreaker(failureThreshold: 3, openDuration: TimeSpan.FromSeconds(10))
    .WithFallbackAsync(async () =>
    {
        Console.WriteLine("Executing fallback...");
        await Task.Delay(50);
        return -1;
    })
    .OnRetry((attempt, ex) => Console.WriteLine($"Retry {attempt}: {ex.Message}"))
    .OnCircuitOpen(() => Console.WriteLine("Circuit breaker opened"))
    .OnCircuitClose(() => Console.WriteLine("Circuit breaker closed"));

int result = await policy.ExecuteAsync<int>(async (ct) =>
{
    Console.WriteLine("Attempting operation...");
    await Task.Delay(50, ct);
    throw new TimeoutException("Simulated failure");
});

Console.WriteLine($"Result: {result}");

```

## Retry Based on Result Condition
```csharp
var policy = SmartRetryPolicy.Policy()
    .RetryIf<int>(value => value < 0) // retry if result is negative
    .Retry(3)
    .WithLinearBackoff(0.5)
    .WithFallback(() => 0);

int result = policy.Execute(() =>
{
    Console.WriteLine("Returning -1 to trigger retry...");
    return -1;
});

// Outputs: 0 (fallback)
Console.WriteLine($"Result: {result}"); 

```

# Advanced Features

* Max Retry Duration: Stop retrying after a total duration.
* CancellationToken Support: Cancel retry loops gracefully.
* Custom Backoff Functions: Provide your own delay logic.
* Async Logging Hooks: Integrate with metrics or monitoring systems.
* Named Policies: Standardize retry/circuit-breaker behavior across your app.