Resilience Patterns Documentation

https://failsafe-go.dev
Admin
This documentation provides comprehensive guides and explanations for implementing various...
Tokens:15,799
Snippets:272
Trust Score:5.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Create and Use Adaptive Throttler

Source: https://failsafe-go.dev/adaptive-throttler

Demonstrates how to create an AdaptiveThrottler with specific failure handling and rate thresholds, and then use it with Failsafe to get data.

```go
throttler := adaptivethrottler.NewBuilder[string]().
  HandleErrors(ErrConnecting).
  WithFailureRateThreshold(0.1, 5, time.Minute).
  WithMaxRejectionRate(.9).
  Build()

// Get with adaptive throttling
response, err := failsafe.With(throttler).Get(FetchData)
```

--------------------------------

### Get Async with Retries

Source: https://failsafe-go.dev/async-execution

Retrieve a result asynchronously with a retry policy. The Get() method blocks until the execution completes and returns the result or an error.

```go
// Get asynchronously with retries
result := failsafe.With(retryPolicy).GetAsync(Connect)
connection, err := result.Get()
```

--------------------------------

### Get Remaining Delay

Source: https://failsafe-go.dev/circuit-breaker

Retrieves the remaining delay before the circuit breaker transitions from open to half-open.

```go
breaker.RemainingDelay()
```

--------------------------------

### Get a Result with Retries

Source: https://failsafe-go.dev/

Retrieves a result from a function using the configured retry policy. Useful for operations that return a value upon success.

```go
// Get with retries
response, err := failsafe.With(retryPolicy).Get(SendRequest)
```

--------------------------------

### Get Execution Info During Retry

Source: https://failsafe-go.dev/execution-info

Access execution details like the number of attempts within a Failsafe-Go execution. Useful for logging or conditional logic during retries.

```go
failsafe.With(retryPolicy).RunWithExecution(func(e failsafe.Execution[any]) error {
  logger.Info("Connecting", "attempts", e.Attempts())
  return Connect()
})

```

--------------------------------

### Create and Use AdaptiveLimiter

Source: https://failsafe-go.dev/adaptive-limiter

Demonstrates how to create an AdaptiveLimiter with various configurations and use it within a Failsafe execution.

```go
limiter := adaptivelimiter.NewBuilder[string]().
  WithLimits(1, 100, 20).
  WithRecentWindow(time.Second, 30*time.Second, 50).
  WithBaselineWindow(10).
  WithQueueing(2, 3).
  Build()

// Get with adaptive limiting
response, err := failsafe.With(limiter).Get(FetchData)

```

--------------------------------

### Create and Use a Hedge Policy

Source: https://failsafe-go.dev/hedge

Demonstrates how to create a HedgePolicy with a 1-second delay and a maximum of 2 hedges, then use it to run a request.

```go
// Hedge up to 2 times with a 1 second delay between attempts
hedgePolicy := hedgepolicy.NewBuilderWithDelay[any](time.Second).
  WithMaxHedges(2).
  Build()
  
// Run with hedges
err := failsafe.With(hedgePolicy).Run(SendRequest)

```

--------------------------------

### Create and Use a Basic Bulkhead

Source: https://failsafe-go.dev/bulkhead

Create a bulkhead to permit a fixed number of concurrent executions and use it with Failsafe.

```go
// Permit 10 concurrent executions
bulkhead := bulkhead.New[any](10)
err := failsafe.With(bulkhead).Run(SendRequest)
```

--------------------------------

### Get a Result Asynchronously with Retries

Source: https://failsafe-go.dev/

Retrieves a result from a function asynchronously with retries. The ExecutionResult allows waiting for completion and retrieving the outcome.

```go
// Get asynchronously with retries
result := failsafe.With(retryPolicy).GetAsync(SendRequest)
```

--------------------------------

### Execute with Fallback Policy

Source: https://failsafe-go.dev/fallback

Demonstrates how to use a configured Fallback policy within the Failsafe execution flow.

```go
connection, err := failsafe.With(fallback).Get(Connect)
```

--------------------------------

### Create and Use a Retry Policy

Source: https://failsafe-go.dev/retry

Demonstrates how to create a retry policy that handles specific errors and retries up to a certain number of times with a fixed delay. It then shows how to apply this policy to an execution.

```go
// Retry on ErrConnecting up to 3 times with a 1 second delay between attempts
retryPolicy := retrypolicy.NewBuilder[Connection]().
  HandleErrors(ErrConnecting).
  WithDelay(time.Second).
  WithMaxRetries(3).
  Build()
  
// Get with retries
connection, err := failsafe.With(retryPolicy).Get(Connect)

```

--------------------------------

### Get Last Result During Retry

Source: https://failsafe-go.dev/execution-info

Retrieve the last result from a Failsafe-Go execution. This is helpful when subsequent executions depend on the outcome of previous ones.

```go
failsafe.With(retryPolicy).GetWithExecution(func(e failsafe.Execution[int]) (int, error) {
  return e.LastResult() + 1, nil
})

```

--------------------------------

### Create and Use a Cache Policy with a Fixed Key

Source: https://failsafe-go.dev/cache

Demonstrates how to create a cache policy with a fixed key and use it to cache and retrieve execution results. This is useful for consistently caching results under a specific identifier.

```go
// Store connections under the "connection" key in the cache
cachePolicy := cachePolicy.NewBuilder(cache).
  WithKey("connection").
  Build()
  
// Get a connection from the cache, else create a new one
connection, err := failsafe.With(cachePolicy).Get(Connect)
```

--------------------------------

### Create a Prioritizer with Usage Tracking

Source: https://failsafe-go.dev/execution-prioritization

Configure a Prioritizer to track individual user usage, enabling throttling of higher-usage users during overload.

```go
prioritizer := adaptivelimiter.NewPrioritizerBuilder().
  WithUsageTracker(priority.NewUsageTracker()).
  Build()
```

--------------------------------

### Configure Min, Max, and Initial Limits

Source: https://failsafe-go.dev/adaptive-limiter

Sets the minimum, maximum, and initial concurrency limits for the adaptive limiter.

```go
builder.WithLimits(1, 100, 20)

```

--------------------------------

### Timeout Composed Inside RetryPolicy

Source: https://failsafe-go.dev/timeout

Illustrates a Timeout composed inside a RetryPolicy. Each attempt gets its own timeout, and a timeout occurrence does not automatically cancel outer retries. This allows for retrying an operation that might individually time out.

```go
failsafe.With(retryPolicy, timeout).Run(Connect)
```

--------------------------------

### Create a Prioritizer

Source: https://failsafe-go.dev/execution-prioritization

Instantiate a Prioritizer and schedule its calibrations to manage execution priorities.

```go
prioritizer := adaptivelimiter.NewPrioritizer()
prioritizer.ScheduleCalibrations(ctx, time.Second)
```

--------------------------------

### Create and Use a Circuit Breaker

Source: https://failsafe-go.dev/circuit-breaker

Demonstrates how to create a circuit breaker with specific failure and success thresholds, and then use it to wrap an execution.

```go
breaker := circuitbreaker.NewBuilder[any]().
  HandleErrors(ErrSending).
  WithFailureThreshold(5).
  WithDelay(time.Minute).
  WithSuccessThreshold(2).
  Build()
  
err := failsafe.With(breaker).Run(SendMessage)
```

--------------------------------

### Execute with Priority and Usage Tracking

Source: https://failsafe-go.dev/execution-prioritization

Perform executions with both priority and user context to enable adaptive limiting and usage-based throttling.

```go
ctx := priority.High.AddTo(context.Background())
ctx = priority.ContextWithUser(ctx, "user1")
executor := failsafe.With(limiter).WithContext(ctx)

// Get with adaptive limiting and usage tracking
response, err := executor.Get(FetchData)
```

--------------------------------

### Create and Use a Timeout

Source: https://failsafe-go.dev/timeout

Demonstrates how to create a new timeout and use it within a Failsafe execution. The timeout is set for 10 seconds.

```go
import (
	"time"
	"github.com/failsafe-go/failsafe-go"
	"github.com/failsafe-go/failsafe-go/timeout"
)

// Timeout after 10 seconds
timeout := timeout.New[any](10*time.Second)
err := failsafe.With(timeout).Run(Connect)
```

--------------------------------

### Use Cache Policy with Execution-Time Cache Key

Source: https://failsafe-go.dev/cache

Shows how to use a cache policy with a cache key provided at execution time via a Context. This allows for different cache keys to be used for different executions of the same policy.

```go
ctx := cache.ContextWithCacheKey(context.Background(), "connection")
connection, err := failsafe.With(cachePolicy).WithContext(ctx).Get(Connect)
```

--------------------------------

### Configure Queueing with Rejection Factors

Source: https://failsafe-go.dev/adaptive-limiter

Enables queueing for executions and configures initial and maximum rejection factors to gradually reject executions as the queue fills up.

```go
builder.WithQueueing(2, 3)

```

--------------------------------

### Configure Failure Handling

Source: https://failsafe-go.dev/retry

Shows how to configure a retry policy to handle specific errors or results as failures that should trigger a retry.

```go
builder.
  HandleErrors(ErrConnecting).
  HandleResult(nil)

```

--------------------------------

### Configure Budget for Retries

Source: https://failsafe-go.dev/retry

Illustrates how to add a budget to a retry policy to control the maximum number of outstanding retries across a system.

```go
builder.WithBudget(budget)

```

--------------------------------

### Composing Specific Policy around 'any' Policy

Source: https://failsafe-go.dev/type-safety

Shows how to compose a policy with a specific result type (Connection) around a policy with 'any' as the result type.

```go
circuitBreaker := circuitbreaker.NewWithDefaults[any]()
retryPolicy := retrypolicy.NewWithDefaults[Connection]()

// Compose RetryPolicy[Connection] around CircuitBreaker[any]
failsafe.With(retryPolicy).ComposeAny(circuitBreaker)
```

--------------------------------

### Configure Abort Conditions

Source: https://failsafe-go.dev/retry

Shows how to configure specific results, errors, or conditions that should cause retries to abort immediately.

```go
builder.
  AbortOnResult(true)
  AbortOnErrors(context.Canceled)
  AbortIf(AbortCondition)

```

--------------------------------

### Composing 'any' Policy around Specific Policy

Source: https://failsafe-go.dev/type-safety

Illustrates composing a policy with 'any' as the result type around a policy with a specific result type (Connection).

```go
// Compose CircuitBreaker[any] around RetryPolicy[Connection]
failsafe.WithAny[Connection](circuitBreaker).Compose(retryPolicy)
```

--------------------------------

### Try Acquiring Permit Standalone

Source: https://failsafe-go.dev/rate-limiter

Manually attempt to acquire a permit from a rate limiter. Returns true if a permit was acquired immediately.

```go
if rateLimiter.TryAcquirePermit() {
  DoSomething()
}

```

--------------------------------

### Compose Policies with Variadic Arguments

Source: https://failsafe-go.dev/policies

Compose multiple policies by passing them as variadic arguments to With. This offers a more concise syntax for policy composition.

```go
failsafe.With(fallback, retryPolicy, circuitBreaker, timeout).Get(fn)
```

--------------------------------

### Acquire Permit with Priority

Source: https://failsafe-go.dev/execution-prioritization

Use a limiter in a standalone manner to acquire a permit with a specified priority.

```go
permit, err := limiter.AcquirePermitWithPriority(ctx, priority.High)
```

--------------------------------

### Configure Exponential Backoff Delay

Source: https://failsafe-go.dev/retry

Shows how to configure a delay that increases exponentially between retry attempts.

```go
builder.WithBackoff(time.Second, 30*time.Second)

```

--------------------------------

### Configure Bulkhead with Max Wait Time

Source: https://failsafe-go.dev/bulkhead

Configure a bulkhead to wait for execution permission for a specified duration, ensuring fairness.

```go
// Wait up to 1 second for execution permission
bulkhead := bulkhead.NewBuilder[any](10).
  WithMaxWaitTime(time.Second).
  Build()
```

--------------------------------

### Basic Execution with Any Result Type

Source: https://failsafe-go.dev/type-safety

Demonstrates a basic Failsafe execution where the result type is 'any'. This is useful when the specific return type of the execution does not matter.

```go
retryPolicy := retrypolicy.NewWithDefaults[any]()
err := failsafe.With(retryPolicy).Run(Connect)
```

--------------------------------

### Build a Prioritized Limiter

Source: https://failsafe-go.dev/execution-prioritization

Create an adaptive limiter that utilizes a Prioritizer for prioritized rejection when overloaded.

```go
limiter := adaptivelimiter.NewBuilder[any]().BuildPrioritized(prioritizer)
```

--------------------------------

### Configure Fixed Delay

Source: https://failsafe-go.dev/retry

Demonstrates setting a fixed delay between retry attempts.

```go
builder.WithDelay(time.Second)

```

--------------------------------

### Create and Use Smooth Rate Limiter

Source: https://failsafe-go.dev/rate-limiter

Create a smooth rate limiter that permits a specified number of executions per time period. Use it with Failsafe to control execution rates.

```go
// Permits 100 executions per second
limiter := ratelimiter.NewSmooth(100, time.Second)
err := failsafe.With(limiter).Run(SendMessage)

```

--------------------------------

### Create a New Budget

Source: https://failsafe-go.dev/execution-budgets

Allows up to 25% retries or hedges by default, with a minimum of 5 in progress. Use when you need to limit concurrent retries or hedges.

```go
budget := budget.NewBuilder().
  WithMaxRate(.25).
  WithMinConcurrency(5).
  Build()
```

--------------------------------

### HTTP Client with Priority Propagation

Source: https://failsafe-go.dev/http

Create an http.Client with a RoundTripper that supports propagating execution priority or level information from the context through outgoing requests. Pass nil as the first argument if no specific transport is needed initially.

```go
client := &http.Client{
  Transport: failsafehttp.NewRoundTripperWithLevel(nil),
}

```

--------------------------------

### Create Fallback with Alternative Error

Source: https://failsafe-go.dev/fallback

Instantiate a Fallback policy that will return a predefined error upon failure.

```go
fallback := fallback.NewWithError(ErrConnecting)
```

--------------------------------

### Acquire and Release Permit in Standalone Mode

Source: https://failsafe-go.dev/adaptive-limiter

Manually acquires a permit from the limiter, records its success or failure, and releases it. Handles potential errors during acquisition and execution.

```go
permit, err := limiter.AcquirePermit(ctx)
if err != nil {
  return err
}

if err := sendRequest(); err != nil {
  permit.Drop()
  return err
}
permit.Record()

```

--------------------------------

### Create Fallback with Alternative Result

Source: https://failsafe-go.dev/fallback

Instantiate a Fallback policy that will return a predefined result upon failure.

```go
fallback := fallback.NewWithResult(defaultResult)
```

--------------------------------

### Configure Return Last Failure

Source: https://failsafe-go.dev/retry

Shows how to configure a retry policy to return the last execution result and error directly, instead of wrapping them in an `ExceededError`.

```go
builder.ReturnLastFailure()

```

--------------------------------

### Configure Time-Based Jitter

Source: https://failsafe-go.dev/retry

Shows how to apply a time-based jitter to the delay between retry attempts.

```go
builder.WithJitter(100*time.Second)

```

--------------------------------

### Configure Baseline Window

Source: https://failsafe-go.dev/adaptive-limiter

Sets the average age of values in the baseline window, influencing how quickly the limiter adapts to changes in load.

```go
builder.WithBaselineWindow(10)

```

--------------------------------

### Create gRPC Server InHandle for Load Limiting

Source: https://failsafe-go.dev/grpc

On the server side, use load limiting or time limiting policies to create a failsafe ServerInHandle.

```go
inTapHandle := failsafegrpc.NewServerInHandle[any](bulkhead, timeout)
server := grpc.NewServer(grpc.InTapHandle(inTapHandle))
```

--------------------------------

### Configure Rate Limiter to Wait

Source: https://failsafe-go.dev/rate-limiter

Configure a rate limiter to wait for execution permission for a maximum duration instead of immediately failing when exceeded.

```go
// Wait up to 1 second for execution permission
builder.WithMaxWaitTime(time.Second)

```

--------------------------------

### Handle Bulkhead Full Event

Source: https://failsafe-go.dev/bulkhead

Register an event listener to be notified when the bulkhead is full, allowing for custom error handling or logging.

```go
builder.OnBulkheadFull(func(e failsafe.ExecutionEvent[any]) {
  logger.Error("Bulkhead full")
})
```

--------------------------------

### Configure Delay Function

Source: https://failsafe-go.dev/retry

Shows how to provide a custom function to compute the delay between retry attempts based on execution results or errors.

```go
builder.WithDelayFunc(ComputeDelay)

```

--------------------------------

### Standalone Adaptive Throttler Operation

Source: https://failsafe-go.dev/adaptive-throttler

Demonstrates manually operating an AdaptiveThrottler outside of the Failsafe execution flow. It shows acquiring a permit, performing an action, and recording success or error.

```go
if throttler.TryAcquirePermit() {
  if err := doSomething(); err != nil {
    throttler.RecordError(err)
  else {
    throttler.RecordSuccess()
  }
}
```

--------------------------------

### Recommended Policy Composition Order

Source: https://failsafe-go.dev/policies

A common ordering for composing resilience policies, placing Fallback as the outer-most and Timeout as the inner-most.

```go
failsafe.With(fallback, cachePolicy, retryPolicy, circuitBreaker, bulkhead, timeout)
```

--------------------------------

### Create Fallback with Function

Source: https://failsafe-go.dev/fallback

Instantiate a Fallback policy that computes an alternative result or error using a provided function.

```go
fallback := fallback.NewWithFunc(func(e failsafe.Execution[Connection]) (Connection, error) {
  return ConnectToBackup(backupConfig)
})
```

--------------------------------

### Execute with Priority

Source: https://failsafe-go.dev/execution-prioritization

Add priority information to the context to perform executions with a specific priority using a prioritized limiter.

```go
ctx := priority.High.AddTo(context.Background())
executor := failsafe.With(limiter).WithContext(ctx)

// Get with adaptive limiting, using high priority
response, err := executor.Get(FetchData)
```

--------------------------------

### Create and Use Bursty Rate Limiter

Source: https://failsafe-go.dev/rate-limiter

Create a bursty rate limiter that permits a specified number of executions per time period. This allows for bursts of executions at the beginning of each period.

```go
// Permits 10 executions per second
limiter := ratelimiter.NewBursty(10, time.Second)
err := failsafe.With(limiter).Run(SendMessage)

```

--------------------------------

### Enable Debug Logging for Prioritizer

Source: https://failsafe-go.dev/execution-prioritization

Provide an slog.Logger to the Prioritizer builder to enable debug logging for threshold changes.

```go
builder.WithLogger(logger)
```

--------------------------------

### Configure Fallback Failure Handling

Source: https://failsafe-go.dev/fallback

Configure a Fallback policy to handle specific errors and results as failures. This is useful when composing policies or handling errors from inner policies.

```go
builder.HandleErrors(ErrConnecting, retrypolicy.ErrExceeded).HandleResult(nil)
```

--------------------------------

### Configure Executor with Context

Source: https://failsafe-go.dev/execution-info

Create a Failsafe-Go executor configured with a context. This context can then be accessed via an Execution or any event within the execution flow.

```go
executor := failsafe.With(retryPolicy).WithContext(ctx)

```

--------------------------------

### Create and Use a Reusable Executor

Source: https://failsafe-go.dev/

Saves a composition of resilience policies into an Executor for reuse. Allows consistent application of policies to multiple function calls.

```go
executor := failsafe.With(retryPolicy, circuitBreaker)
err := executor.Run(Connect)
```

--------------------------------

### Create Smooth Rate Limiter with Max Rate

Source: https://failsafe-go.dev/rate-limiter

Create a smooth rate limiter by directly specifying the maximum rate of individual executions, ensuring executions are permitted at or below this rate.

```go
// Permits an execution every 10 milliseconds
limiter := ratelimiter.NewSmoothWithMaxRate(10*time.Millisecond)

```

--------------------------------

### Configure Dynamic Hedging Delay

Source: https://failsafe-go.dev/hedge

Configures a dynamic delay for hedging based on a function that calculates latency, ensuring hedges target long-tail requests.

```go
hedgePolicy := hedgepolicy.NewBuilderWithDelayFunc[any](
  func(exec failsafe.ExecutionAttempt[any]) time.Duration {
    return p95Latency()  
  }).
  WithMaxHedges(2).
  Build()

```

--------------------------------

### Configure Max Duration

Source: https://failsafe-go.dev/retry

Explains how to set a maximum duration for an execution, after which retries will stop even if the maximum attempts have not been reached.

```go
builder.WithMaxDuration(5*time.Minute)

```

--------------------------------

### Configure Correlation Window

Source: https://failsafe-go.dev/adaptive-limiter

Sets the number of recent throughput and inflight measurements to store for overload detection.

```go
builder.WithCorrelationWindow(50)

```

--------------------------------

### Execution with Specific Result Type and Event Listener

Source: https://failsafe-go.dev/type-safety

Illustrates executing a request with a specific result type (*http.Response) and attaching an OnSuccess event listener to log the status code.

```go
response, err := failsafe.With(retryPolicy).
  OnSuccess(func(e failsafe.ExecutionDoneEvent[*http.Response]) {
    logger.Info("Request sent", "statusCode", e.Result.StatusCode)
  }).
  Get(SendHttpRequest)
```

--------------------------------

### Reserve Permit Standalone with Scheduler

Source: https://failsafe-go.dev/rate-limiter

Reserve a permit from a rate limiter and schedule a function to execute after the permit is available, using an external scheduler.

```go
permitWaitTime := rateLimiter.ReservePermit()
scheduler.Schedule(SomeFunc, permitWaitTime)

```

--------------------------------

### Configure Recent Quantile

Source: https://failsafe-go.dev/adaptive-limiter

Specifies the quantile of recent execution times to use when comparing against the baseline for overload detection.

```go
builder.WithRecentQuantile(.5)

```

--------------------------------

### Enable Debug Logging

Source: https://failsafe-go.dev/adaptive-limiter

Provides an slog.Logger instance to the builder to enable debug logging for AdaptiveLimiter limit changes.

```go
builder.WithLogger(logger)

```

--------------------------------

### Handle Specific Errors and Results

Source: https://failsafe-go.dev/policies

Configure policies to handle specific errors, error types, or results. This allows for fine-grained control over failure conditions.

```go
builder.
  HandleErrors(ErrClosed, ErrShutdown).
  HandleErrorTypes(net.OpError{}, new(net.Error)).
  HandleResult(nil)
```

--------------------------------

### Configure Delay Before Half-Opening

Source: https://failsafe-go.dev/circuit-breaker

Configures the delay duration before the circuit breaker transitions from open to half-open state.

```go
builder.WithDelay(30*time.Second)
```

--------------------------------

### Create a Retry Policy

Source: https://failsafe-go.dev/

Defines a retry policy that handles specific errors, sets a delay between retries, and limits the maximum number of retries.

```go
retryPolicy := retrypolicy.NewBuilder[SomeResponse]().
  HandleErrors(ErrConnecting).
  WithDelay(time.Second).
  WithMaxRetries(3).
  Build()
```

--------------------------------

### Configure Random Delay

Source: https://failsafe-go.dev/retry

Illustrates setting a random delay within a specified range between retry attempts.

```go
builder.WithRandomDelay(time.Second, 10*time.Second)

```

--------------------------------

### Apply Budget to Hedge Policy

Source: https://failsafe-go.dev/execution-budgets

Applies a budget to a hedge policy. Use the same budget for retries and hedges if desired to manage overall concurrency.

```go
hedgePolicy := hedgepolicy.NewBuilderWithDelay[any](time.Second).
  WithBudget(budget).
  Build()

// Run with budgeted hedges
err := failsafe.With(hedgePolicy).Run(SendRequest)
```

--------------------------------

### Composing Policies with Same Specific Result Type

Source: https://failsafe-go.dev/type-safety

Demonstrates composing multiple policies (retry and circuit breaker) that share the same specific result type (*http.Response).

```go
circuitBreaker := circuitbreaker.NewWithDefaults[*http.Response]()
response, err := failsafe.With(retryPolicy, circuitBreaker).Get(SendHttpRequest)
```

--------------------------------

### Configure Recent Execution Window

Source: https://failsafe-go.dev/adaptive-limiter

Sets the duration and sampling requirements for the recent execution time window used to detect overload.

```go
builder.WithRecentWindow(time.Second, 30*time.Second, 50)

```

--------------------------------

### HTTP Server Handler with Priority Propagation

Source: https://failsafe-go.dev/http

Create an http.Handler that supports propagating execution priority or level information. The boolean argument controls whether a level should be generated if one does not exist.

```go
handler := failsafehttp.NewHandlerWithLevel(innerHandler, true)

```

--------------------------------

### Compose Policies Sequentially

Source: https://failsafe-go.dev/policies

Compose multiple policies around a function using sequential calls. The inner-most policy handles the function result first.

```go
failsafe.With(fallback).
  Compose(retryPolicy).
  Compose(circuitBreaker).
  Compose(timeout).
  Get(fn)
```

--------------------------------

### Standalone Circuit Breaker Operations

Source: https://failsafe-go.dev/circuit-breaker

Demonstrates manual control over circuit breaker states and recording execution results.

```go
breaker.Open()
breaker.HalfOpen()
breaker.Close()

if breaker.TryAcquirePermit() {
  if err := doSomething(); err != nil {
    breaker.RecordError(err)
  else {
    breaker.RecordSuccess()
  }
}
```

--------------------------------

### Configure Max Retries

Source: https://failsafe-go.dev/retry

Demonstrates setting the maximum number of retries allowed for a retry policy, which is distinct from the total number of attempts.

```go
builder.WithMaxRetries(2)

```

--------------------------------

### Create gRPC Server Unary Interceptor

Source: https://failsafe-go.dev/grpc

Create a failsafe UnaryServerInterceptor for a policy composition.

```go
interceptor := failsafegrpc.NewUnaryServerInterceptor[SomeResponse](retryPolicy, circuitBreaker)
server := grpc.NewServer(target, grpc.UnaryInterceptor(interceptor))
```

--------------------------------

### Configure Max Hedges

Source: https://failsafe-go.dev/hedge

Sets the maximum number of hedged executions to perform. By default, only one hedged execution is performed.

```go
builder.WithMaxHedges(2)

```

--------------------------------

### Policy OnSuccess and OnFailure Listeners

Source: https://failsafe-go.dev/event-listeners

Register listeners for policy-specific success and failure events. These indicate if an attempt succeeded or failed according to the policy's configuration.

```go
policyBuilder.
  OnSuccess(func(e failsafe.ExecutionEvent[Connection]) {
    logger.Info("Connected", "connection", e.LastResult())
  }).
  OnFailure(func(e failsafe.ExecutionEvent[Connection]) {
    logger.Error("Failed to create connection", "error", e.LastError())
  })
```

--------------------------------

### Configure Jitter Factor

Source: https://failsafe-go.dev/retry

Demonstrates adding a random jitter factor to the delay between retry attempts.

```go
builder.WithJitterFactor(.1)

```

--------------------------------

### Add Retry Event Listener

Source: https://failsafe-go.dev/retry

Demonstrates how to add an event listener to a retry policy to be notified when a retry is scheduled, about to be attempted, or when retries are exceeded or aborted.

```go
builder.OnRetry(func(e failsafe.ExecutionEvent[any]) {
  logger.Error("Retrying after error", "error", e.LastError())
})

```

--------------------------------

### Specific Result Type with Retry Policy

Source: https://failsafe-go.dev/type-safety

Shows how to configure a retry policy with a specific result type (*http.Response). This allows handling specific response codes and logging on failure.

```go
retryPolicy := retrypolicy.NewBuilder[*http.Response]().
  HandleIf(func(response *http.Response, err error) bool {
    return response != nil && response.StatusCode == 500
  }).
  OnFailure(func(e failsafe.ExecutionEvent[*http.Response]) {
    logger.Error("Failed attempt", "statusCode", e.LastResult().StatusCode)
  }).
  Build()
```

--------------------------------

### Timeout Event Listener

Source: https://failsafe-go.dev/timeout

Demonstrates how to attach an event listener to be notified when a timeout is exceeded. This allows for custom handling, such as logging, when an execution takes too long.

```go
builder.OnTimeoutExceeded(func(e failsafe.ExecutionEvent[Connection]) {
  logger.Error("Connection timed out")
})
```

--------------------------------

### Configure Max Attempts

Source: https://failsafe-go.dev/retry

Illustrates how to set the maximum number of execution attempts for a retry policy. This can be a specific number or disabled by setting it to -1.

```go
builder.WithMaxAttempts(3)

```

--------------------------------

### Configure Min Concurrency for Budget

Source: https://failsafe-go.dev/execution-budgets

Sets the minimum number of concurrent executions that can be retries or hedges. Ensures a baseline level of retries/hedges are allowed.

```go
builder.WithMinConcurrency(5)
```

--------------------------------

### Compose Multiple Resilience Policies

Source: https://failsafe-go.dev/

Combines fallback, retry, circuit breaker, and timeout policies to enhance resilience. The order of policies is significant.

```go
fallback := fallback.NewWithResult(backupConnection)
circuitBreaker := circuitbreaker.NewWithDefaults[Connection]()
timeout := timeout.New[Connection](10*time.Second)

// Get with fallback, retries, circuit breaker, and timeout
connection, err := failsafe.With(fallback, retryPolicy, circuitBreaker, timeout).Get(Connect)
```

--------------------------------

### Configure Failure Threshold Ratio

Source: https://failsafe-go.dev/circuit-breaker

Sets the circuit breaker to open when a specific ratio of recent executions have failed.

```go
builder.WithFailureThresholdRatio(3, 5)
```

--------------------------------

### Circuit Breaker with Retry-After Delay

Source: https://failsafe-go.dev/http

Configure a circuit breaker to respect the Retry-After header in HTTP responses. The HandleIf function identifies retryable responses (e.g., 429 Too Many Requests), and WithDelayFunc uses the failsafehttp.DelayFunc to implement the delay.

```go
circuitBreaker := circuitbreaker.NewBuilder[*http.Response]().
  HandleIf(func(response *http.Response, err error) bool {
    return response != nil && response.StatusCode == 429
  }).
  WithDelayFunc(failsafehttp.DelayFunc).
  Build()

```

--------------------------------

### Configure Max Rate for Budget

Source: https://failsafe-go.dev/execution-budgets

Sets the maximum rate of retries or hedges permitted before rejections occur. Use to control the proportion of executions that can be retries or hedges.

```go
builder.WithMaxRate(.5)
```

--------------------------------

### Configure Max Limit Factor Decay

Source: https://failsafe-go.dev/adaptive-limiter

Applies a decay to the max limit factor, reducing headroom for bursts as inflight executions increase.

```go
builder.WithMaxLimitFactorDecay(1)

```

--------------------------------

### Add Event Listener for Hedge Attempts

Source: https://failsafe-go.dev/hedge

Registers an event listener to be notified when a hedge is about to be attempted, allowing for logging or other actions.

```go
builder.OnHedge(func(e failsafe.ExecutionEvent[any]) {
  logger.Error("Hedging after error", "error", e.LastError())
})

```

--------------------------------

### Configure Failure Rate Threshold

Source: https://failsafe-go.dev/adaptive-throttler

Sets the failure rate threshold for the AdaptiveThrottler, specifying the percentage of failures, minimum executions, and time period before rejections begin.

```go
// Starts rejecting at 10% failures per minute, after 10 executions
builder.WithFailureRateThreshold(.1, 10, time.Minute)
```

--------------------------------

### Configure Success Threshold Ratio

Source: https://failsafe-go.dev/circuit-breaker

Sets the circuit breaker to close again if a specific ratio of recent trial executions succeed.

```go
builder.WithSuccessThresholdRatio(3, 5)
```

--------------------------------

### Apply Budget to Retry Policy

Source: https://failsafe-go.dev/execution-budgets

Applies a budget to a retry policy. Ensure the budget is shared across retries in your system for effective overload prevention.

```go
retryPolicy := retrypolicy.NewBuilder[any]().
  WithBudget(budget).
  Build()

// Run with budgeted retries
err := failsafe.With(retryPolicy).Run(SendRequest)
```

--------------------------------

### Standalone Bulkhead Permit Acquisition

Source: https://failsafe-go.dev/bulkhead

Manually acquire and release permits from a bulkhead for fine-grained control over resource access.

```go
if bulkhead.TryAcquirePermit() {
  doSomething()
  bulkhead.ReleasePermit()
}
```

--------------------------------

### Configure Cancellation Conditions for Hedges

Source: https://failsafe-go.dev/hedge

Specifies conditions under which outstanding hedges should be canceled. By default, any successful result cancels hedges.

```go
builder.
  CancelOnResult(true).
  CancelOnError(ErrConnecting).
  CancelIf(CancelCondition)

```

--------------------------------

### Cancel Execution with Context Timeout

Source: https://failsafe-go.dev/execution-cancellation

Integrate Failsafe-Go with Go's context package to cancel executions. The execution will be canceled when the provided context is done.

```go
ctx, _ := context.WithTimeout(context.Background(), time.Second)

// Connect will be canceled by the ctx after 1 second
failsafe.With(retryPolicy).WithContext(ctx).Get(Connect)
```

--------------------------------

### Create gRPC Client Unary Interceptor

Source: https://failsafe-go.dev/grpc

Create a failsafe UnaryClientInterceptor for a policy composition to handle errors, limit load, or limit execution time.

```go
interceptor := failsafegrpc.NewUnaryClientInterceptor[SomeResponse](retryPolicy, circuitBreaker)
client, err := grpc.NewClient(target, grpc.WithUnaryInterceptor(interceptor))

// Perform an RPC with retries and circuit breaking
service := somepkg.NewSomeServiceClient(client)
service.DoSomething(ctx, request)
```

--------------------------------

### Run a Function with Retries

Source: https://failsafe-go.dev/

Executes a function with the configured retry policy applied. Suitable for operations that might fail temporarily.

```go
// Run with retries
err := failsafe.With(retryPolicy).Run(Connect)
```

--------------------------------

### Run Async with Retries

Source: https://failsafe-go.dev/async-execution

Execute a function asynchronously with a retry policy. The Error() method blocks until the execution completes and returns any error encountered.

```go
// Run asynchronously with retries
result := failsafe.With(retryPolicy).RunAsync(SendMessage)
err := result.Error()
```

--------------------------------

### HTTP Client with Failsafe RoundTripper

Source: https://failsafe-go.dev/http

Use a Failsafe RoundTripper with an http.Client to apply policies like retries and circuit breaking to all outgoing requests made by the client.

```go
client := &http.Client{
  Transport: failsafehttp.NewRoundTripper(http.DefaultTransport, retryPolicy, circuitBreaker),
}

// Get with retries and circuit breaking
client.Get("http://failsafe-go.dev")

```

--------------------------------

### Fallback with gRPC Server Interceptor

Source: https://failsafe-go.dev/grpc

A Fallback with a UnaryServerInterceptor can be used as usual since it allows an alternative result to be returned.

```go
fb := fallback.WithResult(&SomeResponse{Msg: "fallback"})
```

--------------------------------

### Configure Count-Based Failure Threshold

Source: https://failsafe-go.dev/circuit-breaker

Sets the circuit breaker to open after a successive number of executions have failed.

```go
builder.WithFailureThreshold(5)
```

--------------------------------

### Register Fallback Execution Event Listener

Source: https://failsafe-go.dev/fallback

Add an event listener to a Fallback policy to be notified when the fallback is executed. This allows for logging or other actions upon fallback.

```go
builder.OnFallbackExecuted(func(e failsafe.ExecutionDoneEvent[any]) {
  logger.Info("Fallback executed", "result", e.Result)
})
```

--------------------------------

### Build gRPC Retry Policy

Source: https://failsafe-go.dev/grpc

Build retry policies with built-in detection of retryable gRPC errors like Unavailable, DeadlineExceeded, and ResourceExhausted.

```go
retryPolicy := failsafegrpc.NewRetryPolicyBuilder().
  WithBackoff(time.Second, 30*time.Second).
  WithMaxRetries(3).
  Build()
```

--------------------------------

### Configure Time-Based Failure Threshold

Source: https://failsafe-go.dev/circuit-breaker

Sets the circuit breaker to open when a number of failures occur within a specified time period.

```go
builder.WithFailureThresholdPeriod(3, time.Minute)
```

--------------------------------

### Configure Success Threshold

Source: https://failsafe-go.dev/circuit-breaker

Sets the circuit breaker to close again if a specified number of trial executions succeed.

```go
builder.WithSuccessThreshold(5)
```

--------------------------------

### Handle ExceededError

Source: https://failsafe-go.dev/retry

Demonstrates how to handle the `ExceededError` returned when a retry policy is exhausted, allowing access to the last result and error.

```go
response, err := failsafe.With(retryPolicy).Get(SendMessage)
if ee := retrypolicy.AsExceededError(err); ee != nil {
  logger.Error("Failed to send message", "response", ee.LastResult, "err", ee.LastError)
}

```

--------------------------------

### Register Threshold Changed Listener

Source: https://failsafe-go.dev/execution-prioritization

Attach a callback function to a Prioritizer builder to be notified when the rejection threshold changes.

```go
prioritizerBuilder.OnThresholdChanged(func(e adaptivelimiter.ThresholdChangedEvent) {
  logger.Info("Threshold changed", "oldThresh", e.OldThreshold, "newThresh", e.NewThreshold)
})
```

--------------------------------

### Disable Max Attempts Limit

Source: https://failsafe-go.dev/retry

Shows how to disable the default maximum attempt limit for a retry policy by setting the value to -1.

```go
builder.WithMaxAttempts(-1)

```

--------------------------------

### Configure Max Rejection Rate

Source: https://failsafe-go.dev/adaptive-throttler

Sets the maximum rejection rate for the AdaptiveThrottler. A value less than 1 is recommended to ensure some executions still flow, allowing the throttler to detect system recovery.

```go
// Reject up to 75% of executions
builder.MaxRejectionRate(.75)
```

--------------------------------

### Configure Max Limit Factor

Source: https://failsafe-go.dev/adaptive-limiter

Sets the maximum factor by which the concurrency limit can increase relative to inflight executions.

```go
builder.WithMaxLimitFactor(5)

```

--------------------------------

### Handle Custom Conditions

Source: https://failsafe-go.dev/policies

Define custom conditions for handling failures based on response status codes or other criteria. This provides flexibility beyond standard error handling.

```go
builder.HandleIf(func(response *http.Response, err error) bool {
  return response != nil && response.StatusCode == 500
})
```

--------------------------------

### Failsafe HTTP Handler

Source: https://failsafe-go.dev/http

Create a Failsafe http.Handler by wrapping an inner handler with policies like load limiting or time limiting. This protects the server-side handler from excessive load or slow requests.

```go
handler = failsafehttp.NewHandler(innerHandler, bulkhead, timeout)

```

--------------------------------

### Configure Failure Rate Threshold

Source: https://failsafe-go.dev/circuit-breaker

Sets the circuit breaker to open when the rate of failures out of a minimum number of executions exceeds a threshold within a time period.

```go
builder.WithFailureRateThreshold(.2, 5, time.Minute)
```

--------------------------------

### Configure Failure Handling

Source: https://failsafe-go.dev/adaptive-throttler

Configures the AdaptiveThrottler to handle specific errors or results as failures. This snippet shows handling a specific error and a nil result.

```go
builder.
  HandleErrors(ErrConnecting).
  HandleResult(nil)
```

--------------------------------

### Executor OnDone Listener

Source: https://failsafe-go.dev/event-listeners

Register a listener to be called when an executor's execution is done, regardless of success or failure. Useful for general logging or metrics.

```go
failsafe.With(retryPolicy, circuitBreaker).
  OnDone(func(e failsafe.ExecutionDoneEvent[any]) {
    if e.Error != nil {
      logger.Error("Failed to create connection", "error", e.Error)
    } else {
      logger.Info("Connected", "connection", e.Result)
    }
  }).
  Get(Connect)
```

--------------------------------

### Executor OnFailure Listener

Source: https://failsafe-go.dev/event-listeners

Register a listener to be called when an executor's execution fails for any policy. Use for actions upon any failure.

```go
executor.OnFailure(func(e failsafe.ExecutionDoneEvent[*http.Response]) {
  logger.Error("Request failed")
})
```

--------------------------------

### Executor OnSuccess Listener

Source: https://failsafe-go.dev/event-listeners

Register a listener to be called when an executor's execution succeeds across all policies. Use for actions upon successful completion.

```go
executor.OnSuccess(func(e failsafe.ExecutionDoneEvent[*http.Response]) {
  logger.Info("Request succeeded")
})
```

--------------------------------

### Configure Cache Policy to Cache Conditionally

Source: https://failsafe-go.dev/cache

Configures a cache policy to only cache results when a specific condition is met. This is useful for selectively caching successful responses, like HTTP 200 OK.

```go
builder.CacheIf(func(response *http.Response, err error) bool {
  return response != nil && response.StatusCode == 200
})
```

--------------------------------

### Add Budget Exceeded Event Listener

Source: https://failsafe-go.dev/execution-budgets

Adds a listener that is notified when the budget is exceeded. Use to log or react to budget over-utilization.

```go
builder.OnBudgetExceeded(func(e budget.ExceededEvent) {
  logger.Error("Budget exceeded")
})
```

--------------------------------

### Handle Errors from Inner Policies

Source: https://failsafe-go.dev/policies

Configure an outer policy to handle errors returned by any inner policies in a composition. This is useful for centralized error management.

```go
policyBuilder.HandleErrors(
  retrypolicy.ErrExceeded,
  circuitbreaker.ErrOpen,
  timeout.ErrExceeded
)
```

--------------------------------

### Run a Function Asynchronously with Retries

Source: https://failsafe-go.dev/

Executes a function asynchronously with retries. The result is returned as an ExecutionResult that can be awaited.

```go
// Run asynchronously with retries
result := failsafe.With(retryPolicy).RunAsync(Connect)
```

--------------------------------

### Cooperative Cancellation with IsCanceled()

Source: https://failsafe-go.dev/execution-cancellation

Implement cooperative cancellation by periodically checking the IsCanceled() method within your execution logic. This allows your code to gracefully stop its work when cancellation is requested.

```go
failsafe.With(timeout).RunWithExecution(func(exec failsafe.Execution[any]) error {
  for {
    if !exec.IsCanceled() {
      if err := DoWork(); err != nil {
        return err
      }
    }
  }
  return nil
})
```

--------------------------------

### Failsafe HTTP Request

Source: https://failsafe-go.dev/http

Create a Failsafe Request to wrap an http.Request and an http.Client, allowing policies to be applied directly to a specific request. This approach handles errors that occur before the RoundTripper is invoked.

```go
failsafeRequest := failsafehttp.NewRequest(request, client, retryPolicy)

// Perform request with retries
response, err := failsafeRequest.Do()

```

--------------------------------

### Register Limit Changed and Limit Exceeded Event Listeners

Source: https://failsafe-go.dev/adaptive-limiter

Registers callbacks to be notified when the adaptive limiter's limit changes or is exceeded. Requires adaptivelimiter and failsafe packages.

```go
builder.OnLimitChanged(func(e adaptivelimiter.LimitChangedEvent) {
  logger.Info("AdaptiveLimiter limit changed", "oldLimit", e.OldLimit, "newLimit", e.NewLimit)
}).OnLimitExceeded(func(e failsafe.ExecutionEvent[any]) {
  logger.Info("AdaptiveLimiter limit exceeded")
})

```

--------------------------------

### Register Rate Limit Exceeded Listener

Source: https://failsafe-go.dev/rate-limiter

Register an event listener to be notified when a rate limit has been exceeded by an execution attempt.

```go
builder.OnRateLimitExceeded(func(e failsafe.ExecutionEvent[any]) {
  logger.Error("Rate limited")
})

```

--------------------------------

### Register Cache Event Listeners for Cache Hit and Miss

Source: https://failsafe-go.dev/cache

Adds event listeners to a cache policy to handle cache hit and miss events. This is useful for monitoring cache performance and understanding execution flow.

```go
builder.OnCacheHit(func(e failsafe.ExecutionDoneEvent[any]) {
  logger.Info("Cache hit", "result", e.Result)
}).onCacheMiss(func(e failsafe.ExecutionEvent[any]) {
  logger.Info("Cache miss")
})
```

--------------------------------

### Cooperative Cancellation with Canceled() Channel

Source: https://failsafe-go.dev/execution-cancellation

Use the Canceled() channel provided by the execution context to detect cancellation signals. This allows for non-blocking cancellation checks within a select statement.

```go
failsafe.With(timeout).RunWithExecution(func(exec failsafe.Execution[any]) error {
  for {
    select {
    case <-exec.Canceled():
      return nil
    case task := <-GetTask():
      Process(task)
    }
  }
  return nil
})
```

--------------------------------

### Cancel Connect Call with Timeout

Source: https://failsafe-go.dev/execution-cancellation

Use a timeout policy to cancel an execution after a specified duration. This is useful for preventing indefinite waits.

```go
// Cancel Connect call after 1 second
failsafe.With(timeout.New[any](time.Second)).Get(Connect)
```

--------------------------------

### Check Async Execution Completion

Source: https://failsafe-go.dev/async-execution

Detect when an asynchronous execution is complete using the Done() channel. After completion, you can retrieve the result or error.

```go
select {
case <-result.Done():
  connection, err := result.Get()
}
```

--------------------------------

### Register State Changed Listener

Source: https://failsafe-go.dev/circuit-breaker

Registers a callback function to be executed when the circuit breaker's state changes.

```go
builder.OnStateChanged(func(e circuitbreaker.StateChangedEvent) {
  logger.Info("CircuitBreaker state changed", "oldState", e.OldState, "newState", e.NewState)
})
```

--------------------------------

### Fallback with gRPC Client Interceptor

Source: https://failsafe-go.dev/grpc

When using a Fallback with a UnaryClientInterceptor, set the fallback value against the execution's LastResult() as the interceptor cannot return an alternative result.

```go
fb := fallback.WithFunc(func(exec failsafe.Execution[*SomeResponse]) (*SomeResponse, error) {
  exec.LastResult().Msg = "fallback"
  return nil, nil
})
```

--------------------------------

### Retry Policy for HTTP Failures

Source: https://failsafe-go.dev/http

Build a retry policy specifically for HTTP requests using NewRetryPolicyBuilder. This builder includes built-in detection for retryable HTTP errors and responses, and allows configuration of backoff and max retries.

```go
retryPolicy := failsafehttp.NewRetryPolicyBuilder().
  WithBackoff(time.Second, 30*time.Second).
  WithMaxRetries(3).
  Build()

```
Tokens:
Raw