
Security News
Node.js Homepage Adds Paid Support Link, Prompting Contributor Pushback
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
elysia-rate-limit
Advanced tools
Lightweight rate limiter plugin for Elysia.js
bun add elysia-rate-limit
If you're using Bun v1.0.3 or lower, elysia-rate-limit
v2.0.0 or higher will not be compatible. Please use elysia-rate-limit
v1.3.0 instead.
As long as you're on the latest version of Bun, and Elysia.
Using the latest version of elysia-rate-limit
would works just fine.
However, please refer to the following table to determine which version to use.
Plugin version | Requirements |
---|---|
3.0.0+ | Bun > 1.0.3, Elysia >= 1.0.0 |
2.0.0 - 2.2.0 | Bun > 1.0.3, Elysia < 1.0.0 |
1.0.2 - 1.3.0 | Bun <= 1.0.3, Elysia < 1.0.0 |
Check out full sample at example
import { Elysia } from 'elysia'
import { rateLimit } from 'elysia-rate-limit'
new Elysia().use(rateLimit()).listen(3000)
number
Default: 60000
Duration for requests to be remembered in milliseconds.
Also used in the Retry-After
header when the limit is reached.
number
Default: 10
Maximum of request to be allowed during 1 duration
timeframe.
string | Response | Error
Default: rate-limit reached
Response to be sent when the rate limit is reached.
If you define a value as a string,
then it will be sent as a plain text response with status code 429. If you define a value as a Response
object,
then it will be sent as is.
And if you define a value as an Error
object, then it will be thrown as an error.
Response
object responsenew Elysia()
.use(
rateLimit({
errorResponse: new Response("rate-limited", {
status: 429,
headers: new Headers({
'Content-Type': 'text/plain',
'Custom-Header': 'custom',
}),
}),
})
)
Error
object responseimport { HttpStatusEnum } from 'elysia-http-status-code/status'
export class RateLimitError extends Error {
constructor(
public message: string = 'rate-limited',
public detail: string = '',
public status: number = HttpStatusEnum.HTTP_429_TOO_MANY_REQUESTS // or just 429
) {
super(message)
}
}
new Elysia()
.use(
rateLimit({
errorResponse: new RateLimitError(),
})
)
// use with error hanlder
.error({
rateLimited: RateLimitError,
})
.onError({ as: 'global' }, ({ code }) => {
switch (code) {
case 'rateLimited':
return code
break
}
})
'global' | 'scoped'
Default: 'global'
Sometimes you may want
to only apply rate limit plugin to curtain Elysia instance.
This option will allow you
to choose scope local
apply to only current instance and descendant only.
But by default,
rate limit plugin will apply to all instances that apply the plugin.
Read more : Scope - ElysiaJS | ElysiaJS
<T extends object>(equest: Request, server: Server | null, derived: T) => MaybePromise<string>
Custom key generator to categorize client requests, return as a string. By default, this plugin will categorize client by their IP address via server.requestIP()
function.
If you deploy your server behind a proxy (i.e. NGINX, Cloudflare), you may need to implement your own generator to get client's real IP address.
// IMPORTANT: Only use this if your server is behind Cloudflare AND
// you've restricted access to only Cloudflare IPs
const cloudflareGenerator = (req, server) => {
// Verify the request is coming from Cloudflare
// In production, you should maintain a list of Cloudflare IP ranges
// and verify the request IP is in that range
const isFromCloudflare = verifyCloudflareIP(server?.requestIP(req)?.address)
if (isFromCloudflare) {
// Only trust CF-Connecting-IP if the request comes from Cloudflare
return req.headers.get('CF-Connecting-IP') ?? server?.requestIP(req)?.address ?? ''
}
// For non-Cloudflare requests, use the direct IP
return server?.requestIP(req)?.address ?? ''
}
// Example function to verify Cloudflare IPs (implement this based on your needs)
function verifyCloudflareIP(ip) {
// In a real implementation, check if IP is in Cloudflare's IP ranges
// https://www.cloudflare.com/ips/
return true // Replace with actual implementation
}
There's a third argument where you can use derive values from external plugin within key generator as well. Only downsize is you have to definitely those types be yourself, please be sure to test those values before actually defining types manually.
import { ip } from 'elysia-ip'
import type { SocketAddress } from 'bun'
import type { Generator } from 'elysia-rate-limit'
const ipGenerator: Generator<{ ip: SocketAddress }> = (_req, _serv, { ip }) => {
return ip
}
boolean
Default: false
Should this plugin count rate-limit to user when request failed?
By default,
this plugin will refund request count to a client
when onError
lifecycle called.
(Learn more in Lifecycle)
Context
Context for storing requests count for each client, if you want to implement your own Context
you can write it to comply with Context
protocol
import type { Context } from 'elysia-rate-limit'
export class CustomContext implements Context {
// implementation here
}
By default, context implementation, caching will be an LRU cache with a maximum of 5,000 entries. If you prefer to use this cache implementation but with larger cache size, you can define a new context with preferred cache size as follows
import { DefaultContext } from 'elysia-rate-limit'
new Elysia().use(
rateLimit({
// define max cache size to 10,000
context: new DefaultContext(10_000),
})
)
boolean
Default true
Should this plugin automatically set RateLimit-*
headers to the response?
If you want to disable this feature, you can set this option to false
.
(request: Request, key: string): boolean | Promise<boolean>
Default: (): false
A custom function
to determine that should this request be counted into rate-limit
or not based on information given by Request
object
(i.e., Skip counting rate-limit on some route) and the key of the given request,
by default, this will always return false
which means counted everything.
() => Server
Default: undefined
A function to inject server instance to the plugin, this is useful when you want to use default key generator in detached Elysia instances. You can check out the example here.
Please use this function as a last resort, as defining this option will make plugin to make an extra function call, which may affect performance.
4.4.0
FAQs
Rate-limiter for Elysia.js
The npm package elysia-rate-limit receives a total of 5,275 weekly downloads. As such, elysia-rate-limit popularity was classified as popular.
We found that elysia-rate-limit demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.
Research
Security News
The Socket Research Team investigates a malicious Python typosquat of a popular password library that forces Windows shutdowns when input is incorrect.