Rate Limiting & Throttling 🚦

<?php
// Why bother? Imagine a login form with NO rate limit. An attacker can try
// thousands of passwords per second. This loop shows how fast that adds up.

$attemptsPerSecond = 500;     // a script firing requests in a tight loop
$secondsRunning    = 60;      // left alone for just one minute

$total = $attemptsPerSecond * $secondsRunning;
echo "Password guesses in 1 minute: {$total}\n";   // 30000

// 30,000 free guesses a minute is how accounts get cracked, bills explode,
// and servers fall over. A rate limit caps each client at, say, 5 tries
// per 5 minutes — turning a brute-force attack into a non-starter.
$allowed = 5;
echo "With a limit of {$allowed}/5min, guesses in 1 minute: {$allowed}\n";

Password guesses in 1 minute: 30000
With a limit of 5/5min, guesses in 1 minute: 5

<?php
// FIXED WINDOW: count requests inside a fixed time slot (e.g. each 60s).
// The window key changes when the clock ticks into the next minute, so old
// counts expire on their own. Simplest algorithm — one counter per window.

function fixedWindow(array &$store, string $key, int $limit, int $windowSec, int $now): array
{
    // intdiv($now, 60) gives the window number: 1700000000 -> 28333333.
    $bucket = $key . ':' . intdiv($now, $windowSec);   // e.g. "ip:1.2.3.4:28333333"
    $count  = ($store[$bucket] ?? 0) + 1;              // ?? 0 = "0 if not seen yet"
    $store[$bucket] = $count;

    $allowed   = $count <= $limit;                     // true while under the cap
    $remaining = max(0, $limit - $count);              // never report a negative
    return [$allowed, $remaining];
}

$store = [];
$now   = 1700000000;                                   // a fixed timestamp

// Limit: 3 requests per 60-second window.
for ($i = 1; $i <= 5; $i++) {
    [$ok, $left] = fixedWindow($store, "ip:1.2.3.4", 3, 60, $now);
    $status = $ok ? "200 OK" : "429 Too Many Requests";
    echo "Request {$i}: {$status} (remaining: {$left})\n";
}

Request 1: 200 OK (remaining: 2)
Request 2: 200 OK (remaining: 1)
Request 3: 200 OK (remaining: 0)
Request 4: 429 Too Many Requests (remaining: 0)
Request 5: 429 Too Many Requests (remaining: 0)

<?php
// TOKEN BUCKET: each client has a bucket of N tokens that refills at a constant
// rate. Each request spends 1 token; an empty bucket means 429. This allows
// short bursts (spend saved-up tokens) while capping the long-term average.

class TokenBucket
{
    private float $tokens;          // tokens available right now
    private float $lastRefill;      // when we last topped the bucket up

    public function __construct(
        private int   $capacity,        // most tokens the bucket can hold
        private float $refillPerSecond, // tokens added every second
        float         $now,
    ) {
        $this->tokens     = $capacity;  // start full
        $this->lastRefill = $now;
    }

    /** Try to take one token. Returns [allowed, remaining]. */
    public function consume(float $now): array
    {
        // Add the tokens that accrued since the last call, capped at capacity.
        $elapsed = $now - $this->lastRefill;
        $this->tokens = min($this->capacity, $this->tokens + $elapsed * $this->refillPerSecond);
        $this->lastRefill = $now;

        if ($this->tokens >= 1) {
            $this->tokens--;                      // spend a token
            return [true, (int) floor($this->tokens)];
        }
        return [false, 0];                        // bucket empty -> deny
    }
}

// Bucket of 5 tokens refilling at 2/sec. Fire 6 requests in the SAME instant
// (no time passes, so no refill), then one more 1 second later.
$now    = 1700000000.0;
$bucket = new TokenBucket(capacity: 5, refillPerSecond: 2, now: $now);

for ($i = 1; $i <= 6; $i++) {
    [$ok, $left] = $bucket->consume($now);        // same timestamp each time
    $status = $ok ? "200 OK" : "429 Too Many";
    echo "t=0s  Request {$i}: {$status} (remaining: {$left})\n";
}

[$ok, $left] = $bucket->consume($now + 1.0);      // 1s later -> +2 tokens refilled
echo "t=1s  Request 7: " . ($ok ? "200 OK" : "429 Too Many") . " (remaining: {$left})\n";

t=0s  Request 1: 200 OK (remaining: 4)
t=0s  Request 2: 200 OK (remaining: 3)
t=0s  Request 3: 200 OK (remaining: 2)
t=0s  Request 4: 200 OK (remaining: 1)
t=0s  Request 5: 200 OK (remaining: 0)
t=0s  Request 6: 429 Too Many (remaining: 0)
t=1s  Request 7: 200 OK (remaining: 1)

<?php
// IN PRODUCTION you run many servers, so the counter can't live in one process's
// memory — it lives in Redis, shared by all of them. The pattern is two commands:
// INCR (atomically add 1, returns the new value) and EXPIRE (auto-delete later).

// $redis = new Redis(); $redis->connect('127.0.0.1', 6379);

function rateLimit(Redis $redis, string $id, int $limit, int $windowSec): void
{
    // One key per client per window. The window number is part of the key, so
    // when the minute rolls over you get a brand-new key starting at 0.
    $window = intdiv(time(), $windowSec);
    $key    = "ratelimit:{$id}:{$window}";

    $count = $redis->incr($key);          // atomic +1, even across servers
    if ($count === 1) {
        $redis->expire($key, $windowSec); // first hit sets the auto-expiry
    }

    $remaining = max(0, $limit - $count);

    // Tell EVERY response how much budget is left (clients use these to back off).
    header("X-RateLimit-Limit: {$limit}");
    header("X-RateLimit-Remaining: {$remaining}");
    header("X-RateLimit-Reset: " . (($window + 1) * $windowSec));

    if ($count > $limit) {
        $retryAfter = $windowSec - (time() % $windowSec);   // seconds to next window
        http_response_code(429);                            // 429 Too Many Requests
        header("Retry-After: {$retryAfter}");               // when it's safe to retry
        exit(json_encode(['error' => 'Rate limit exceeded']));
    }
}

// Prefer the logged-in user id; fall back to IP for anonymous callers.
$id = $_SESSION['user_id'] ?? $_SERVER['REMOTE_ADDR'];
// rateLimit($redis, $id, limit: 100, windowSec: 60);   // 100 requests/minute

// A blocked response looks like this on the wire:
echo "HTTP/1.1 429 Too Many Requests\n";
echo "X-RateLimit-Limit: 100\n";
echo "X-RateLimit-Remaining: 0\n";
echo "Retry-After: 37\n";
echo "\n";
echo '{"error":"Rate limit exceeded"}' . "\n";

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 37

{"error":"Rate limit exceeded"}

<?php
// WHO do you limit, and WHERE? Pick the right identity, then check it FIRST —
// before any expensive work — so an abuser never reaches your database.

function clientId(array $request): string
{
    // 1) Per API key: trusted partners get a known, generous quota.
    if (!empty($request['api_key'])) {
        return "key:" . $request['api_key'];
    }
    // 2) Per user: logged-in people are limited as themselves, not their office IP.
    if (!empty($request['user_id'])) {
        return "user:" . $request['user_id'];
    }
    // 3) Per IP: the only handle you have on anonymous traffic.
    return "ip:" . $request['ip'];
}

// Middleware runs at the FRONT of the pipeline. Return early on 429 so the
// controller, the database, and the rest of the app are never touched.
function handle(array $request): string
{
    $id = clientId($request);
    // if (overLimit($id)) return "429 Too Many Requests for {$id}";
    return "200 OK -> routed to controller for {$id}";
}

$requests = [
    ['api_key' => 'PARTNER-7'],                  // -> key:PARTNER-7
    ['user_id' => 42],                           // -> user:42
    ['ip' => '203.0.113.9'],                     // -> ip:203.0.113.9
];

foreach ($requests as $r) {
    echo handle($r) . "\n";
}

200 OK -> routed to controller for key:PARTNER-7
200 OK -> routed to controller for user:42
200 OK -> routed to controller for ip:203.0.113.9

<?php
// 🎯 YOUR TURN — finish this fixed-window check, then run it.
// The window already works; you just decide allowed/denied and what's left.

function check(array &$store, string $key, int $limit, int $windowSec, int $now): array
{
    $bucket = $key . ':' . intdiv($now, $windowSec);
    $count  = ($store[$bucket] ?? 0) + 1;
    $store[$bucket] = $count;

    // 1) A request is allowed while the count has not passed the limit.
    $allowed = ___;                 // 👉 compare $count with $limit (use <=)

    // 2) Remaining must never go below zero.
    $remaining = ___;               // 👉 use max(0, $limit - $count)

    return [$allowed, $remaining];
}

$store = [];
for ($i = 1; $i <= 4; $i++) {
    [$ok, $left] = check($store, "user:7", 2, 60, 1700000000);
    echo "Request {$i}: " . ($ok ? "200 OK" : "429") . " (remaining: {$left})\n";
}

// ✅ Expected output:
//    Request 1: 200 OK (remaining: 1)
//    Request 2: 200 OK (remaining: 0)
//    Request 3: 429 (remaining: 0)
//    Request 4: 429 (remaining: 0)

Request 1: 200 OK (remaining: 1)
Request 2: 200 OK (remaining: 0)
Request 3: 429 (remaining: 0)
Request 4: 429 (remaining: 0)

<?php
// 🎯 YOUR TURN — a client is over its limit. Send the right rejection.
// Fill in the status code and the two headers a well-behaved 429 must carry.

$limit      = 100;
$retryAfter = 30;                   // seconds until the window resets

// 1) The HTTP status for "you've sent too many requests".
$status = ___;                      // 👉 the number is 429

// 2) Tells the client HOW LONG to wait before retrying.
$retryHeader = "Retry-After: " . ___;   // 👉 use $retryAfter

// 3) Tells the client how many requests it had in total.
$limitHeader = "X-RateLimit-Limit: " . ___;   // 👉 use $limit

echo "HTTP/1.1 {$status} Too Many Requests\n";
echo "{$limitHeader}\n";
echo "X-RateLimit-Remaining: 0\n";
echo "{$retryHeader}\n";

// ✅ Expected output:
//    HTTP/1.1 429 Too Many Requests
//    X-RateLimit-Limit: 100
//    X-RateLimit-Remaining: 0
//    Retry-After: 30

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 30