CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-dev-langchain4j--langchain4j-http-client

HTTP client abstraction for LangChain4j with synchronous/asynchronous execution and Server-Sent Events (SSE) streaming support

Overview
Eval results
Files

timeout-configuration.mddocs/guides/

Timeout Configuration Guide

This guide covers configuring connect and read timeouts for HTTP client instances.

Basic Client Configuration

import dev.langchain4j.http.client.*;
import java.time.Duration;

HttpClientBuilder builder = HttpClientBuilderLoader.loadHttpClientBuilder();

HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(10))
    .readTimeout(Duration.ofSeconds(30))
    .build();

Timeout Types

Connect Timeout

The connect timeout determines the maximum time to wait when establishing a connection to the server.

Includes:

  • DNS resolution
  • TCP connection establishment
  • TLS/SSL handshake (if using HTTPS)

When exceeded:

  • A RuntimeException is thrown from execute() methods
  • The exception typically wraps a SocketTimeoutException

Recommended values:

  • Fast networks: 5-10 seconds
  • Slow networks: 15-30 seconds
  • Mobile networks: 30-60 seconds

Read Timeout

The read timeout determines the maximum time to wait between receiving data packets from the server.

Important: For each chunk of data received, the timeout is reset. This is NOT the total time for the request.

When exceeded:

  • A RuntimeException is thrown from execute() methods
  • For SSE streams, ServerSentEventListener.onError() is called with the timeout exception

Recommended values:

  • Standard APIs: 30-60 seconds
  • LLM APIs (non-streaming): 60-120 seconds
  • SSE streaming: 2-5 minutes (time between events)
  • Long-polling: up to 10 minutes

Configuration Patterns

Short Timeout for Fast APIs

HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(5))
    .readTimeout(Duration.ofSeconds(10))
    .build();

Long Timeout for Streaming

HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(15))
    .readTimeout(Duration.ofMinutes(5))  // Allow 5 minutes between events
    .build();

Reading Current Configuration

HttpClientBuilder builder = HttpClientBuilderLoader.loadHttpClientBuilder();

// Check current configuration
Duration currentConnectTimeout = builder.connectTimeout();
Duration currentReadTimeout = builder.readTimeout();

System.out.println("Connect timeout: " + currentConnectTimeout);
System.out.println("Read timeout: " + currentReadTimeout);

// Modify if needed
if (currentReadTimeout.compareTo(Duration.ofSeconds(30)) < 0) {
    builder.readTimeout(Duration.ofSeconds(30));
}

HttpClient client = builder.build();

Configuring with Environment Variables

// Read timeouts from environment or use defaults
String connectTimeoutEnv = System.getenv("HTTP_CONNECT_TIMEOUT_SECONDS");
int connectTimeoutSeconds = connectTimeoutEnv != null
    ? Integer.parseInt(connectTimeoutEnv)
    : 10;

String readTimeoutEnv = System.getenv("HTTP_READ_TIMEOUT_SECONDS");
int readTimeoutSeconds = readTimeoutEnv != null
    ? Integer.parseInt(readTimeoutEnv)
    : 30;

HttpClient client = builder
    .connectTimeout(Duration.ofSeconds(connectTimeoutSeconds))
    .readTimeout(Duration.ofSeconds(readTimeoutSeconds))
    .build();

Multiple Client Configurations

Factory Pattern for Different Timeouts

public class HttpClientFactory {
    public static HttpClient createDefault() {
        return HttpClientBuilderLoader.loadHttpClientBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .readTimeout(Duration.ofSeconds(30))
            .build();
    }

    public static HttpClient createForStreaming() {
        return HttpClientBuilderLoader.loadHttpClientBuilder()
            .connectTimeout(Duration.ofSeconds(15))
            .readTimeout(Duration.ofMinutes(5))
            .build();
    }

    public static HttpClient createForRest() {
        return HttpClientBuilderLoader.loadHttpClientBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .readTimeout(Duration.ofSeconds(30))
            .build();
    }
}

Reusing Builder for Multiple Clients

HttpClientBuilder builder = HttpClientBuilderLoader.loadHttpClientBuilder();

// Create client with short timeout
HttpClient fastClient = builder
    .connectTimeout(Duration.ofSeconds(5))
    .readTimeout(Duration.ofSeconds(10))
    .build();

// Create another client with long timeout
HttpClient slowClient = builder
    .connectTimeout(Duration.ofSeconds(30))
    .readTimeout(Duration.ofMinutes(2))
    .build();

Note: The behavior of builder reuse depends on the specific implementation. Some implementations may share state between builds, while others create independent configurations.

Spring Boot Configuration

Spring Bean Configuration

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HttpClientConfiguration {

    @Value("${http.connect.timeout.seconds:10}")
    private int connectTimeoutSeconds;

    @Value("${http.read.timeout.seconds:30}")
    private int readTimeoutSeconds;

    @Bean
    public HttpClient httpClient() {
        return HttpClientBuilderLoader.loadHttpClientBuilder()
            .connectTimeout(Duration.ofSeconds(connectTimeoutSeconds))
            .readTimeout(Duration.ofSeconds(readTimeoutSeconds))
            .build();
    }
}

application.properties

http.connect.timeout.seconds=10
http.read.timeout.seconds=30

Timeout Examples by Use Case

Strict Timeouts for Internal APIs

HttpClient strictClient = builder
    .connectTimeout(Duration.ofSeconds(3))
    .readTimeout(Duration.ofSeconds(10))
    .build();

Lenient Timeouts for External APIs

HttpClient lenientClient = builder
    .connectTimeout(Duration.ofSeconds(30))
    .readTimeout(Duration.ofSeconds(120))
    .build();

Very Long Timeouts for Streaming

HttpClient streamingClient = builder
    .connectTimeout(Duration.ofSeconds(15))
    .readTimeout(Duration.ofMinutes(10))
    .build();

SPI Configuration

Multiple HTTP Client Implementations

When multiple HTTP client implementations are available in the classpath:

# Specify which HTTP client implementation to use
java -Dlangchain4j.http.clientBuilderFactory=com.example.MyHttpClientFactory ...

If not specified and multiple implementations exist, an IllegalStateException is thrown.

Implementing Custom HTTP Client

public class MyHttpClientFactory implements HttpClientBuilderFactory {
    @Override
    public HttpClientBuilder create() {
        return new MyHttpClientBuilder();
    }
}

Register via META-INF/services/dev.langchain4j.http.client.HttpClientBuilderFactory:

com.example.MyHttpClientFactory

Best Practices

  1. Set appropriate timeouts: Always configure timeouts based on your use case. Default timeouts may not be suitable for all scenarios.

  2. Longer timeouts for streaming: SSE and streaming APIs require longer read timeouts since there may be delays between events.

  3. Shorter timeouts for internal APIs: Internal services typically have faster response times and should use shorter timeouts to fail fast.

  4. Consider network conditions: Mobile and remote users may need longer timeouts than local network users.

  5. Test timeout behavior: Verify that your timeout settings work correctly for both successful requests and timeout scenarios.

  6. Document timeout choices: Make timeout configurations visible and document why specific values were chosen.

Related Documentation

  • API Reference: Configuration API
  • SSE Configuration: SSE Streaming Guide
  • Error Handling: Timeout Error Handling

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-http-client

docs

guides

asynchronous-sse-streams.md

error-handling.md

form-data-uploads.md

logging-configuration.md

synchronous-requests.md

timeout-configuration.md

index.md

installation.md

quick-start.md

tile.json