or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

asynchronous-strategies.mdbulkhead-strategies.mdcircuit-breaker-strategies.mdconfiguration.mdfallback-strategies.mdindex.mdprogrammatic-api.mdrate-limiting-strategies.mdretry-strategies.mdtimeout-strategies.md
tile.json

tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance

Build fault-tolerant network services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkus/quarkus-smallrye-fault-tolerance@3.23.x

To install, run

npx @tessl/cli install tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance@3.23.0

index.mddocs/

Quarkus SmallRye Fault Tolerance Extension

A comprehensive Quarkus extension that provides fault tolerance capabilities for microservices by implementing the MicroProfile Fault Tolerance specification through SmallRye Fault Tolerance. The extension enables resilient microservices with retry mechanisms, circuit breakers, timeouts, fallbacks, bulkheads, and rate limiting through both annotation-based and programmatic APIs.

Package Information

  • Package Name: quarkus-smallrye-fault-tolerance
  • Package Type: Maven (Quarkus Extension)
  • Group ID: io.quarkus
  • Artifact ID: quarkus-smallrye-fault-tolerance
  • Language: Java
  • Installation: Add dependency to pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-fault-tolerance</artifactId>
</dependency>

Core Imports

Standard MicroProfile Fault Tolerance annotations:

import org.eclipse.microprofile.faulttolerance.Retry;
import org.eclipse.microprofile.faulttolerance.CircuitBreaker;
import org.eclipse.microprofile.faulttolerance.Timeout;
import org.eclipse.microprofile.faulttolerance.Fallback;
import org.eclipse.microprofile.faulttolerance.Bulkhead;
import org.eclipse.microprofile.faulttolerance.Asynchronous;
import org.eclipse.microprofile.faulttolerance.FallbackHandler;

SmallRye-specific extensions:

import io.smallrye.faulttolerance.api.RateLimit;
import io.smallrye.faulttolerance.api.RetryWhen;
import io.smallrye.faulttolerance.api.BeforeRetry;
import io.smallrye.faulttolerance.api.ExponentialBackoff;
import io.smallrye.faulttolerance.api.FibonacciBackoff;
import io.smallrye.faulttolerance.api.CustomBackoff;
import io.smallrye.faulttolerance.api.ApplyGuard;
import io.smallrye.faulttolerance.api.TypedGuard;
import io.smallrye.faulttolerance.api.AsynchronousNonBlocking;
import java.time.temporal.ChronoUnit;

Basic Usage

import jakarta.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.faulttolerance.Retry;
import org.eclipse.microprofile.faulttolerance.CircuitBreaker;
import org.eclipse.microprofile.faulttolerance.Timeout;
import org.eclipse.microprofile.faulttolerance.Fallback;

@ApplicationScoped
public class WeatherService {
    
    // Basic retry with circuit breaker and timeout
    @Retry(maxRetries = 3, delay = 1000)
    @CircuitBreaker(requestVolumeThreshold = 5, failureRatio = 0.5)
    @Timeout(5000)
    public String getCurrentWeather(String city) {
        // Call external weather API that might fail
        return callExternalWeatherAPI(city);
    }
    
    // Fallback method for when circuit breaker opens
    @Fallback(fallbackMethod = "getDefaultWeather")
    @CircuitBreaker(requestVolumeThreshold = 3)
    public String getWeatherWithFallback(String city) {
        return callExternalWeatherAPI(city);
    }
    
    public String getDefaultWeather(String city) {
        return "Weather data temporarily unavailable for " + city;
    }
    
    // Rate limiting with SmallRye extension
    @RateLimit(value = 10, window = 1, windowUnit = ChronoUnit.MINUTES)
    public String getLimitedWeatherData(String city) {
        return callExternalWeatherAPI(city);
    }
    
    private String callExternalWeatherAPI(String city) {
        // Implementation would make HTTP call to external service
        throw new RuntimeException("Service temporarily unavailable");
    }
}

Architecture

The extension integrates seamlessly with Quarkus and CDI, providing fault tolerance through:

  • Annotation-based Configuration: Apply fault tolerance strategies using standard annotations
  • Configuration Override: Override annotation settings through application.properties
  • Metrics Integration: Optional Micrometer metrics for monitoring fault tolerance behavior
  • Context Propagation: Automatic context propagation for reactive programming
  • CDI Integration: Full support for CDI beans and dependency injection

Capabilities

Retry Mechanisms

Automatic retry functionality with configurable delays, maximum attempts, and conditional retry logic based on exception types or return values.

@Retry(maxRetries = 3, delay = 1000, delayUnit = ChronoUnit.MILLISECONDS)
public ReturnType retryableMethod();

@RetryWhen(exception = ExceptionPredicate.class, result = ResultPredicate.class)
public ReturnType conditionalRetryMethod();

Retry Strategies

Circuit Breaker Patterns

Prevents cascading failures by monitoring failure rates and temporarily blocking calls to failing services.

@CircuitBreaker(
    requestVolumeThreshold = 20,
    failureRatio = 0.5,
    delay = 5000,
    successThreshold = 3
)
public ReturnType protectedMethod();

@CircuitBreakerName("custom-breaker")
public ReturnType namedCircuitBreakerMethod();

Circuit Breaker Strategies

Timeout Controls

Enforces maximum execution time limits for method calls to prevent hanging operations.

@Timeout(value = 5, unit = ChronoUnit.SECONDS)
public ReturnType timedMethod();

Timeout Strategies

Fallback Mechanisms

Provides alternative execution paths when primary methods fail, including custom fallback handlers and fallback methods.

@Fallback(fallbackMethod = "alternativeMethod")
public ReturnType methodWithFallback();

@Fallback(value = CustomFallbackHandler.class)
public ReturnType methodWithHandler();

class CustomFallbackHandler implements FallbackHandler<ReturnType> {
    public ReturnType handle(ExecutionContext context);
}

Fallback Strategies

Bulkhead Isolation

Controls concurrent access to methods by limiting the number of simultaneous executions and managing queuing for asynchronous operations.

@Bulkhead(value = 10, waitingTaskQueue = 20)
public ReturnType limitedConcurrencyMethod();

Bulkhead Strategies

Rate Limiting

Controls the frequency of method invocations with time windows and minimum spacing between calls.

@RateLimit(
    value = 100,
    window = 1,
    windowUnit = ChronoUnit.MINUTES,
    type = RateLimitType.FIXED
)
public ReturnType rateLimitedMethod();

Rate Limiting Strategies

Asynchronous Execution

Enables non-blocking execution patterns with both blocking and non-blocking asynchronous strategies.

@Asynchronous
public CompletionStage<ReturnType> asyncMethod();

@AsynchronousNonBlocking
public Uni<ReturnType> nonBlockingAsyncMethod();

Asynchronous Strategies

Programmatic API

Programmatic fault tolerance configuration using TypedGuard for scenarios where annotation-based configuration is not sufficient.

TypedGuard<ReturnType> guard = TypedGuard.create(ReturnType.class)
    .withRetry().maxRetries(3).done()
    .withCircuitBreaker().requestVolumeThreshold(5).done()
    .build();

Supplier<ReturnType> guardedSupplier = guard.adaptSupplier(this::methodToGuard);

Programmatic API

Configuration Management

Comprehensive configuration system supporting global, per-class, and per-method configuration overrides through application properties.

// Configuration interfaces for runtime and build-time settings
SmallRyeFaultToleranceConfig runtimeConfig;
SmallRyeFaultToleranceBuildTimeConfig buildTimeConfig;

Configuration Options

Types

Core Fault Tolerance Types

// Exception handling predicates
interface Predicate<T> {
    boolean test(T t);
}

// Execution context for fallback handlers
interface ExecutionContext {
    Method getMethod();
    Object[] getParameters();
    Throwable getFailure();
}

// Fallback handler interface
interface FallbackHandler<T> {
    T handle(ExecutionContext context);
}

// Before retry handler interface
interface BeforeRetryHandler {
    void handle(InvocationContext context);
}

// Custom backoff strategy interface
interface CustomBackoffStrategy {
    long nextDelayInMillis(int attemptIndex);
}

Configuration Types

// Rate limit types
enum RateLimitType {
    FIXED, ROLLING, SMOOTH
}

// Time units for configuration
enum ChronoUnit {
    MILLIS, SECONDS, MINUTES, HOURS, DAYS
}

Programmatic Guard Types

// Basic guard interface
interface Guard {
    // Guard operations
}

// Typed guard for specific return types
interface TypedGuard<T> extends Guard {
    T call(Callable<T> callable) throws Exception;
    Supplier<T> adaptSupplier(Supplier<T> supplier);
    Function<U, T> adaptFunction(Function<U, T> function);
    // Additional adaptation methods
}