or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-framework.mdconfiguration.mdexceptions.mdindex.mdretry-handlers.mdssl-support.md
tile.json

tessl/maven-com-netflix-ribbon--ribbon-core

Client configuration APIs and shared utilities for Netflix's Ribbon IPC library, providing core interfaces for load balancing, fault tolerance, and service discovery capabilities in cloud environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.netflix.ribbon/ribbon-core@2.7.x

To install, run

npx @tessl/cli install tessl/maven-com-netflix-ribbon--ribbon-core@2.7.0

index.mddocs/

Netflix Ribbon Core

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.

Package Information

  • Package Name: ribbon-core
  • Package Type: maven
  • Language: Java
  • Installation: <dependency><groupId>com.netflix.ribbon</groupId><artifactId>ribbon-core</artifactId><version>2.7.18</version></dependency>

Core Imports

import com.netflix.client.*;
import com.netflix.client.config.*;

Common classes:

import com.netflix.client.IClient;
import com.netflix.client.ClientRequest;
import com.netflix.client.IResponse;
import com.netflix.client.config.IClientConfig;
import com.netflix.client.config.CommonClientConfigKey;

Basic Usage

import com.netflix.client.*;
import com.netflix.client.config.*;

// Create client configuration
IClientConfig config = IClientConfig.Builder.newBuilder()
    .withClientName("my-service")
    .build();

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

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

// Set up retry handler
RetryHandler retryHandler = new DefaultLoadBalancerRetryHandler(
    config.get(CommonClientConfigKey.MaxAutoRetries),
    config.get(CommonClientConfigKey.MaxAutoRetriesNextServer),
    true
);

Architecture

Ribbon Core is organized around several key architectural components:

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

Capabilities

Client Framework

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

public interface IClient<S extends ClientRequest, T extends IResponse> {
    T execute(S request, IClientConfig requestConfig) throws Exception;
}

public class ClientRequest implements Cloneable {
    public ClientRequest(URI uri);
    public ClientRequest(URI uri, Object loadBalancerKey, boolean isRetriable);
    public URI getUri();
    public Object getLoadBalancerKey();
    public boolean isRetriable();
    public ClientRequest replaceUri(URI newURI);
}

public interface IResponse extends Closeable {
    Object getPayload() throws ClientException;
    boolean hasPayload();
    boolean isSuccess();
    URI getRequestedURI();
    Map<String, ?> getHeaders();
}

Client Framework

Configuration Management

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

public interface IClientConfig {
    String getClientName();
    <T> T get(IClientConfigKey<T> key);
    <T> T getOrDefault(IClientConfigKey<T> key);
    <T> IClientConfig set(IClientConfigKey<T> key, T value);
    <T> Property<T> getDynamicProperty(IClientConfigKey<T> key);
    void loadProperties(String clientName);
}

public abstract class CommonClientConfigKey<T> implements IClientConfigKey<T> {
    public static final IClientConfigKey<String> AppName;
    public static final IClientConfigKey<Integer> ConnectTimeout;
    public static final IClientConfigKey<Integer> ReadTimeout;
    public static final IClientConfigKey<Integer> MaxAutoRetries;
    // ... many more configuration keys
}

Configuration Management

Retry and Fault Tolerance

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

public interface RetryHandler {
    boolean isRetriableException(Throwable e, boolean sameServer);
    boolean isCircuitTrippingException(Throwable e);
    int getMaxRetriesOnSameServer();
    int getMaxRetriesOnNextServer();
}

public class DefaultLoadBalancerRetryHandler implements RetryHandler {
    public DefaultLoadBalancerRetryHandler();
    public DefaultLoadBalancerRetryHandler(int retrySameServer, int retryNextServer, boolean retryEnabled);
    public DefaultLoadBalancerRetryHandler(IClientConfig clientConfig);
}

Retry and Fault Tolerance

Exception Management

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

public class ClientException extends Exception {
    public ClientException(String message);
    public ClientException(int errorCode, String message);
    public ClientException(ErrorType error, String message, Throwable chainedException);
    
    public ErrorType getErrorType();
    public int getErrorCode();
    public String getErrorMessage();
    
    public enum ErrorType {
        GENERAL, CONFIGURATION, NUMBEROF_RETRIES_EXEEDED,
        SOCKET_TIMEOUT_EXCEPTION, READ_TIMEOUT_EXCEPTION,
        UNKNOWN_HOST_EXCEPTION, CONNECT_EXCEPTION,
        CLIENT_THROTTLED, SERVER_THROTTLED, CACHE_MISSING
    }
}

Exception Management

SSL Security

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

public abstract class AbstractSslContextFactory {
    protected AbstractSslContextFactory(KeyStore trustStore, String trustStorePassword, 
                                       KeyStore keyStore, String keyStorePassword);
    public SSLContext getSSLContext() throws ClientSslSocketFactoryException;
    public KeyStore getKeyStore();
    public KeyStore getTrustStore();
}

public class URLSslContextFactory extends AbstractSslContextFactory {
    public URLSslContextFactory(URL trustStoreUrl, String trustStorePassword,
                               URL keyStoreUrl, String keyStorePassword) 
                               throws ClientSslSocketFactoryException;
}

SSL Security