Bucket capacity with multiple bandwidths

[alantonica]

Hi,

I'm struggling to understand how the capacity is set up for a bucket.
The documentation states:

By default initial size of the bucket equals capacity and if you want to have a smaller amount in the bucket you use withInitialTokens

int initialTokens = 42;
Bandwidth limit = Bandwidth
    .simple(1000, Duration.ofHours(1))
    .withInitialTokens(initialTokens);
Bucket bucket = Bucket.builder()
    .addLimit(limit)
    .build();

1. First of all what is this capacity? where is it defined?
2. How does this work with multiple bandwidths with different initial tokens?
3. If i do ConsumptionProbe probe = rateLimitService.tryConsumeAndReturnRemaining(<id>);
   which bandwidth does the `available tokens refer to?

In my project I define 2 bandwidths:

public BucketConfiguration getBucketConfiguration(RateLimitRefillPlan refillPlan) {
    return BucketConfiguration.builder()
        .addLimit(Bandwidth.simple(refillPlan.getRefillAmount(), Duration.ofHours(1))
            .withId(THROTTLE_BUSINESS_LIMIT)
            .withInitialTokens(refillPlan.getRefillAmount()))
        .addLimit(Bandwidth.simple(THROTTLE_BURST_REFILL_AMOUNT, Duration.ofSeconds(5))
            .withId(THROTTLE_BURST_PROTECTION)
            .withInitialTokens(1))
        .build();
  }
...

    BucketProxy bucketProxy = rateLimitProxyManager.builder()
        .withRecoveryStrategy(RecoveryStrategy.RECONSTRUCT)
        .build(id, configuration);

pretty much as in documentation.

Can someone clarify how this works? Thank you

[vladimir-bukhtoyarov]

Answer 1

Bandwidth limit = Bandwidth.simple(1000, Duration.ofHours(1));

According to source code the code above equals to following:

int capacity = 1000;
Refill.greedy(1000, Duration.ofHours(1))
Bandwidth limit = Bandwidth.classic(capacity, refill)

• capacity specifies the maximim amount of tokens
• refill specifies the speed(and style) in which consumed tokens are returned back.

Answer 2

Capacity, currently available tokens, and last refill date are maintended independently for each bandwidth.
Aggregated acapacity for whole bucket is useless and never used. Aggregated available tokens is taken as minimum from all bandwidths. If first bandwidth has 3 available tokens, second bandwidth has 1 token and you try to consume 2 tokens then request will be rejected because min(3, 1) < 2

Answer 3

It will be minimum available tokens from all bandwidths. If you need to access for more detailed stat then Verbose API can help(see javadoc for VerboseResult).

[alantonica]

Ok, so if i understood correctly, the Bucket per se has multiple little buckets (called bandwidths) and whenever we try co consume a specific amount, will be something like for each bandwidth try consume x tokens

[vladimir-bukhtoyarov]

yes

[alantonica]

Nice. Ok, got it now. Thank you