Token Bucket

Parameters

• bucketSize, refillRate.

Description

• Global bucket limits requests across all users.
• Tokens are consumed per request; when out of tokens, requests are dropped until the next refill.

Example: bucketSize = 5, refillRate = 1 token/sec.

• T0 (01:00:00.000): Bucket starts full with 4 tokens.
• T1 (01:00:01.100): 1 request arrives, consumes 1 token, 3 tokens left.
• T2 (01:00:01.200): 3 more requests arrive, consume 3 tokens, bucket empty.
• T3 (01:00:01.300): No tokens, requests dropped. Bucket refills 4 token per second.
• T4 (01:00:02.000): Bucket is refilled with all 5 tokens.
• T5 (01:00:02.100): 1 request arrives, consumes 1 token, 3 tokens left.
• T6 (01:00:03.000): No more requests so far. Bucket is refilled back to 4 tokens (adds 3 missing ones).

How to use

When creating your API, you can use the RateLimitFactory to create a leaking bucket rate limit.

Api.create(8080)
      .rateLimit(RateLimitFactory.customTokenBucket(4, Duration.ofSeconds(1)))
      .addRoute(Route.builder("/"),
      .path(RouteMethod.GET, "/", controller::handler))
      .start();
          

Factory

The RateLimitFactory provides a default and a custom method for this rate limiter.

• For more details on the check the source code of the RateLimitFactory

See more in our blog post about Rate Limiters