Custom key resolver

A key resolver determines which requests share the same rate limit bucket. Custom resolvers let you implement advanced strategies like per-tenant limiting, API key-based limits, or composite keys.

Understanding key resolvers

The RateLimitKeyResolver interface (from key/RateLimitKeyResolver.java:11-21) is responsible for generating a unique key that identifies which bucket a request should be counted against:

public interface RateLimitKeyResolver {
    /**
     * Compute a key identifying the caller/bucket.
     * Guidelines:
     * - Return a non-empty, stable string (same caller -> same key)
     * - Prefer predictable formats (e.g., "user:123", "ip:203.0.113.10")
     */
    String resolveKey(RateLimitContext context);
}

Default behavior

The DefaultRateLimitKeyResolver (from key/DefaultRateLimitKeyResolver.java:11-32) creates keys from scope and method metadata:

@Override
public String resolveKey(RateLimitContext context) {
    RateLimit annotation = context.getAnnotation();
    
    String scope = normalizeScope(annotation.scope());
    if (annotation.key() != null && !annotation.key().isBlank()) {
        return scope + ":" + annotation.key().trim();
    }
    
    return scope + ":" + context.getTargetClass().getName() 
        + "#" + context.getMethod().getName();
}

This generates keys like:

global:com.example.ApiController#getData
user:search (when key = "search" is specified)

Create your resolver class

Implement the RateLimitKeyResolver interface:

package com.example.ratelimit;

import io.github.v4runsharma.ratelimiter.core.RateLimitContext;
import io.github.v4runsharma.ratelimiter.key.RateLimitKeyResolver;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.stereotype.Component;

@Component
public class UserIdKeyResolver implements RateLimitKeyResolver {

    @Override
    public String resolveKey(RateLimitContext context) {
        Authentication auth = SecurityContextHolder.getContext().getAuthentication();
        
        if (auth == null || !auth.isAuthenticated()) {
            return "anonymous";
        }
        
        String userId = auth.getName();
        String methodName = context.getMethod().getName();
        
        return "user:" + userId + ":" + methodName;
    }
}

Reference the resolver in your annotation

Use the keyResolver parameter to specify your custom resolver:

import com.example.ratelimit.UserIdKeyResolver;
import io.github.v4runsharma.ratelimiter.annotation.RateLimit;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ApiController {

    @RateLimit(
        limit = 10,
        duration = 1,
        keyResolver = UserIdKeyResolver.class
    )
    @GetMapping("/api/data")
    public String getData() {
        return "Data";
    }
}

Access invocation context

The RateLimitContext interface (from core/RateLimitContext.java:15-46) provides rich information about the invocation:

public interface RateLimitContext {
    RateLimit getAnnotation();      // The @RateLimit annotation
    Class<?> getTargetClass();      // The controller class
    Method getMethod();             // The method being called
    Object[] getArguments();        // Method arguments
    Object getTarget();             // The target instance
}

You can use this to extract parameters, inspect annotations, or access instance state.

Example: API key resolver

Limit requests per API key extracted from a header:

import io.github.v4runsharma.ratelimiter.core.RateLimitContext;
import io.github.v4runsharma.ratelimiter.key.RateLimitKeyResolver;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Component;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;

@Component
public class ApiKeyResolver implements RateLimitKeyResolver {

    @Override
    public String resolveKey(RateLimitContext context) {
        HttpServletRequest request = getCurrentRequest();
        
        String apiKey = request.getHeader("X-API-Key");
        if (apiKey == null || apiKey.isBlank()) {
            return "no-api-key";
        }
        
        return "apikey:" + apiKey;
    }
    
    private HttpServletRequest getCurrentRequest() {
        ServletRequestAttributes attrs = 
            (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        return attrs.getRequest();
    }
}

Example: Tenant-based resolver

Group rate limits by tenant ID:

import io.github.v4runsharma.ratelimiter.core.RateLimitContext;
import io.github.v4runsharma.ratelimiter.key.RateLimitKeyResolver;
import org.springframework.stereotype.Component;

@Component
public class TenantKeyResolver implements RateLimitKeyResolver {

    private final TenantContext tenantContext;
    
    public TenantKeyResolver(TenantContext tenantContext) {
        this.tenantContext = tenantContext;
    }

    @Override
    public String resolveKey(RateLimitContext context) {
        String tenantId = tenantContext.getCurrentTenantId();
        String endpoint = context.getMethod().getName();
        
        return "tenant:" + tenantId + ":" + endpoint;
    }
}

Example: Parameter-based resolver

Extract keys from method parameters:

import io.github.v4runsharma.ratelimiter.core.RateLimitContext;
import io.github.v4runsharma.ratelimiter.key.RateLimitKeyResolver;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.PathVariable;

import java.lang.reflect.Parameter;

@Component
public class ResourceIdResolver implements RateLimitKeyResolver {

    @Override
    public String resolveKey(RateLimitContext context) {
        Parameter[] parameters = context.getMethod().getParameters();
        Object[] arguments = context.getArguments();
        
        for (int i = 0; i < parameters.length; i++) {
            if (parameters[i].isAnnotationPresent(PathVariable.class)) {
                PathVariable pathVar = parameters[i].getAnnotation(PathVariable.class);
                if ("resourceId".equals(pathVar.value())) {
                    return "resource:" + arguments[i];
                }
            }
        }
        
        return "unknown";
    }
}

Usage:

@RateLimit(
    limit = 100,
    duration = 1,
    keyResolver = ResourceIdResolver.class
)
@GetMapping("/api/resources/{resourceId}")
public Resource getResource(@PathVariable String resourceId) {
    return resourceService.findById(resourceId);
}

Best practices

Return stable, predictable keys

Keys should be deterministic - the same caller should always get the same key:

// Good: Stable key format
return "user:" + userId + ":" + methodName;

// Bad: Non-deterministic (includes timestamp)
return "user:" + userId + ":" + System.currentTimeMillis();

Handle missing context gracefully

Always provide a fallback when context is unavailable:

@Override
public String resolveKey(RateLimitContext context) {
    Authentication auth = SecurityContextHolder.getContext().getAuthentication();
    
    if (auth == null || !auth.isAuthenticated()) {
        return "anonymous";  // Fallback for unauthenticated users
    }
    
    return "user:" + auth.getName();
}

Use meaningful prefixes

Prefix keys with their type for clarity and to avoid collisions:

// Good: Clear prefixes
return "user:" + userId;
return "apikey:" + apiKey;
return "ip:" + ipAddress;

// Bad: No context
return userId;
return apiKey;

Consider key cardinality

Be mindful of how many unique keys you generate:

// High cardinality: One bucket per user per endpoint
return "user:" + userId + ":" + methodName;

// Lower cardinality: One bucket per user across all endpoints
return "user:" + userId;

// Lowest cardinality: One global bucket
return "global";

Higher cardinality provides more granular control but uses more Redis memory.

Register as default resolver

To use your resolver as the default for all annotations:

import io.github.v4runsharma.ratelimiter.key.RateLimitKeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;

@Configuration
public class RateLimiterConfig {

    @Bean
    @Primary
    public RateLimitKeyResolver defaultKeyResolver() {
        return new UserIdKeyResolver();
    }
}

Now all @RateLimit annotations without an explicit keyResolver will use your custom resolver.

Get Started

Core Concepts

Guides

Configuration

Understanding key resolvers

Default behavior

Example: API key resolver

Example: Tenant-based resolver

Example: Parameter-based resolver

Best practices

Return stable, predictable keys

Handle missing context gracefully

Use meaningful prefixes

Consider key cardinality

Register as default resolver

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Configuration

​Understanding key resolvers

​Default behavior

​Example: API key resolver

​Example: Tenant-based resolver

​Example: Parameter-based resolver

​Best practices

​Return stable, predictable keys

​Handle missing context gracefully

​Use meaningful prefixes

​Consider key cardinality

​Register as default resolver

Build docs developers (and LLMs) love

Understanding key resolvers

Default behavior

Example: API key resolver

Example: Tenant-based resolver

Example: Parameter-based resolver

Best practices

Return stable, predictable keys

Handle missing context gracefully

Use meaningful prefixes

Consider key cardinality

Register as default resolver