1. Overview
In this tutorial, we’ll explore a few possible ways to implement request timeouts for a Spring REST API.
Then we’ll discuss the benefits and drawbacks of each. Request timeouts are useful for preventing a poor user experience, especially if there’s an alternative that we can default to when a resource is taking too long. This design pattern is called the Circuit Breaker pattern, but we won’t elaborate more on that here.
2. @Transactional Timeouts
One way we can implement a request timeout on database calls is to take advantage of Spring’s @Transactional annotation. It has a timeout property that we can set. The default value for this property is -1, which is equivalent to not having any timeout at all. For external configuration of the timeout value, we must use a different property, timeoutString, instead.
For example, let’s assume we set this timeout to 30. If the execution time of the annotated method exceeds this number of seconds, an exception will be thrown. This might be useful for rolling back long-running database queries.
To see this in action, we’ll write a very simple JPA repository layer that will represent an external service that takes too long to complete and causes a timeout to occur. This JpaRepository extension has a time-costly method in it:
public interface BookRepository extends JpaRepository<Book, String> {
default int wasteTime() {
Stopwatch watch = Stopwatch.createStarted();
// delay for 2 seconds
while (watch.elapsed(SECONDS) < 2) {
int i = Integer.MIN_VALUE;
while (i < Integer.MAX_VALUE) {
i++;
}
}
}
}
If we invoke our wasteTime() method while inside a transaction with a timeout of 1 second, the timeout will elapse before the method finishes executing:
@GetMapping("/author/transactional")
@Transactional(timeout = 1)
public String getWithTransactionTimeout(@RequestParam String title) {
bookRepository.wasteTime();
return bookRepository.findById(title)
.map(Book::getAuthor)
.orElse("No book found for this title.");
}
Calling this endpoint results in a 500 HTTP error, which we can transform into a more meaningful response. It also requires very little setup to implement.
However, there are a few drawbacks to this timeout solution.
First, it’s dependent on having a database with Spring-managed transactions. Second, it’s not globally applicable to a project, since the annotation must be present on each method or class that needs it. It also doesn’t allow sub-second precision. Finally, it doesn’t cut the request short when the timeout is reached, so the requesting entity still has to wait the full amount of time.
Let’s consider some alternate options.
3. Resilience4j TimeLimiter
Resilience4j is a library that primarily manages fault-tolerance for remote communications. Its TimeLimiter module is what we’re interested in here.
First, we must include the resilience4j-timelimiter dependency in our project:
<dependency>
<groupId>io.github.resilience4j</groupId>
<artifactId>resilience4j-timelimiter</artifactId>
<version>2.1.0</version>
</dependency>
Next, we’ll define a simple TimeLimiter that has a timeout duration of 500 milliseconds:
private TimeLimiter ourTimeLimiter = TimeLimiter.of(TimeLimiterConfig.custom()
.timeoutDuration(Duration.ofMillis(500)).build());
We can easily configure this externally.
We can use our TimeLimiter to wrap the same logic that our @Transactional example used:
@GetMapping("/author/resilience4j")
public Callable<String> getWithResilience4jTimeLimiter(@RequestParam String title) {
return TimeLimiter.decorateFutureSupplier(ourTimeLimiter, () ->
CompletableFuture.supplyAsync(() -> {
bookRepository.wasteTime();
return bookRepository.findById(title)
.map(Book::getAuthor)
.orElse("No book found for this title.");
}));
}
The TimeLimiter offers several benefits over the @Transactional solution. Namely, it supports sub-second precision and immediate notification of the timeout response. However, we still have to manually include it in all endpoints that require a timeout. It also requires some lengthy wrapping code, and the error it produces is still a generic 500 HTTP error. Finally, it requires returning a Callable
The TimeLimiter comprises only a subset of features from Resilience4j, and interfaces nicely with a Circuit Breaker pattern.
4. Spring MVC request-timeout
Spring provides us with a property called spring.mvc.async.request-timeout. This property allows us to define a request timeout with millisecond precision.
Let’s define the property with a 750-millisecond timeout:
spring.mvc.async.request-timeout=750
This property is global and externally configurable, but like the TimeLimiter solution, it only applies to endpoints that return a Callable. Let’s define an endpoint that’s similar to the TimeLimiter example, but without needing to wrap the logic in Futures, or supplying a TimeLimiter:
@GetMapping("/author/mvc-request-timeout")
public Callable<String> getWithMvcRequestTimeout(@RequestParam String title) {
return () -> {
bookRepository.wasteTime();
return bookRepository.findById(title)
.map(Book::getAuthor)
.orElse("No book found for this title.");
};
}
We can see that the code is less verbose, and that Spring automatically implements the configuration when we define the application property. Once the timeout has been reached, the response is returned immediately, and it even returns a more descriptive 503 HTTP error instead of a generic 500. Every endpoint in our project will inherit this timeout configuration automatically.
Now let’s consider another option that will allow us to define timeouts with a little more granularity.
5. WebClient Timeouts
Rather than setting a timeout for an entire endpoint, we may want to simply have a timeout for a single external call. WebClient is Spring’s reactive web client that allows us to configure a response timeout.
It’s also possible to configure timeouts on Spring’s older RestTemplate object; however, most developers now prefer WebClient over RestTemplate.
To use WebClient, we must first add Spring’s WebFlux dependency to our project:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
<version>2.4.2</version>
</dependency>
Let’s define a WebClient with a response timeout of 250 milliseconds that we can use to call ourselves via localhost in its base URL:
@Bean
public WebClient webClient() {
return WebClient.builder()
.baseUrl("http://localhost:8080")
.clientConnector(new ReactorClientHttpConnector(
HttpClient.create().responseTimeout(Duration.ofMillis(250))
))
.build();
}
Clearly, we can easily configure this timeout value externally. We can also configure the base URL externally, as well as several other optional properties.
Now we can inject our WebClient into our controller, and use it to call our own /transactional endpoint, which still has a timeout of 1 second. Since we configured our WebClient to timeout in 250 milliseconds, we should see it fail much faster than 1 second.
Here is our new endpoint:
@GetMapping("/author/webclient")
public String getWithWebClient(@RequestParam String title) {
return webClient.get()
.uri(uriBuilder -> uriBuilder
.path("/author/transactional")
.queryParam("title", title)
.build())
.retrieve()
.bodyToMono(String.class)
.block();
}
After calling this endpoint, we can see that we do receive the WebClient‘s timeout in the form of a 500 HTTP error response. We can also check the logs to see the downstream @Transactional timeout, but its timeout will be printed remotely if we called an external service instead of localhost.
Configuring different request timeouts for different backend services may be necessary, and is possible with this solution. Also, the Mono or Flux response that publishers returned by WebClient contain plenty of error handling methods for handling the generic timeout error response.
6. Conclusion
In this article, we explored several different solutions for implementing a request timeout. There are several factors to consider when deciding which one to use.
If we want to place a timeout on our database requests, we might want to use Spring’s @Transactional method and its timeout property. If we’re trying to integrate with a broader Circuit Breaker pattern, using Resilience4j’s TimeLimiter would make sense. Using the Spring MVC request-timeout property is best for setting a global timeout for all requests, but we can also easily define more granular timeouts per resource with WebClient.
For a working example of all of these solutions, the code is ready and runnable out of the box over on GitHub.