SYSTEM

Java HttpClient

What it is

java.net.http.HttpClient is the native HTTP client shipped with the JDK since Java 11. It supports HTTP/1.1 and HTTP/2, synchronous (send) and asynchronous (sendAsync) request styles, and uses CompletableFuture for async composition. It replaced the older URLConnection-based client that had been the JDK's built-in HTTP option for decades.

Why it shows up in timeout guidance

Zalando's timeouts post cites Java HttpClient as the canonical anti-example of library defaults — specifically, that both the connection timeout and the request timeout default to infinite:

"Unfortunately, many libraries set default timeouts too high or infinite. They aim to attract as many users as possible and try to make their library work in most situations. But for production services, it is not acceptable. It can even be dangerous. For example for native java HttpClient the default connection/request timeout is infinite, which is unlikely within your SLA :)" (Source: )

A Java service that builds requests via HttpClient.newHttpClient() or HttpRequest.newBuilder() without calling .connectTimeout(...) and .timeout(...) will wait forever for an unresponsive downstream — the textbook prelude to concepts/thread-pool-exhaustion.

The correct shape:

HttpClient client = HttpClient.newBuilder()
    .connectTimeout(Duration.ofMillis(500))   // RTT × 3-ish
    .build();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://downstream.example.com/orders"))
    .timeout(Duration.ofMillis(700))          // downstream p99.9
    .build();

Both timeouts must be set. The client-level .connectTimeout(...) bounds the handshake; the request-level .timeout(...) bounds the request after the connection is established.

Seen in

• — canonical citation as the library whose infinite default timeouts are "the enemy."

Related

• concepts/connection-timeout — set via .connectTimeout() on the client builder.
• concepts/request-timeout — set via .timeout() on the request builder.
• concepts/thread-pool-exhaustion — the failure mode unbounded HttpClient calls produce.
• patterns/explicit-timeout-on-remote-calls — the house- style rule that HttpClient defaults violate.