🚦 feat(synapse): Rate limiting with Bucket4j

[sbharatjoshi]

Summary

Implement rate limiting using Bucket4j to protect Synapse endpoints from abuse. Configurable per-API-key rate limit with token bucket algorithm.

---

🏛️ Technical Specifications

• Framework: Bucket4j with bucket4j-spring-boot-starter + Caffeine cache backend
• Module: spector-synapse → com.spectrayan.spector.synapse.security
• Key Classes:
  • RateLimitFilter — Spring Security filter that checks request rate before processing
  • Uses Bucket4j token bucket algorithm with configurable refill rate
• Configuration:

  spector.security:
    rate-limit:
      enabled: true
      requests-per-second: 100
      burst-capacity: 200

• Cache Backend: Caffeine cache for in-memory bucket storage (keyed by API key or IP)
• Response: 429 Too Many Requests with Retry-After header (seconds until next available token)
• Exclusions: /actuator/**, /health endpoints are never rate-limited
• Dependencies: com.bucket4j:bucket4j-core, com.github.ben-manes.caffeine:caffeine

✅ Acceptance Criteria

• Given rate limiting is configured, when a client exceeds 100 req/s, then subsequent requests receive 429 Too Many Requests with Retry-After header
• Given spector.security.rate-limit.requests-per-second is configurable, when set to 200, then the limit is 200 req/s
• Given health/actuator endpoints are excluded, when rate limiting is active, then monitoring is never throttled

🚀 Contributor Guidance

1. Add bucket4j-core and caffeine to spector-synapse/pom.xml
2. Implement RateLimitFilter extending OncePerRequestFilter
3. Create buckets: Bucket.builder().addLimit(Bandwidth.simple(limit, Duration.ofSeconds(1))).build()
4. Store buckets in CacheManager keyed by API key or client IP
5. Register in the Spring Security filter chain (before authentication)
6. Build: mvn clean compile -pl spector-synapse

📚 References

• Bucket4j
• Rate Limiting with Bucket4j

RICE-C Score

Factor	Score	Rationale
Reach	3/5	Operators exposing Spector publicly
Impact	2x	Prevents abuse
Effort	S	~1 day

[titanspectrayan]

🏛️ Architectural Decision Record & Design Review (@titan)

We have completed the architectural design review for Unified Robust Rate Limiting across the Spector ecosystem. The full ADR has been committed to spectrayan/RnD/adr-robust-unified-rate-limiting-architecture.md.

Summary of 4-Pillar Design:

1. Inbound REST/MCP/SSE Surface: Pre-auth RateLimitFilter in Spring Security leveraging Bucket4j + Caffeine (zero external deps default) with hierarchical key resolution (API Key -> User -> Tenant -> IP) and standard RFC 7807 429 responses with Retry-After.
2. Outbound LLM Calls: ResilientRateLimitedLlmProvider with dual-dimension RPM + TPM token reservation & post-settlement, concurrency semaphores, and exponential backoff with provider failover.
3. Camel Connectors & Ingestion: Declarative <throttle> EIP parameters across route templates and ingestion sink backpressure.
4. Messaging Channels: Per-sender anti-flood protection in ChannelRouter and platform pacing in CamelChannelAdapter.
5. Cloud-Readiness: Pluggable RateLimitStateStore SPI (Caffeine in-memory <-> Redis distributed cluster) and Actuator /actuator/ratelimits management endpoint.

Handing over to @forge for implementation.