Quota Enforcement & Rate Limiting
Relevant source files
The following files were used as context for generating this wiki page:
Quota Enforcement and Rate Limiting in hex-yt-intel represent a dual-layered protection system designed to ensure platform stability and manage commercial tiering. The system distinguishes between Traffic Protection (short-term DDoS/abuse prevention) and Billing Quotas (monthly usage limits for analyses). This architecture leverages a combination of Upstash Redis for high-frequency sliding-window rate limiting and Supabase/Postgres for atomic, persistent quota management.
The system follows a "Fail-Open" philosophy where infrastructure blips in the rate-limiting or quota components do not hard-block paying users, prioritizing availability over strictness for legitimate traffic.
Sources: web/lib/services/traffic.ts:1-12, web/lib/services/billing.ts:1-12, CLAUDE.md:14-16
Architectural Overview
The protection logic is implemented as a sequential "Bouncer" pattern. When an API request is received, it must pass through the Traffic Guard before reaching the Billing Charge phase.
The diagram shows the sequential flow from request ingestion to the LLM cascade, highlighting the distinct roles of Redis for traffic and Postgres for billing.
Sources: web/lib/services/traffic.ts:221-230, web/lib/services/billing.ts:74-80, README.md:18-22
Traffic Protection (Rate Limiting)
The Traffic Service manages per-minute abuse protection using a Sliding-Window algorithm implemented in Redis. This prevents the "burst-leak" race conditions common in fixed-window counters.
Core Implementation
The system uses an atomic Lua script within Redis to manage a Sorted Set of timestamps. This ensures that the removal of old timestamps and the counting of the current window happen in a single operation.
| Component | Description |
|---|---|
| Storage | Upstash Redis |
| Data Structure | Redis Sorted Set (ZSET) |
| Window Size | 60 Seconds |
| Fail-Safe | Fails OPEN if Redis is unavailable |
Sources: web/lib/services/traffic.ts:6-12, web/lib/services/traffic.ts:140-155
Tier-Based Rate Limits
Rate limits are strictly enforced based on the user's subscription tier.
| Tier | Requests Per Minute | Requests Per Hour |
|---|---|---|
| Free | 3 | 50 |
| Pro | 30 | 500 |
| Enterprise | 300 | 10,000 |
Sources: web/lib/services/traffic.ts:25-40
Sliding Window Logic (Lua)
-- Remove timestamps older than window
local cutoff = now - window
redis.call('ZREMRANGEBYSCORE', key, '-inf', cutoff)
-- Count remaining requests in window
local count = redis.call('ZCARD', key)
-- Determine if request is allowed
if count < limit then
redis.call('ZADD', key, now, member)
count = count + 1
allowed = 1
end
Sources: web/lib/services/traffic.ts:64-88
Quota Enforcement (Billing)
The Billing Service manages the monthly analysis quota. Unlike the traffic guard, this is a persistent counter stored in Postgres, representing the "commercial truth" of a user's account.
Atomic Quota Operations
Quota increments are handled via the increment_user_quota_atomic Postgres RPC. This function performs a security check to ensure only the authorized user or service role can modify the quota and ensures the increment only occurs if the user is under their specific tier limit.
| Tier | Monthly Quota |
|---|---|
| Free | 3 Analyses |
| Pro | Unlimited |
| Enterprise | Unlimited |
Sources: web/lib/services/billing.ts:26-31, supabase/migrations/20260521210000_hardening_wave_4_fixes.sql:71-85
Quota Lifecycle
- Charge: Occurs after the traffic guard passes but before the LLM cascade begins.
- Persistence: The analysis is marked with a
billing_status. - Refund: If the LLM ingestion fails, the
billing_statusis updated tofailed, which effectively "refunds" the quota for the month.
Sources: web/lib/services/billing.ts:5-12, web/lib/services/billing.ts:122-132
Security & Hardening
The system implements several hardening measures to prevent privilege escalation and ensure data integrity.
RPC Security
Postgres functions are defined with SECURITY DEFINER but include strict search_path and auth.uid() checks to prevent unauthorized users from modifying the quotas of others.
CREATE OR REPLACE FUNCTION public.increment_user_quota_atomic(p_user_id uuid)
-- ...
BEGIN
IF auth.uid() IS NOT NULL AND auth.uid() != p_user_id THEN
RAISE EXCEPTION 'Unauthorized: Cannot modify quota for another user';
END IF;
-- ...
END;
Sources: supabase/migrations/20260521210000_hardening_wave_4_fixes.sql:63-75
Monitoring and Abuse Detection
Every rate-limit breach and quota exhaustion event is logged to a usage_logs table in Supabase. These events are also captured in Sentry with full context (User ID, Tier, Endpoint) for real-time monitoring.
Sources: web/lib/services/traffic.ts:114-130, web/lib/services/billing.ts:43-58
Conclusion
The Quota Enforcement & Rate Limiting system provides a robust, multi-layered defense for the hex-yt-intel platform. By separating short-term traffic management (Redis) from long-term billing quotas (Postgres), the system achieves high performance for frequent checks while maintaining strict data integrity for commercial usage limits. The "fail-open" design ensures that infrastructure issues do not degrade the user experience for authorized subscribers.