mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
988 lines
46 KiB
HTML
988 lines
46 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>api-api-rate-limiting</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/api-api-rate-limiting.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/api-api-rate-limiting">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/api-api-rate-limiting.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>api-api-rate-limiting</h1><p class="lede">Implementing rate limiting for APIs</p><h1>API Rate Limiting</h1>
|
|
<p><strong>Use this skill when:</strong></p>
|
|
<ul><li>Implementing rate limiting for APIs</li><li>Protecting services from abuse or overload</li><li>Choosing rate limiting algorithms</li><li>Setting up tiered access controls</li><li>Designing fair resource allocation</li><li>Handling rate limit responses</li></ul>
|
|
<h2>When to Use Rate Limiting</h2>
|
|
<h3>Protection Scenarios</h3>
|
|
<p>Apply rate limiting to prevent:</p>
|
|
<pre><code>SCENARIO → SOLUTION
|
|
─────────────────────────────────────────────────
|
|
DDoS attacks → Per-IP rate limits
|
|
API abuse → Per-user + per-IP limits
|
|
Cost control → Tiered limits by plan
|
|
Resource exhaustion → Global rate limits
|
|
Brute force attacks → Aggressive limits on auth endpoints
|
|
Scraping prevention → Low limits on list endpoints
|
|
Fair usage → Per-user quotas</code></pre>
|
|
<h3>Endpoint Classification</h3>
|
|
<p>Different endpoints need different limits:</p>
|
|
<pre><code class="lang-python"># Critical/Auth endpoints - strictest limits
|
|
POST /login # 5 requests/minute per IP
|
|
POST /signup # 3 requests/hour per IP
|
|
POST /password-reset # 3 requests/hour per user
|
|
|
|
# Read endpoints - moderate limits
|
|
GET /users # 100 requests/minute per user
|
|
GET /posts # 200 requests/minute per user
|
|
|
|
# Write endpoints - lower limits
|
|
POST /posts # 50 requests/minute per user
|
|
PUT /posts/:id # 30 requests/minute per user
|
|
|
|
# Expensive operations - very low limits
|
|
POST /reports/generate # 5 requests/hour per user
|
|
POST /exports/csv # 10 requests/day per user
|
|
|
|
# Public endpoints - IP-based limits
|
|
GET /public/feed # 60 requests/minute per IP</code></pre>
|
|
<h2>Rate Limiting Algorithms</h2>
|
|
<h3>Token Bucket</h3>
|
|
<p>Best for allowing bursts while maintaining average rate.</p>
|
|
<p><strong>How it works:</strong></p>
|
|
<ol><li>Bucket holds tokens (up to capacity)</li><li>Tokens added at fixed rate</li><li>Each request consumes tokens</li><li>Request rejected if insufficient tokens</li></ol>
|
|
<p><strong>Implementation:</strong></p>
|
|
<pre><code class="lang-python">import time
|
|
import redis
|
|
|
|
class TokenBucket:
|
|
def __init__(self, redis_client: redis.Redis, key: str,
|
|
capacity: int, refill_rate: float):
|
|
"""
|
|
capacity: Maximum tokens in bucket
|
|
refill_rate: Tokens added per second
|
|
"""
|
|
self.redis = redis_client
|
|
self.key = f"rate_limit:token_bucket:{key}"
|
|
self.capacity = capacity
|
|
self.refill_rate = refill_rate
|
|
|
|
def allow_request(self, tokens_needed: int = 1) -> bool:
|
|
"""Check if request is allowed and consume tokens"""
|
|
now = time.time()
|
|
|
|
# Lua script for atomic operation
|
|
script = """
|
|
local key = KEYS[1]
|
|
local capacity = tonumber(ARGV[1])
|
|
local refill_rate = tonumber(ARGV[2])
|
|
local tokens_needed = tonumber(ARGV[3])
|
|
local now = tonumber(ARGV[4])
|
|
|
|
local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
|
|
local tokens = tonumber(bucket[1]) or capacity
|
|
local last_refill = tonumber(bucket[2]) or now
|
|
|
|
-- Refill tokens based on time elapsed
|
|
local elapsed = now - last_refill
|
|
tokens = math.min(capacity, tokens + (elapsed * refill_rate))
|
|
|
|
-- Check if enough tokens
|
|
if tokens >= tokens_needed then
|
|
tokens = tokens - tokens_needed
|
|
redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
|
|
redis.call('EXPIRE', key, 3600)
|
|
return 1
|
|
else
|
|
return 0
|
|
end
|
|
"""
|
|
|
|
result = self.redis.eval(
|
|
script,
|
|
1,
|
|
self.key,
|
|
self.capacity,
|
|
self.refill_rate,
|
|
tokens_needed,
|
|
now
|
|
)
|
|
|
|
return bool(result)
|
|
|
|
def get_remaining(self) -> int:
|
|
"""Get remaining tokens"""
|
|
bucket = self.redis.hmget(self.key, 'tokens', 'last_refill')
|
|
if not bucket[0]:
|
|
return self.capacity
|
|
|
|
tokens = float(bucket[0])
|
|
last_refill = float(bucket[1])
|
|
now = time.time()
|
|
|
|
elapsed = now - last_refill
|
|
tokens = min(self.capacity, tokens + (elapsed * self.refill_rate))
|
|
|
|
return int(tokens)
|
|
|
|
# Usage
|
|
limiter = TokenBucket(redis_client, user_id, capacity=100, refill_rate=10)
|
|
if limiter.allow_request():
|
|
# Process request
|
|
return response
|
|
else:
|
|
# Rate limited
|
|
return 429</code></pre>
|
|
<p><strong>Best for:</strong> APIs with bursty traffic patterns, credit-based systems</p>
|
|
<h3>Leaky Bucket</h3>
|
|
<p>Best for smoothing traffic to constant rate.</p>
|
|
<p><strong>How it works:</strong></p>
|
|
<ol><li>Requests enter queue (bucket)</li><li>Processed at fixed rate (leak)</li><li>New requests rejected if bucket full</li></ol>
|
|
<p><strong>Implementation:</strong></p>
|
|
<pre><code class="lang-python">class LeakyBucket:
|
|
def __init__(self, redis_client: redis.Redis, key: str,
|
|
capacity: int, leak_rate: float):
|
|
"""
|
|
capacity: Maximum queue size
|
|
leak_rate: Requests processed per second
|
|
"""
|
|
self.redis = redis_client
|
|
self.key = f"rate_limit:leaky_bucket:{key}"
|
|
self.capacity = capacity
|
|
self.leak_rate = leak_rate
|
|
|
|
def allow_request(self) -> bool:
|
|
"""Check if request can be queued"""
|
|
now = time.time()
|
|
|
|
script = """
|
|
local key = KEYS[1]
|
|
local capacity = tonumber(ARGV[1])
|
|
local leak_rate = tonumber(ARGV[2])
|
|
local now = tonumber(ARGV[3])
|
|
|
|
local bucket = redis.call('HMGET', key, 'size', 'last_leak')
|
|
local size = tonumber(bucket[1]) or 0
|
|
local last_leak = tonumber(bucket[2]) or now
|
|
|
|
-- Leak based on time elapsed
|
|
local elapsed = now - last_leak
|
|
local leaked = elapsed * leak_rate
|
|
size = math.max(0, size - leaked)
|
|
|
|
-- Check if space available
|
|
if size < capacity then
|
|
size = size + 1
|
|
redis.call('HMSET', key, 'size', size, 'last_leak', now)
|
|
redis.call('EXPIRE', key, 3600)
|
|
return 1
|
|
else
|
|
return 0
|
|
end
|
|
"""
|
|
|
|
result = self.redis.eval(
|
|
script,
|
|
1,
|
|
self.key,
|
|
self.capacity,
|
|
self.leak_rate,
|
|
now
|
|
)
|
|
|
|
return bool(result)
|
|
|
|
# Usage
|
|
limiter = LeakyBucket(redis_client, user_id, capacity=50, leak_rate=5)</code></pre>
|
|
<p><strong>Best for:</strong> Protecting downstream services, guaranteed constant load</p>
|
|
<h3>Fixed Window</h3>
|
|
<p>Best for simple per-period limits.</p>
|
|
<p><strong>How it works:</strong></p>
|
|
<ol><li>Time divided into fixed windows</li><li>Counter increments per request</li><li>Counter resets at window boundary</li></ol>
|
|
<p><strong>Implementation:</strong></p>
|
|
<pre><code class="lang-python">class FixedWindow:
|
|
def __init__(self, redis_client: redis.Redis, key: str,
|
|
limit: int, window_seconds: int):
|
|
self.redis = redis_client
|
|
self.key = f"rate_limit:fixed_window:{key}"
|
|
self.limit = limit
|
|
self.window_seconds = window_seconds
|
|
|
|
def allow_request(self) -> bool:
|
|
"""Check if request is allowed"""
|
|
now = time.time()
|
|
window = int(now // self.window_seconds)
|
|
key = f"{self.key}:{window}"
|
|
|
|
# Increment counter
|
|
count = self.redis.incr(key)
|
|
|
|
# Set expiration on first request
|
|
if count == 1:
|
|
self.redis.expire(key, self.window_seconds * 2)
|
|
|
|
return count <= self.limit
|
|
|
|
def get_remaining(self) -> int:
|
|
"""Get remaining requests in window"""
|
|
now = time.time()
|
|
window = int(now // self.window_seconds)
|
|
key = f"{self.key}:{window}"
|
|
|
|
count = int(self.redis.get(key) or 0)
|
|
return max(0, self.limit - count)
|
|
|
|
def get_reset_time(self) -> int:
|
|
"""Get timestamp when window resets"""
|
|
now = time.time()
|
|
window = int(now // self.window_seconds)
|
|
return int((window + 1) * self.window_seconds)
|
|
|
|
# Usage
|
|
limiter = FixedWindow(redis_client, user_id, limit=100, window_seconds=60)</code></pre>
|
|
<p><strong>Best for:</strong> Simple quotas, easy to understand for users</p>
|
|
<p><strong>Downside:</strong> Burst at window boundaries (200 requests at 11:59 + 12:00)</p>
|
|
<h3>Sliding Window</h3>
|
|
<p>Best for smooth rate limiting without boundary bursts.</p>
|
|
<p><strong>How it works:</strong></p>
|
|
<ol><li>Track request timestamps</li><li>Count requests in rolling time window</li><li>Remove old requests outside window</li></ol>
|
|
<p><strong>Implementation:</strong></p>
|
|
<pre><code class="lang-python">class SlidingWindow:
|
|
def __init__(self, redis_client: redis.Redis, key: str,
|
|
limit: int, window_seconds: int):
|
|
self.redis = redis_client
|
|
self.key = f"rate_limit:sliding_window:{key}"
|
|
self.limit = limit
|
|
self.window_seconds = window_seconds
|
|
|
|
def allow_request(self) -> bool:
|
|
"""Check if request is allowed"""
|
|
now = time.time()
|
|
window_start = now - self.window_seconds
|
|
|
|
pipe = self.redis.pipeline()
|
|
|
|
# Remove old requests
|
|
pipe.zremrangebyscore(self.key, 0, window_start)
|
|
|
|
# Count requests in window
|
|
pipe.zcard(self.key)
|
|
|
|
# Add current request (temporarily)
|
|
pipe.zadd(self.key, {str(now): now})
|
|
|
|
# Set expiration
|
|
pipe.expire(self.key, self.window_seconds)
|
|
|
|
results = pipe.execute()
|
|
count = results[1]
|
|
|
|
# Remove current request if over limit
|
|
if count >= self.limit:
|
|
self.redis.zrem(self.key, str(now))
|
|
return False
|
|
|
|
return True
|
|
|
|
def get_remaining(self) -> int:
|
|
"""Get remaining requests in window"""
|
|
now = time.time()
|
|
window_start = now - self.window_seconds
|
|
|
|
# Clean and count
|
|
self.redis.zremrangebyscore(self.key, 0, window_start)
|
|
count = self.redis.zcard(self.key)
|
|
|
|
return max(0, self.limit - count)
|
|
|
|
# Usage
|
|
limiter = SlidingWindow(redis_client, user_id, limit=100, window_seconds=60)</code></pre>
|
|
<p><strong>Best for:</strong> Fair rate limiting, preventing boundary bursts</p>
|
|
<p><strong>Downside:</strong> Higher memory usage (stores timestamps)</p>
|
|
<h2>Storage Backends</h2>
|
|
<h3>Redis (Recommended)</h3>
|
|
<p>Best for distributed systems:</p>
|
|
<pre><code class="lang-python">import redis
|
|
|
|
# Single instance
|
|
redis_client = redis.Redis(
|
|
host='localhost',
|
|
port=6379,
|
|
db=0,
|
|
decode_responses=True
|
|
)
|
|
|
|
# Redis Cluster
|
|
from redis.cluster import RedisCluster
|
|
|
|
redis_client = RedisCluster(
|
|
host='redis-cluster',
|
|
port=6379,
|
|
decode_responses=True
|
|
)
|
|
|
|
# With connection pooling
|
|
pool = redis.ConnectionPool(
|
|
host='localhost',
|
|
port=6379,
|
|
max_connections=50
|
|
)
|
|
redis_client = redis.Redis(connection_pool=pool)</code></pre>
|
|
<p><strong>Pros:</strong> Fast, atomic operations, distributed, persistence <strong>Cons:</strong> Extra dependency, network latency</p>
|
|
<h3>In-Memory</h3>
|
|
<p>Best for single-instance applications:</p>
|
|
<pre><code class="lang-python">import time
|
|
from collections import defaultdict
|
|
from threading import Lock
|
|
|
|
class InMemoryRateLimiter:
|
|
def __init__(self):
|
|
self.limits = defaultdict(lambda: {'count': 0, 'reset': 0})
|
|
self.lock = Lock()
|
|
|
|
def check_limit(self, key: str, limit: int, window: int) -> bool:
|
|
now = time.time()
|
|
|
|
with self.lock:
|
|
if now > self.limits[key]['reset']:
|
|
self.limits[key] = {'count': 0, 'reset': now + window}
|
|
|
|
if self.limits[key]['count'] < limit:
|
|
self.limits[key]['count'] += 1
|
|
return True
|
|
|
|
return False
|
|
|
|
# Usage
|
|
limiter = InMemoryRateLimiter()
|
|
if limiter.check_limit(user_id, limit=100, window=60):
|
|
# Process request
|
|
pass</code></pre>
|
|
<p><strong>Pros:</strong> No external dependencies, zero latency <strong>Cons:</strong> Not distributed, lost on restart, memory growth</p>
|
|
<h3>Database</h3>
|
|
<p>Best for long-term quota tracking:</p>
|
|
<pre><code class="lang-python"># PostgreSQL example
|
|
import psycopg2
|
|
from datetime import datetime, timedelta
|
|
|
|
def check_rate_limit(user_id: int, limit: int, window_minutes: int) -> bool:
|
|
conn = psycopg2.connect("dbname=myapp")
|
|
cursor = conn.cursor()
|
|
|
|
window_start = datetime.utcnow() - timedelta(minutes=window_minutes)
|
|
|
|
# Clean old requests
|
|
cursor.execute("""
|
|
DELETE FROM rate_limit_requests
|
|
WHERE user_id = %s AND timestamp < %s
|
|
""", (user_id, window_start))
|
|
|
|
# Count recent requests
|
|
cursor.execute("""
|
|
SELECT COUNT(*) FROM rate_limit_requests
|
|
WHERE user_id = %s AND timestamp >= %s
|
|
""", (user_id, window_start))
|
|
|
|
count = cursor.fetchone()[0]
|
|
|
|
if count < limit:
|
|
cursor.execute("""
|
|
INSERT INTO rate_limit_requests (user_id, timestamp)
|
|
VALUES (%s, %s)
|
|
""", (user_id, datetime.utcnow()))
|
|
conn.commit()
|
|
conn.close()
|
|
return True
|
|
|
|
conn.close()
|
|
return False</code></pre>
|
|
<p><strong>Pros:</strong> Persistent, queryable, good for analytics <strong>Cons:</strong> Slower, higher load on DB</p>
|
|
<h2>Rate Limit Headers</h2>
|
|
<h3>Standard Headers</h3>
|
|
<p>Return rate limit info to clients:</p>
|
|
<pre><code class="lang-python">from flask import Flask, jsonify, request
|
|
|
|
app = Flask(__name__)
|
|
|
|
def add_rate_limit_headers(response, limiter, key: str):
|
|
"""Add rate limit headers to response"""
|
|
response.headers['X-RateLimit-Limit'] = str(limiter.limit)
|
|
response.headers['X-RateLimit-Remaining'] = str(limiter.get_remaining())
|
|
response.headers['X-RateLimit-Reset'] = str(limiter.get_reset_time())
|
|
|
|
return response
|
|
|
|
@app.route('/api/posts')
|
|
def get_posts():
|
|
user_id = request.headers.get('X-User-ID')
|
|
limiter = FixedWindow(redis_client, user_id, limit=100, window_seconds=60)
|
|
|
|
if not limiter.allow_request():
|
|
response = jsonify({'error': 'Rate limit exceeded'})
|
|
response.status_code = 429
|
|
response.headers['Retry-After'] = str(
|
|
limiter.get_reset_time() - int(time.time())
|
|
)
|
|
return add_rate_limit_headers(response, limiter, user_id)
|
|
|
|
# Process request
|
|
data = {'posts': [...]}
|
|
response = jsonify(data)
|
|
return add_rate_limit_headers(response, limiter, user_id)</code></pre>
|
|
<h3>Header Meanings</h3>
|
|
<pre><code>X-RateLimit-Limit: 100
|
|
→ Maximum requests allowed in window
|
|
|
|
X-RateLimit-Remaining: 45
|
|
→ Requests remaining in current window
|
|
|
|
X-RateLimit-Reset: 1234567890
|
|
→ Unix timestamp when limit resets
|
|
|
|
Retry-After: 30
|
|
→ Seconds until client can retry (429 response)</code></pre>
|
|
<h2>Limiting Strategies</h2>
|
|
<h3>Per-User Limiting</h3>
|
|
<p>Identify users by authentication:</p>
|
|
<pre><code class="lang-python">def get_rate_limit_key(request) -> str:
|
|
# Authenticated users
|
|
if request.user.is_authenticated:
|
|
return f"user:{request.user.id}"
|
|
|
|
# API key users
|
|
api_key = request.headers.get('X-API-Key')
|
|
if api_key:
|
|
return f"api_key:{api_key}"
|
|
|
|
# Fallback to IP
|
|
return f"ip:{request.remote_addr}"</code></pre>
|
|
<h3>Per-IP Limiting</h3>
|
|
<p>Protect against anonymous abuse:</p>
|
|
<pre><code class="lang-python">def get_client_ip(request) -> str:
|
|
"""Get real client IP (behind proxy)"""
|
|
# Check proxy headers
|
|
if request.headers.get('X-Forwarded-For'):
|
|
return request.headers['X-Forwarded-For'].split(',')[0].strip()
|
|
|
|
if request.headers.get('X-Real-IP'):
|
|
return request.headers['X-Real-IP']
|
|
|
|
return request.remote_addr
|
|
|
|
# Use IP as key
|
|
limiter = FixedWindow(redis_client, get_client_ip(request), limit=60, window_seconds=60)</code></pre>
|
|
<h3>Tiered Rate Limits</h3>
|
|
<p>Different limits by user tier:</p>
|
|
<pre><code class="lang-python">RATE_LIMITS = {
|
|
'free': {'requests_per_minute': 60, 'requests_per_day': 1000},
|
|
'basic': {'requests_per_minute': 300, 'requests_per_day': 10000},
|
|
'premium': {'requests_per_minute': 1000, 'requests_per_day': 100000},
|
|
'enterprise': {'requests_per_minute': 5000, 'requests_per_day': 1000000},
|
|
}
|
|
|
|
def check_user_rate_limit(user_id: int, tier: str) -> bool:
|
|
limits = RATE_LIMITS[tier]
|
|
|
|
# Check per-minute limit
|
|
minute_limiter = FixedWindow(
|
|
redis_client,
|
|
f"user:{user_id}:minute",
|
|
limit=limits['requests_per_minute'],
|
|
window_seconds=60
|
|
)
|
|
|
|
# Check per-day limit
|
|
day_limiter = FixedWindow(
|
|
redis_client,
|
|
f"user:{user_id}:day",
|
|
limit=limits['requests_per_day'],
|
|
window_seconds=86400
|
|
)
|
|
|
|
return minute_limiter.allow_request() and day_limiter.allow_request()</code></pre>
|
|
<h2>Graceful Degradation</h2>
|
|
<h3>Progressive Rate Limiting</h3>
|
|
<p>Gradually restrict rather than hard stop:</p>
|
|
<pre><code class="lang-python">def get_priority_level(request) -> int:
|
|
"""Determine request priority (higher = more important)"""
|
|
if request.user.tier == 'enterprise':
|
|
return 3
|
|
elif request.user.tier == 'premium':
|
|
return 2
|
|
elif request.user.tier == 'basic':
|
|
return 1
|
|
else:
|
|
return 0
|
|
|
|
def adaptive_rate_limit(request) -> bool:
|
|
"""Allow high-priority requests during high load"""
|
|
load = get_system_load() # 0-100
|
|
priority = get_priority_level(request)
|
|
|
|
# Increase rate limits under heavy load
|
|
if load > 80:
|
|
# Only allow enterprise
|
|
return priority >= 3
|
|
elif load > 60:
|
|
# Block free tier
|
|
return priority >= 1
|
|
else:
|
|
# Normal operation
|
|
return True</code></pre>
|
|
<h3>Queue-Based Handling</h3>
|
|
<p>Queue requests instead of rejecting:</p>
|
|
<pre><code class="lang-python">import asyncio
|
|
from collections import deque
|
|
|
|
class RateLimitQueue:
|
|
def __init__(self, rate: int):
|
|
self.rate = rate
|
|
self.queue = deque()
|
|
self.processing = False
|
|
|
|
async def add_request(self, request_handler, *args):
|
|
"""Add request to queue"""
|
|
future = asyncio.Future()
|
|
self.queue.append((request_handler, args, future))
|
|
|
|
if not self.processing:
|
|
asyncio.create_task(self.process_queue())
|
|
|
|
return await future
|
|
|
|
async def process_queue(self):
|
|
"""Process queue at fixed rate"""
|
|
self.processing = True
|
|
interval = 1.0 / self.rate
|
|
|
|
while self.queue:
|
|
handler, args, future = self.queue.popleft()
|
|
|
|
try:
|
|
result = await handler(*args)
|
|
future.set_result(result)
|
|
except Exception as e:
|
|
future.set_exception(e)
|
|
|
|
await asyncio.sleep(interval)
|
|
|
|
self.processing = False
|
|
|
|
# Usage
|
|
queue = RateLimitQueue(rate=10) # 10 requests/second
|
|
result = await queue.add_request(process_request, data)</code></pre>
|
|
<h2>Algorithm Comparison Matrix</h2>
|
|
<pre><code>ALGORITHM | BURST | SMOOTH | MEMORY | COMPLEXITY | USE CASE
|
|
──────────────────────────────────────────────────────────────────
|
|
Token Bucket | Yes | No | Low | Medium | Bursty APIs
|
|
Leaky Bucket | No | Yes | Low | Medium | Constant load
|
|
Fixed Window | Yes | No | Low | Low | Simple quotas
|
|
Sliding Window | No | Yes | High | High | Fair limiting</code></pre>
|
|
<h2>Response Patterns</h2>
|
|
<h3>Standard 429 Response</h3>
|
|
<pre><code class="lang-python">from flask import jsonify
|
|
|
|
def rate_limit_exceeded_response(limiter, key: str):
|
|
reset_time = limiter.get_reset_time()
|
|
retry_after = reset_time - int(time.time())
|
|
|
|
response = jsonify({
|
|
'error': 'Rate limit exceeded',
|
|
'message': f'Try again in {retry_after} seconds',
|
|
'retry_after': retry_after,
|
|
'limit': limiter.limit,
|
|
'reset': reset_time
|
|
})
|
|
|
|
response.status_code = 429
|
|
response.headers['Retry-After'] = str(retry_after)
|
|
response.headers['X-RateLimit-Limit'] = str(limiter.limit)
|
|
response.headers['X-RateLimit-Remaining'] = '0'
|
|
response.headers['X-RateLimit-Reset'] = str(reset_time)
|
|
|
|
return response</code></pre>
|
|
<h2>Anti-Patterns to Avoid</h2>
|
|
<p><strong>DON'T use fixed window for critical endpoints:</strong></p>
|
|
<pre><code class="lang-python"># ❌ BAD - Allows 200 requests in 1 second (burst at boundary)
|
|
limiter = FixedWindow(redis_client, key, limit=100, window_seconds=60)
|
|
|
|
# ✅ GOOD - Use sliding window or token bucket
|
|
limiter = SlidingWindow(redis_client, key, limit=100, window_seconds=60)</code></pre>
|
|
<p><strong>DON'T forget to handle Redis failures:</strong></p>
|
|
<pre><code class="lang-python"># ❌ BAD - Crashes on Redis failure
|
|
if limiter.allow_request():
|
|
return response
|
|
|
|
# ✅ GOOD - Fail open (allow request) on errors
|
|
try:
|
|
if not limiter.allow_request():
|
|
return rate_limit_exceeded_response(limiter, key)
|
|
except redis.RedisError:
|
|
# Log error but allow request
|
|
logger.error("Rate limiter unavailable")</code></pre>
|
|
<p><strong>DON'T rate limit health checks:</strong></p>
|
|
<pre><code class="lang-python"># ✅ GOOD - Exempt monitoring endpoints
|
|
EXEMPT_PATHS = ['/health', '/metrics', '/status']
|
|
|
|
@app.before_request
|
|
def check_rate_limit():
|
|
if request.path in EXEMPT_PATHS:
|
|
return None # Skip rate limiting
|
|
|
|
# Apply rate limiting
|
|
...</code></pre>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><strong>api-authentication.md</strong> - User identification for per-user limits</li><li><strong>redis-patterns.md</strong> - Redis optimization for rate limiting</li><li><strong>api-error-handling.md</strong> - Proper 429 response patterns</li><li><strong>api-caching.md</strong> - Reduce load to avoid rate limits</li></ul>
|
|
<hr>
|
|
<h2>Level 3: Resources</h2>
|
|
<h3>Overview</h3>
|
|
<p>The <strong>api-rate-limiting</strong> skill includes comprehensive resources for implementing production-grade rate limiting:</p>
|
|
<ul><li><strong>REFERENCE.md</strong>: 3,100+ line technical reference covering algorithms, implementations, and standards</li><li><strong>3 Scripts</strong>: Testing, analysis, and benchmarking tools</li><li><strong>8 Examples</strong>: Production-ready code in Python, Node.js, Go, and configuration examples</li></ul>
|
|
<h3>REFERENCE.md</h3>
|
|
<p><strong>Location</strong>: <code>skills/api/api-rate-limiting/resources/REFERENCE.md</code></p>
|
|
<p>Comprehensive technical reference (3,100+ lines) covering:</p>
|
|
<p><strong>Core Topics</strong>:</p>
|
|
<ul><li>Rate limiting fundamentals and algorithms (token bucket, leaky bucket, fixed/sliding window)</li><li>Distributed rate limiting with Redis and Lua scripts</li><li>HTTP headers and RFC 6585 compliance</li><li>Storage backends (Redis, Memcached, in-memory, PostgreSQL)</li><li>Implementation patterns for Flask, FastAPI, Express, Echo</li></ul>
|
|
<p><strong>Advanced Topics</strong>:</p>
|
|
<ul><li>Multi-tier rate limiting (per-second, per-minute, per-hour, per-day)</li><li>Limiting strategies (per-user, per-IP, per-endpoint, tiered)</li><li>Error handling and graceful degradation</li><li>Performance optimization and scalability</li><li>Security considerations and DDoS protection</li></ul>
|
|
<p><strong>Language Implementations</strong>:</p>
|
|
<ul><li>Python (FastAPI + Redis with async)</li><li>Go (Echo + Redis with golang.org/x/time/rate)</li><li>Node.js (Express + Redis with Lua scripts)</li></ul>
|
|
<p><strong>References</strong>:</p>
|
|
<ul><li>RFC 6585 (429 Too Many Requests)</li><li>RFC 7231 (Retry-After header)</li><li>IETF Draft: RateLimit Headers</li><li>Industry standards (GitHub, Twitter, Stripe)</li></ul>
|
|
<h3>Scripts</h3>
|
|
<p><strong>1. test_rate_limits.py</strong> - API Rate Limiting Testing Tool</p>
|
|
<p>Tests API rate limiting behavior by sending requests and analyzing responses.</p>
|
|
<pre><code class="lang-bash"># Test with burst
|
|
./test_rate_limits.py --endpoint https://api.example.com/resource
|
|
|
|
# Sustained load test
|
|
./test_rate_limits.py --endpoint https://api.example.com --rps 10 --duration 60
|
|
|
|
# Test boundary burst vulnerability
|
|
./test_rate_limits.py --endpoint https://api.example.com --boundary-test --limit 100 --window 60
|
|
|
|
# JSON output
|
|
./test_rate_limits.py --endpoint https://api.example.com --json</code></pre>
|
|
<p>Features:</p>
|
|
<ul><li>Send burst or sustained requests</li><li>Measure thresholds and reset times</li><li>Validate rate limit headers (X-RateLimit-*, Retry-After)</li><li>Detect algorithm (token bucket, sliding window, fixed window)</li><li>Check RFC 6585 compliance</li><li>Detect boundary burst vulnerability</li></ul>
|
|
<p><strong>2. analyze_patterns.py</strong> - Traffic Pattern Analysis Tool</p>
|
|
<p>Analyzes API access logs to recommend optimal rate limit configurations.</p>
|
|
<pre><code class="lang-bash"># Analyze access log
|
|
./analyze_patterns.py --log-file /var/log/nginx/access.log
|
|
|
|
# JSON output
|
|
./analyze_patterns.py --log-file access.log --json
|
|
|
|
# Custom time window
|
|
./analyze_patterns.py --log-file access.log --time-window 3600</code></pre>
|
|
<p>Features:</p>
|
|
<ul><li>Parse common log formats (Nginx, Apache, JSON)</li><li>Identify traffic patterns (burst, steady, abuse, scraping)</li><li>Detect potential abuse (high RPS, error rates)</li><li>Calculate percentiles (P50, P90, P95, P99)</li><li>Recommend rate limits per endpoint</li><li>Top endpoints and clients analysis</li></ul>
|
|
<p><strong>3. benchmark_throughput.py</strong> - Performance Benchmarking Tool</p>
|
|
<p>Benchmarks rate limiter implementation performance and compares algorithms.</p>
|
|
<pre><code class="lang-bash"># Benchmark single algorithm
|
|
./benchmark_throughput.py --algorithm token_bucket
|
|
|
|
# Compare all algorithms
|
|
./benchmark_throughput.py --algorithm all
|
|
|
|
# Custom load parameters
|
|
./benchmark_throughput.py --algorithm sliding_window --concurrent-users 100 --requests 50
|
|
|
|
# JSON output
|
|
./benchmark_throughput.py --algorithm all --json</code></pre>
|
|
<p>Features:</p>
|
|
<ul><li>Test throughput (requests/second)</li><li>Measure latency (avg, median, P95, P99)</li><li>Compare algorithms (token bucket, sliding window, fixed window)</li><li>Test concurrent users</li><li>Measure Redis overhead</li><li>Generate performance report</li></ul>
|
|
<h3>Examples</h3>
|
|
<p><strong>Location</strong>: <code>skills/api/api-rate-limiting/resources/examples/</code></p>
|
|
<p><strong>1. python/token_bucket.py</strong> - Token Bucket with Redis</p>
|
|
<p>Production-ready token bucket implementation using Redis and Lua scripts.</p>
|
|
<p>Features:</p>
|
|
<ul><li>Atomic operations with Lua</li><li>Configurable capacity and refill rate</li><li>Thread-safe distributed implementation</li><li>Graceful error handling (fail open)</li></ul>
|
|
<pre><code class="lang-python">limiter = TokenBucket(redis_client, "user:123", capacity=100, refill_rate=10)
|
|
if limiter.consume():
|
|
response = handle_request()
|
|
else:
|
|
wait = limiter.wait_time()
|
|
return error_response(f"Rate limited. Retry in {wait:.1f}s", 429)</code></pre>
|
|
<p><strong>2. python/sliding_window.py</strong> - Sliding Window with Redis</p>
|
|
<p>Sliding window implementation using Redis sorted sets for smooth rate limiting.</p>
|
|
<p>Features:</p>
|
|
<ul><li>No boundary burst vulnerability</li><li>Accurate request tracking with timestamps</li><li>Atomic operations with Lua</li><li>Memory-efficient with automatic cleanup</li></ul>
|
|
<pre><code class="lang-python">limiter = SlidingWindow(redis_client, "user:123", limit=100, window_seconds=60)
|
|
allowed, remaining = limiter.allow_request_with_remaining()
|
|
if allowed:
|
|
print(f"Request allowed. {remaining} remaining")</code></pre>
|
|
<p><strong>3. nodejs/express-rate-limiter.js</strong> - Express Middleware</p>
|
|
<p>Complete Express middleware for rate limiting with Redis backend.</p>
|
|
<p>Features:</p>
|
|
<ul><li>Fixed window rate limiting</li><li>Configurable per-route limits</li><li>Standard rate limit headers</li><li>Custom key generators</li><li>Graceful error handling (fail open)</li></ul>
|
|
<pre><code class="lang-javascript">const rateLimiter = createRateLimiter(redisClient);
|
|
app.use('/api', rateLimiter({ limit: 100, window: 60 }));</code></pre>
|
|
<p><strong>4. go/rate_limiter.go</strong> - Go Implementation</p>
|
|
<p>Go rate limiter using golang.org/x/time/rate with Redis backend.</p>
|
|
<p>Features:</p>
|
|
<ul><li>Token bucket algorithm with burst support</li><li>Redis-backed distributed limiting</li><li>Thread-safe operations</li><li>Local in-memory option for single-instance apps</li></ul>
|
|
<pre><code class="lang-go">limiter := NewRedisRateLimiter(redisClient, 100, 10)
|
|
if limiter.Allow("user:123") {
|
|
// Process request
|
|
}</code></pre>
|
|
<p><strong>5. python/fastapi-limiter.py</strong> - FastAPI Integration</p>
|
|
<p>FastAPI rate limiting with async Redis operations and dependency injection.</p>
|
|
<p>Features:</p>
|
|
<ul><li>Async Redis operations</li><li>Dependency injection pattern</li><li>Configurable per-route limits</li><li>Standard rate limit headers</li><li>Middleware for global limits</li></ul>
|
|
<pre><code class="lang-python">@app.get("/api/resource")
|
|
async def get_resource(
|
|
_: None = Depends(rate_limit(limit=100, window=60))
|
|
):
|
|
return {"data": "value"}</code></pre>
|
|
<p><strong>6. redis/lua-rate-limiter.lua</strong> - Lua Scripts Collection</p>
|
|
<p>Complete collection of Lua scripts for atomic rate limiting in Redis.</p>
|
|
<p>Includes:</p>
|
|
<ul><li>Token bucket algorithm</li><li>Sliding window algorithm</li><li>Fixed window algorithm</li><li>Leaky bucket algorithm</li><li>Multi-tier rate limiting</li><li>Distributed lock operations</li></ul>
|
|
<p><strong>7. config/nginx-rate-limit.conf</strong> - Nginx Configuration</p>
|
|
<p>Production-ready Nginx configuration using limit_req module.</p>
|
|
<p>Features:</p>
|
|
<ul><li>Multiple rate limit zones</li><li>Per-endpoint limits</li><li>Burst handling (burst, nodelay, delay)</li><li>Custom error responses</li><li>IP whitelisting</li><li>Multi-tier limiting</li></ul>
|
|
<pre><code class="lang-nginx">limit_req_zone $binary_remote_addr zone=api:10m rate=100r/s;
|
|
|
|
location /api/ {
|
|
limit_req zone=api burst=200 delay=100;
|
|
proxy_pass http://backend;
|
|
}</code></pre>
|
|
<p><strong>8. python/distributed-limiter.py</strong> - Advanced Distributed Limiter</p>
|
|
<p>Complete distributed rate limiter supporting multiple algorithms and strategies.</p>
|
|
<p>Features:</p>
|
|
<ul><li>Multiple algorithms (token bucket, sliding window, fixed window)</li><li>Multi-tier limiting (per-second, per-minute, per-hour, per-day)</li><li>Graceful fallback on errors</li><li>Monitoring hooks</li><li>Thread-safe operations</li></ul>
|
|
<pre><code class="lang-python">limiter = DistributedRateLimiter(redis_client)
|
|
|
|
result = limiter.check_limit("user:123", limits={
|
|
"per_second": 10,
|
|
"per_minute": 100,
|
|
"per_hour": 1000
|
|
})</code></pre>
|
|
<h3>Quick Start</h3>
|
|
<ol><li><strong>Read REFERENCE.md</strong> for comprehensive algorithm explanations and best practices</li><li><strong>Choose algorithm</strong>: Token bucket (bursts), Sliding window (smooth), Fixed window (simple)</li><li><strong>Pick example</strong>: Start with your language/framework</li><li><strong>Test with scripts</strong>: Use test_rate_limits.py to validate behavior</li><li><strong>Tune limits</strong>: Use analyze_patterns.py on production logs</li><li><strong>Benchmark</strong>: Use benchmark_throughput.py to compare algorithms</li></ol>
|
|
<h3>Algorithm Selection Guide</h3>
|
|
<pre><code>NEED BURSTS?
|
|
├─ Yes → Token Bucket (python/token_bucket.py)
|
|
└─ No → Need smooth limiting?
|
|
├─ Yes → Sliding Window (python/sliding_window.py)
|
|
└─ No → Fixed Window (simplest, nginx-rate-limit.conf)
|
|
|
|
DISTRIBUTED?
|
|
├─ Yes → Use Redis examples (all Python/Node.js/Go examples)
|
|
└─ No → Use in-memory (go/rate_limiter.go LocalRateLimiter)
|
|
|
|
LANGUAGE?
|
|
├─ Python → fastapi-limiter.py or distributed-limiter.py
|
|
├─ Node.js → express-rate-limiter.js
|
|
├─ Go → rate_limiter.go
|
|
└─ Nginx → nginx-rate-limit.conf</code></pre>
|
|
<h3>Related Resources</h3>
|
|
<ul><li><strong>api-authentication.md</strong> - User identification for per-user limits</li><li><strong>redis-patterns.md</strong> - Redis optimization and Lua scripting</li><li><strong>api-error-handling.md</strong> - Proper 429 response handling</li></ul>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/api-api-rate-limiting.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |