Crate tower_resilience_fallback 

Fallback middleware for Tower services.

Provides alternative responses when the inner service fails, enabling graceful degradation and backup service routing.

Overview

The fallback pattern allows you to provide alternative responses when your primary service fails. This is useful for:

• Returning cached or stale data when the primary source is unavailable
• Providing degraded functionality instead of complete failure
• Routing to backup services
• Transforming errors into user-friendly responses

Fallback Strategies

Static Value

Return a fixed value when the service fails:

use tower_resilience_fallback::FallbackLayer;
use tower::ServiceBuilder;

let layer = FallbackLayer::<String, String, MyError>::value("default response".to_string());

Fallback Function

Compute a response based on the error:

use tower_resilience_fallback::FallbackLayer;

let layer = FallbackLayer::<String, String, MyError>::from_error(|error: &MyError| {
    format!("Service unavailable: {}", error.message)
});

Fallback with Request Context

Access both the original request and error:

use tower_resilience_fallback::FallbackLayer;
use std::sync::Arc;
use std::collections::HashMap;

let cache: Arc<HashMap<String, String>> = Arc::new(HashMap::new());
let cache_clone = Arc::clone(&cache);

let layer = FallbackLayer::<String, String, MyError>::from_request_error(move |req: &String, _err: &MyError| {
    cache_clone.get(req).cloned().unwrap_or_else(|| "not found".to_string())
});

Backup Service

Route to an alternative service (async):

use tower_resilience_fallback::FallbackLayer;

let layer = FallbackLayer::<String, String, MyError>::service(|req: String| async move {
    Ok::<_, MyError>(format!("backup: {}", req))
});

Error Transformation

Convert errors to a different type (still returns error, not success):

use tower_resilience_fallback::FallbackLayer;

// Note: This changes the error type, so layer types must align
let layer = FallbackLayer::<String, String, InternalError>::exception(|err: InternalError| {
    InternalError { code: 500 } // Transform but still error
});

Selective Error Handling

Only trigger fallback for specific errors:

use tower_resilience_fallback::FallbackLayer;

let layer: FallbackLayer<String, String, MyError> = FallbackLayer::builder()
    .value("fallback".to_string())
    .handle(|e: &MyError| e.retryable) // Only fallback on retryable errors
    .build();

Composition with Other Layers

Fallback works well with other resilience patterns:

use tower_resilience_fallback::FallbackLayer;
use tower::ServiceBuilder;

// Fallback catches anything that escapes retry + circuit breaker
let service = ServiceBuilder::new()
    .layer(FallbackLayer::<String, String, MyError>::value("unavailable".to_string()))
    // .layer(CircuitBreakerLayer::new(cb_config))
    // .layer(RetryLayer::new(retry_config))
    .service(tower::service_fn(|req: String| async move {
        Ok::<_, MyError>(req)
    }));

Events

The fallback service emits events for observability:

• Success: Inner service succeeded, no fallback needed
• FailedAttempt: Inner service failed, fallback will be attempted
• Applied: Fallback was successfully applied
• Failed: Fallback itself failed (service fallback only)
• Skipped: Error didn’t match predicate, propagated as-is

Structs

Fallback

A Tower service that provides fallback responses when the inner service fails.

FallbackConfig

Configuration for the fallback service.

FallbackConfigBuilder

Builder for constructing a FallbackLayer.

FallbackLayer

A Tower layer that applies fallback behavior to a service.

Enums

FallbackError

Error type for the fallback service.

FallbackEvent

Events emitted by the fallback service.

FallbackStrategy

The strategy used to produce a fallback response.

Type Aliases

ExceptionFn

Function that transforms an error into a different error.

FromErrorFn

Function that computes a fallback response from an error.

FromRequestErrorFn

Function that computes a fallback response from request and error.

HandlePredicate

Predicate to determine if an error should trigger the fallback.

HandleResponsePredicate

Predicate to determine if a successful response should trigger the fallback.

ServiceFn

Function that calls a backup service asynchronously.

ValueFn

Function that produces a fallback value (no Clone required).