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

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

type RateLimitPluginErrorCode =
  | "RATE_LIMIT_EXCEEDED"
  | "RATE_LIMIT_KEY_MISSING"
  | "RATE_LIMIT_CONFIG_INVALID"

File layout

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.

2.6 KiB Raw Blame History