0
# Quarkus SmallRye Fault Tolerance Extension
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: quarkus-smallrye-fault-tolerance
7
- **Package Type**: Maven (Quarkus Extension)
8
- **Group ID**: io.quarkus
9
- **Artifact ID**: quarkus-smallrye-fault-tolerance
10
- **Language**: Java
11
- **Installation**: Add dependency to `pom.xml`
12
13
```xml
14
<dependency>
15
<groupId>io.quarkus</groupId>
16
<artifactId>quarkus-smallrye-fault-tolerance</artifactId>
17
</dependency>
18
```
19
20
## Core Imports
21
22
Standard MicroProfile Fault Tolerance annotations:
23
24
```java
25
import org.eclipse.microprofile.faulttolerance.Retry;
26
import org.eclipse.microprofile.faulttolerance.CircuitBreaker;
27
import org.eclipse.microprofile.faulttolerance.Timeout;
28
import org.eclipse.microprofile.faulttolerance.Fallback;
29
import org.eclipse.microprofile.faulttolerance.Bulkhead;
30
import org.eclipse.microprofile.faulttolerance.Asynchronous;
31
import org.eclipse.microprofile.faulttolerance.FallbackHandler;
32
```
33
34
SmallRye-specific extensions:
35
36
```java
37
import io.smallrye.faulttolerance.api.RateLimit;
38
import io.smallrye.faulttolerance.api.RetryWhen;
39
import io.smallrye.faulttolerance.api.BeforeRetry;
40
import io.smallrye.faulttolerance.api.ExponentialBackoff;
41
import io.smallrye.faulttolerance.api.FibonacciBackoff;
42
import io.smallrye.faulttolerance.api.CustomBackoff;
43
import io.smallrye.faulttolerance.api.ApplyGuard;
44
import io.smallrye.faulttolerance.api.TypedGuard;
45
import io.smallrye.faulttolerance.api.AsynchronousNonBlocking;
46
import java.time.temporal.ChronoUnit;
47
```
48
49
## Basic Usage
50
51
```java
52
import jakarta.enterprise.context.ApplicationScoped;
53
import org.eclipse.microprofile.faulttolerance.Retry;
54
import org.eclipse.microprofile.faulttolerance.CircuitBreaker;
55
import org.eclipse.microprofile.faulttolerance.Timeout;
56
import org.eclipse.microprofile.faulttolerance.Fallback;
57
58
@ApplicationScoped
59
public class WeatherService {
60
61
// Basic retry with circuit breaker and timeout
62
@Retry(maxRetries = 3, delay = 1000)
63
@CircuitBreaker(requestVolumeThreshold = 5, failureRatio = 0.5)
64
@Timeout(5000)
65
public String getCurrentWeather(String city) {
66
// Call external weather API that might fail
67
return callExternalWeatherAPI(city);
68
}
69
70
// Fallback method for when circuit breaker opens
71
@Fallback(fallbackMethod = "getDefaultWeather")
72
@CircuitBreaker(requestVolumeThreshold = 3)
73
public String getWeatherWithFallback(String city) {
74
return callExternalWeatherAPI(city);
75
}
76
77
public String getDefaultWeather(String city) {
78
return "Weather data temporarily unavailable for " + city;
79
}
80
81
// Rate limiting with SmallRye extension
82
@RateLimit(value = 10, window = 1, windowUnit = ChronoUnit.MINUTES)
83
public String getLimitedWeatherData(String city) {
84
return callExternalWeatherAPI(city);
85
}
86
87
private String callExternalWeatherAPI(String city) {
88
// Implementation would make HTTP call to external service
89
throw new RuntimeException("Service temporarily unavailable");
90
}
91
}
92
```
93
94
## Architecture
95
96
The extension integrates seamlessly with Quarkus and CDI, providing fault tolerance through:
97
98
- **Annotation-based Configuration**: Apply fault tolerance strategies using standard annotations
99
- **Configuration Override**: Override annotation settings through application.properties
100
- **Metrics Integration**: Optional Micrometer metrics for monitoring fault tolerance behavior
101
- **Context Propagation**: Automatic context propagation for reactive programming
102
- **CDI Integration**: Full support for CDI beans and dependency injection
103
104
## Capabilities
105
106
### Retry Mechanisms
107
108
Automatic retry functionality with configurable delays, maximum attempts, and conditional retry logic based on exception types or return values.
109
110
```java { .api }
111
@Retry(maxRetries = 3, delay = 1000, delayUnit = ChronoUnit.MILLISECONDS)
112
public ReturnType retryableMethod();
113
114
@RetryWhen(exception = ExceptionPredicate.class, result = ResultPredicate.class)
115
public ReturnType conditionalRetryMethod();
116
```
117
118
[Retry Strategies](./retry-strategies.md)
119
120
### Circuit Breaker Patterns
121
122
Prevents cascading failures by monitoring failure rates and temporarily blocking calls to failing services.
123
124
```java { .api }
125
@CircuitBreaker(
126
requestVolumeThreshold = 20,
127
failureRatio = 0.5,
128
delay = 5000,
129
successThreshold = 3
130
)
131
public ReturnType protectedMethod();
132
133
@CircuitBreakerName("custom-breaker")
134
public ReturnType namedCircuitBreakerMethod();
135
```
136
137
[Circuit Breaker Strategies](./circuit-breaker-strategies.md)
138
139
### Timeout Controls
140
141
Enforces maximum execution time limits for method calls to prevent hanging operations.
142
143
```java { .api }
144
@Timeout(value = 5, unit = ChronoUnit.SECONDS)
145
public ReturnType timedMethod();
146
```
147
148
[Timeout Strategies](./timeout-strategies.md)
149
150
### Fallback Mechanisms
151
152
Provides alternative execution paths when primary methods fail, including custom fallback handlers and fallback methods.
153
154
```java { .api }
155
@Fallback(fallbackMethod = "alternativeMethod")
156
public ReturnType methodWithFallback();
157
158
@Fallback(value = CustomFallbackHandler.class)
159
public ReturnType methodWithHandler();
160
161
class CustomFallbackHandler implements FallbackHandler<ReturnType> {
162
public ReturnType handle(ExecutionContext context);
163
}
164
```
165
166
[Fallback Strategies](./fallback-strategies.md)
167
168
### Bulkhead Isolation
169
170
Controls concurrent access to methods by limiting the number of simultaneous executions and managing queuing for asynchronous operations.
171
172
```java { .api }
173
@Bulkhead(value = 10, waitingTaskQueue = 20)
174
public ReturnType limitedConcurrencyMethod();
175
```
176
177
[Bulkhead Strategies](./bulkhead-strategies.md)
178
179
### Rate Limiting
180
181
Controls the frequency of method invocations with time windows and minimum spacing between calls.
182
183
```java { .api }
184
@RateLimit(
185
value = 100,
186
window = 1,
187
windowUnit = ChronoUnit.MINUTES,
188
type = RateLimitType.FIXED
189
)
190
public ReturnType rateLimitedMethod();
191
```
192
193
[Rate Limiting Strategies](./rate-limiting-strategies.md)
194
195
### Asynchronous Execution
196
197
Enables non-blocking execution patterns with both blocking and non-blocking asynchronous strategies.
198
199
```java { .api }
200
@Asynchronous
201
public CompletionStage<ReturnType> asyncMethod();
202
203
@AsynchronousNonBlocking
204
public Uni<ReturnType> nonBlockingAsyncMethod();
205
```
206
207
[Asynchronous Strategies](./asynchronous-strategies.md)
208
209
### Programmatic API
210
211
Programmatic fault tolerance configuration using TypedGuard for scenarios where annotation-based configuration is not sufficient.
212
213
```java { .api }
214
TypedGuard<ReturnType> guard = TypedGuard.create(ReturnType.class)
215
.withRetry().maxRetries(3).done()
216
.withCircuitBreaker().requestVolumeThreshold(5).done()
217
.build();
218
219
Supplier<ReturnType> guardedSupplier = guard.adaptSupplier(this::methodToGuard);
220
```
221
222
[Programmatic API](./programmatic-api.md)
223
224
### Configuration Management
225
226
Comprehensive configuration system supporting global, per-class, and per-method configuration overrides through application properties.
227
228
```java { .api }
229
// Configuration interfaces for runtime and build-time settings
230
SmallRyeFaultToleranceConfig runtimeConfig;
231
SmallRyeFaultToleranceBuildTimeConfig buildTimeConfig;
232
```
233
234
[Configuration Options](./configuration.md)
235
236
## Types
237
238
### Core Fault Tolerance Types
239
240
```java { .api }
241
// Exception handling predicates
242
interface Predicate<T> {
243
boolean test(T t);
244
}
245
246
// Execution context for fallback handlers
247
interface ExecutionContext {
248
Method getMethod();
249
Object[] getParameters();
250
Throwable getFailure();
251
}
252
253
// Fallback handler interface
254
interface FallbackHandler<T> {
255
T handle(ExecutionContext context);
256
}
257
258
// Before retry handler interface
259
interface BeforeRetryHandler {
260
void handle(InvocationContext context);
261
}
262
263
// Custom backoff strategy interface
264
interface CustomBackoffStrategy {
265
long nextDelayInMillis(int attemptIndex);
266
}
267
```
268
269
### Configuration Types
270
271
```java { .api }
272
// Rate limit types
273
enum RateLimitType {
274
FIXED, ROLLING, SMOOTH
275
}
276
277
// Time units for configuration
278
enum ChronoUnit {
279
MILLIS, SECONDS, MINUTES, HOURS, DAYS
280
}
281
```
282
283
### Programmatic Guard Types
284
285
```java { .api }
286
// Basic guard interface
287
interface Guard {
288
// Guard operations
289
}
290
291
// Typed guard for specific return types
292
interface TypedGuard<T> extends Guard {
293
T call(Callable<T> callable) throws Exception;
294
Supplier<T> adaptSupplier(Supplier<T> supplier);
295
Function<U, T> adaptFunction(Function<U, T> function);
296
// Additional adaptation methods
297
}
298
```