84 lines
2.6 KiB
Markdown
84 lines
2.6 KiB
Markdown
# OpenSpec Change: enterprise-api-plugin-rate-limit
|
|
|
|
- **Change ID**: enterprise-api-plugin-rate-limit
|
|
- **Package**: `@suaveplan/api-plugin-rate-limit`
|
|
- **Category**: api/data
|
|
- **Target path**: `api/data/api-plugin-rate-limit`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/api-plugin-rate-limit.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/api-plugin-rate-limit` on the genesis branch from scratch at enterprise quality. Rate-limiting plugin that wraps `@suaveplan/rate-limiter` and exposes it as a `@suaveplan/api` plugin service. Registers a `RateLimiterService` accessible by other plugins, provides per-route Hono middleware factory, configurable strategies (fixed-window, sliding-window, token-bucket, leaky-bucket) per endpoint, key extraction (IP, user-id, API-key, custom header), per-tenant override support, admin endpoints for viewing/resetting rate-limit state, and OTel metrics. Routes under `/admin/rate-limits`. Events: `rate-limit:exceeded`, `rate-limit:reset`.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/api` (`workspace:^`) | `definePlugin` |
|
|
| `@suaveplan/api-shared` (`workspace:^`) | Helpers |
|
|
| `@suaveplan/api-plugin-auth` (`workspace:^`) | `requireAuth`, `requireRole` |
|
|
| `@suaveplan/rate-limiter` (`workspace:^`) | Rate-limiter core |
|
|
| `@suaveplan/events` (`workspace:^`) | Event bus |
|
|
| `@suaveplan/error` (`workspace:^`) | `RateLimitPluginError` |
|
|
| `hono` + `@hono/zod-openapi` + `zod` | Routes |
|
|
| `@opentelemetry/api` | OTel |
|
|
|
|
---
|
|
|
|
## Public API surface
|
|
|
|
```ts
|
|
function createRateLimitPlugin(config?: RateLimitPluginConfig): PluginDescriptor
|
|
|
|
// Registered service:
|
|
interface RateLimiterService {
|
|
middleware(options: RouteRateLimitOptions): MiddlewareHandler
|
|
check(key: string, limit: number, windowMs: number): Promise<RateLimitResult>
|
|
reset(key: string): Promise<void>
|
|
getState(key: string): Promise<RateLimitState>
|
|
}
|
|
|
|
interface RateLimitPluginConfig {
|
|
defaultWindowMs?: number
|
|
defaultLimit?: number
|
|
strategy?: 'fixed-window' | 'sliding-window' | 'token-bucket' | 'leaky-bucket'
|
|
keyExtractor?: (c: Context) => string
|
|
}
|
|
```
|
|
|
|
### Error codes
|
|
|
|
```ts
|
|
type RateLimitPluginErrorCode =
|
|
| "RATE_LIMIT_EXCEEDED"
|
|
| "RATE_LIMIT_KEY_MISSING"
|
|
| "RATE_LIMIT_CONFIG_INVALID"
|
|
```
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
api/data/api-plugin-rate-limit/
|
|
package.json tsconfig.json vitest.config.ts
|
|
src/
|
|
index.ts events.ts types/ errors/
|
|
services/rate-limiter/
|
|
middleware/rate-limit/
|
|
routes/admin/
|
|
tests/integration.test.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Impact
|
|
|
|
Prerequisites: `@suaveplan/api`, `@suaveplan/api-plugin-auth`, `@suaveplan/rate-limiter`, `@suaveplan/events`.
|