Implementing `RateLimitKeyResolver`

Your learning outcome for this lesson:

By the end of this lesson, you will be able to design a RateLimitKeyResolver interface for flexible client identification.

1. The Challenge of Client Identification

A rate limiter needs to track usage per client. But who, or what, is a "client"? It could be:

• A user's IP address.
• A specific authenticated user ID.
• An API key assigned to a partner service.
• The API endpoint being called.
• A combination of the above (e.g., limit user X to 10 calls per minute on the /profile endpoint).

Hard-coding the logic to extract these identifiers into our main rate-limiting component would lead to a rigid system, full of if-else statements, that is difficult to extend. Does this problem sound familiar? It's the exact same challenge we faced with the algorithms themselves.

Once again, the Strategy Design Pattern provides the solution. We will define an interface that represents the contract for "resolving a key from a request" and create multiple concrete implementations for different identification strategies.

2. Designing the RateLimitKeyResolver Interface

To design our interface, we can look at existing, battle-tested implementations for inspiration. Spring Cloud Gateway, a popular API gateway project, includes this exact concept.

The Spring Cloud Gateway example uses ServerWebExchange and Mono because it's built on a reactive stack (Spring WebFlux). Since our project uses the traditional servlet stack (Spring Web MVC), we'll adapt this signature. The HttpServletRequest object is the direct equivalent of ServerWebExchange, and we can return a simple String instead of a Mono<String>.

This leads us to a clean and simple interface definition for our project:

import jakarta.servlet.http.HttpServletRequest;

/**
 * A strategy interface for resolving a key from an incoming HTTP request.
 * This key is used to identify the client for rate limiting purposes.
 */
@FunctionalInterface
public interface RateLimitKeyResolver {

    /**
     * Resolves the key for rate limiting from the given HTTP request.
     *
     * @param request The incoming HTTP request.
     * @return The key as a String. Implementations should handle cases where a
     *         key cannot be resolved, typically by returning null or an empty string.
     */
    String resolve(HttpServletRequest request);
}

Note: I've added @FunctionalInterface because our interface has a single abstract method. This is a good practice in modern Java; it allows the interface to be implemented concisely using a lambda expression.

3. Implementing Concrete Key Resolver Strategies

With our interface defined, we can now create concrete strategies for the various identification methods your project requires.

Strategy 1: The IP Address Resolver

The most common strategy is to rate limit based on the client's IP address. A naive implementation might just call request.getRemoteAddr(). However, this fails in most production environments where your application runs behind a load balancer or a reverse proxy. In such cases, getRemoteAddr() will return the IP of the proxy, not the original client.

The standard solution is to inspect the X-Forwarded-For HTTP header.

Based on the logic described in the article, we can write our own IpAddressKeyResolver for Spring MVC:

public class IpAddressKeyResolver implements RateLimitKeyResolver {

    private static final String X_FORWARDED_FOR_HEADER = "X-Forwarded-For";

    @Override
    public String resolve(HttpServletRequest request) {
        String forwardedFor = request.getHeader(X_FORWARDED_FOR_HEADER);

        // If the X-Forwarded-For header is present, it may contain a comma-separated
        // list of IP addresses. The first one is the original client.
        if (forwardedFor != null && !forwardedFor.trim().isEmpty()) {
            return forwardedFor.split(",")[0].trim();
        }

        // If the header is not present, fall back to the remote address.
        return request.getRemoteAddr();
    }
}

This implementation is robust and suitable for a production environment.

Strategy 2: The API Key Resolver

Another common requirement is to limit clients based on a unique API key, usually passed in an HTTP header. The implementation for this is straightforward:

public class ApiKeyResolver implements RateLimitKeyResolver {

    private final String headerName;

    // The header name can be made configurable.
    public ApiKeyResolver(String headerName) {
        this.headerName = headerName;
    }

    @Override
    public String resolve(HttpServletRequest request) {
        return request.getHeader(this.headerName);
    }
}

This simple class demonstrates the power of our abstraction. By instantiating it with new ApiKeyResolver("X-Api-Key"), we have a resolver for that specific header.

Other Potential Strategies

The flexibility of this design allows for many other strategies, fulfilling your project's multi-tenancy requirement:

• User ID Resolver: For authenticated users, you could retrieve the user's ID from Spring Security's SecurityContextHolder.
• Endpoint Resolver: You could use request.getMethod() + "@" + request.getRequestURI() to create a key specific to an endpoint, allowing you to rate limit, for example, POST /api/orders differently from GET /api/products.
• Composite Resolver: You could create a resolver that combines keys, such as userId + ":" + endpointPath, for fine-grained control. We will explore this in a later lesson.

4. How the Pieces Fit Together

Let's visualize how our two strategy interfaces, RateLimiter and RateLimitKeyResolver, will work together inside the Spring HandlerInterceptor we'll build later.

public class RateLimitingInterceptor implements HandlerInterceptor {

    // Our two strategy interfaces
    private final RateLimitKeyResolver keyResolver;
    private final RateLimiter rateLimiter;
    
    // Services to get the right rule and strategies for a request (to be built)
    private final RuleProvider ruleProvider; 
    private final StrategyProvider strategyProvider;

    // Dependencies are injected via constructor
    public RateLimitingInterceptor(...) { ... }

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        // 1. Resolve the key using the KeyResolver strategy
        String key = keyResolver.resolve(request);
        
        if (key == null || key.isEmpty()) {
            // Policy decision: deny or allow if no key is found
            response.sendError(HttpStatus.FORBIDDEN.value(), "Could not identify client");
            return false;
        }

        // 2. Look up the rule and the correct algorithm for this key
        RateLimitRule rule = ruleProvider.getRule(key);
        RateLimiter algorithm = strategyProvider.get(rule.getAlgorithm());

        // 3. Use the RateLimiter strategy to check permission
        if (algorithm.allowRequest(key, rule)) {
            return true; // Request is allowed, proceed to the controller
        } else {
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            // Optional: Add a 'Retry-After' header
            return false; // Request is denied
        }
    }
}

This conceptual code shows a clear separation of concerns:

1. The RateLimitKeyResolver figures out who is calling.
2. The RateLimiter figures out if they are allowed.
3. The HandlerInterceptor orchestrates the process.

Key Takeaways

• Client identification is a core challenge in building a flexible rate limiter.
• The Strategy Design Pattern is the perfect tool to abstract away the logic of how a client is identified.
• We designed a RateLimitKeyResolver interface with a single method: String resolve(HttpServletRequest request).
• We outlined concrete implementations for common strategies like IP address (handling proxies) and API key resolution.
• This design, combined with our RateLimiter interface from the previous lesson, forms the architectural foundation of our multi-tenant rate limiter.

Next Steps

We have now designed the two core abstractions for our rate limiter. In the next module, we will move from design to implementation. Our first step will be to implement the simplest algorithm, the in-memory fixed window counter, and integrate it into our Spring Boot application using the HandlerInterceptor and RateLimitKeyResolver we've just designed.