0
# Rate Limiting Strategies
1
2
Controls the frequency of method invocations with configurable time windows, minimum spacing between calls, and different rate limiting algorithms.
3
4
## Capabilities
5
6
### Basic Rate Limiting
7
8
Standard rate limiting with time windows and invocation limits.
9
10
```java { .api }
11
@RateLimit(
12
value = 100,
13
window = 1,
14
windowUnit = ChronoUnit.MINUTES,
15
minSpacing = 0,
16
minSpacingUnit = ChronoUnit.MILLIS,
17
type = RateLimitType.FIXED
18
)
19
public ReturnType rateLimitedMethod();
20
```
21
22
#### Parameters
23
24
- `value` - Maximum invocations per time window (default: 100)
25
- `window` - Time window length (default: 1)
26
- `windowUnit` - Time unit for window (default: SECONDS)
27
- `minSpacing` - Minimum time between invocations (default: 0)
28
- `minSpacingUnit` - Time unit for min spacing (default: MILLIS)
29
- `type` - Rate limit algorithm type (default: FIXED)
30
31
#### Rate Limit Types
32
33
- `FIXED` - Fixed time windows
34
- `ROLLING` - Rolling time windows
35
- `SMOOTH` - Token bucket algorithm
36
37
#### Usage Example
38
39
```java
40
@ApplicationScoped
41
public class ApiController {
42
43
// Public API endpoint with rate limiting
44
@RateLimit(
45
value = 10,
46
window = 1,
47
windowUnit = ChronoUnit.MINUTES,
48
type = RateLimitType.ROLLING
49
)
50
public ApiResponse publicEndpoint(ApiRequest request) {
51
return apiService.process(request);
52
}
53
54
// Premium API with higher limits
55
@RateLimit(
56
value = 100,
57
window = 1,
58
windowUnit = ChronoUnit.MINUTES,
59
type = RateLimitType.SMOOTH
60
)
61
public ApiResponse premiumEndpoint(ApiRequest request) {
62
return premiumApiService.process(request);
63
}
64
65
// Batch operations with spacing
66
@RateLimit(
67
value = 5,
68
window = 10,
69
windowUnit = ChronoUnit.SECONDS,
70
minSpacing = 1000,
71
minSpacingUnit = ChronoUnit.MILLIS
72
)
73
public BatchResult processBatch(BatchRequest request) {
74
return batchProcessor.process(request);
75
}
76
}
77
```
78
79
### Rate Limiting with External APIs
80
81
Protecting external API calls from exceeding provider limits.
82
83
#### Usage Example
84
85
```java
86
@ApplicationScoped
87
public class ExternalServiceClient {
88
89
// Third-party API with strict rate limits
90
@RateLimit(
91
value = 50,
92
window = 1,
93
windowUnit = ChronoUnit.HOURS,
94
type = RateLimitType.FIXED
95
)
96
@Fallback(fallbackMethod = "getCachedData")
97
public ExternalApiResponse callThirdPartyApi(String query) throws RateLimitException {
98
return thirdPartyClient.query(query);
99
}
100
101
public ExternalApiResponse getCachedData(String query) {
102
return cache.get(query, ExternalApiResponse.class)
103
.orElse(ExternalApiResponse.empty());
104
}
105
106
// Google API with per-minute limits
107
@RateLimit(
108
value = 100,
109
window = 1,
110
windowUnit = ChronoUnit.MINUTES,
111
type = RateLimitType.ROLLING
112
)
113
@Retry(maxRetries = 3, delay = 5000)
114
public GoogleApiResponse callGoogleApi(GoogleApiRequest request) {
115
return googleApiClient.call(request);
116
}
117
118
// Social media API with burst and sustained limits
119
@RateLimit(
120
value = 15,
121
window = 15,
122
windowUnit = ChronoUnit.MINUTES,
123
type = RateLimitType.ROLLING
124
)
125
public SocialMediaPost postToSocialMedia(PostData data) throws RateLimitException {
126
return socialMediaClient.post(data);
127
}
128
}
129
```
130
131
### Combined Rate Limiting Strategies
132
133
Rate limiting combined with other fault tolerance patterns.
134
135
```java { .api }
136
@RateLimit(value = 20, window = 1, windowUnit = ChronoUnit.MINUTES)
137
@CircuitBreaker(requestVolumeThreshold = 10, failureRatio = 0.5)
138
@Retry(maxRetries = 2)
139
public ReturnType combinedStrategy();
140
```
141
142
#### Usage Example
143
144
```java
145
@ApplicationScoped
146
public class NotificationService {
147
148
// Email service with rate limiting and circuit breaker
149
@RateLimit(
150
value = 200,
151
window = 1,
152
windowUnit = ChronoUnit.HOURS,
153
type = RateLimitType.SMOOTH
154
)
155
@CircuitBreaker(requestVolumeThreshold = 15, failureRatio = 0.4)
156
@Fallback(fallbackMethod = "queueEmail")
157
public EmailResult sendEmail(EmailMessage message) throws EmailException {
158
return emailProvider.send(message);
159
}
160
161
public EmailResult queueEmail(EmailMessage message) {
162
emailQueue.enqueue(message);
163
return EmailResult.queued(message.getId());
164
}
165
166
// SMS service with strict rate limiting
167
@RateLimit(
168
value = 50,
169
window = 1,
170
windowUnit = ChronoUnit.MINUTES,
171
minSpacing = 500,
172
minSpacingUnit = ChronoUnit.MILLIS
173
)
174
@Timeout(10000)
175
@Retry(maxRetries = 2, delay = 2000)
176
public SmsResult sendSms(SmsMessage message) throws SmsException {
177
return smsProvider.send(message);
178
}
179
}
180
```
181
182
### User-specific Rate Limiting
183
184
Rate limiting based on user context or request attributes.
185
186
#### Usage Example
187
188
```java
189
@ApplicationScoped
190
public class UserApiController {
191
192
@Inject
193
SecurityContext securityContext;
194
195
// Basic user operations
196
@RateLimit(
197
value = 60,
198
window = 1,
199
windowUnit = ChronoUnit.MINUTES,
200
type = RateLimitType.ROLLING
201
)
202
public UserData getUserData(String userId) {
203
// Rate limit is applied per user context
204
return userService.getData(userId);
205
}
206
207
// Premium user operations with higher limits
208
@RateLimit(
209
value = 500,
210
window = 1,
211
windowUnit = ChronoUnit.MINUTES,
212
type = RateLimitType.SMOOTH
213
)
214
public UserData getPremiumUserData(String userId) {
215
// Higher rate limits for premium users
216
return premiumUserService.getData(userId);
217
}
218
219
// File upload with size-based rate limiting
220
@RateLimit(
221
value = 10,
222
window = 1,
223
windowUnit = ChronoUnit.HOURS,
224
minSpacing = 30000,
225
minSpacingUnit = ChronoUnit.MILLIS
226
)
227
@Bulkhead(value = 3)
228
public UploadResult uploadFile(FileUploadRequest request) {
229
return fileUploadService.upload(request);
230
}
231
}
232
```
233
234
### Background Task Rate Limiting
235
236
Rate limiting for background processes and scheduled tasks.
237
238
#### Usage Example
239
240
```java
241
@ApplicationScoped
242
public class BackgroundTaskService {
243
244
// Data synchronization with external system
245
@RateLimit(
246
value = 10,
247
window = 1,
248
windowUnit = ChronoUnit.MINUTES,
249
type = RateLimitType.FIXED
250
)
251
@Scheduled(every = "30s")
252
public void synchronizeData() {
253
dataSyncService.syncWithExternalSystem();
254
}
255
256
// Report generation
257
@RateLimit(
258
value = 5,
259
window = 1,
260
windowUnit = ChronoUnit.HOURS,
261
minSpacing = 600000,
262
minSpacingUnit = ChronoUnit.MILLIS
263
)
264
public ReportResult generateReport(ReportRequest request) {
265
return reportGenerator.generate(request);
266
}
267
268
// Cleanup operations
269
@RateLimit(
270
value = 1,
271
window = 1,
272
windowUnit = ChronoUnit.HOURS
273
)
274
@Scheduled(cron = "0 0 * * * ?")
275
public void performCleanup() {
276
cleanupService.cleanupOldData();
277
}
278
}
279
```
280
281
## Types
282
283
### Rate Limiting Core Types
284
285
```java { .api }
286
// Rate limit algorithm types
287
enum RateLimitType {
288
FIXED, // Fixed time windows
289
ROLLING, // Rolling time windows
290
SMOOTH // Token bucket algorithm
291
}
292
293
// Rate limit exception
294
class RateLimitException extends RuntimeException {
295
public RateLimitException(String message);
296
public RateLimitException(String message, Throwable cause);
297
}
298
299
// Time units for rate limiting
300
enum ChronoUnit {
301
NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS, DAYS
302
}
303
```