Sliding window rate limiter with Redis 3.2 backend
npm install sliding-window-rate-limiter
Sliding window rate limiter with Redis >= 3.2 backend or in-memory backend.
This module requires ES6 with Node >= 16.
Redis >= 3.2.0 is required for the Redis backend.
``shell`
npm install sliding-window-rate-limiter
_Additionally for Typescript:_
`shell`
npm install -D @types/node @types/ioredis
`js`
const {SlidingWindowRateLimiter} = require("sliding-window-rate-limiter")
_Typescript:_
`ts`
import SlidingWindowRateLimiter from "sliding-window-rate-limiter"
// or
import {SlidingWindowRateLimiter} from "sliding-window-rate-limiter"
`js`
const limiter = SlidingWindowRateLimiter.createLimiter(options)
_Options:_
- interval is a number of milliseconds in a sliding windowredis
- is an instance of ioredis
or URL string to Redis server (only for Redis backend)
- is the time in milliseconds after Redis operation is canceledsafe
(for Redis and SafeRedis backends, optional)
- : true (only for SafeRedis backend)reuseRedisAfter
is the time (milliseconds) to reconnect to the Redis server
after connection failure (only for SafeRedis backend, default value: 2000
milliseconds)
If redis parameter is a string then a new ioredis object is created withretryStrategy set to 1 second and maxRetriesPerRequest set to 1.
_Example:_
`js`
const limiter = SlidingWindowRateLimiter.createLimiter({
interval: 60000,
})
or
`js`
const limiter = SlidingWindowRateLimiter.createLimiter({
interval: 60000,
redis: new Redis({
host: "redis-server",
retryStrategy: _times => 1000,
maxRetriesPerRequest: 1,
}),
safe: true,
})
`js`
const result = await limiter.check(key, limit)
const {usage, reset} = result
Checks current usage for key. If usage is equal to or above limit,reset
additionally sets time in milliseconds.
`js`
const result = await limiter.reserve(key, limit)
const {token, usage, reset} = result
Makes a reservation and returns token with a reservation. If usage islimit
equal to or above , additionally sets reset time in milliseconds.
Throws an error if has occurred.
`js`
const result = await limiter.cancel(key, token)
const {canceled} = result
Cancels a reservation for token and returns the number of canceled`
tokens. It is a zero if no token previously was reserved or it was expired.
`js`
limiter.destroy()
Frees resources used by limiter (timers and Redis connection if created by
limiter itself).
If reserve or usage methods return an error:
`console`
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 the proper version (>= 3.2.0).
This backend holds all data in memory.
This backend requires Redis 3.2 to work. The main advantage is that the state
of the limiter can be shared between many clients.
There is an extended version of the limiter, which behaves gracefully when
the Redis server is unavailable for any reason. In case of Redis connection
failure, SafeRedis backend will always return a positive response object and
will try to use again the Redis server after reuseRedisAfter.
Copyright (c) 2017-2024 Piotr Roszatycki
Based on Lua script from
Copyright (c) 2017 Serguei Poliakov
Inspired by ClassDojo blog note
rolling-rate-limiter`
module.