# API Reference

Complete API documentation for Murphy for Delphi.

## Overview

Murphy's API is organized into layers:

1. **Base Layer** - Core interfaces and base classes used by all policies
2. **Policy Implementations** - Specific resilience pattern implementations
3. **Support Services** - Helper classes and utilities

## Quick Navigation

### Core Components

- [Base Policy](Base-Policy.md) - Core interfaces, base classes, and builders
  - `IPolicy` interface
  - `TPolicy` base class
  - `TPolicyBuilder<T>` generic builder

### Policy APIs

- [Retry Policy](Retry-Policy.md) - Automatic retry with configurable delays
  - `IRetryPolicy` interface
  - `TRetryPolicy` implementation
  - `TRetryBuilder` builder
  - `TRetryContext` context

- [Circuit Breaker Policy](CircuitBreaker-Policy.md) - Prevent cascading failures
  - `ICircuitBreakerPolicy` interface
  - `TCircuitBreakerPolicy` implementation
  - `TCircuitBreakerBuilder` builder
  - `TCircuitState` enumeration
  - `EBrokenCircuitException` exception

- [Fallback Policy](Fallback-Policy.md) - Provide alternative results
  - `IFallbackPolicy<TResult>` generic interface
  - `TFallbackPolicy<TResult>` generic implementation
  - `TFallbackBuilder<TResult>` generic builder

- [Rate Limit Policy](RateLimit-Policy.md) - Control operation rate
  - `IRateLimitPolicy` interface
  - `TRateLimitPolicy` implementation
  - `TRateLimitBuilder` builder
  - `ERateLimitRejectedException` exception

- [Timeout Policy](Timeout-Policy.md) - Abort operations that take too long
  - `ITimeoutPolicy` interface
  - `TTimeoutPolicy` implementation
  - `TTimeoutBuilder` builder
  - `TTimeoutContext` context
  - `ETimeoutRejectedException` exception

- [Bulkhead Policy](Bulkhead-Policy.md) - Limit concurrent executions
  - `IBulkheadPolicy` interface
  - `TBulkheadPolicy` implementation
  - `TBulkheadBuilder` builder
  - `EBulkheadRejectedException` exception

- [Cache Policy](Cache-Policy.md) - Cache expensive results
  - `ICachePolicy<TResult>` generic interface
  - `TCachePolicy<TResult>` generic implementation
  - `TCacheBuilder<TResult>` generic builder

- [Hedging Policy](Hedging-Policy.md) - Reduce tail latency with parallel attempts
  - `IHedgingPolicy` interface
  - `THedgingPolicy` implementation
  - `THedgingBuilder` builder
  - `THedgingContext` context

- [Policy Wrap](PolicyWrap-Policy.md) - Combine multiple policies into one
  - `IPolicyWrap` interface
  - `TPolicyWrap` implementation
  - `TPolicyWrapBuilder` builder

## Common Patterns

### Creating a Policy

All policies follow this pattern:

```pascal
var
  Policy: IPolicyType;
begin
  Policy := TPolicyBuilder.Create
    .Handle(ExceptionType)
    .ConfigMethod1(Value)
    .ConfigMethod2(Value)
    .Build;
end;
```

### Executing with a Policy

Policies provide `Execute` methods:

```pascal
// For procedures (no return value)
Policy.Execute(
  procedure
  begin
    // Your code
  end);

// For functions (with return value)
var Result := Policy.Execute(
  function: TResultType
  begin
    Result := YourFunction;
  end);
```

### Exception Handling

Configure which exceptions to handle:

```pascal
Policy := TBuilder.Create
  .Handle(EFirstException)
  .Handle(ESecondException)
  .Build;
```

## Unit Reference

| Unit | Description | Key Types |
|------|-------------|-----------|
| `Murphy.Base.Policy` | Base interfaces and classes | `IPolicy`, `TPolicy`, `TPolicyBuilder<T>` |
| `Murphy.Policy.Retry` | Retry pattern | `IRetryPolicy`, `TRetryPolicy`, `TRetryBuilder` |
| `Murphy.Policy.CircuitBreaker` | Circuit Breaker pattern | `ICircuitBreakerPolicy`, `TCircuitBreakerPolicy` |
| `Murphy.Policy.Fallback` | Fallback pattern | `IFallbackPolicy<T>`, `TFallbackPolicy<T>` |
| `Murphy.Policy.RateLimit` | Rate Limit pattern | `IRateLimitPolicy`, `TRateLimitPolicy` |
| `Murphy.Policy.Timeout` | Timeout pattern | `ITimeoutPolicy`, `TTimeoutPolicy` |
| `Murphy.Policy.Bulkhead` | Bulkhead pattern | `IBulkheadPolicy`, `TBulkheadPolicy` |
| `Murphy.Policy.Cache` | Cache pattern | `ICachePolicy<T>`, `TCachePolicy<T>` |
| `Murphy.Policy.Hedging` | Hedging pattern | `IHedgingPolicy`, `THedgingPolicy` |
| `Murphy.Policy.Wrap` | Policy Wrap (composition) | `IPolicyWrap`, `TPolicyWrap` |
| `Murphy.Services.Schedulers` | Time abstraction | `IScheduler`, `TConcreteScheduler`, `TTestScheduler` |
| `Murphy.Globals` | Global configuration | `MurphyTestModeEnabled` |

## Type Hierarchy

```
IPolicy (base interface)
  │
  ├── IExecutablePolicy (procedure Execute(AProc: TProc))
  │     │
  │     ├── IRetryPolicy
  │     ├── ICircuitBreakerPolicy
  │     ├── IRateLimitPolicy
  │     ├── ITimeoutPolicy
  │     ├── IBulkheadPolicy
  │     ├── IHedgingPolicy
  │     └── IPolicyWrap
  │
  ├── IFallbackPolicy<TResult>       (function Execute(AFunc: TFunc<TResult>): TResult)
  └── ICachePolicy<TResult>          (function Execute(AFunc: TFunc<TResult>): TResult)

TPolicy (base class)
  │
  ├── TRetryPolicy
  ├── TCircuitBreakerPolicy
  ├── TFallbackPolicy<TResult>
  ├── TRateLimitPolicy
  ├── TTimeoutPolicy
  ├── TBulkheadPolicy
  ├── TCachePolicy<TResult>
  ├── THedgingPolicy
  └── TPolicyWrap

TPolicyBuilder<TPolicy> (generic base builder)
  │
  ├── TRetryBuilder
  ├── TCircuitBreakerBuilder
  ├── TFallbackBuilder<TResult>
  ├── TRateLimitBuilder
  ├── TTimeoutBuilder
  ├── TBulkheadBuilder
  ├── TCacheBuilder<TResult>
  └── THedgingBuilder

TPolicyWrapBuilder (standalone builder, no exception filter of its own)
```

## Common Interfaces

### IPolicy

All policies implement this base interface:

```pascal
type
  IPolicy = interface
    function IsHandled(AException: Exception): Boolean;
  end;
```

**Method**:
- `IsHandled(AException)` - Returns `True` if the policy handles this exception type

### IExecutablePolicy

Policies that execute a parameterless action implement this interface, which extends `IPolicy`:

```pascal
type
  IExecutablePolicy = interface(IPolicy)
    procedure Execute(AProc: TProc);
  end;
```

**Method**:
- `Execute(AProc)` - Runs `AProc` under the policy's resilience logic

**Purpose**: Only types implementing `IExecutablePolicy` can be combined via [Policy Wrap](PolicyWrap-Policy.md). `IRetryPolicy`, `ICircuitBreakerPolicy`, `IRateLimitPolicy`, `ITimeoutPolicy`, `IBulkheadPolicy`, `IHedgingPolicy`, and `IPolicyWrap` all extend it. `IFallbackPolicy<TResult>` and `ICachePolicy<TResult>` do not, since they return a value via `TFunc<TResult>` instead.

### Execute Methods

Most policies provide Execute methods with this signature:

```pascal
// For procedures (IExecutablePolicy)
procedure Execute(AProc: TProc);

// For functions (IFallbackPolicy<TResult>, ICachePolicy<TResult>)
function Execute(AFunc: TFunc<TResult>): TResult;
```

## Exception Types

Murphy defines these custom exceptions:

| Exception | Thrown By | Meaning |
|-----------|-----------|---------|
| `EBrokenCircuitException` | Circuit Breaker | Circuit is open or isolated |
| `ERateLimitRejectedException` | Rate Limit | Rate limit exceeded |
| `ETimeoutRejectedException` | Timeout | Operation exceeded its timeout duration |
| `EBulkheadRejectedException` | Bulkhead | No execution slots available |

## Global Variables

### MurphyTestModeEnabled

**Unit**: `Murphy.Globals`

**Type**: `Boolean`

**Default**: `False`

**Purpose**: Enable test mode to disable actual delays (for unit testing)

**Usage**:
```pascal
uses Murphy.Globals;

procedure SetupTest;
begin
  MurphyTestModeEnabled := True;
end;

procedure TeardownTest;
begin
  MurphyTestModeEnabled := False;
end;
```

## Detailed Documentation

Click on any of the links below for complete API documentation:

- **[Base Policy API](Base-Policy.md)** - Foundation for all policies
- **[Retry Policy API](Retry-Policy.md)** - Retry pattern implementation
- **[Circuit Breaker Policy API](CircuitBreaker-Policy.md)** - Circuit breaker pattern
- **[Fallback Policy API](Fallback-Policy.md)** - Fallback pattern
- **[Rate Limit Policy API](RateLimit-Policy.md)** - Rate limiting pattern
- **[Timeout Policy API](Timeout-Policy.md)** - Timeout pattern
- **[Bulkhead Policy API](Bulkhead-Policy.md)** - Bulkhead pattern
- **[Cache Policy API](Cache-Policy.md)** - Cache pattern
- **[Hedging Policy API](Hedging-Policy.md)** - Hedging pattern
- **[Policy Wrap API](PolicyWrap-Policy.md)** - Policy composition

## See Also

- [Pattern Guides](../Home.md#pattern-guides) - Usage guides with examples
- [Architecture](../04-Architecture.md) - Internal design and extension points
- [Getting Started](../02-Getting-Started.md) - Quick start guide

---

[← Architecture](../04-Architecture.md) | [Back to Index](../Home.md) | [Base Policy →](Base-Policy.md)