tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance

Build fault-tolerant network services

—

Pending

Overview

Eval results

Files

Rate Limiting Strategies

Name: tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance
Author: tessl

Controls the frequency of method invocations with configurable time windows, minimum spacing between calls, and different rate limiting algorithms.

Capabilities

Basic Rate Limiting

Standard rate limiting with time windows and invocation limits.

@RateLimit(
    value = 100,
    window = 1,
    windowUnit = ChronoUnit.MINUTES,
    minSpacing = 0,
    minSpacingUnit = ChronoUnit.MILLIS,
    type = RateLimitType.FIXED
)
public ReturnType rateLimitedMethod();

Parameters

value - Maximum invocations per time window (default: 100)
window - Time window length (default: 1)
windowUnit - Time unit for window (default: SECONDS)
minSpacing - Minimum time between invocations (default: 0)
minSpacingUnit - Time unit for min spacing (default: MILLIS)
type - Rate limit algorithm type (default: FIXED)

Rate Limit Types

FIXED - Fixed time windows
ROLLING - Rolling time windows
SMOOTH - Token bucket algorithm

Usage Example

@ApplicationScoped
public class ApiController {
    
    // Public API endpoint with rate limiting
    @RateLimit(
        value = 10,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.ROLLING
    )
    public ApiResponse publicEndpoint(ApiRequest request) {
        return apiService.process(request);
    }
    
    // Premium API with higher limits
    @RateLimit(
        value = 100,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.SMOOTH
    )
    public ApiResponse premiumEndpoint(ApiRequest request) {
        return premiumApiService.process(request);
    }
    
    // Batch operations with spacing
    @RateLimit(
        value = 5,
        window = 10,
        windowUnit = ChronoUnit.SECONDS,
        minSpacing = 1000,
        minSpacingUnit = ChronoUnit.MILLIS
    )
    public BatchResult processBatch(BatchRequest request) {
        return batchProcessor.process(request);
    }
}

Rate Limiting with External APIs

Protecting external API calls from exceeding provider limits.

Usage Example

@ApplicationScoped
public class ExternalServiceClient {
    
    // Third-party API with strict rate limits
    @RateLimit(
        value = 50,
        window = 1,
        windowUnit = ChronoUnit.HOURS,
        type = RateLimitType.FIXED
    )
    @Fallback(fallbackMethod = "getCachedData")
    public ExternalApiResponse callThirdPartyApi(String query) throws RateLimitException {
        return thirdPartyClient.query(query);
    }
    
    public ExternalApiResponse getCachedData(String query) {
        return cache.get(query, ExternalApiResponse.class)
            .orElse(ExternalApiResponse.empty());
    }
    
    // Google API with per-minute limits
    @RateLimit(
        value = 100,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.ROLLING
    )
    @Retry(maxRetries = 3, delay = 5000)
    public GoogleApiResponse callGoogleApi(GoogleApiRequest request) {
        return googleApiClient.call(request);
    }
    
    // Social media API with burst and sustained limits
    @RateLimit(
        value = 15,
        window = 15,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.ROLLING
    )
    public SocialMediaPost postToSocialMedia(PostData data) throws RateLimitException {
        return socialMediaClient.post(data);
    }
}

Combined Rate Limiting Strategies

Rate limiting combined with other fault tolerance patterns.

@RateLimit(value = 20, window = 1, windowUnit = ChronoUnit.MINUTES)
@CircuitBreaker(requestVolumeThreshold = 10, failureRatio = 0.5)
@Retry(maxRetries = 2)
public ReturnType combinedStrategy();

Usage Example

@ApplicationScoped
public class NotificationService {
    
    // Email service with rate limiting and circuit breaker
    @RateLimit(
        value = 200,
        window = 1,
        windowUnit = ChronoUnit.HOURS,
        type = RateLimitType.SMOOTH
    )
    @CircuitBreaker(requestVolumeThreshold = 15, failureRatio = 0.4)
    @Fallback(fallbackMethod = "queueEmail")
    public EmailResult sendEmail(EmailMessage message) throws EmailException {
        return emailProvider.send(message);
    }
    
    public EmailResult queueEmail(EmailMessage message) {
        emailQueue.enqueue(message);
        return EmailResult.queued(message.getId());
    }
    
    // SMS service with strict rate limiting
    @RateLimit(
        value = 50,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        minSpacing = 500,
        minSpacingUnit = ChronoUnit.MILLIS
    )
    @Timeout(10000)
    @Retry(maxRetries = 2, delay = 2000)
    public SmsResult sendSms(SmsMessage message) throws SmsException {
        return smsProvider.send(message);
    }
}

User-specific Rate Limiting

Rate limiting based on user context or request attributes.

Usage Example

@ApplicationScoped
public class UserApiController {
    
    @Inject
    SecurityContext securityContext;
    
    // Basic user operations
    @RateLimit(
        value = 60,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.ROLLING
    )
    public UserData getUserData(String userId) {
        // Rate limit is applied per user context
        return userService.getData(userId);
    }
    
    // Premium user operations with higher limits
    @RateLimit(
        value = 500,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.SMOOTH
    )
    public UserData getPremiumUserData(String userId) {
        // Higher rate limits for premium users
        return premiumUserService.getData(userId);
    }
    
    // File upload with size-based rate limiting
    @RateLimit(
        value = 10,
        window = 1,
        windowUnit = ChronoUnit.HOURS,
        minSpacing = 30000,
        minSpacingUnit = ChronoUnit.MILLIS
    )
    @Bulkhead(value = 3)
    public UploadResult uploadFile(FileUploadRequest request) {
        return fileUploadService.upload(request);
    }
}

Background Task Rate Limiting

Rate limiting for background processes and scheduled tasks.

Usage Example

@ApplicationScoped
public class BackgroundTaskService {
    
    // Data synchronization with external system
    @RateLimit(
        value = 10,
        window = 1,
        windowUnit = ChronoUnit.MINUTES,
        type = RateLimitType.FIXED
    )
    @Scheduled(every = "30s")
    public void synchronizeData() {
        dataSyncService.syncWithExternalSystem();
    }
    
    // Report generation
    @RateLimit(
        value = 5,
        window = 1,
        windowUnit = ChronoUnit.HOURS,
        minSpacing = 600000,
        minSpacingUnit = ChronoUnit.MILLIS
    )
    public ReportResult generateReport(ReportRequest request) {
        return reportGenerator.generate(request);
    }
    
    // Cleanup operations
    @RateLimit(
        value = 1,
        window = 1,
        windowUnit = ChronoUnit.HOURS
    )
    @Scheduled(cron = "0 0 * * * ?")
    public void performCleanup() {
        cleanupService.cleanupOldData();
    }
}

Types

Rate Limiting Core Types

// Rate limit algorithm types
enum RateLimitType {
    FIXED,   // Fixed time windows
    ROLLING, // Rolling time windows  
    SMOOTH   // Token bucket algorithm
}

// Rate limit exception
class RateLimitException extends RuntimeException {
    public RateLimitException(String message);
    public RateLimitException(String message, Throwable cause);
}

// Time units for rate limiting
enum ChronoUnit {
    NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS, DAYS
}

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance

docs

asynchronous-strategies.md

bulkhead-strategies.md

circuit-breaker-strategies.md

configuration.md

fallback-strategies.md

index.md

programmatic-api.md

rate-limiting-strategies.md

retry-strategies.md

timeout-strategies.md

tile.json

tessl/maven-io-quarkus--quarkus-smallrye-fault-tolerance