wisp-rate-limiting/wisp.ratelimiting/RateLimiter

RateLimiter

interface RateLimiter

An interface for acquiring and releasing rate limit tokens

Terms:

key - a unique identifier for the entity or operation being rate limited
bucket - a container for rate limit tokens applied to a specific key
token - a unit of rate limit capacity. When we go to perform a rate limited operation, we attempt to consume a token from the bucket. If successful, we can perform the operation.

See also: https://en.wikipedia.org/wiki/Token_bucket

Types

ConsumptionData

data class ConsumptionData(val didConsume: Boolean, val remaining: Long, val resetTime: Instant)

ExecutionResult

data class ExecutionResult<T>(val result: T?, val consumptionData: RateLimiter.ConsumptionData)

TestConsumptionResult

data class TestConsumptionResult(val couldHaveConsumed: Boolean, val remaining: Long, val resetTime: Instant)

Functions

availableTokens

abstract fun availableTokens(key: String, configuration: RateLimitConfiguration): Long

Returns how many tokens remain in the bucket. Note that this data may be stale when it comes back, as time has elapsed and other pods could have taken tokens in the meantime.

consumeToken

abstract fun consumeToken(key: String, configuration: RateLimitConfiguration, amount: Long = 1): RateLimiter.ConsumptionData

Consumes amount tokens from the bucket associated with the given key This will raise any exception thrown by the bucket4j proxy manager implementation, e.g. subclasses of JedisException when using the Jedis implementation.

releaseToken

abstract fun releaseToken(key: String, configuration: RateLimitConfiguration, amount: Long = 1)

Releases amount tokens back to the bucket associated with the given key This will raise any exception thrown by the bucket4j proxy manager implementation, e.g. subclasses of JedisException when using the Jedis implementation.

resetBucket

abstract fun resetBucket(key: String, configuration: RateLimitConfiguration)

Resets the bucket back to its maximum capacity

testConsumptionAttempt

abstract fun testConsumptionAttempt(key: String, configuration: RateLimitConfiguration, amount: Long = 1): RateLimiter.TestConsumptionResult

This tests whether amount tokens are available in the bucket associated with the given key. It is essentially a dry run of consumeToken. Note that this data may be stale when it comes back, as time has elapsed and other pods could have taken tokens in the meantime.

withToken

open fun <T> withToken(key: String, configuration: RateLimitConfiguration, f: () -> T): RateLimiter.ExecutionResult<T>

Executes the given function if a token is available This will raise any exception thrown by the bucket4j proxy manager implementation, e.g. subclasses of JedisException when using the Jedis implementation.