suaveplan/openspec/archive/2026-05-18-add-api-plugin-rate-limit/proposal.md

Add @suaveplan/api-plugin-rate-limit — Hono rate-limit middleware as a definePlugin

Package: @suaveplan/api-plugin-rate-limit (NEW, server-tier) Status: PROPOSED Type: new-package

• Spec delta: ./specs/api-plugin-rate-limit/spec.md

Why

Genesis ships @suaveplan/api (orchestrator), @suaveplan/api-plugin (definePlugin foundation), and @suaveplan/rate-limiter (universal rate-limit core with TokenBucket / SlidingWindow / FixedWindow algorithms, OTel instrumentation, pluggable storage). What's missing is the glue that turns the universal limiter into a one-line api.use(...) install on the @suaveplan/api Hono host, with per-route + per-tenant configuration, IP whitelist, parameterised route matching, RFC 7807 Problem+JSON 429 body, and standard X-RateLimit-* / RateLimit-* / Retry-After headers.

The legacy upstream api-plugin-rate-limit (audited in enterprise/api-plugin-rate-limit.md) had visible gaps the audit called out specifically: tenant multiplier was only used as a bucket-key prefix (never applied to the numeric limit), the path matcher supported only exact match + trailing /* (no :id params), and no HTTP middleware shipped at all — callers had to wire service.check() by hand from their routers. This genesis package fixes all three from day one.

What changes

Net-new package at 0.1.0. ADDED:

Plugin factory + descriptor surface

• createRateLimitPlugin(options: RateLimitPluginOptions): PluginDescriptor<RateLimitPluginConfig> — Zod-validated factory returning a PluginDescriptor from @suaveplan/api-plugin. The descriptor's lifecycle hooks implement the canonical 6-step onInit flow shared by every @suaveplan/api-plugin-* package.
• RateLimitPluginOptions (Zod-validated via RateLimitPluginOptionsSchema): { defaultLimit, defaultWindowMs, routes?, tenants?, ipWhitelist?, keyResolver?, storage?, headerStyle?, emitRetryAfter?, logger? }.
• RateLimitPluginConfig — the resolved options.

RateLimitService (registered in the host ServiceRegistry)

• createRateLimitService({ config, storage, clock, logger }): RateLimitService — exported factory so sibling plugins can build their own service instance if needed.
• RateLimitService.check({ ip, tenantId?, path, method }): Promise<RateLimitDecision> — returns the decision the middleware consumes.
• RateLimitService.reset(key) — resets the counter for a resolved key.
• ServiceRegistry module augmentation: declare module "@suaveplan/api-plugin/service-registry" { interface ServiceRegistry { rateLimitService: RateLimitService } }.

Hono middleware

• rateLimit({ service, headerStyle?, emitRetryAfter?, resolveIp?, resolveTenantId?, onDenied? }): MiddlewareHandler — Hono middleware factory.
• Sets c.set("rateLimit", decision) via ContextVariableMap augmentation so downstream handlers can read the decision typed.
• Returns 429 + Problem+JSON body on denial; emits configured headers on every response.

Path matcher

• compilePathPattern(source) / matchPath(pattern, path) / isPathMatch(source, path) — Hono-compatible path-pattern compilation and matching: exact, trailing wildcard (/*), inline wildcard (/api/*), named params (:id).

Headers + Problem+JSON

• buildRateLimitHeaders({ decision, style, emitRetryAfter, now? }) — assembles X-RateLimit-* and/or RateLimit-* triples plus Retry-After.
• buildRateLimitProblem(decision) — RFC 7807 application/problem+json body for a denied decision.

Errors + observability

• RateLimitPluginError extends SuaveplanError<RateLimitPluginErrorCode> via defineCodes("RATE_LIMIT_PLUGIN", [...]). Codes: INVALID_INPUT, SERVICE_NOT_AVAILABLE, LIMIT_EXCEEDED, STORAGE_FAILURE, INVALID_PATH_PATTERN.
• OTel instruments: counter rate_limit.checks_total{outcome,routeId,tenantId}, counter rate_limit.denials_total{routeId,tenantId}, histogram rate_limit.check_duration_ms, counter rate_limit.bypassed_total{reason}.

Subpath exports

., ./plugin/plugin, ./middleware/rate-limit, ./services/rate-limit-service, ./schemas/options, ./path-matcher/path-matcher, ./headers/headers, ./error-codes/error-codes, ./otel/instruments, ./types/types.

Out of scope

• Redis / SurrealDB storage adapters. The plugin accepts any caller-supplied RateLimitStorage so operators can plug in a distributed backend, but no concrete Redis adapter ships in this package (that lives in @suaveplan/rate-limiter follow-ups).
• Adaptive rate limiting based on observed system load. Architectural follow-up — out of scope for the initial ship.
• Weighted request cost (a route charges N tokens per call). The underlying limiter has one token per request; a cost option on RouteRule is a follow-up.
• Admin endpoint for dynamic tenant overrides. The current surface treats tenants as a boot-time array; runtime mutation is a separate plugin.
• Honey-pot IPs / auto-ban. Operational policy belongs above the rate-limit layer.

Source mapping

This change derives from ../suaveplan/enterprise/api-plugin-rate-limit.md.

Requirement	Source lines	Notes
Wraps @suaveplan/rate-limiter as an @suaveplan/api plugin	L13	verbatim
Per-route configuration	L13	verbatim
Per-tenant multiplier + bypass	L13, L31, L44	extended (multiplier APPLIED to limit, not just bucket key — fixes audit smell)
IP whitelist	L13	verbatim
Token-bucket / sliding-window algorithm choice	L13	inherited via @suaveplan/rate-limiter defaults
X-RateLimit-* / Retry-After headers	L13, L50	extended with RFC 9238 style and Problem+JSON body
RateLimitService registered on plugin context	L13	extended into ServiceRegistry slot (genesis pattern)
service.check({ ip, tenantId, key, path, method }) shape	L13	reworded — drops key (resolver derives it)
MemoryStorage default + pluggable RateLimitStorage	L13, L33, L45	extended (legacy only wired Memory)
Tenant multiplier APPLIED to numeric limit	L35, L44	fixes legacy smell
Parameterised path matcher (:id support)	L34, L46	fixes legacy smell
Hono middleware shipped	L36, L47	fixes legacy gap
OTel counters (allowed / denied / bypassed) + duration histogram	L48	extended
RFC 7807 Problem+JSON 429 body	L65 (acceptance row 7)	extended
Zod-validated boundary options	L13 (genesis-wide policy), L55	genesis-wide policy
RateLimitPluginError + 5 codes	L55	genesis-wide policy
ServiceRegistry module augmentation	L13	genesis pattern (post-audit)

Requirements with no source line

Requirement	Justification
100% test coverage threshold	Genesis-wide policy
@suaveplan/testing/runner test imports	Genesis-wide policy (CLAUDE.md §11)
Sibling .md per implementation file	Genesis-wide policy (AGENTS.md §4)
Five-files-per-feature layout	Genesis-wide policy (CLAUDE.md)
Subpath exports per feature module	Genesis-wide policy (AGENTS.md §6)
6-step canonical onInit	Genesis pattern (mirrors api-plugin-auth)

Verification approach

• src/path-matcher/path-matcher.test.ts — every pattern form + match outcome.
• src/headers/headers.test.ts — every header style + Problem+JSON body shape.
• src/error-codes/error-codes.test.ts — every code reachable + instanceof narrowing.
• src/otel/instruments.test.ts — lazy build + cache + reset against in-memory MeterProvider.
• src/schemas/options.test.ts — boundary validation + defaults applied.
• src/services/rate-limit-service.test.ts — IP whitelist, tenant bypass, tenant multiplier applied to limit, OTel emission, storage failure wrap.
• src/middleware/rate-limit.test.ts — 429 emission, headers on allowed AND denied responses, decision attached to context.
• src/plugin/plugin.test.ts — Zod boundary, 6-step onInit, app missing → typed error, registers service, installs middleware.
• src/api-plugin-rate-limit.spec-conformance.test.ts — every code reachable from a real production path, expectTypeOf on RateLimitService / RateLimitDecision / ContextVariableMap augmentation.
• tests/integration/full-app.test.ts — real @suaveplan/api host + the plugin + multiple routes; verifies 429 emission, Retry-After header, per-tenant isolation, header families on every response.
• tests/dep-graph.test.ts — deps + 10 subpaths + sibling .md per feature.

Migration impact

None — additive only. No package in genesis currently depends on this name.

Impact

Affected dependents

No dependents (verified by bunx turbo ls --filter=...@suaveplan/api-plugin-rate-limit).