Core Interfaces API Reference

/**
 * A client for executing HTTP requests both synchronously and asynchronously.
 * This interface is currently experimental and subject to change.
 */
public interface HttpClient {
    /**
     * Executes a given HTTP request synchronously and returns the response.
     * This method blocks until the entire response is received.
     *
     * @param request the HTTP request to be executed
     * @return a SuccessfulHttpResponse containing the response data for successful HTTP requests (2XX status codes)
     * @throws dev.langchain4j.exception.HttpException if the server returns a client (4XX) or server (5XX) error response
     * @throws RuntimeException if an unexpected error occurs during request execution (e.g., network issues, timeouts)
     */
    SuccessfulHttpResponse execute(HttpRequest request);

    /**
     * Executes a given HTTP request asynchronously with server-sent events (SSE) handling.
     * This method returns immediately while processing continues on a separate thread.
     * Events are processed through the provided ServerSentEventListener.
     * Uses the DefaultServerSentEventParser for parsing.
     *
     * The execution flow:
     * 1. The request is initiated asynchronously
     * 2. Received SSE data is parsed using the DefaultServerSentEventParser
     * 3. Parsed events are delivered to the listener's appropriate methods
     * 4. If an error occurs, ServerSentEventListener.onError(Throwable) is called
     *
     * If any exception is thrown from the listener's methods, the stream processing
     * will be terminated and no further events will be processed.
     *
     * @param request the HTTP request to be executed
     * @param listener the listener to receive parsed events and error notifications
     */
    void execute(HttpRequest request, ServerSentEventListener listener);

    /**
     * Executes a given HTTP request asynchronously with server-sent events (SSE) handling.
     * This method returns immediately while processing continues on a separate thread.
     * Events are processed through the provided ServerSentEventListener.
     *
     * The execution flow:
     * 1. The request is initiated asynchronously
     * 2. Received SSE data is parsed using the provided parser
     * 3. Parsed events are delivered to the listener's appropriate methods
     * 4. If an error occurs, ServerSentEventListener.onError(Throwable) is called
     *
     * If any exception is thrown from the listener's methods, the stream processing
     * will be terminated and no further events will be processed.
     *
     * @param request the HTTP request to be executed
     * @param parser the parser to process incoming server-sent events
     * @param listener the listener to receive parsed events and error notifications
     */
    void execute(HttpRequest request, ServerSentEventParser parser, ServerSentEventListener listener);
}

public interface HttpClientBuilder {
    /**
     * Returns the currently configured connect timeout.
     *
     * @return the connect timeout duration
     */
    Duration connectTimeout();

    /**
     * Sets the connect timeout for establishing connections.
     * This is the maximum time to wait when establishing a connection to the server.
     *
     * @param timeout the connect timeout duration
     * @return this builder for method chaining
     */
    HttpClientBuilder connectTimeout(Duration timeout);

    /**
     * Returns the currently configured read timeout.
     *
     * @return the read timeout duration
     */
    Duration readTimeout();

    /**
     * Sets the read timeout for reading data from connections.
     * This is the maximum time to wait between receiving data packets.
     *
     * @param timeout the read timeout duration
     * @return this builder for method chaining
     */
    HttpClientBuilder readTimeout(Duration timeout);

    /**
     * Builds and returns the configured HttpClient instance.
     *
     * @return the configured HttpClient
     */
    HttpClient build();
}

public class HttpClientBuilderLoader {
    /**
     * Loads an HttpClientBuilder from the classpath using ServiceLoader.
     * Supports the 'langchain4j.http.clientBuilderFactory' system property
     * to specify which implementation to use when multiple are available.
     *
     * @return HttpClientBuilder instance
     * @throws IllegalStateException if no HTTP client is found in classpath,
     *         or if multiple clients are found without explicit selection,
     *         or if the selected client doesn't match any available implementation
     */
    public static HttpClientBuilder loadHttpClientBuilder();
}

/**
 * Factory interface for creating HttpClientBuilder instances.
 * Implement this interface and register via ServiceLoader to provide
 * a custom HTTP client implementation.
 */
public interface HttpClientBuilderFactory {
    /**
     * Creates a new HttpClientBuilder instance.
     *
     * @return HttpClientBuilder instance
     */
    HttpClientBuilder create();
}

public class SuccessfulHttpResponse {
    /**
     * Creates a new builder instance for constructing HTTP responses.
     *
     * @return new Builder instance
     */
    public static Builder builder();

    /**
     * Returns the HTTP status code.
     * Always in the range 200-299 for successful responses.
     *
     * @return the HTTP status code (200-299)
     */
    public int statusCode();

    /**
     * Returns the response headers as a multi-value map.
     * Header names are case-sensitive as received from the server.
     *
     * @return the response headers
     */
    public Map<String, List<String>> headers();

    /**
     * Returns the response body as a string.
     *
     * @return the response body, or null if no body was present
     */
    public String body();

    public static class Builder {
        /**
         * Sets the HTTP status code.
         * Must be in the range 200-299.
         *
         * @param statusCode the HTTP status code
         * @return this builder
         * @throws IllegalArgumentException if statusCode is not between 200 and 299
         */
        public Builder statusCode(int statusCode);

        /**
         * Sets the response headers.
         *
         * @param headers map of header names to lists of values
         * @return this builder
         */
        public Builder headers(Map<String, List<String>> headers);

        /**
         * Sets the response body.
         *
         * @param body the response body as a string
         * @return this builder
         */
        public Builder body(String body);

        /**
         * Builds the SuccessfulHttpResponse instance.
         *
         * @return the constructed SuccessfulHttpResponse
         * @throws IllegalArgumentException if statusCode is not between 200 and 299
         */
        public SuccessfulHttpResponse build();
    }
}

/**
 * Thrown when the server returns a client error (4XX) or server error (5XX) status code.
 * Part of package: dev.langchain4j.exception
 */
public class HttpException extends RuntimeException {
    // Exception details including status code and response body
}