# Introduction to Murphy for Delphi

## What is Murphy?

Murphy for Delphi is a comprehensive library that implements **Chaos Engineering** patterns for building resilient and fault-tolerant applications. Named after [Murphy's Law](https://en.wikipedia.org/wiki/Murphy%27s_law) ("Anything that can go wrong will go wrong"), this library helps you prepare for and handle failures gracefully in your Delphi applications.

## Why Murphy?

In distributed systems and modern applications, failures are inevitable:
- Network requests can timeout
- External services can become unavailable
- Database connections can fail
- APIs can be throttled or return errors
- Resources can be exhausted

Murphy provides battle-tested patterns to handle these scenarios without writing complex error-handling code from scratch.

## Key Features

### Ready-to-Use Patterns
Murphy implements four essential resilience patterns:

1. **Retry** - Automatically retry failed operations with configurable delays
2. **Circuit Breaker** - Prevent cascading failures by temporarily blocking calls to failing services
3. **Fallback** - Provide alternative results when operations fail
4. **Rate Limit** - Control the rate of operations to prevent system overload

### Fluent API
All patterns use a fluent, builder-based API that makes configuration intuitive and readable:

```pascal
var
  Policy: IRetryPolicy;
begin
  Policy := TRetryBuilder.Create
    .Handle(EIdHTTPProtocolException)
    .Retry(3)
    .Wait(TTimeSpan.FromSeconds(2))
    .Build;
end;
```

### Type Safety
Murphy leverages Delphi's strong type system and generics for type-safe operations:

```pascal
var
  FallbackPolicy: IFallbackPolicy<string>;
  Result: string;
begin
  FallbackPolicy := TFallbackBuilder<string>.Create
    .Handle(Exception)
    .Fallback(function: string
              begin
                Result := 'Default Value';
              end)
    .Build;

  Result := FallbackPolicy.Execute(function: string
                                    begin
                                      Result := GetDataFromService;
                                    end);
end;
```

### Exception Filtering
Each policy can be configured to handle specific exception types:

```pascal
RetryPolicy := TRetryBuilder.Create
  .Handle(EIdHTTPProtocolException)  // Only retry HTTP exceptions
  .Handle(EIdSocketError)             // Also retry socket errors
  .Retry(3)
  .Build;
```

### Testability
Murphy includes a test mode that allows you to unit test your code without actual delays:

```pascal
uses Murphy.Globals;

procedure TMyTests.TestRetryPolicy;
begin
  MurphyTestModeEnabled := True;  // Disable actual waiting

  // Your test code here - retries happen instantly

  MurphyTestModeEnabled := False;
end;
```

### Composability
Patterns can be combined to create sophisticated resilience strategies (see [Combining Patterns](Patterns/Combining-Patterns.md)).

## When to Use Murphy

Murphy is ideal for:

- **Microservices** - Handle inter-service communication failures
- **REST API Clients** - Retry transient HTTP errors
- **Database Operations** - Handle connection timeouts and transient failures
- **External Service Integration** - Protect against third-party service outages
- **Resource-Intensive Operations** - Rate limit to prevent resource exhaustion
- **Critical Systems** - Improve overall system reliability

## Design Philosophy

Murphy follows these principles:

1. **Simple by default, flexible when needed** - Common scenarios require minimal configuration
2. **Explicit over implicit** - Behavior should be clear and predictable
3. **Composable** - Patterns work independently or together
4. **Testable** - Test mode enables fast, deterministic testing
5. **Performant** - Minimal overhead when patterns aren't triggered

## What Murphy Is Not

Murphy is **not**:
- A complete application framework
- A replacement for proper error handling
- A solution for all reliability problems
- A logging or monitoring framework (though it works well with them)

Murphy complements your existing error handling and doesn't replace good design practices.

## Inspiration

Murphy for Delphi is inspired by:
- [Polly](https://github.com/App-vNext/Polly) (.NET resilience library)
- Netflix's [Hystrix](https://github.com/Netflix/Hystrix) (Circuit Breaker implementation)
- Chaos Engineering principles pioneered by Netflix

## Quick Comparison

| Scenario | Without Murphy | With Murphy |
|----------|---------------|-------------|
| HTTP request fails | Immediate error | Automatic retry with delay |
| Service constantly failing | Keep trying forever, wasting resources | Circuit breaker opens, fail fast |
| Database temporarily unavailable | Application crashes | Fallback to cached data |
| API rate limit exceeded | Errors for users | Rate limiter prevents over-calling |

## Next Steps

- **New to Chaos Engineering?** Read [Chaos Engineering Basics](03-Chaos-Engineering.md)
- **Ready to start?** Check out [Getting Started](02-Getting-Started.md)
- **Want to dive deep?** Explore the [Architecture](04-Architecture.md)
- **Need specific pattern info?** See the [Pattern Guides](Home.md#pattern-guides)

---

[← Back to Index](Home.md) | [Getting Started →](02-Getting-Started.md)