Algorithm Logic

Determines whether a request should be allowed based on the state of its corresponding leaky bucket.

This function is the primary entry point for the leaky bucket algorithm. When a request arrives, this function is called to check if it should be processed or rejected. It operates by finding or creating a bucket associated with the user's key. Every request is added to a queue for its bucket.

A dedicated worker thread is responsible for processing the queue for each bucket. This function ensures that a worker is started for a new bucket but avoids starting duplicate workers. The final result (True or False) is communicated back to the caller once the worker has processed the request.

Algorithm Flow

1. Validation: Check if capacity is valid (> 0)
2. Key Construction: Build composite cache key from throttle name, IP zone, and user key
3. Bucket Management: Find existing bucket or create new one atomically
4. Request Queuing: Add request to bucket's processing queue
5. Worker Management: Start worker thread for new buckets (one-time operation)
6. Response: Wait for worker to process request and return result

Concurrency Model

• Each bucket has its own worker thread for serialized processing
• Multiple clients can safely call this function concurrently
• STM ensures atomic bucket creation and state management
• Workers are started lazily on first request per bucket

Examples

-- Basic usage: 10 request capacity, 1 request per second leak rate
isAllowed <- allowRequest cache "api-throttle" "us-east-1" "user-123" 10 1.0
if isAllowed
  then putStrLn "Request is allowed."
  else putStrLn "Request is blocked (429 Too Many Requests)."

-- High-throughput API with burst tolerance
let capacity = 100        -- Allow burst of up to 100 requests
    leakRate = 10.0       -- Process 10 requests per second steadily

result <- allowRequest cache "high-volume" "zone-premium" "client-456" capacity leakRate
when result $ processApiRequest

-- Rate limiting for different service tiers
let (cap, rate) = case userTier of
      Premium -> (50, 5.0)   -- 50 burst, 5/sec sustained
      Standard -> (20, 2.0)  -- 20 burst, 2/sec sustained  
      Basic -> (5, 0.5)      -- 5 burst, 1 per 2 seconds

allowed <- allowRequest cache "tiered-api" zone userId cap rate