HTTP 429, RateLimit Headers & Retry-After

"""HTTP 429 end to end: server sends Retry-After + RateLimit fields, client waits with jitter.

Run: python3 http429.py   (stdlib only, about 3 seconds; starts a server on 127.0.0.1)
Header names follow draft-ietf-httpapi-ratelimit-headers-11 (RateLimit-Policy, RateLimit)
plus the legacy X-RateLimit-* triple that many public APIs still send.
"""
import email.utils
import math
import random
import threading
import time
import urllib.error
import urllib.request
from collections import Counter
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

LIMIT, WINDOW = 5, 2  # 5 requests per 2 s per client, fixed window to keep the math visible


class Limiter:
    def __init__(self) -> None:
        self.lock = threading.Lock()
        self.windows: dict = {}  # client -> (window_start, count)

    def check(self, client: str):
        now = time.time()
        with self.lock:
            start, count = self.windows.get(client, (now, 0))
            if now - start >= WINDOW:
                start, count = now, 0
            reset = max(1, math.ceil(start + WINDOW - now))  # whole seconds, like delay-seconds
            if count >= LIMIT:
                return False, 0, reset
            self.windows[client] = (start, count + 1)
            return True, LIMIT - count - 1, reset


LIMITER = Limiter()


class Handler(BaseHTTPRequestHandler):
    def do_GET(self) -> None:
        client = self.headers.get("X-Client-Id", "anon")  # Step 1: identify the caller
        ok, remaining, reset = LIMITER.check(client)        # Step 2: limiter decision
        self.send_response(200 if ok else 429)
        self.send_header("RateLimit-Policy", f'"default";q={LIMIT};w={WINDOW}')
        self.send_header("RateLimit", f'"default";r={remaining};t={reset}')
        self.send_header("X-RateLimit-Limit", str(LIMIT))
        self.send_header("X-RateLimit-Remaining", str(remaining))
        self.send_header("X-RateLimit-Reset", str(reset))
        if not ok:
            self.send_header("Retry-After", str(reset))   # Step 3: truthful wait, in seconds
            self.send_header("Content-Type", "application/problem+json")
        self.end_headers()
        self.wfile.write(b"ok" if ok else b'{"title":"Too Many Requests","status":429}')

    def log_message(self, *args) -> None:  # keep the demo output quiet
        pass


def parse_retry_after(value, now=None):
    """Retry-After is either delay-seconds ("7") or an HTTP-date. Returns seconds or None."""
    if value is None:
        return None
    value = value.strip()
    if value.isdigit():
        return float(value)
    try:
        when = email.utils.parsedate_to_datetime(value).timestamp()
    except (TypeError, ValueError):
        return None                       # malformed: ignore it, fall back to backoff
    return max(0.0, when - (now if now is not None else time.time()))


def backoff_delay(attempt: int, retry_after, base=0.2, cap=30.0, rng=random) -> float:
    """Step 4-5: honor Retry-After as a floor, then add jitter. No header: full-jitter backoff."""
    if retry_after is not None:
        return min(cap, retry_after + rng.uniform(0, max(1.0, 0.5 * retry_after)))
    return rng.uniform(0, min(cap, base * 2 ** attempt))


def get_with_retry(url: str, client: str, max_attempts: int = 5):
    for attempt in range(max_attempts):
        req = urllib.request.Request(url, headers={"X-Client-Id": client})
        try:
            with urllib.request.urlopen(req) as resp:
                return resp.status, attempt, resp.headers["RateLimit"]
        except urllib.error.HTTPError as e:
            if e.code not in (429, 503):     # only throttling and overload are retryable here
                raise
            wait = backoff_delay(attempt, parse_retry_after(e.headers.get("Retry-After")))
            time.sleep(wait)                 # Step 6: retry after the budget refills
    return 429, max_attempts, None


def herd(clients=1000, retry_after=10, jitter=True, seed=1):
    """Diagram 2: when do 1000 throttled clients come back? Busiest 100 ms slot and slot count."""
    rng = random.Random(seed)
    arrivals = Counter(
        int(10 * (backoff_delay(0, retry_after, rng=rng) if jitter else retry_after))
        for _ in range(clients)
    )
    return max(arrivals.values()), len(arrivals)


if __name__ == "__main__":
    srv = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    url = f"http://127.0.0.1:{srv.server_address[1]}/items"
    print("8 calls from one client, limit 5 per 2 s:")
    for i in range(8):
        status, retries, rl = get_with_retry(url, "c1")
        print(f"  call {i + 1}: status={status} retries={retries} RateLimit={rl}")
    srv.shutdown()
    date = email.utils.formatdate(time.time() + 3, usegmt=True)
    print(f"Retry-After as HTTP-date 3 s ahead -> wait {parse_retry_after(date):.1f} s (1 s resolution)")
    for j in (False, True):
        peak, slots = herd(jitter=j)
        print(f"herd jitter={j!s:5s}: busiest 100 ms slot has {peak:4d} of 1000 retries, spread over {slots} slots")

/**
 * 429 client handling in TypeScript: honor Retry-After, add jitter, and pace on the RateLimit field.
 * Run: npx tsx http429.ts   (Node 18+, uses node:http and global fetch, about 3 s)
 */
import { createServer } from "node:http";
import type { AddressInfo } from "node:net";

const LIMIT = 5, WINDOW_S = 2;
let windowStart = Date.now(), used = 0;

// Server: fixed window per process, Step 2-3 of Diagram 1.
const server = createServer((_req, res) => {
  const now = Date.now();
  if (now - windowStart >= WINDOW_S * 1000) { windowStart = now; used = 0; }
  const reset = Math.max(1, Math.ceil((windowStart + WINDOW_S * 1000 - now) / 1000));
  const ok = used < LIMIT;
  if (ok) used++;
  res.setHeader("RateLimit-Policy", `"default";q=${LIMIT};w=${WINDOW_S}`);
  res.setHeader("RateLimit", `"default";r=${LIMIT - used};t=${reset}`);
  if (!ok) res.setHeader("Retry-After", String(reset)); // seconds, never earlier than the window end
  res.statusCode = ok ? 200 : 429;
  res.end(ok ? "ok" : "slow down");
});

/** Retry-After: delay-seconds or HTTP-date. Returns milliseconds, or null if absent or malformed. */
export function parseRetryAfter(v: string | null, nowMs = Date.now()): number | null {
  if (!v) return null;
  if (/^\d+$/.test(v.trim())) return Number(v) * 1000;
  const t = Date.parse(v);
  return Number.isNaN(t) ? null : Math.max(0, t - nowMs);
}

/** RateLimit: "default";r=0;t=2  ->  { r: 0, t: 2 }. Malformed fields must be ignored. */
export function parseRateLimit(v: string | null): { r: number; t: number } | null {
  const m = v?.match(/;r=(\d+)(?:;t=(\d+))?/);
  return m ? { r: Number(m[1]), t: Number(m[2] ?? 0) } : null;
}

const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

/** Step 4-6: wait Retry-After plus jitter; with no header, exponential backoff with full jitter. */
function delayMs(attempt: number, retryAfterMs: number | null): number {
  if (retryAfterMs !== null) return retryAfterMs + Math.random() * Math.max(1000, retryAfterMs / 2);
  return Math.random() * Math.min(30_000, 200 * 2 ** attempt);
}

let pauseUntil = 0; // proactive pacing: shared by all calls of this client

async function call(url: string, maxAttempts = 5): Promise<{ status: number; retries: number }> {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const wait = pauseUntil - Date.now();
    if (wait > 0) await sleep(wait); // budget is known to be 0: do not even send
    const res = await fetch(url);
    await res.text();
    const rl = parseRateLimit(res.headers.get("RateLimit"));
    if (rl && rl.r === 0) pauseUntil = Date.now() + rl.t * 1000; // pace before hitting the wall
    if (res.status !== 429 && res.status !== 503) return { status: res.status, retries: attempt };
    await sleep(delayMs(attempt, parseRetryAfter(res.headers.get("Retry-After"))));
  }
  return { status: 429, retries: maxAttempts };
}

server.listen(0, "127.0.0.1", async () => {
  const url = `http://127.0.0.1:${(server.address() as AddressInfo).port}/items`;
  const t0 = Date.now();
  for (let i = 1; i <= 8; i++) {
    const { status, retries } = await call(url);
    console.log(`call ${i}: status=${status} retries=${retries} t=${((Date.now() - t0) / 1000).toFixed(1)}s`);
  }
  console.log("parseRetryAfter('7') =", parseRetryAfter("7"), "ms; bad value ->", parseRetryAfter("soon"));
  server.close();
});