hono-rate-limiter 0.4.2 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -146
- package/dist/index.cjs +689 -0
- package/dist/index.d.cts +601 -0
- package/dist/index.d.ts +601 -0
- package/dist/index.js +683 -0
- package/package.json +43 -8
- package/index.cjs.d.ts +0 -1
- package/index.cjs.js +0 -1
- package/index.esm.d.ts +0 -1
- package/index.esm.js +0 -1
- package/src/core.d.ts +0 -13
- package/src/headers.d.ts +0 -28
- package/src/index.d.ts +0 -3
- package/src/store.d.ts +0 -110
- package/src/types.d.ts +0 -243
- package/src/utils.d.ts +0 -10
- package/src/websocket.d.ts +0 -14
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Rhinobase
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,158 +1,20 @@
|
|
|
1
|
-
|
|
1
|
+
# 🔥 Hono Rate Limiter
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[](https://github.com/rhinobase/hono-rate-limiter/actions/workflows/test.yml)
|
|
3
|
+
[](https://deepwiki.com/rhinobase/hono-rate-limiter)
|
|
6
4
|
[](https://npmjs.org/package/hono-rate-limiter "View this project on NPM")
|
|
7
5
|
[](https://www.npmjs.com/package/hono-rate-limiter)
|
|
8
|
-
[](https://jsr.io/@hono-rate-limiter/hono-rate-limiter)
|
|
9
|
-
[](https://bundlephobia.com/result?p=hono-rate-limiter)
|
|
10
|
-
[](https://bundlephobia.com/result?p=hono-rate-limiter)
|
|
11
|
-
[](LICENSE)
|
|
12
|
-
|
|
13
|
-
</div>
|
|
14
|
-
|
|
15
|
-
Rate limiting middleware for [Hono](https://hono.dev/). Use to
|
|
16
|
-
limit repeated requests to public APIs and/or endpoints such as password reset.
|
|
17
|
-
|
|
18
|
-
> [!NOTE]
|
|
19
|
-
> The `keyGenerator` function needs to be defined for `hono-rate-limiter` to work properly in your environment. Please ensure that you define the `keyGenerator` function according to the documentation before using the library.
|
|
20
|
-
|
|
21
|
-
## Installation
|
|
22
|
-
|
|
23
|
-
```sh
|
|
24
|
-
# Using npm/yarn/pnpm/bun
|
|
25
|
-
npm add hono-rate-limiter
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
## Usage
|
|
29
|
-
|
|
30
|
-
### Rest APIs
|
|
31
|
-
|
|
32
|
-
```ts
|
|
33
|
-
import { rateLimiter } from "hono-rate-limiter";
|
|
34
|
-
|
|
35
|
-
// Apply the rate limiting middleware to all requests.
|
|
36
|
-
app.use(
|
|
37
|
-
rateLimiter({
|
|
38
|
-
windowMs: 15 * 60 * 1000, // 15 minutes
|
|
39
|
-
limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
|
|
40
|
-
standardHeaders: "draft-6", // draft-6: `RateLimit-*` headers; draft-7: combined `RateLimit` header
|
|
41
|
-
keyGenerator: (c) => "<unique_key>", // Method to generate custom identifiers for clients.
|
|
42
|
-
// store: ... , // Redis, MemoryStore, etc. See below.
|
|
43
|
-
})
|
|
44
|
-
);
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
### WebSocket APIs
|
|
48
|
-
|
|
49
|
-
```ts
|
|
50
|
-
import { webSocketLimiter } from "hono-rate-limiter";
|
|
51
|
-
import { upgradeWebSocket } from "hono/cloudflare-workers";
|
|
52
|
-
import { RedisStore } from "@hono-rate-limiter/redis";
|
|
53
|
-
import { Redis } from "@upstash/redis/cloudflare";
|
|
54
|
-
|
|
55
|
-
const limiter = webSocketLimiter({
|
|
56
|
-
windowMs: 15 * 60 * 1000, // 15 minutes
|
|
57
|
-
limit: 100, // Limit each IP to 100 requests per `window` (here, per 15 minutes).
|
|
58
|
-
keyGenerator: (c) => "<unique_key>", // Method to generate custom identifiers for clients.
|
|
59
|
-
store: new RedisStore({ client }), // Define your DataStore. See below.
|
|
60
|
-
});
|
|
61
|
-
|
|
62
|
-
// Apply the rate limiting middleware to ws requests.
|
|
63
|
-
app.get(
|
|
64
|
-
"/",
|
|
65
|
-
upgradeWebSocket(
|
|
66
|
-
limiter((c) => {
|
|
67
|
-
return {
|
|
68
|
-
onOpen: () => {
|
|
69
|
-
console.log("Connection opened");
|
|
70
|
-
},
|
|
71
|
-
async onMessage(event, ws) {
|
|
72
|
-
console.log(`Message from client: ${event.data}`);
|
|
73
|
-
ws.send("Hello from server!");
|
|
74
|
-
},
|
|
75
|
-
onClose: () => {
|
|
76
|
-
console.log("Connection closed");
|
|
77
|
-
},
|
|
78
|
-
};
|
|
79
|
-
})
|
|
80
|
-
)
|
|
81
|
-
);
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
## Data Stores
|
|
85
|
-
|
|
86
|
-
`hono-rate-limiter` supports external data stores to synchronize hit counts across multiple processes and servers.
|
|
87
|
-
|
|
88
|
-
By default, `MemoryStore` is used. This one does not synchronize its state across instances. It’s simple to deploy, and often sufficient for basic abuse prevention, but will be inconsistent across reboots or in deployments with multiple process or servers.
|
|
89
6
|
|
|
90
|
-
|
|
7
|
+
Simple rate limiter for [Hono](https://hono.dev/).
|
|
91
8
|
|
|
92
|
-
|
|
9
|
+
For documentation visit [honohub.dev](https://honohub.dev).
|
|
93
10
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
| MemoryStore | (default) Simple in-memory option. Does not share state when the app has multiple processes or servers. |
|
|
97
|
-
| [@hono-rate-limiter/redis](https://www.npm.im/@hono-rate-limiter/redis) | A [Redis](https://redis.io/)-backed store, used with [`@vercel/kv`](https://www.npmjs.com/package/@vercel/kv) and [`@upstash/redis`](https://www.npmjs.com/package/@upstash/redis) . [](https://www.npmjs.com/package/@hono-rate-limiter/redis) |
|
|
98
|
-
| [@hono-rate-limiter/cloudflare](https://www.npm.im/@hono-rate-limiter/cloudflare) | A [Cloudflare](https://www.cloudflare.com/)-backed store, used with [Durable Object](https://developers.cloudflare.com/durable-objects/), [WorkersKV](https://developers.cloudflare.com/kv/) and [Workers Rate Limiting](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/) API. [](https://www.npmjs.com/package/@hono-rate-limiter/cloudflare) |
|
|
99
|
-
| [rate-limit-redis](https://npm.im/rate-limit-redis) | A [Redis](https://redis.io/)-backed store, more suitable for large or demanding deployments. |
|
|
100
|
-
| [rate-limit-postgresql](https://www.npm.im/@acpr/rate-limit-postgresql) | A [PostgreSQL](https://www.postgresql.org/)-backed store. |
|
|
101
|
-
| [rate-limit-memcached](https://npmjs.org/package/rate-limit-memcached) | A [Memcached](https://memcached.org/)-backed store. |
|
|
102
|
-
| [cluster-memory-store](https://npm.im/@express-rate-limit/cluster-memory-store) | A memory-store wrapper that shares state across all processes on a single server via the [node:cluster](https://nodejs.org/api/cluster.html) module. Does not share state across multiple servers. |
|
|
103
|
-
| [precise-memory-rate-limit](https://www.npm.im/precise-memory-rate-limit) | A memory store similar to the built-in one, except that it stores a distinct timestamp for each key. |
|
|
104
|
-
| [typeorm-rate-limit-store](https://www.npmjs.com/package/typeorm-rate-limit-store) | Supports a variety of databases via [TypeORM](https://typeorm.io/): MySQL, MariaDB, CockroachDB, SQLite, Microsoft SQL Server, Oracle, SAP Hana, and more. |
|
|
105
|
-
| [@rlimit/storage](https://www.npmjs.com/package/@rlimit/storage) | A distributed rlimit store, ideal for multi-regional deployments. |
|
|
106
|
-
|
|
107
|
-
Take a look at this [guide](https://express-rate-limit.mintlify.app/guides/creating-a-store) if you wish to create your own store.
|
|
108
|
-
|
|
109
|
-
## Notes
|
|
110
|
-
|
|
111
|
-
- The `keyGenerator` function determines what to limit a request on, it should represent a unique characteristic of a user or class of user that you wish to rate limit. Good choices include API keys in `Authorization` headers, URL paths or routes, specific query parameters used by your application, and/or user IDs.
|
|
112
|
-
- It is not recommended to use IP addresses (since these can be shared by many users in many valid cases) or locations (the same), as you may find yourself unintentionally rate limiting a wider group of users than you intended.
|
|
113
|
-
|
|
114
|
-
## Examples
|
|
115
|
-
|
|
116
|
-
- [hono-rate-limiter.vercel.app](https://hono-rate-limiter.vercel.app) - Uses Vercel KV and deployed on Vercel
|
|
117
|
-
- [hono-rate-limiter.rhinobase.workers.dev](https://hono-rate-limiter.rhinobase.workers.dev) - Built using Cloudflare Workers
|
|
118
|
-
|
|
119
|
-
## Troubleshooting
|
|
120
|
-
|
|
121
|
-
If the suggestions here don't work, please try posting questions on [GitHub Discussions](https://github.com/rhinobase/hono-rate-limiter/discussions) or in the #help channel of [Hono Discord](https://discord.gg/xUtamz2vxH).
|
|
122
|
-
|
|
123
|
-
### Typescript Type Issue
|
|
124
|
-
|
|
125
|
-
When working with packages that are not officially supported by `hono-rate-limiter`, you might encounter type-related issues. These can be easily resolved by referring to the discussions in [#22](https://github.com/rhinobase/hono-rate-limiter/issues/22), [#10](https://github.com/rhinobase/hono-rate-limiter/issues/10). Example -
|
|
126
|
-
|
|
127
|
-
```ts
|
|
128
|
-
rateLimiter({
|
|
129
|
-
// ...
|
|
130
|
-
store: new RedisStore({
|
|
131
|
-
sendCommand: (...args: string[]) => redisClient.sendCommand(args),
|
|
132
|
-
}) as unknown as Store,
|
|
133
|
-
});
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
### Using `hono-rate-limiter` with Cloudflare Workers or Pages
|
|
137
|
-
|
|
138
|
-
If you're trying to use `hono-rate-limiter` in a Cloudflare environment (such as Workers or Pages), you may encounter the following error:
|
|
139
|
-
|
|
140
|
-
```bash
|
|
141
|
-
Uncaught Error: Disallowed operation called within global scope. Asynchronous I/O (ex: fetch() or connect()), setting a timeout, and generating random values are not allowed within global scope. To fix this error, perform this operation within a handler. https://developers.cloudflare.com/workers/runtime-apis/handlers/
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
This happens because the default memory store used by `hono-rate-limiter` cannot run in the Cloudflare environment due to its restrictions on global asynchronous operations.
|
|
145
|
-
|
|
146
|
-
#### Solution
|
|
147
|
-
|
|
148
|
-
To resolve this issue, you need to use a compatible store for Cloudflare. You can use the [`@hono-rate-limiter/cloudflare`](https://www.npmjs.com/package/@hono-rate-limiter/cloudflare) package, which is specifically designed to work with Cloudflare's infrastructure.
|
|
11
|
+
> [!Note]
|
|
12
|
+
> This package is still in development and your feedback is highly appreciated. If you have any suggestions or issues, please let us know by creating an issue on GitHub.
|
|
149
13
|
|
|
150
14
|
## Contributing
|
|
151
15
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
To get started, please read our [Contributing Guide](https://github.com/rhinobase/hono-rate-limiter/blob/main/CONTRIBUTING.md).
|
|
16
|
+
Visit our [contributing docs](https://github.com/rhinobase/hono-rate-limiter/blob/main/CONTRIBUTING.md).
|
|
155
17
|
|
|
156
18
|
## Credits
|
|
157
19
|
|
|
158
|
-
The
|
|
20
|
+
The idea for this project was inspired by [express-rate-limit](https://github.com/express-rate-limit/express-rate-limit)
|