feat: pluggable rate limiting for transcoded REST routes

[polaz]

Problem

structured-proxy fronts public REST surfaces of gRPC services. Deployments that expose transcoded routes to untrusted clients currently have to bolt rate limiting on elsewhere (upstream service or a separate gateway), which duplicates auth-context parsing and splits edge policy across components.

Proposal

Config-driven rate limiting middleware applied at the transcoding layer:

• Key extraction: configurable per route group; sources: authenticated principal (claim from validated JWT), API key header, client IP fallback for anonymous traffic
• Algorithm: GCRA (token-bucket equivalent, single stored timestamp per key) so legitimate burst traffic (page-render request fans) passes while sustained abuse is throttled
• Backends: in-process store (single replica) + Redis-protocol store (Redis/Dragonfly) for multi-replica deployments, selected in config
• Tiering: named limit profiles ({ rate_per_min, burst }) referenced from route/principal matchers, so operators define tiers as data
• Response contract: 429 with Retry-After and RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset headers (draft-ietf-httpapi-ratelimit-headers)

Acceptance criteria

• Middleware is off by default; enabling it requires zero code changes in consuming binaries (config only)
• Atomic limit check per request (single round-trip to backend, Lua/CAS based for the Redis-protocol store)
• Multi-replica correctness: N proxy replicas sharing one store enforce one combined limit
• Standard rate-limit response headers on both allowed and rejected requests
• Unit tests for GCRA math (burst boundary, refill, clock skew) + integration test with a Redis-protocol container
• Docs: config reference + sizing guidance

Estimate

3d

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• feat(shield): enforce rate limiting (endpoint classes + per-identifier, pluggable store) #24

🔗 Related PRs

#23 - feat(transcode): complete google.api.http request/response mapping [merged]
#25 - feat(shield): enforce rate limiting via pluggable store [merged]
#32 - feat(transcode): propagate W3C trace-context and request deadlines to gRPC [merged]
#36 - feat(authz): external authorization via Envoy ext_authz gRPC [merged]
#42 - perf(transcode): remove per-request route allocations on the hot path [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!