Package io.lettuce.core.support.http

HTTP client infrastructure for lightweight HTTP operations.

See: Description

Interface Summary

Interface	Description
HttpClient	Interface for performing HTTP requests in a dependency-agnostic manner.
HttpClient.ConnectionConfig	Per-connection configuration for HTTP connections.
HttpClient.ConnectionConfig.Builder	Builder for HttpClient.ConnectionConfig.
HttpClient.HttpConnection	Represents an HTTP connection that can be reused for multiple requests.
HttpClient.Request	Represents an HTTP request with method, path, query parameters, headers, and optional body.
HttpClient.Request.RequestBuilder	Builder for constructing HTTP requests.
HttpClient.Response	Represents an HTTP response with status code, headers, and body.
HttpClientProvider	SPI (Service Provider Interface) for providing custom HttpClient implementations.

Class Summary

Class	Description
HttpClientResources	Manages a shared HttpClient instance with lazy initialization.
NettyHttpClientProvider	Default HttpClientProvider that creates Netty-based HTTP clients.

Enum Summary

Enum	Description
HttpClient.Method	HTTP request method.

Package io.lettuce.core.support.http Description

HTTP client infrastructure for lightweight HTTP operations.

Overview

This package provides a lightweight, dependency-agnostic HTTP client abstraction designed for health checks, REST API calls, and other HTTP-based operations. The implementation uses Netty's HTTP codecs and supports connection reuse, SSL/TLS, custom timeouts, and asynchronous operations.

Key Components

• HttpClient - Main interface for HTTP operations with connection-based API
• HttpClient.HttpConnection - Reusable HTTP connection for multiple requests
• HttpClient.Request - HTTP request builder with fluent API
• HttpClient.Response - HTTP response with status, headers, and body
• HttpClient.ConnectionConfig - Per-connection configuration (SSL, timeouts)
• HttpClientProvider - SPI for custom HTTP client implementations
• HttpClientResources - Shared resource management with lazy initialization

Basic Usage

The HTTP client uses a connection-based API where connections can be reused for multiple requests to the same host:

 
 {
     @code
     // Get the shared HTTP client
     HttpClient client = HttpClientResources.get();

     // Configure connection settings
     HttpClient.ConnectionConfig config = HttpClient.ConnectionConfig.builder().connectionTimeout(5000).readTimeout(5000)
             .build();

     // Establish connection (reusable for multiple requests)
     try (HttpClient.HttpConnection connection = client.connect(URI.create("https://api.example.com"), config)) {

         // Execute first request
         HttpClient.Request request1 = HttpClient.Request.get("/v1/health").build();
         HttpClient.Response response1 = connection.execute(request1);

         if (response1.getStatusCode() == 200) {
             String body = response1.getResponseBody(StandardCharsets.UTF_8);
             System.out.println("Health check: " + body);
         }

         // Reuse connection for second request
         HttpClient.Request request2 = HttpClient.Request.get("/v1/databases").queryParam("fields", "uid,status")
                 .header("Authorization", "Bearer token").build();
         HttpClient.Response response2 = connection.execute(request2);

         // Process response2...
     }
 }
 

Asynchronous Operations

Both connection establishment and request execution support asynchronous operations:

 
 {
     @code
     HttpClient client = HttpClientResources.get();
     HttpClient.ConnectionConfig config = HttpClient.ConnectionConfig.defaults();

     // Async connection
     CompletableFuture<HttpClient.HttpConnection> connectionFuture = client
             .connectAsync(URI.create("https://api.example.com"), config);

     connectionFuture.thenCompose(connection -> {
         HttpClient.Request request = HttpClient.Request.get("/v1/status").build();
         // Async request execution
         return connection.executeAsync(request);
     }).thenAccept(response -> {
         System.out.println("Status: " + response.getStatusCode());
     }).exceptionally(ex -> {
         ex.printStackTrace();
         return null;
     });
 }
 

SSL/TLS Support

HTTPS connections are supported via SslOptions. SSL options are configured per-connection:

 
 {
     @code
     // Configure SSL options
     SslOptions sslOptions = SslOptions.builder().truststore(new File("/path/to/truststore.jks"), "password".toCharArray())
             .protocols("TLSv1.2", "TLSv1.3").build();

     // Create connection config with SSL
     HttpClient.ConnectionConfig config = HttpClient.ConnectionConfig.builder().sslOptions(sslOptions).connectionTimeout(5000)
             .readTimeout(5000).build();

     HttpClient client = HttpClientResources.get();
     try (HttpClient.HttpConnection connection = client.connect(URI.create("https://secure-api.example.com"), config)) {
         HttpClient.Request request = HttpClient.Request.get("/secure/endpoint").build();
         HttpClient.Response response = connection.execute(request);
         // Process response...
     }
 }
 

Request Builder API

The HttpClient.Request interface provides a fluent builder for constructing HTTP requests:

 
 {
     @code
     // Simple GET request
     HttpClient.Request request = HttpClient.Request.get("/api/users").build();

     // GET with query parameters
     HttpClient.Request request = HttpClient.Request.get("/api/users").queryParam("page", "1").queryParam("limit", "10")
             .build();

     // GET with custom headers
     HttpClient.Request request = HttpClient.Request.get("/api/users").header("Authorization", "Bearer token")
             .header("Accept", "application/json").build();

     // Combined: path, query params, and headers
     HttpClient.Request request = HttpClient.Request.get("/api/databases").queryParam("fields", "uid,name,status")
             .header("Authorization", "Basic " + base64Credentials).build();
 }
 

Default Implementation

The default implementation uses Netty's HTTP client (NettyHttpClient) with the following features:

• Shared event loop group for efficient resource usage
• Configurable thread pool size via -Dio.lettuce.http.eventLoopThreads system property
• HTTP/1.1 with keep-alive for connection reuse
• Sequential request processing to avoid HTTP/1.1 pipelining issues
• Per-connection SSL/TLS configuration
• Configurable connection and read timeouts

Custom Implementations

Custom HTTP client implementations can be provided via the HttpClientProvider SPI. To register a custom provider:

1. Implement HttpClientProvider
2. Create a file META-INF/services/io.lettuce.core.support.http.HttpClientProvider
3. Add the fully qualified class name of your implementation to the file

Example Custom Provider

 
 {
     @code
     public class CustomHttpClientProvider implements HttpClientProvider {

         @Override
         public HttpClient createHttpClient() {
             return new CustomHttpClient();
         }

         @Override
         public boolean isAvailable() {
             try {
                 Class.forName("com.example.CustomHttpClient");
                 return true;
             } catch (ClassNotFoundException e) {
                 return false;
             }
         }

         @Override
         public int getPriority() {
             return 10; // Higher priority than default (0)
         }
 
     }
 }
 

Resource Management

HttpClientResources manages a shared HTTP client instance with lazy initialization:

Since:

7.4

Author:

Ivo Gaydazhiev