Skip to content

Latest commit

 

History

History
203 lines (161 loc) · 5.69 KB

RATE_LIMITING_IMPLEMENTATION.md

File metadata and controls

203 lines (161 loc) · 5.69 KB

Rate Limiting Implementation Summary

Overview

Rate limiting has been successfully implemented for donation-related endpoints to prevent abuse and accidental overload while maintaining normal user functionality.

Changes Made

1. New Dependencies

  • Added express-rate-limit package for rate limiting functionality

2. New Files Created

src/middleware/rateLimiter.js

Rate limiting middleware with two configurations:

  • donationRateLimiter: 10 requests/minute for creation operations
  • verificationRateLimiter: 30 requests/minute for verification operations

Key features:

  • IP-based rate limiting
  • Standard RateLimit headers in responses
  • HTTP 429 status code for exceeded limits
  • Integration with idempotency middleware (cached responses don't count)
  • Detailed error messages with retry information

3. Modified Files

src/routes/donation.js

Applied rate limiters to donation endpoints:

  • POST /donations - Uses donationRateLimiter
  • POST /donations/send - Uses donationRateLimiter
  • POST /donations/verify - Uses verificationRateLimiter

Read-only endpoints remain unaffected:

  • GET /donations
  • GET /donations/:id
  • GET /donations/recent
  • GET /donations/limits
  • PATCH /donations/:id/status

README.md

  • Added rate limiting to features list
  • Added idempotency to features list

docs/guides/QUICK_START.md

  • Updated API endpoints section with rate limit information
  • Added rate limiting documentation reference

package.json

  • Added express-rate-limit dependency
  • Added test:rate-limit script

4. Documentation

docs/features/RATE_LIMITING.md

Comprehensive documentation covering:

  • Implementation details
  • Protected vs unaffected endpoints
  • Rate limit response format and headers
  • Integration with idempotency
  • Configuration options
  • Testing procedures
  • Security considerations
  • Monitoring recommendations
  • Future enhancement suggestions

test-rate-limit.js

Test script to verify rate limiting functionality:

  • Tests donation creation endpoint (10 req/min limit)
  • Tests verification endpoint (30 req/min limit)
  • Validates proper HTTP 429 responses
  • Checks rate limit headers
  • Run with: npm run test:rate-limit

Rate Limit Configuration

Donation Creation Endpoints

  • Endpoints: POST /donations, POST /donations/send
  • Limit: 10 requests per minute per IP
  • Window: 60 seconds
  • Rationale: Stricter limit for write operations that interact with blockchain

Verification Endpoint

  • Endpoint: POST /donations/verify
  • Limit: 30 requests per minute per IP
  • Window: 60 seconds
  • Rationale: More lenient for read-heavy verification operations

Response Format

Success Response (within limits)

{
  "success": true,
  "data": { ... }
}

Headers include:

  • RateLimit-Limit: Maximum requests allowed
  • RateLimit-Remaining: Requests remaining in window
  • RateLimit-Reset: Unix timestamp when limit resets

Rate Limited Response (exceeded)

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many donation requests from this IP. Please try again later.",
    "retryAfter": "2024-01-15T10:30:00.000Z"
  }
}

HTTP Status: 429 (Too Many Requests)

Integration Points

Idempotency Middleware

Rate limiter is integrated with idempotency:

  • Requests served from idempotency cache don't count toward rate limit
  • Prevents legitimate retries from being blocked
  • Maintains security while improving user experience

Middleware Order

Correct execution order ensures security:

  1. Rate limiter (first check)
  2. API key validation
  3. Idempotency check
  4. Permission check
  5. Business logic

Testing

Manual Testing

# Start the server
npm start

# In another terminal, run the test script
npm run test:rate-limit

Expected Results

  • First 10 donation requests: Success (201)
  • 11th+ donation requests: Rate limited (429)
  • After 60 seconds: Rate limit resets
  • First 30 verification requests: Success/Error (200/500)
  • 31st+ verification requests: Rate limited (429)

Security Benefits

  1. Abuse Prevention: Limits malicious actors from overwhelming the system
  2. Resource Protection: Prevents accidental overload from misconfigured clients
  3. Fair Usage: Ensures all users get fair access to the API
  4. Cost Control: Reduces unnecessary blockchain transaction attempts
  5. DoS Mitigation: Provides basic protection against denial-of-service attacks

No Breaking Changes

The implementation:

  • Does not modify existing business logic
  • Does not change response formats for successful requests
  • Does not affect read-only endpoints
  • Maintains backward compatibility
  • Only adds rate limiting protection layer

Unaffected Components

The following remain unchanged:

  • Wallet routes (/wallets/*)
  • Stats routes (/stats/*)
  • Stream routes (/stream/*)
  • Transaction routes (/transaction/*)
  • Database schema
  • Service layer logic
  • Stellar integration
  • Authentication/authorization
  • Error handling (except new 429 responses)

Future Considerations

  1. User-based rate limiting: In addition to IP-based
  2. Dynamic limits: Based on user tier or reputation
  3. Redis backend: For distributed rate limiting across multiple servers
  4. Environment configuration: Make limits configurable via .env
  5. Monitoring dashboard: Track rate limit metrics
  6. Alerting: Notify admins of sustained violations

Dependencies

{
  "express-rate-limit": "^7.4.1"
}

Related Documentation