# Murphy for Delphi - Documentation

Welcome to the Murphy for Delphi documentation! Murphy is a comprehensive Chaos Engineering library for Delphi that provides ready-to-use implementations of nine common resilience and fault-tolerance patterns.

> [!IMPORTANT]
>
> Warning: some of this documentation was generated or reworked with an LLM tool (Claude). It may therefore contain errors and/or inaccuracies. If you encounter any, please report the issue or propose a fix by submitting a pull request.

## Table of Contents

### Getting Started
- [Introduction](01-Introduction.md) - What is Murphy and why use it
- [Getting Started](02-Getting-Started.md) - Installation and first steps
- [Chaos Engineering Basics](03-Chaos-Engineering.md) - Understanding Chaos Engineering principles

### Core Concepts
- [Architecture](04-Architecture.md) - Design principles and internal architecture

### API Reference
- [API Reference Index](API-Reference/README.md)
  - [Base Policy](API-Reference/Base-Policy.md) - Core interfaces and base classes
  - [Retry Policy](API-Reference/Retry-Policy.md) - Retry pattern API
  - [Circuit Breaker Policy](API-Reference/CircuitBreaker-Policy.md) - Circuit Breaker pattern API
  - [Fallback Policy](API-Reference/Fallback-Policy.md) - Fallback pattern API
  - [Rate Limit Policy](API-Reference/RateLimit-Policy.md) - Rate Limit pattern API
  - [Timeout Policy](API-Reference/Timeout-Policy.md) - Timeout pattern API
  - [Bulkhead Policy](API-Reference/Bulkhead-Policy.md) - Bulkhead pattern API
  - [Cache Policy](API-Reference/Cache-Policy.md) - Cache pattern API
  - [Hedging Policy](API-Reference/Hedging-Policy.md) - Hedging pattern API
  - [Policy Wrap](API-Reference/PolicyWrap-Policy.md) - Policy composition API

### Pattern Guides
- [Retry Pattern](Patterns/Retry.md) - Automatic retry with configurable delays
- [Circuit Breaker Pattern](Patterns/CircuitBreaker.md) - Prevent cascading failures
- [Fallback Pattern](Patterns/Fallback.md) - Provide alternative results on failure
- [Rate Limit Pattern](Patterns/RateLimit.md) - Control operation rate
- [Timeout Pattern](Patterns/Timeout.md) - Abort operations that take too long
- [Bulkhead Pattern](Patterns/Bulkhead.md) - Isolate resources by limiting concurrency
- [Cache Pattern](Patterns/Cache.md) - Cache expensive results, serve stale data on failure
- [Hedging Pattern](Patterns/Hedging.md) - Reduce tail latency with parallel attempts
- [Policy Wrap](Patterns/PolicyWrap.md) - Combine multiple policies into one
- [Combining Patterns](Patterns/Combining-Patterns.md) - Advanced: Using multiple patterns together

### Advanced Topics
- [Testing with Murphy](Advanced/Testing.md) - Unit testing and test mode
- [Best Practices](Advanced/Best-Practices.md) - Recommendations and common pitfalls
- [Contributing](Advanced/Contributing.md) - How to contribute to Murphy

## Quick Links

### Installation
```bash
# Using Blocks package manager
blocks install marcobreveglieri.murphy-delphi
```

### Quick Example
```pascal
uses Murphy.Policy.Retry;

var
  RetryPolicy: IRetryPolicy;
begin
  // Create a retry policy
  RetryPolicy := TRetryBuilder.Create
    .Handle(EIdHTTPProtocolException)
    .Retry(3)
    .Wait(TTimeSpan.FromSeconds(1))
    .Build;

  // Execute code with automatic retry
  RetryPolicy.Execute(
    procedure
    begin
      // Your code here - will be retried on failure
      MakeHttpRequest;
    end);
end;
```

## Supported Patterns

| Pattern | Purpose | Use Case |
|---------|---------|----------|
| **Retry** | Automatically retry failed operations | Transient network errors, temporary service unavailability |
| **Circuit Breaker** | Prevent cascading failures | Protect against persistent downstream failures |
| **Fallback** | Provide alternative results | Return cached data, default values, or degraded functionality |
| **Rate Limit** | Control operation rate | Prevent API throttling, protect resource consumption |
| **Timeout** | Abort operations that take too long | Slow network calls, unresponsive services, enforcing SLAs |
| **Bulkhead** | Limit concurrent executions | Protect connection pools, isolate workloads, cap parallel work |
| **Cache** | Cache expensive results for a duration | Expensive lookups, remote configuration, reducing backend load |
| **Hedging** | Launch parallel attempts, return the first success | Tail-latency reduction, replicated services, flaky endpoints |
| **Policy Wrap** | Combine multiple policies into one | Sophisticated resilience strategies, combining retry/timeout/circuit breaker |

## Requirements

- Delphi 11 Alexandria or later
- Supports Windows (Win32, Win64)

## License

Murphy for Delphi is released under the MIT License. See the [LICENSE](../LICENSE) file for details.

## Contributing

We welcome contributions! Please see our [Contributing Guide](Advanced/Contributing.md) for details on how to get started.

## Support

- **Issues**: [GitHub Issues](https://github.com/marcobreveglieri/murphy-delphi/issues)
- **Discussions**: [GitHub Discussions](https://github.com/marcobreveglieri/murphy-delphi/discussions)

---

**Next Steps**: Start with the [Introduction](01-Introduction.md) to learn more about Murphy, or jump straight to [Getting Started](02-Getting-Started.md) to begin using the library.