88 lines
12 KiB
Markdown
88 lines
12 KiB
Markdown
# @suaveplan/rate-limiter - Enterprise rate limiter: TokenBucket, SlidingWindow, FixedWindow algorithms; tenant multipliers; rule-based routing; pluggable storage; OTel instrumentation
|
|
|
|
## Summary
|
|
|
|
Enterprise rate limiter with three algorithms, rule-based routing, tenant multipliers, pluggable storage, and OTel instrumentation.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
<!-- end:auto-docs --> - [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_- [fixed-window](./src/core/fixed-window/fixed-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_ - [rate-limiter](./src/core/rate-limiter/rate-limiter.md) — <!-- begin:auto-docs --> _(no submodules)_- [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_ - [sliding-window](./src/core/sliding-window/sliding-window.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_ - [token-bucket](./src/core/token-bucket/token-bucket.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [rate-limiter-error](./src/errors/rate-limiter-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_ - [rate-limit-middleware](./src/middleware/rate-limit-middleware/rate-limit-middleware.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_ - [rate-limiter.schemas](./src/schemas/rate-limiter.schemas.md) — <!-- begin:auto-docs --> _(no submodules)_- [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_ - [adapter](./src/storage/adapter/adapter.md) — <!-- begin:auto-docs --> _(no submodules)_- [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_ - [memory-storage](./src/storage/memory-storage/memory-storage.md) — <!-- begin:auto-docs --> _(no submodules)_
|
|
## Algorithms
|
|
|
|
| Algorithm | Use case |
|
|
|---|---|
|
|
| `TokenBucket` | Burst-friendly continuous rate |
|
|
| `SlidingWindow` | Smooth per-key limit (default) |
|
|
| `FixedWindow` | Coarse counter, lowest memory |
|
|
|
|
## Quick Start
|
|
|
|
```ts
|
|
import { createRateLimiter } from "@suaveplan/rate-limiter";
|
|
|
|
const limiter = createRateLimiter({
|
|
defaultConfig: { limit: 100, window: 60_000 },
|
|
});
|
|
|
|
const result = await limiter.check({ key: "user:42" });
|
|
if (!result.allowed) {
|
|
console.log(`Retry after ${result.retryAfter}ms`);
|
|
}
|
|
```
|
|
|
|
## Rule-based routing
|
|
|
|
```ts
|
|
const limiter = createRateLimiter({
|
|
defaultConfig: { limit: 100, window: 60_000 },
|
|
rules: [
|
|
{
|
|
id: "admin-bypass",
|
|
limit: 0, window: 60_000,
|
|
priority: 100, bypass: true,
|
|
conditions: [{ field: "userId", operator: "in", value: ["admin-1"] }],
|
|
},
|
|
{
|
|
id: "strict-login",
|
|
limit: 5, window: 60_000,
|
|
priority: 50,
|
|
conditions: [{ field: "path", operator: "eq", value: "/login" }],
|
|
},
|
|
],
|
|
enableTenantLimits: true,
|
|
tenantMultipliers: { enterprise: 10 },
|
|
});
|
|
```
|
|
|
|
## Modules
|
|
|
|
- [`src/errors/rate-limiter-error.md`](src/errors/rate-limiter-error.md) — Error codes and `RateLimiterError`
|
|
- [`src/types/rate-limiter.types.md`](src/types/rate-limiter.types.md) — All shared types
|
|
- [`src/core/token-bucket/token-bucket.md`](src/core/token-bucket/token-bucket.md) — TokenBucket algorithm
|
|
- [`src/core/sliding-window/sliding-window.md`](src/core/sliding-window/sliding-window.md) — SlidingWindow algorithm
|
|
- [`src/core/fixed-window/fixed-window.md`](src/core/fixed-window/fixed-window.md) — FixedWindow algorithm
|
|
- [`src/core/rate-limiter/rate-limiter.md`](src/core/rate-limiter/rate-limiter.md) — `createRateLimiter` orchestrator
|
|
- [`src/storage/storage-adapter/storage-adapter.md`](src/storage/storage-adapter/storage-adapter.md) — `RateLimitStorage` interface
|
|
- [`src/storage/memory-storage/memory-storage.md`](src/storage/memory-storage/memory-storage.md) — `MemoryStorage` adapter
|
|
- [`src/middleware/rate-limit-middleware/rate-limit-middleware.md`](src/middleware/rate-limit-middleware/rate-limit-middleware.md) — Middleware helpers
|
|
- [`src/schemas/rate-limiter.schemas.md`](src/schemas/rate-limiter.schemas.md) — Zod schemas
|