[Feature] Implement Token Bucket Rate Limiting for Public API Endpoints Issue #42 | Status: Open | Labels: backend, enhancement, security, priority-high

Currently, our public-facing API endpoints lack traffic throttling. This leaves the system vulnerable to Denial of Service (DoS) attacks, brute-force attempts, and resource exhaustion from high-volume automated scraping.

We need to implement a Token Bucket Rate Limiting middleware to regulate incoming traffic without degrading the experience for legitimate users.

Proposed Solution

Create a reusable middleware component that tracks API requests using an in-memory cache (or Redis for distributed setups).

• Default Limit: 100 requests per minute per IP address.

• Burst Allowance: Allow short bursts of up to 20 concurrent requests above the standard threshold.

• Headers: Include standard rate-limiting headers in every HTTP response:

  • X-RateLimit-Limit: Total allowed requests per window.

  • X-RateLimit-Remaining: Requests remaining in the current window.

  • X-RateLimit-Reset: Timestamp when the token bucket refills.

Acceptance Criteria

• [ ] Middleware intercepts incoming routing requests before hitting controller logic.

• [ ] Clients exceeding the threshold receive an HTTP 429 (Too Many Requests) status code.

• [ ] The response body for blocked requests returns a standardized JSON error message explaining the throttle limit.

• [ ] Unit tests achieve at least 90% code coverage for the rate-limiting logic.

• [ ] Integration tests verify that normal traffic flows without added latency (overhead must be < 5ms).

Part 2: Pull Request (Submitted for AI Review)

PR Title: feat(api): implement token bucket rate limiter (#42)

Author: AI-Developer | Branch: feature/rate-limiter -> main

Summary of Changes

This pull request resolves Issue #42 by introducing a lightweight, high-performance rate-limiting middleware designed to protect public API routes.

Key Modifications

• src/middleware/rateLimiter.py: Created the core token bucket algorithm that evaluates IP timestamps and token replenishment rates.

• src/config/apiConfig.py: Added configurable environment variables (RATE_LIMIT_MAX_REQUESTS, RATE_LIMIT_WINDOW_SEC) to allow easy adjustments without code redeployment.

• src/routes/index.py: Registered the middleware globally across all /api/v1/public/* routes.

• tests/test_rate_limiter.py: Added comprehensive automated tests simulating normal traffic, burst traffic, and cooldown periods.

Verification & Test Results

Test Case | Simulated Input | Expected Output | Actual Result | Status
-- | -- | -- | -- | --
Normal Load | 50 requests in 30 sec | HTTP 200 OK | HTTP 200 OK | PASS
Burst Traffic | 110 requests in 10 sec | HTTP 200 (first 100), HTTP 429 (next 10) | HTTP 200 (first 100), HTTP 429 (next 10) | PASS
Header Check | Single valid request | X-RateLimit-Remaining: 99 present | X-RateLimit-Remaining: 99 present | PASS
Window Reset | Request sent after reset timestamp | HTTP 200 OK (Bucket refilled) | HTTP 200 OK (Bucket refilled) | PASS

Reviewer Checklist (For AI / Lead Reviewer)

Note for Reviewers: Please pay special attention to the thread-safety implementation in rateLimiter.py to ensure race conditions do not occur during high-concurrency burst tests.

• [ ] Verify that environment variable defaults fallback gracefully if missing.

• [ ] Confirm that HTTP 429 error messages do not leak internal system stack traces.

• [ ] Assess whether an external Redis store should be prioritized over in-memory storage for multi-server scaling.

• [ ] Approve merge if CI/CD pipeline and security scans pass.

Review PR #42 and its feature/rate-limiter branch first, then inspect the public API routing and middleware entry point it targets. Verify the stated acceptance criteria: 429 responses, standardized JSON errors and rate-limit headers, at least 90% unit-test coverage, and integration-test overhead below 5ms.

Written by the indexing model from the issue text.