0
# Netflix Ribbon Core
1

2
Netflix Ribbon Core provides foundational client-side load balancing, configuration management, and fault tolerance capabilities for distributed systems. This library serves as the core foundation for Netflix's Ribbon IPC framework, offering essential interfaces and utilities for building resilient, cloud-native client applications.
3

4
## Package Information
5

6
- **Package Name**: ribbon-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `<dependency><groupId>com.netflix.ribbon</groupId><artifactId>ribbon-core</artifactId><version>2.7.18</version></dependency>`
10

11
## Core Imports
12

13
```java
14
import com.netflix.client.*;
15
import com.netflix.client.config.*;
16
```
17

18
Common classes:
19
```java
20
import com.netflix.client.IClient;
21
import com.netflix.client.ClientRequest;
22
import com.netflix.client.IResponse;
23
import com.netflix.client.config.IClientConfig;
24
import com.netflix.client.config.CommonClientConfigKey;
25
```
26

27
## Basic Usage
28

29
```java
30
import com.netflix.client.*;
31
import com.netflix.client.config.*;
32

33
// Create client configuration
34
IClientConfig config = IClientConfig.Builder.newBuilder()
35
    .withClientName("my-service")
36
    .build();
37

38
// Configure timeouts and retry behavior
39
config.set(CommonClientConfigKey.ConnectTimeout, 5000);
40
config.set(CommonClientConfigKey.ReadTimeout, 10000);
41
config.set(CommonClientConfigKey.MaxAutoRetries, 3);
42

43
// Create a request
44
URI serviceUri = URI.create("http://my-service/api/data");
45
ClientRequest request = new ClientRequest(serviceUri);
46

47
// Set up retry handler
48
RetryHandler retryHandler = new DefaultLoadBalancerRetryHandler(
49
    config.get(CommonClientConfigKey.MaxAutoRetries),
50
    config.get(CommonClientConfigKey.MaxAutoRetriesNextServer),
51
    true
52
);
53
```
54

55
## Architecture
56

57
Ribbon Core is organized around several key architectural components:
58

59
- **Client Framework**: Core interfaces (`IClient`, `ClientRequest`, `IResponse`) that define the request/response contract
60
- **Configuration System**: Dynamic property management with runtime reloading capabilities (`IClientConfig`, `Property`)
61
- **Retry Logic**: Pluggable retry handlers for different failure scenarios (`RetryHandler`)
62
- **Exception Management**: Comprehensive exception hierarchy with error categorization (`ClientException`)
63
- **SSL Support**: SSL context factories for secure communication
64
- **Utility Components**: Helper classes for common operations and resource management
65

66
## Capabilities
67

68
### Client Framework
69

70
Core interfaces for executing client requests with support for load balancing keys and retry configuration.
71

72
```java { .api }
73
public interface IClient<S extends ClientRequest, T extends IResponse> {
74
    T execute(S request, IClientConfig requestConfig) throws Exception;
75
}
76

77
public class ClientRequest implements Cloneable {
78
    public ClientRequest(URI uri);
79
    public ClientRequest(URI uri, Object loadBalancerKey, boolean isRetriable);
80
    public URI getUri();
81
    public Object getLoadBalancerKey();
82
    public boolean isRetriable();
83
    public ClientRequest replaceUri(URI newURI);
84
}
85

86
public interface IResponse extends Closeable {
87
    Object getPayload() throws ClientException;
88
    boolean hasPayload();
89
    boolean isSuccess();
90
    URI getRequestedURI();
91
    Map<String, ?> getHeaders();
92
}
93
```
94

95
[Client Framework](./client-framework.md)
96

97
### Configuration Management
98

99
Dynamic configuration system with type-safe property access, runtime reloading, and hierarchical property resolution.
100

101
```java { .api }
102
public interface IClientConfig {
103
    String getClientName();
104
    <T> T get(IClientConfigKey<T> key);
105
    <T> T getOrDefault(IClientConfigKey<T> key);
106
    <T> IClientConfig set(IClientConfigKey<T> key, T value);
107
    <T> Property<T> getDynamicProperty(IClientConfigKey<T> key);
108
    void loadProperties(String clientName);
109
}
110

111
public abstract class CommonClientConfigKey<T> implements IClientConfigKey<T> {
112
    public static final IClientConfigKey<String> AppName;
113
    public static final IClientConfigKey<Integer> ConnectTimeout;
114
    public static final IClientConfigKey<Integer> ReadTimeout;
115
    public static final IClientConfigKey<Integer> MaxAutoRetries;
116
    // ... many more configuration keys
117
}
118
```
119

120
[Configuration Management](./configuration.md)
121

122
### Retry and Fault Tolerance
123

124
Configurable retry logic with support for different exception types and circuit breaker patterns.
125

126
```java { .api }
127
public interface RetryHandler {
128
    boolean isRetriableException(Throwable e, boolean sameServer);
129
    boolean isCircuitTrippingException(Throwable e);
130
    int getMaxRetriesOnSameServer();
131
    int getMaxRetriesOnNextServer();
132
}
133

134
public class DefaultLoadBalancerRetryHandler implements RetryHandler {
135
    public DefaultLoadBalancerRetryHandler();
136
    public DefaultLoadBalancerRetryHandler(int retrySameServer, int retryNextServer, boolean retryEnabled);
137
    public DefaultLoadBalancerRetryHandler(IClientConfig clientConfig);
138
}
139
```
140

141
[Retry and Fault Tolerance](./retry-handlers.md)
142

143
### Exception Management
144

145
Comprehensive exception hierarchy with error codes, types, and detailed error information for proper error handling.
146

147
```java { .api }
148
public class ClientException extends Exception {
149
    public ClientException(String message);
150
    public ClientException(int errorCode, String message);
151
    public ClientException(ErrorType error, String message, Throwable chainedException);
152
    
153
    public ErrorType getErrorType();
154
    public int getErrorCode();
155
    public String getErrorMessage();
156
    
157
    public enum ErrorType {
158
        GENERAL, CONFIGURATION, NUMBEROF_RETRIES_EXEEDED,
159
        SOCKET_TIMEOUT_EXCEPTION, READ_TIMEOUT_EXCEPTION,
160
        UNKNOWN_HOST_EXCEPTION, CONNECT_EXCEPTION,
161
        CLIENT_THROTTLED, SERVER_THROTTLED, CACHE_MISSING
162
    }
163
}
164
```
165

166
[Exception Management](./exceptions.md)
167

168
### SSL Security
169

170
SSL context factories for secure communication with support for custom keystores and truststores.
171

172
```java { .api }
173
public abstract class AbstractSslContextFactory {
174
    protected AbstractSslContextFactory(KeyStore trustStore, String trustStorePassword, 
175
                                       KeyStore keyStore, String keyStorePassword);
176
    public SSLContext getSSLContext() throws ClientSslSocketFactoryException;
177
    public KeyStore getKeyStore();
178
    public KeyStore getTrustStore();
179
}
180

181
public class URLSslContextFactory extends AbstractSslContextFactory {
182
    public URLSslContextFactory(URL trustStoreUrl, String trustStorePassword,
183
                               URL keyStoreUrl, String keyStorePassword) 
184
                               throws ClientSslSocketFactoryException;
185
}
186
```
187

188
[SSL Security](./ssl-support.md)