Getting Started

Getting Started

This guide covers how to install BucketGuard and implement basic rate limiting in your application.

Installation

BucketGuard requires Java 21 or newer.

Gradle (Groovy)

implementation 'com.github.frosxt:BucketGuard:version'

Gradle (Kotlin)

implementation("com.github.frosxt:BucketGuard:version")

Maven

<dependency>
    <groupId>com.github.frosxt</groupId>
    <artifactId>BucketGuard</artifactId>
    <version>version</version>
</dependency>

Basic Usage

The simplest use case is a global rate limiter that restricts the total number of actions across your application.

import com.github.frosxt.bucketguard.api.RateLimiter;
import com.github.frosxt.bucketguard.api.factory.BucketGuards;
import com.github.frosxt.bucketguard.api.spec.TokenBucketSpec;

import java.time.Duration;

public class Application {
    public static void main(String[] args) {
        // Define the rules: 100 requests per minute
        TokenBucketSpec spec = TokenBucketSpec.builder()
            .capacity(100)
            .refillTokens(100)
            .refillPeriod(Duration.ofMinutes(1))
            .build();

        // Create the limiter
        RateLimiter limiter = BucketGuards.tokenBucket(spec);

        // Protect a resource
        if (limiter.tryAcquire().granted()) {
            processRequest();
        } else {
            rejectRequest();
        }
    }
}

Next Steps

• Learn how to configure behavior in Configuration.
• Implement users-specific limits with Keyed Rate Limiting.