0
# Retry and Fault Tolerance
1

2
Configurable retry logic with support for different exception types, circuit breaker patterns, and request-specific retry behavior. The retry system provides intelligent failure handling for distributed systems.
3

4
## Capabilities
5

6
### RetryHandler Interface
7

8
Core interface for determining if exceptions are retriable and circuit-related.
9

10
```java { .api }
11
/**
12
 * Interface for determining if exceptions are retriable and circuit-related
13
 */
14
public interface RetryHandler {
15
    /**
16
     * Default retry handler instance
17
     */
18
    RetryHandler DEFAULT = new DefaultLoadBalancerRetryHandler();
19
    
20
    /**
21
     * Tests if exception is retriable
22
     * @param e the exception to test
23
     * @param sameServer true if retry should be on same server, false for different server
24
     * @return true if the exception indicates the request can be retried
25
     */
26
    boolean isRetriableException(Throwable e, boolean sameServer);
27
    
28
    /**
29
     * Tests if exception should trip circuit breaker
30
     * @param e the exception to test
31
     * @return true if this exception should cause the circuit breaker to open
32
     */
33
    boolean isCircuitTrippingException(Throwable e);
34
    
35
    /**
36
     * Returns max retries on same server
37
     * @return maximum number of retry attempts on the same server
38
     */
39
    int getMaxRetriesOnSameServer();
40
    
41
    /**
42
     * Returns max retries on different servers
43
     * @return maximum number of retry attempts on different servers
44
     */
45
    int getMaxRetriesOnNextServer();
46
}
47
```
48

49
### DefaultLoadBalancerRetryHandler
50

51
Default retry handler implementation with support for common Java network exceptions.
52

53
```java { .api }
54
/**
55
 * Default retry handler implementation with support for common Java network exceptions
56
 */
57
public class DefaultLoadBalancerRetryHandler implements RetryHandler {
58
    /**
59
     * Creates retry handler with default settings
60
     */
61
    public DefaultLoadBalancerRetryHandler();
62
    
63
    /**
64
     * Creates retry handler with specific retry counts
65
     * @param retrySameServer maximum retries on same server
66
     * @param retryNextServer maximum retries on different servers
67
     * @param retryEnabled whether retry is enabled at all
68
     */
69
    public DefaultLoadBalancerRetryHandler(int retrySameServer, int retryNextServer, boolean retryEnabled);
70
    
71
    /**
72
     * Creates retry handler from client configuration
73
     * @param clientConfig configuration containing retry settings
74
     */
75
    public DefaultLoadBalancerRetryHandler(IClientConfig clientConfig);
76
    
77
    /**
78
     * Tests if exception is retriable
79
     * @param e the exception to test
80
     * @param sameServer true if retry should be on same server
81
     * @return true if the exception indicates the request can be retried
82
     */
83
    public boolean isRetriableException(Throwable e, boolean sameServer);
84
    
85
    /**
86
     * Tests if exception should trip circuit breaker
87
     * @param e the exception to test
88
     * @return true if this exception should cause the circuit breaker to open
89
     */
90
    public boolean isCircuitTrippingException(Throwable e);
91
    
92
    /**
93
     * Returns max retries on same server
94
     * @return maximum number of retry attempts on the same server
95
     */
96
    public int getMaxRetriesOnSameServer();
97
    
98
    /**
99
     * Returns max retries on different servers
100
     * @return maximum number of retry attempts on different servers
101
     */
102
    public int getMaxRetriesOnNextServer();
103
}
104
```
105

106
**Usage Examples:**
107

108
```java
109
import com.netflix.client.*;
110
import com.netflix.client.config.*;
111

112
// Default retry handler
113
RetryHandler defaultHandler = new DefaultLoadBalancerRetryHandler();
114

115
// Custom retry configuration
116
RetryHandler customHandler = new DefaultLoadBalancerRetryHandler(
117
    3,      // max retries on same server
118
    2,      // max retries on different servers  
119
    true    // retry enabled
120
);
121

122
// Configuration-based retry handler
123
IClientConfig config = ClientConfigFactory.DEFAULT.newConfig();
124
config.set(CommonClientConfigKey.MaxAutoRetries, 3);
125
config.set(CommonClientConfigKey.MaxAutoRetriesNextServer, 1);
126
config.set(CommonClientConfigKey.OkToRetryOnAllOperations, false);
127

128
RetryHandler configHandler = new DefaultLoadBalancerRetryHandler(config);
129

130
// Using retry handler in client logic
131
public class MyClient {
132
    private final RetryHandler retryHandler;
133
    
134
    public MyClient(RetryHandler retryHandler) {
135
        this.retryHandler = retryHandler;
136
    }
137
    
138
    public void handleRequest(ClientRequest request) {
139
        int sameServerRetries = 0;
140
        int nextServerRetries = 0;
141
        
142
        while (true) {
143
            try {
144
                // Attempt request execution
145
                executeRequest(request);
146
                break; // Success
147
                
148
            } catch (Exception e) {
149
                boolean canRetrySameServer = sameServerRetries < retryHandler.getMaxRetriesOnSameServer()
150
                    && retryHandler.isRetriableException(e, true);
151
                    
152
                boolean canRetryNextServer = nextServerRetries < retryHandler.getMaxRetriesOnNextServer()
153
                    && retryHandler.isRetriableException(e, false);
154
                
155
                if (canRetrySameServer) {
156
                    sameServerRetries++;
157
                    // Retry on same server
158
                } else if (canRetryNextServer) {
159
                    nextServerRetries++;
160
                    // Retry on different server
161
                } else {
162
                    // Check if should trip circuit breaker
163
                    if (retryHandler.isCircuitTrippingException(e)) {
164
                        // Trip circuit breaker
165
                    }
166
                    throw e; // No more retries
167
                }
168
            }
169
        }
170
    }
171
}
172
```
173

174
### RequestSpecificRetryHandler
175

176
Retry handler implementation created for each request allowing request-specific overrides.
177

178
```java { .api }
179
/**
180
 * Retry handler implementation created for each request allowing request-specific overrides
181
 */
182
public class RequestSpecificRetryHandler implements RetryHandler {
183
    /**
184
     * Creates request-specific retry handler
185
     * @param okToRetryOnConnectErrors whether to retry on connection errors
186
     * @param okToRetryOnAllErrors whether to retry on all types of errors
187
     */
188
    public RequestSpecificRetryHandler(boolean okToRetryOnConnectErrors, boolean okToRetryOnAllErrors);
189
    
190
    /**
191
     * Creates request-specific retry handler with base handler
192
     * @param okToRetryOnConnectErrors whether to retry on connection errors
193
     * @param okToRetryOnAllErrors whether to retry on all types of errors
194
     * @param baseRetryHandler base retry handler to delegate to
195
     * @param requestConfig configuration for this specific request
196
     */
197
    public RequestSpecificRetryHandler(boolean okToRetryOnConnectErrors, boolean okToRetryOnAllErrors, 
198
                                     RetryHandler baseRetryHandler, IClientConfig requestConfig);
199
    
200
    /**
201
     * Tests if exception is connection-related
202
     * @param e the exception to test
203
     * @return true if this is a connection-related exception
204
     */
205
    public boolean isConnectionException(Throwable e);
206
    
207
    /**
208
     * Tests if exception is retriable
209
     * @param e the exception to test
210
     * @param sameServer true if retry should be on same server
211
     * @return true if the exception indicates the request can be retried
212
     */
213
    public boolean isRetriableException(Throwable e, boolean sameServer);
214
    
215
    /**
216
     * Tests if exception should trip circuit breaker
217
     * @param e the exception to test
218
     * @return true if this exception should cause the circuit breaker to open
219
     */
220
    public boolean isCircuitTrippingException(Throwable e);
221
    
222
    /**
223
     * Returns max retries on same server
224
     * @return maximum number of retry attempts on the same server
225
     */
226
    public int getMaxRetriesOnSameServer();
227
    
228
    /**
229
     * Returns max retries on different servers
230
     * @return maximum number of retry attempts on different servers
231
     */
232
    public int getMaxRetriesOnNextServer();
233
}
234
```
235

236
**Advanced Usage Examples:**
237

238
```java
239
// Request-specific retry behavior
240
public class AdaptiveClient {
241
    private final RetryHandler baseRetryHandler;
242
    
243
    public AdaptiveClient(RetryHandler baseRetryHandler) {
244
        this.baseRetryHandler = baseRetryHandler;
245
    }
246
    
247
    public void executeIdempotentRequest(ClientRequest request, IClientConfig config) {
248
        // For idempotent requests, allow retries on all errors
249
        RetryHandler requestHandler = new RequestSpecificRetryHandler(
250
            true,  // retry on connect errors
251
            true,  // retry on all errors (safe for idempotent operations)
252
            baseRetryHandler,
253
            config
254
        );
255
        
256
        executeWithRetry(request, config, requestHandler);
257
    }
258
    
259
    public void executeNonIdempotentRequest(ClientRequest request, IClientConfig config) {
260
        // For non-idempotent requests, only retry on connection errors
261
        RetryHandler requestHandler = new RequestSpecificRetryHandler(
262
            true,   // retry on connect errors
263
            false,  // don't retry on other errors (not safe for non-idempotent)
264
            baseRetryHandler,
265
            config
266
        );
267
        
268
        executeWithRetry(request, config, requestHandler);
269
    }
270
    
271
    private void executeWithRetry(ClientRequest request, IClientConfig config, RetryHandler handler) {
272
        // Implementation using the specific retry handler
273
    }
274
}
275

276
// Circuit breaker integration
277
public class CircuitBreakerAwareClient {
278
    private volatile boolean circuitOpen = false;
279
    private long circuitOpenTime = 0;
280
    private final long circuitRecoveryTimeout = 30000; // 30 seconds
281
    
282
    public void executeRequest(ClientRequest request, IClientConfig config) {
283
        RetryHandler retryHandler = new DefaultLoadBalancerRetryHandler(config);
284
        
285
        // Check circuit breaker state
286
        if (circuitOpen) {
287
            long now = System.currentTimeMillis();
288
            if (now - circuitOpenTime > circuitRecoveryTimeout) {
289
                circuitOpen = false; // Try to recover
290
            } else {
291
                throw new RuntimeException("Circuit breaker is open");
292
            }
293
        }
294
        
295
        try {
296
            // Execute request with retry logic
297
            executeWithHandler(request, retryHandler);
298
            
299
        } catch (Exception e) {
300
            if (retryHandler.isCircuitTrippingException(e)) {
301
                circuitOpen = true;
302
                circuitOpenTime = System.currentTimeMillis();
303
            }
304
            throw e;
305
        }
306
    }
307
}
308
```
309

310
### Exception Classification
311

312
The retry handlers classify exceptions into different categories for appropriate handling:
313

314
**Retriable Exceptions** (typically network-related):
315
- `ConnectException` - Connection refused or failed
316
- `SocketTimeoutException` - Socket operation timed out
317
- `NoRouteToHostException` - No route to target host
318

319
**Circuit Breaker Exceptions** (indicate service issues):
320
- `SocketTimeoutException` - May indicate service overload
321
- `ConnectException` - May indicate service down
322
- HTTP 5xx responses - Server errors
323

324
**Non-Retriable Exceptions** (client or business logic errors):
325
- `UnknownHostException` - DNS resolution failure
326
- HTTP 4xx responses - Client errors
327
- Business logic exceptions