Genkai (jp. 限界, limit) is a small library which allows you to limit requests or function calls.

libraryDependencies ++= Seq(
  "com.nryanov.genkai" %% "<genkai-module>" % "[version]"
)

• Token bucket
• Fixed window
• Sliding window

Description of each of them can be found here: https://cloud.google.com/solutions/rate-limiting-strategies-techniques

All strategies are cost-based.

The main structure and some abstractions are similar to sttp. If you familiar with it then you should be comfortable with this library too :)

There are integrations for Monix, cats-effect and ZIO.

It is not necessary to use these integrations. There are also built-in Identity, Try, Either and Future wrappers.

RateLimiter

ConcurrentRateLimiter

import genkai._
import genkai.redis.jedis._
import redis.clients.jedis.JedisPool

object Main {
 def main(args: Array[String]): Unit = {
    val jedisPool = new JedisPool()
    val strategy = FixedWindow(10, Window.Minute) // 10 requests per 1 minute
    val rateLimiter: RateLimiter[Identity] = JedisSyncRateLimiter(jedisPool, strategy)
    
    val key: String = "my key"
    
    if (rateLimiter.acquire(key)) {
      // some logic
    } else {
      // handle `too many requests` 
    }
  }
}

More examples can be found in the examples folder.

Some methods of RateLimiter[F[_]] trait require implicit Key instance for your key object.

trait Key[A] {
  /**
   * @param value - value which will be used as unique (or not) identifier
   * @return - string representation of id
   */
  def convert(value: A): String
}

Key[A] allows you to control locks. For example, if you define custom Key[String] which always returns constant id then it will work as a global rate limiter.

There are a number of default implementation for basic types, but it is possible to define a new one if necessary.