Retry

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Handle temporary network issues
• Retry on specific error codes
• Implement exponential backoff

​

Installation

import "github.com/go-mizu/mizu/middlewares/retry"

​

Quick Start

app := mizu.New()

// Retry up to 3 times on 5xx errors
app.Use(retry.New(3))

​

Configuration

​

Options

​

Examples

​

Basic Retry

app.Use(retry.New(3))

​

With Backoff

app.Use(retry.WithOptions(retry.Options{
    MaxRetries: 5,
    Delay:      100 * time.Millisecond,
    MaxDelay:   5 * time.Second,
    Multiplier: 2.0, // Exponential backoff
}))

​

Specific Status Codes

app.Use(retry.WithOptions(retry.Options{
    MaxRetries: 3,
    RetryOn:    []int{502, 503, 504}, // Gateway errors only
}))

​

Custom Condition

app.Use(retry.WithOptions(retry.Options{
    MaxRetries: 3,
    RetryIf: func(c *mizu.Ctx, err error) bool {
        // Retry on timeout errors
        return errors.Is(err, context.DeadlineExceeded)
    },
}))

​

Constant Delay

app.Use(retry.WithOptions(retry.Options{
    MaxRetries: 3,
    Delay:      1 * time.Second,
    Multiplier: 1.0, // No increase
}))

​

API Reference

​

Functions

// New creates retry middleware
func New(maxRetries int) mizu.Middleware

// WithOptions creates with configuration
func WithOptions(opts Options) mizu.Middleware

​

Backoff Calculation

delay = min(initialDelay * (multiplier ^ attempt), maxDelay)

• Attempt 1: 100ms
• Attempt 2: 200ms
• Attempt 3: 400ms

​

Technical Details

​

Implementation Architecture

• Response Writer Wrapping: Each retry attempt wraps the response writer to capture the status code without committing the response until success or max retries reached
• Exponential Backoff Algorithm: Delay calculation follows the formula: delay = min(initialDelay * (multiplier ^ attempt), maxDelay)
• Retry Decision Logic: The RetryIf function receives the context, error, and current attempt number to make intelligent retry decisions
• State Management: The middleware tracks attempt count, last error, and current delay across retry iterations

​

Default Behavior

• Retries up to 3 times (4 total attempts including initial)
• Starts with 100ms delay
• Uses 2.0x multiplier for exponential backoff
• Caps maximum delay at 1 second
• Retries on any error or 5xx HTTP status codes

​

Helper Functions

• RetryOn(codes ...int): Creates a RetryIf function that retries only on specific HTTP status codes
• RetryOnError(): Creates a RetryIf function that retries only when an error is returned
• NoRetry(): Creates a RetryIf function that disables retries (useful for testing)

​

Performance Considerations

• The middleware sleeps between retries using time.Sleep, blocking the goroutine
• Response writer wrapping adds minimal overhead
• Status code capture happens in memory without additional allocations
• The OnRetry callback allows for logging and metrics without impacting retry logic

​

Best Practices

• Use exponential backoff to prevent thundering herd
• Set reasonable max retries (3-5)
• Only retry idempotent operations
• Add jitter for distributed systems
• Log retry attempts for debugging

​

Testing

​

Test Coverage

​

Related Middlewares

• circuitbreaker - Circuit breaker
• timeout - Request timeout
• idempotency - Idempotency keys