README
sliding-window-rate-limiter
Sliding window rate limiter with Redis >= 3.2 backend or in-memory backend.
Requirements
This module requires ES6 with Node >= 10.
Redis >= 3.2.0 is required for Redis backend.
Installation
npm install sliding-window-rate-limiter
Additionally for Typescript:
npm install -D @types/node @types/ioredis
Usage
const {SlidingWindowRateLimiter} = require("sliding-window-rate-limiter")
Typescript:
import SlidingWindowRateLimiter from "sliding-window-rate-limiter"
// or
import {SlidingWindowRateLimiter} from "sliding-window-rate-limiter"
constructor
const limiter = SlidingWindowRateLimiter.createLimiter(options)
Options:
interval
is a number of milliseconds in a sliding windowredis
is an instance ofioredis
or URL string to Redis server (only for Redis backend)operationTimeout
is a time in milliseconds after Redis operation is canceled (for Redis and SafeRedis backends, optional)safe
:true
(only for SafeRedis backend)reuseRedisAfter
is a time (milliseconds) to reconnect to Redis server after connection failure (only for SafeRedis backend, default value: 2000 milliseconds)
If redis
parameter is a string then new ioredis
object is created with
retryStrategy
set to 1 second and maxRetriesPerRequest
set to 1.
Example:
const limiter = SlidingWindowRateLimiter.createLimiter({
interval: 60000,
})
or
const limiter = SlidingWindowRateLimiter.createLimiter({
interval: 60000,
redis: new Redis({
host: "redis-server",
retryStrategy: _times => 1000,
maxRetriesPerRequest: 1,
}),
safe: true,
})
check
const result = await limiter.check(key, limit)
const {usage, reset} = result
Checks current usage for key
. If usage
is equal or above limit
,
additionaly sets reset
time in milliseconds.
reserve
const result = await limiter.reserve(key, limit)
const {token, usage, reset} = result
Makes a reservation and returns token
with a reservation. If usage
is equal
or above limit
, additionaly sets reset
time in milliseconds. Throws an
error if has occurred.
cancel
const result = await limiter.cancel(key, token)
const {canceled} = result
Cancels a reservation for token
and returns number of canceled
tokens. It
is a zero if no token previously was reserved or it was expired.
destroy
limiter.destroy()
Frees resources used by limiter (timers and Redis connection if was created by limiter itself).
Errors
If reserve
or usage
methods returns an error:
ERR Error running script (call to f_8ff6a0f745b738fe1d9fa74079c4c13d032e9947): @user_script:1: user_script:1: attempt to call field \'replicate_commands\' (a nil value)
then check if Redis has proper version (>= 3.2.0).
Backends
Memory
This backend holds all data in memory.
Redis
This backend requires Redis 3.2 to work. Main advantage is that the state of limiter can be shared between many clients.
SafeRedis
There is extended version of limiter, which behaves gracefully, when Redis
server is unavailable for any reason. In case of Redis connection failure,
SafeRedis backend will always return positive response object and will try to
use again the Redis server after reuseRedisAfter
.
License
Copyright (c) 2017-2020 Piotr Roszatycki piotr.roszatycki@gmail.com
Based on Lua script from https://github.com/3hedgehogs/inredis-ratelimiter
Copyright (c) 2017 Serguei Poliakov serguei.poliakov@gmail.com
Inspired by ClassDojo blog note
https://engineering.classdojo.com/blog/2015/02/06/rolling-rate-limiter/ and
rolling-rate-limiter
module.