https://github.com/coveooss/spillway
A simple, distributed and flexible rate limiter
https://github.com/coveooss/spillway
java rate-limit
Last synced: 28 days ago
JSON representation
A simple, distributed and flexible rate limiter
- Host: GitHub
- URL: https://github.com/coveooss/spillway
- Owner: coveooss
- License: mit
- Created: 2016-04-20T21:56:55.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2025-04-05T19:14:59.000Z (about 2 months ago)
- Last Synced: 2025-04-05T20:22:56.032Z (about 2 months ago)
- Topics: java, rate-limit
- Language: Java
- Homepage:
- Size: 263 KB
- Stars: 35
- Watchers: 14
- Forks: 13
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Spillway
[](https://travis-ci.org/coveo/spillway)
[](https://github.com/coveo/spillway/blob/master/LICENSE)
[](https://maven-badges.herokuapp.com/maven-central/com.coveo/spillway)
## A distributed throttling solution
Spillway is an easy to use solution to add distributed throttling at the software level in your public API.
This is particularly useful if multiple services are running in different JVMs.
It is also possible to quickly to react when throttling happens with our built-in call-back mechanism.
Storage backend currently supported:
- In memory (for usage within the same JVM)
- Redis
All external storage can be (and should be) wrapped in our asynchronous storage to avoid slowing down/stopping queries if external problems occurs with the external storage.
## Getting Started
#### Add Spillway to your project pom
```xml
com.coveo
spillway
2.0.0
```
#### Documentation
The java documentation is available here: https://coveooss.github.io/spillway/
#### Usage
###### Sample 1
```java
LimitUsageStorage storage = new AsyncLimitUsageStorage(new RedisStorage("localhost"));
SpillwayFactory spillwayFactory = new SpillwayFactory(storage);
Limit myLimit = LimitBuilder.of("myLimit").to(2).per(Duration.ofMinutes(1)).build();
Spillway spillway = spillwayFactory.enforce("myResource", myLimit);
spillway.call("myLimit"); // nothing happens
spillway.call("myLimit"); // nothing happens
spillway.call("myLimit"); // throws SpillwayLimitExceededException
```
###### Sample 2
```java
LimitUsageStorage storage = new InMemoryStorage();
SpillwayFactory spillwayFactory = new SpillwayFactory(storage);
Limit userLimit = LimitBuilder.of("perUser", User::getName).to(3).per(Duration.ofHours(1)).build();
Limit ipLimit = LimitBuilder.of("perIp", User::getIp).to(3).per(Duration.ofHours(1)).withExceededCallback(myCallback).build();
Spillway spillway = spillwayFactory.enforce("myResource", userLimit, ipLimit);
User john = new User("john", "127.0.0.1");
User gina = new User("gina", "127.0.0.1");
spillway.tryCall(john); // true
spillway.tryCall(gina); // true
spillway.tryCall(john); // true
spillway.tryCall(gina); // false, perIp limit exceeded.
```
###### Sample 3
```java
LimitUsageStorage storage = new InMemoryStorage();
SpillwayFactory spillwayFactory = new SpillwayFactory(storage);
LimitOverride override = LimitOverrideBuilder.of("john").to(10).per(Duration.ofHours(1)).build();
Limit userLimit = LimitBuilder.of("perUser").to(30).per(Duration.ofHours(1)).withLimitOverride(override).build();
Spillway spillway = spillwayFactory.enforce("myResource", userLimit);
spillway.tryCall("john", 11); // false
spillway.tryCall("gina", 20); // true
```
## External Resources
[cirrus-up-cloud](https://github.com/cirrus-up-cloud) wrote a [nice blog post](https://www.cirrusup.cloud/limit-accepted-requests-using-aws-elasticache/) about using Spillway on AWS with Elasticache.