Fallback

​

Overview

• Graceful degradation
• Default responses on failure
• Service resilience

​

Installation

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

​

Quick Start

app := mizu.New()

// Return cached data on error
app.Use(fallback.New(func(c *mizu.Ctx) error {
    return c.JSON(200, cachedResponse)
}))

​

Configuration

​

Options

​

Examples

​

Basic Fallback

app.Use(fallback.New(func(c *mizu.Ctx) error {
    return c.JSON(200, map[string]string{
        "message": "Service temporarily unavailable",
        "status":  "degraded",
    })
}))

​

On Specific Errors

app.Use(fallback.WithOptions(fallback.Options{
    Handler: fallbackHandler,
    OnError: func(err error) bool {
        return errors.Is(err, ErrDatabaseUnavailable)
    },
}))

​

On Status Codes

app.Use(fallback.WithOptions(fallback.Options{
    Handler:  fallbackHandler,
    OnStatus: []int{500, 502, 503, 504},
}))

​

Cached Response

var cachedData atomic.Value

// Update cache periodically
go func() {
    for {
        data := fetchData()
        cachedData.Store(data)
        time.Sleep(time.Minute)
    }
}()

app.Use(fallback.New(func(c *mizu.Ctx) error {
    return c.JSON(200, cachedData.Load())
}))

​

API Reference

​

Functions

// New creates fallback middleware
func New(handler mizu.Handler) mizu.Middleware

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

​

Technical Details

​

Implementation Architecture

1. Error Interception: The middleware wraps the next handler in the chain and catches any returned errors
2. Panic Recovery: When CatchPanic is enabled, it uses Go’s defer/recover mechanism to catch panics and convert them to errors
3. Response Capture: For status code-based fallbacks (like NotFound), it uses a custom responseCapture type that wraps http.ResponseWriter to intercept status codes
4. Handler Delegation: Based on the configuration, it delegates to the appropriate fallback handler

​

Key Components

• Options: Configuration structure that defines when and how to trigger fallback responses
• responseCapture: Internal type that captures HTTP response status codes before they’re written
• panicError: Custom error type that wraps panic values, converting non-error panics into error types

​

Execution Flow

Request → Middleware → [Optional Panic Recovery] → Next Handler → Error Check → Fallback Handler (if needed) → Response

​

Error Handling Chain

1. New(): Basic error handler with custom function
2. Default(): Simple text response fallback
3. JSON(): Structured JSON error responses
4. Redirect(): Redirect-based error handling
5. Chain(): Sequential fallback handlers with conditional logic
6. NotFound(): Status code-specific handling for 404s
7. ForStatus(): Generic status code-specific handling

​

Best Practices

• Keep fallback responses lightweight
• Log when fallback is triggered
• Monitor fallback rate
• Use cached data when possible

​

Testing

​

Related Middlewares

• circuitbreaker - Circuit breaker
• retry - Automatic retries
• cache - Response caching