Rate Limiting Middleware#

The SmolForge API implements comprehensive rate limiting to protect against abuse and ensure fair resource usage.

Architecture#

The rate limiting middleware uses an in-memory Map with TTL entries for high performance. This approach:

• No database queries per request (zero latency overhead)
• Practical for Workers: Single isolate handles many requests before recycling
• Automatic cleanup: Old entries removed every 5 minutes
• Reset on cold start: Acceptable for API rate limiting (not meant to survive indefinitely)

If persistence across Worker restarts is needed in the future, the migrations/0004_rate_limits.sql provides a D1-based schema.

Rate Limits by Request Type#

Read Operations#

• Unauthenticated: 600 requests/minute per IP
• Authenticated: 3000 requests/minute per user

Write Operations (POST, PUT, PATCH, DELETE)#

• Unauthenticated: 600 requests/minute per IP
• Authenticated: 1200 requests/minute per user

Account Creation#

• Limit: 5 registrations/hour per IP
• Applied to: POST /api/auth/register

Git Operations (push, clone, refs)#

• Limit: 300 requests/hour per user
• Applied to: Paths with refs/heads, refs/tags, or /git/

Repo Creation#

• Limit: 100 per hour per user/IP key
• Applied to: POST /api/repos (excluding issues and PRs)

Storage Quota Warning (Non-blocking)#

• Threshold: 500MB per user
• Behavior: Returns X-Storage-Warning header when exceeded
• Does not block: Requests continue normally

Implementation Details#

File Location#

• Middleware: /src/middleware/rateLimit.ts
• Integrated independently by each API component through /src/components/http.ts
• Migration: /migrations/0004_rate_limits.sql

Key Functions#

rateLimitMiddleware#

Main middleware that enforces rate limits. Applied globally to all routes.

app.use('*', rateLimitMiddleware);

storageQuotaMiddleware#

Secondary middleware that checks storage quota and returns warning headers. Applied to API routes only.

app.use('/api/*', storageQuotaMiddleware);

Client IP Detection#

Resolves client IP in order of preference:

1. cf-connecting-ip (Cloudflare header)
2. x-forwarded-for (proxy header)
3. Fallback: 127.0.0.1

Response Headers#

All rate-limited responses include:

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

When limit is exceeded (429 response):

• Retry-After: Seconds to wait before retrying

Rate Limit Exceeded Response#

Status: 429 Too Many Requests

{
  "error": "Too many requests",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "retryAfter": 45
}

Excluded Routes#

The following routes are excluded from rate limiting:

• /health - Health check endpoint
• Non-API routes (static assets, SPA fallback)

Storage Quota Checking#

If a user exceeds 500MB of repository storage, they receive a warning header:

X-Storage-Warning: 120% of quota used

Requests are not blocked but the header alerts the client to the situation.

Future D1 Integration#

When migrating to D1-based persistence, the storage_quotas table tracks:

• User's total storage in bytes
• Configured quota (default 500MB)
• When warning was last sent (to avoid spam)

Testing#

Example rate limit scenarios:

Test Unauthenticated Read Limit (60/minute)#

for i in {1..65}; do
  curl https://api.cloudforge.dev/api/users \
    -H "X-Forwarded-For: 192.168.1.100"
done
# 61st+ requests return 429

Test Authenticated Write Limit (120/minute)#

for i in {1..125}; do
  curl -X POST https://api.cloudforge.dev/api/repos \
    -H "Authorization: Bearer <token>"
done
# 121st+ requests return 429

Test Git Operation Limit (30/hour)#

for i in {1..35}; do
  git push origin main  # This repo's push
done
# 31st+ pushes return 429

Future Enhancements#

1. Per-route custom limits: Add decorator/attribute for specific endpoints
2. Sliding window algorithm: More precise tracking across time boundaries
3. Distributed rate limiting: Use Durable Objects for cross-Worker coordination
4. Rate limit tiers: Different limits based on subscription level
5. IP allowlist: Bypass rate limits for internal services
6. Analytics: Track rate limit violations for abuse patterns

Implementation Notes#

• The in-memory Map stores RateLimitEntry objects with separate tracking for general and git operations
• Cleanup runs automatically when accessed and every 5+ minutes
• Rate limit window resets are absolute (not sliding): a new window starts at the reset time
• Storage quota check is non-blocking: failures are logged but don't interrupt the request
• The middleware runs after error middleware but before route handlers