Spring Boot Rate Limiting with Interceptors

Your learning outcome for this lesson:

By the end of this lesson, you will be able to integrate the rate limiter into the Spring Boot request lifecycle using the configured interceptor and return an HTTP 429 (Too Many Requests) response when a limit is exceeded.

1. Intercepting Requests with HandlerInterceptor

To check if a request should be rate-limited, we need to execute our logic before the request reaches the controller's handler method. If we wait until the controller method is executing, we've already wasted server resources on a request that should have been blocked.

Spring MVC provides a powerful mechanism for this called a HandlerInterceptor. It allows you to "intercept" the request-response cycle at three key points.

The HandlerInterceptor interface has three default methods you can override:

1. preHandle(): Executed before the target controller method. This is where we will implement our rate-limiting check. It returns a boolean: true to continue processing the request, false to stop it.
2. postHandle(): Executed after the controller method but before the response is sent to the client. Useful for modifying the response or adding common headers.
3. afterCompletion(): Executed after the complete request has finished and the response has been sent. Useful for cleanup tasks.

Let's watch a video that introduces the concept and demonstrates how to create and register a basic interceptor.

2. Implementing the RateLimitInterceptor

Now, let's create our own RateLimitInterceptor. This class will be the central point of our integration, bringing together the key resolver and the rate limiter logic.

Here are the steps we'll follow in our implementation:

1. Create the class: It will implement the HandlerInterceptor interface.
2. Make it a Spring Bean: We'll annotate it with @Component so Spring's dependency injection container can manage it.
3. Inject Dependencies: We'll use constructor injection to get the RateLimiter and RateLimitKeyResolver beans. Since we've defined only one implementation for each so far (FixedWindowCounter and IpAddressKeyResolver, which should also be annotated as @Components), Spring will automatically wire them in.
4. Implement preHandle(): This is where the core logic resides. We'll resolve the key, check the rate limit, and either allow or block the request.

The article snippets below provide excellent templates for our RateLimitInterceptor and its configuration.

Based on this structure, here is the complete code for our RateLimitInterceptor.java. It cleanly integrates the components we've already built.

package com.example.ratelimiter.interceptor;

import com.example.ratelimiter.core.RateLimiter;
import com.example.ratelimiter.core.RateLimitKeyResolver;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

@Component
public class RateLimitInterceptor implements HandlerInterceptor {

    private final RateLimiter rateLimiter;
    private final RateLimitKeyResolver keyResolver;

    // Using constructor injection to get our strategy beans from the Spring context.
    public RateLimitInterceptor(RateLimiter rateLimiter, RateLimitKeyResolver keyResolver) {
        this.rateLimiter = rateLimiter;
        this.keyResolver = keyResolver;
    }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 1. Resolve the client key using our configured strategy.
        String key = keyResolver.resolve(request);

        // 2. Check if the request is allowed by the rate limiter.
        if (rateLimiter.tryAcquire(key)) {
            // If allowed, continue to the controller.
            return true;
        } else {
            // If denied, set the 429 status and stop the request.
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            response.getWriter().write("Too Many Requests");
            return false;
        }
    }
}

3. Registering the Interceptor with Spring

Creating the interceptor class isn't enough. We need to tell Spring when and where to apply it. This is done by creating a configuration class that implements WebMvcConfigurer.

This configuration class will:

1. Be annotated with @Configuration to mark it as a source of bean definitions.
2. Implement the addInterceptors method.
3. Inside addInterceptors, we'll add our RateLimitInterceptor to the InterceptorRegistry.
4. We'll use addPathPatterns to specify that our interceptor should only apply to API endpoints, for example, everything under /api/.

Let's look at another code example and a short video segment that solidify this concept.

Here's the code for our WebConfig.java:

package com.example.ratelimiter.config;

import com.example.ratelimiter.interceptor.RateLimitInterceptor;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    private final RateLimitInterceptor rateLimitInterceptor;

    // Spring injects our interceptor bean here.
    public WebConfig(RateLimitInterceptor rateLimitInterceptor) {
        this.rateLimitInterceptor = rateLimitInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        // Register the interceptor and define which paths it should apply to.
        registry.addInterceptor(rateLimitInterceptor)
                .addPathPatterns("/api/**"); // Protect all endpoints under /api/*
    }
}

With this configuration in place, any HTTP request to a URL like /api/users or /api/products will first pass through our RateLimitInterceptor's preHandle method before it ever reaches the corresponding controller.

Key Takeaways

• HandlerInterceptor is the Spring MVC component used to inject logic into the request lifecycle, perfect for cross-cutting concerns like rate limiting.
• The preHandle method is the ideal place for our check, as it runs before the controller and can prevent the request from proceeding by returning false.
• We use WebMvcConfigurer and the addInterceptors method to register our interceptor with Spring.
• addPathPatterns gives us fine-grained control over which endpoints are protected by the interceptor.
• When a limit is exceeded, we stop the request processing and return an HTTP 429 (Too Many Requests) status code.

Next Steps

Fantastic work! You have now fully integrated the core components of the rate limiter. You have an algorithm, a key resolver, and an interceptor that ties them into the request pipeline.

But how do we know it actually works? In the next lesson, we will focus on verification. You will learn how to write an integration test using @SpringBootTest to simulate a burst of requests and verify that our rate-limited endpoint correctly allows some requests and blocks others with a 429 status.