suaveplan/openspec/archive/2026-04-24-enterprise-rate-limiter/proposal.md

# OpenSpec Change: enterprise-rate-limiter

- **Change ID**: enterprise-rate-limiter
- **Package**: `@suaveplan/rate-limiter`
- **Category**: universal
- **Target path**: `universal/auth/rate-limiter`
- **Status**: PENDING
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/rate-limiter.md`

---

## Summary

Deliver `@suaveplan/rate-limiter` on the genesis branch from scratch at enterprise quality. The package provides tenant-specific rate limiting with multiple algorithms: `TokenBucket` (burst-friendly), `SlidingWindow` (smooth), and `FixedWindow` (simple); a `RateLimiter` orchestrator that applies rule-based routing to the right algorithm; pluggable `RateLimitStorage` adapters (`MemoryStorage`, adapter interface); multi-tenant multipliers; and framework-agnostic middleware helpers. The genesis rewrite removes Hono coupling from the core types, adds structured errors via `@suaveplan/error`, Zod schemas, injectable clock and RNG for determinism, OTel instrumentation, `AbortSignal` on async storage paths, property-based tests, and mitata benchmarks.

---

## Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | Base class for `RateLimiterError`; `defineCodes` for `RATE.*` error codes |
| `@suaveplan/types` (`workspace:^`) | `Clock` (injectable window computation), `Rng` (injectable jitter), `LoggerLike`, `EventBusLike` |
| `@suaveplan/events` (`workspace:^`) | `EventBus` for `rate:limit:exceeded` events |
| `@suaveplan/logger` (`workspace:^`) | Structured logging with trace correlation |
| `zod` (`catalog:forms`) | Zod schemas for all option types |
| `@opentelemetry/api` (`catalog:observability`) | Spans, counters, histograms |
| `tslib` (`catalog:build`) | TypeScript runtime helpers |

Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`), `@suaveplan/testing` (`workspace:^`).

---

## Preserved public API surface (from main branch)

### Core types

```ts
interface RateLimitResult {
  readonly allowed: boolean
  readonly remaining: number
  readonly limit: number
  readonly resetIn: number          // ms until window resets
  readonly retryAfter?: number      // ms to wait (only when allowed === false)
  readonly metadata?: Record<string, unknown>
}

interface RateLimitConfig {
  readonly limit: number
  readonly window: number           // ms
  readonly id?: string
  readonly description?: string
}

interface RateLimitRule extends RateLimitConfig {
  readonly priority?: number
  readonly conditions?: RateLimitCondition[]
  readonly bypass?: boolean
}

interface RateLimitCondition {
  readonly field: string
  readonly operator: "eq" | "neq" | "in" | "nin" | "matches"
  readonly value: unknown
}

interface RateLimitContext {
  readonly key: string
  readonly tenantId?: string
  readonly userId?: string
  readonly ip?: string
  readonly path?: string
  readonly method?: string
  readonly metadata?: Record<string, unknown>
}

interface RateLimiterOptions {
  readonly defaultConfig: RateLimitConfig
  readonly storage?: RateLimitStorage
  readonly rules?: RateLimitRule[]
  readonly enableTenantLimits?: boolean
  readonly tenantMultipliers?: Record<string, number>
  readonly keyPrefix?: string
  readonly clock?: Clock
  readonly bus?: EventBusLike
  readonly logger?: LoggerLike
}

// State shapes (serialisable for persistence)
interface TokenBucketState {
  tokens: number
  lastRefill: number     // epoch ms
}

interface SlidingWindowState {
  requests: number[]     // array of epoch ms timestamps
}

interface CounterState {
  count: number
  windowStart: number    // epoch ms
}

interface RateLimitState {
  key: string
  algorithm: RateLimitAlgorithm
  state: TokenBucketState | SlidingWindowState | CounterState
  config: RateLimitConfig
  updatedAt: number
}

type RateLimitAlgorithm = "token-bucket" | "sliding-window" | "fixed-window"

interface TenantRateLimitConfig extends RateLimitConfig {
  tenantId: string
  multiplier?: number
}

// Events
interface RateLimiterEvents {
  'rate:limit:exceeded': RateLimitedPayload
  'rate:limit:reset': RateLimitResetPayload
}

interface RateLimitedPayload {
  key: string
  tenantId?: string
  remaining: number
  resetIn: number
}

interface RateLimitResetPayload {
  key: string
  tenantId?: string
}
```

### Storage adapter

```ts
interface RateLimitStorage {
  get(key: string): Promise<RateLimitState | null>
  set(key: string, state: RateLimitState, ttl: number): Promise<void>
  delete(key: string): Promise<void>
  clear(): Promise<void>
}

interface MemoryStorageOptions {
  maxSize?: number
  clock?: Clock
}

class MemoryStorage implements RateLimitStorage {
  constructor(options?: MemoryStorageOptions)
}
```

### Core algorithms

```ts
interface TokenBucketOptions {
  capacity: number
  refillRate: number       // tokens per ms
  initialTokens?: number
  clock?: Clock
}

class TokenBucket {
  constructor(options: TokenBucketOptions)
  consume(tokens?: number): RateLimitResult
  refill(tokens?: number): void
  readonly available: number
  readonly capacity: number
}

interface SlidingWindowOptions {
  limit: number
  windowMs: number
  clock?: Clock
}

class SlidingWindow {
  constructor(options: SlidingWindowOptions)
  check(key: string): RateLimitResult
  reset(key: string): void
}
```

### Middleware helpers

```ts
function createRateLimiter(options: RateLimiterOptions): RateLimiterInstance
function createIpRateLimiter(config: RateLimitConfig, storage?: RateLimitStorage): MiddlewareFn
function createRouteRateLimiter(routes: Record<string, RateLimitConfig>, storage?: RateLimitStorage): MiddlewareFn
function createRateLimitChecker(options: RateLimiterOptions): (context: RateLimitContext) => Promise<RateLimitResult>
function getRateLimitResult(context: RateLimitContext, storage: RateLimitStorage, config: RateLimitConfig): Promise<RateLimitResult>

interface RateLimiterMiddlewareOptions {
  keyExtractor?: (req: unknown) => string
  onLimited?: (result: RateLimitResult) => void
  skip?: (req: unknown) => boolean
}

interface RateLimiterInstance {
  check(context: RateLimitContext): Promise<RateLimitResult>
  reset(key: string): Promise<void>
  getState(key: string): Promise<RateLimitState | null>
}
```

### Error codes

```ts
type RateLimiterErrorCode =
  | "RATE_STORAGE_ERROR"
  | "RATE_INVALID_CONFIG"
  | "RATE_KEY_MISSING"
  | "RATE_STATE_CORRUPT"

class RateLimiterError extends SuaveplanError<RateLimiterErrorCode>
function registerRateLimiterErrorCodes(): void
```

---

## New additions for genesis

### 1. FixedWindow algorithm

A third algorithm (`FixedWindow`) complements `TokenBucket` and `SlidingWindow`. Uses a simple counter with a hard window boundary — lowest memory overhead, suitable for coarse limits.

```ts
interface FixedWindowOptions {
  limit: number
  windowMs: number
  clock?: Clock
}

class FixedWindow {
  constructor(options: FixedWindowOptions)
  check(key: string): RateLimitResult
  reset(key: string): void
}
```

### 2. Clock and Rng injection

`TokenBucket` refill timing and `SlidingWindow` / `FixedWindow` window boundaries use injectable `Clock` (from `@suaveplan/types`). No bare `Date.now()` at module scope. `MemoryStorage` TTL checks also use injectable `Clock`.

### 3. `RateLimiterInstance` orchestrator

`createRateLimiter` returns a `RateLimiterInstance` that:
- Selects algorithm (token-bucket / sliding-window / fixed-window) per rule or default config.
- Applies `rules` in priority order — first matching rule wins; bypass rules skip limiting.
- Applies `tenantMultipliers` to effective limit for matching tenant contexts.
- Emits `rate:limit:exceeded` on optional `bus` when `allowed === false`.
- Emits `rate:limit:reset` on `reset()`.

### 4. OTel instrumentation

- `rate_limiter.check` span + `rate_limiter.checks_total` counter (labels: `algorithm`, `allowed: bool`, `tenant_id`)
- `rate_limiter.check_duration_ms` histogram
- `rate_limiter.exceeded_total` counter (label: `key_prefix`, `tenant_id`)
- `rate_limiter.storage_get_total` / `rate_limiter.storage_set_total` counters

### 5. Zod schemas

`RateLimitConfigSchema`, `RateLimitRuleSchema`, `RateLimitContextSchema`, `RateLimiterOptionsSchema`, `TokenBucketOptionsSchema`, `SlidingWindowOptionsSchema`, `FixedWindowOptionsSchema`, `MemoryStorageOptionsSchema`.

### 6. Property-based tests (fast-check)

- TokenBucket invariant: `available` never exceeds `capacity`; `available` never goes below 0.
- SlidingWindow monotonicity: `remaining` never increases within a window without a `reset`.
- Tenant multiplier correctness: effective limit for tenant with multiplier `m` equals `config.limit * m`.
- Rule priority ordering: when two rules match, the one with higher `priority` is applied.
- Storage round-trip: `set(key, state)` then `get(key)` returns a deep-equal state (within TTL).

### 7. Benchmark suite

- `TokenBucket.consume` — 1 000 000 iterations (pure in-memory).
- `SlidingWindow.check` — 100 000 iterations with a 1 000-entry timestamp window.
- `FixedWindow.check` — 100 000 iterations.
- `createRateLimiter.check` with MemoryStorage — 100 000 iterations.
- `MemoryStorage.get` + `set` — 1 000 000 round-trips.

---

## File layout

```text
universal/auth/rate-limiter/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/
      index.ts
    types/
      rate-limiter.types.ts
      rate-limiter.types.md
    core/
      token-bucket/
        token-bucket.ts
        token-bucket.md
        token-bucket.types.ts
        token-bucket.test.ts
        index.ts
      sliding-window/
        sliding-window.ts
        sliding-window.md
        sliding-window.types.ts
        sliding-window.test.ts
        index.ts
      fixed-window/
        fixed-window.ts
        fixed-window.md
        fixed-window.types.ts
        fixed-window.test.ts
        index.ts
      rate-limiter/
        rate-limiter.ts                 # createRateLimiter + RateLimiterInstance
        rate-limiter.md
        rate-limiter.types.ts
        rate-limiter.test.ts
        index.ts
    storage/
      storage-adapter/
        storage-adapter.ts              # RateLimitStorage interface
        storage-adapter.md
        storage-adapter.types.ts
        index.ts
      memory-storage/
        memory-storage.ts
        memory-storage.md
        memory-storage.test.ts
        index.ts
    middleware/
      rate-limit-middleware/
        rate-limit-middleware.ts        # createIpRateLimiter, createRouteRateLimiter, etc.
        rate-limit-middleware.md
        rate-limit-middleware.types.ts
        rate-limit-middleware.test.ts
        index.ts
    schemas/
      rate-limiter.schemas.ts
      rate-limiter.schemas.md
      rate-limiter.schemas.test.ts
    __benchmarks__/
      rate-limiter.bench.ts
  tests/
    integration.test.ts
    property.test.ts
```

---

## Impact

**Downstream packages**: API gateway and server packages will use `createRateLimiter` for request throttling. Auth plugins will use the tenant-specific configuration.

**Breaking changes from main-branch API**: Hono-specific types in `RateLimiterMiddlewareOptions` are replaced with framework-agnostic `MiddlewareFn`; a `createHonoAdapter` bridge is exported for compat. All other symbols are preserved. `FixedWindow` is a net-new addition.

**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/logger` must be published to Verdaccio before this package can be built or tested.