https://github.com/walshydev/spark-ratelimiter
Easy rate-limit implementation for SparkJava.
https://github.com/walshydev/spark-ratelimiter
java rate-limiter rate-limiting ratelimit spark sparkjava
Last synced: about 2 months ago
JSON representation
Easy rate-limit implementation for SparkJava.
- Host: GitHub
- URL: https://github.com/walshydev/spark-ratelimiter
- Owner: WalshyDev
- Created: 2020-03-17T19:05:30.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-03-17T19:21:49.000Z (over 5 years ago)
- Last Synced: 2025-04-19T23:54:36.360Z (about 2 months ago)
- Topics: java, rate-limiter, rate-limiting, ratelimit, spark, sparkjava
- Language: Java
- Size: 2.93 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Spark-RateLimiter
## Description
This is a tiny library which allows you to set up rate-limiting using SparkJava. If you run an API and need to rate-limit requests then this is the lib for you!
## Usage
This rate-limiter will add 3 headers when a request comes in, it will then test if the max amount has been hit. If it does get it then this sends an empty `429` status code.
#### Headers
Clients just need to look for and respect these headers if they do not wish to be rate-limited.
```
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 49999
```
### Basic
Here's a basic usage which allows for 30 requests in a minute span using the requester IP address as the defining key.
This will map to all /api requests.
```java
private final RateLimiter rateLimiter = new RateLimiter(30, 1, TimeUnit.MINUTES);
public void setup() {
rateLimiter.map("/api/*");
Spark.path("/api", () -> Spark.get("/", (req, res) -> "{\"Hello\", \"World!\"}"));
}
```
### Defining the key
Defining which key to use as the rate-limiter is easy. Just add a new parameter to the `RateLimiter` class constructor.
```java
private final RateLimiter rateLimiter = new RateLimiter(30, 1, TimeUnit.MINUTES, Request::queryString);
public void setup() {
rateLimiter.map("/api/*");
Spark.path("/api", () -> Spark.get("/", (req, res) -> "{\"Hello\", \"World!\"}"));
}
```
### Map to a specific endpoint
To map to a specific path rather than a group you can just use that endpoint. For example:
```java
private final RateLimiter rateLimiter = new RateLimiter(30, 1, TimeUnit.MINUTES);
public void setup() {
rateLimiter.map("/api/some/endpoint");
// Since we only map to `/api/some/endpoint` this GET will not be rate-limited.
Spark.path("/api", () -> Spark.get("/", (req, res) -> "{\"Hello\", \"World!\"}"));
}
```
## Maven/Gradle
### Maven
```xml
jitpack.io
https://jitpack.io
...
com.github.WalshyDev
Spark-RateLimiter
VERSION
```
### Gradle
```groovy
repositories {
maven { url 'https://jitpack.io' }
}
...
dependencies {
implementation 'com.github.WalshyDev:Spark-RateLimiter:VERSION'
}
```
## Cleanup
The `RateLimiter` uses a `ScheduledExecutorService` internally. You should stop this executor on program shutdown. To do this just call `RateLimiter#stop`