Set a Timeout in Spring WebClient

1. Overview

Spring 5 added a completely new framework – Spring WebFlux, which supports reactive programming in our web applications. To perform HTTP requests, we can use the WebClient interface, which provides a functional API based on the Reactor Project.

In this tutorial, we’ll focus on timeout settings for our WebClient. We’ll discuss different methods, how to set the different timeouts properly, both globally in the whole application and specific to a request.

2. WebClient and HTTP Clients

Before we move on, let’s make a quick recap. Spring WebFlux includes its own client, the WebClient class, to perform HTTP requests in a reactive way. The WebClient also requires an HTTP client library to work properly. Spring delivers built-in support for some of them, but the Reactor Netty is used by default.

Most of the configurations, including timeouts, can be done using those clients.

3. Configuring Timeouts via HTTP Client

As we mentioned previously, the easiest way to set different WebClient timeouts in our application is to set them globally using an underlying HTTP client. It’s also the most efficient way to do this.

As Netty is a default client library for the Spring WebFlux, we’ll cover our examples using the Reactor Netty HttpClient class.

3.1. Response Timeout

The response timeout is the time we wait to receive a response after sending a request. We can use the responseTimeout() method to configure it for the client:

HttpClient client = HttpClient.create()
  .responseTimeout(Duration.ofSeconds(1)); 

In this example, we configure the timeout for 1 second. Netty doesn’t set the response timeout by default.

After that, we can supply the HttpClient to the Spring WebClient:

WebClient webClient = WebClient.builder()
  .clientConnector(new ReactorClientHttpConnector(httpClient))
  .build();

After doing that, the WebClient inherits all the configurations provided by the underlying HttpClient for all requests sent.

3.2. Connection Timeout

The connection timeout is a period within which a connection between a client and a server must be established. We can use different channel options keys and the option() method to perform the configuration:

HttpClient client = HttpClient.create()
  .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);

// create WebClient...

The value provided is in milliseconds, so we configured the timeout for 10 seconds. Netty sets that value to 30 seconds by default.

Moreover, we can configure the keep-alive option, which will send TCP check probes when the connection is idle:

HttpClient client = HttpClient.create()
  .option(ChannelOption.SO_KEEPALIVE, true)
  .option(EpollChannelOption.TCP_KEEPIDLE, 300)
  .option(EpollChannelOption.TCP_KEEPINTVL, 60)
  .option(EpollChannelOption.TCP_KEEPCNT, 8);

// create WebClient...

So, we’ve enabled keep-alive checks to probe after 5 minutes of being idle, at 60 seconds intervals. We also set the maximum number of probes before the connection dropping to 8.

When the connection is not established in a given time or dropped, a ConnectTimeoutException is thrown.

3.3. Read and Write Timeout

A read timeout occurs when no data was read within a certain period of time, while the write timeout when a write operation cannot finish at a specific time. The HttpClient allows to configure additional handlers to configure those timeouts:

HttpClient client = HttpClient.create()
  .doOnConnected(conn -> conn
    .addHandler(new ReadTimeoutHandler(10, TimeUnit.SECONDS))
    .addHandler(new WriteTimeoutHandler(10)));

// create WebClient...

In this situation, we configured a connected callback via the doOnConnected() method, where we created additional handlers. To configure timeouts we added ReadTimeOutHandler and WriteTimeOutHandler instances. We set both of them to 10 seconds.

The constructors for these handlers accept two variants of parameters. For the first one, we provided a number with the TimeUnit specification, while the second converts the given number to seconds.

The underlying Netty library delivers ReadTimeoutException and WriteTimeoutException classes accordingly to handle errors.

3.4. SSL/TLS Timeout

The handshake timeout is the duration in time that the system tries to establish an SSL connection before halting the operation. We can set the SSL configuration via the secure() method:

HttpClient.create()
  .secure(spec -> spec.sslContext(SslContextBuilder.forClient())
    .defaultConfiguration(SslProvider.DefaultConfigurationType.TCP)
    .handshakeTimeout(Duration.ofSeconds(30))
    .closeNotifyFlushTimeout(Duration.ofSeconds(10))
    .closeNotifyReadTimeout(Duration.ofSeconds(10)));

// create WebClient...

As above, we set a handshake timeout to 30 seconds (default: 10s), while close_notify flush (default: 3s) and read (default: 0s) timeouts to 10 seconds. All methods are delivered by the SslProvider.Builder interface.

The SslHandshakeTimeoutException is used when a handshake failed due to a configured timeout.

3.5. Proxy Timeout

HttpClient also supports proxy functionality. If the connection establishment attempt to the peer does not finish within the proxy timeout, the connection attempt fails. We set this timeout during the proxy() configuration:

HttpClient.create()
  .proxy(spec -> spec.type(ProxyProvider.Proxy.HTTP)
    .host("proxy")
    .port(8080)
    .connectTimeoutMillis(30000));

// create WebClient...

We used connectTimeoutMillis() to set the timeout to 30 seconds when the default value is 10.

The Netty library also implements its own ProxyConnectException in case of any fails.

4. Request-Level Timeouts

In the previous section, we configured different timeouts globally using HttpClient. However, we can also set the response request-specific timeouts independently of the global settings.

4.1. Response Timeout – Using HttpClientRequest

As previously, we can configure the response timeout also at the request level:

webClient.get()
  .uri("https://baeldung.com/path")
  .httpRequest(httpRequest -> {
    HttpClientRequest reactorRequest = httpRequest.getNativeRequest();
    reactorRequest.responseTimeout(Duration.ofSeconds(2));
  });

In the case above, we used the WebClient’s httpRequest() method to get access to the native HttpClientRequest from the underlying Netty library. Next, we used it to set the timeout value to 2 seconds.

This kind of response timeout setting overrides any response timeout on the HttpClient level. We can also set this value to null to remove any previously configured value.

4.2. Reactive Timeout – Using Reactor Core

Reactor Netty uses Reactor Core as its Reactive Streams implementation. To configure another timeout, we can use the timeout() operator provided by Mono and Flux publishers:

webClient.get()
  .uri("https://baeldung.com/path")
  .retrieve()
  .bodyToFlux(JsonNode.class)
  .timeout(Duration.ofSeconds(5));

In that situation, the TimeoutException will appear in case no item arrives within the given 5 seconds.

Keep in mind that it’s better to use the more specific timeout configuration options available in Reactor Netty since they provide more control for a specific purpose and use case.

The timeout() method applies to the whole operation, from establishing the connection to the remote peer to receiving the response. It doesn’t override any HttpClient related settings.

5. Exception Handling

We’ve just learned about different timeout configurations. Now it’s time to quickly talk about exception handling. Each type of timeout delivers a dedicated exception, so we can easily handle them using Ractive Streams and onError blocks:

webClient.get()
  .uri("https://baeldung.com/path")
  .retrieve()
  .bodyToFlux(JsonNode.class)
  .timeout(Duration.ofSeconds(5))
  .onErrorMap(ReadTimeoutException.class, ex -> new HttpTimeoutException("ReadTimeout"))
  .onErrorReturn(SslHandshakeTimeoutException.class, new TextNode("SslHandshakeTimeout"))
  .doOnError(WriteTimeoutException.class, ex -> log.error("WriteTimeout"))
  ...

We can reuse any previously described exceptions and write our own handling methods using Reactor.

Moreover, we can also add some logic according to the HTTP status:

webClient.get()
  .uri("https://baeldung.com/path")
  .onStatus(HttpStatus::is4xxClientError, resp -> {
    log.error("ClientError {}", resp.statusCode());
    return Mono.error(new RuntimeException("ClientError"));
  })
  .retrieve()
  .bodyToFlux(JsonNode.class)
  ...

6. Conclusion

In this tutorial, we learned how to configure timeouts in Spring WebFlux on our WebClient using Netty examples.

We quickly talked about different timeouts and the ways to set them correctly at the HttpClient level and also how to apply them to our global settings. Then, we worked with a single request to configure the response timeout at a request-specific level. Finally, we showed different methods to handle occurring exceptions.