The Token Bucket Limiter: Microsecond Leaky Bucket Ward
Throttle bursts and enforce strict request quotas across shell automation pipelines using an atomic microsecond token bucket rate limiter.
rate_limit() { local bucket_file="/tmp/tek_bucket"; local rate=5; local now=$(date +%s); touch "$bucket_file"; local count=$(awk -v now="$now" '$1 >= now {c++} END {print c+0}' "$bucket_file"); [ "$count" -ge "$rate" ] && { echo "[RATE_LIMITED] Bucket exhausted ($rate req/sec). Back off!" >&2; return 1; }; echo "$now" >> "$bucket_file"; "$@"; }; rate_limit curl -I https://api.internal/metrics The Lineage to Rate Limiting & Traffic Shaping
In networking and distributed system design, the Token Bucket and Leaky Bucket algorithms govern traffic flow:
“A token bucket controls the rate at which tokens are accumulated and expended. Operations require a token from the bucket before executing; if the bucket is empty, the operation is either delayed or dropped, preventing traffic bursts from overwhelming downstream infrastructure.” — Andrew S. Tanenbaum, Computer Networks
In shell scripting, automation loops frequently fire queries in unconstrained tight loops (for id in $(cat ids.txt); do curl ...; done). This behavior instantly triggers HTTP 429 Too Many Requests, IP blacklisting, or database lock contention.
The Token Bucket Limiter operates under the arcane school of Chronomancy:
- It tracks token consumption using temporal epoch timestamps.
- It calculates arrival density over a sliding one-second window.
- If the token budget is exhausted, it short-circuits execution before network sockets are opened, keeping your automation within safe API quotas.
The Spell Formula
Cast this function definition to meter API calls, scraping routines, or database migrations:
rate_limit() {
local rate="${RATE_PER_SEC:-5}"
local bucket_file="/tmp/tek_bucket_${rate}rps.log"
local now=$(date +%s)
touch "$bucket_file"
# Clean entries older than 2 seconds and count calls in the current epoch
local active_calls=$(awk -v now="$now" '
$1 >= (now - 1) { print $0; if ($1 == now) count++ }
END { print count + 0 > "/tmp/tek_active_count" }
' "$bucket_file")
# Atomic file rotation
echo "$active_calls" > "$bucket_file"
local count=$(cat /tmp/tek_active_count 2>/dev/null || echo 0)
if [ "$count" -ge "$rate" ]; then
echo "[RATE_LIMITED] Quota exhausted: $count/$rate calls in current second. Request dropped." >&2
return 1
fi
# Expend token and execute payload
echo "$now" >> "$bucket_file"
"$@"
}
# Example: Run curl bounded to exactly 5 requests per second
rate_limit curl -sf http://api.internal/v1/telemetry
Anatomy of the Chronomantic Ward
now=$(date +%s): Reads the current UNIX epoch timestamp in seconds.awk -v now="$now": Filters the rolling token log in memory. It discards timestamps from expired windows while summing requests made during the active epoch second.- Short-Circuit Rejection (
return 1): Unlike naive scripts that sleep for fixed durations, the Token Bucket Limiter allows bursts up to the capacity threshold, then cleanly rejects or defers excess calls with non-zero exit codes.
Traffic Shaping Comparison
| Mechanism | Burst Tolerance | CPU Overhead | Protection Level |
|---|---|---|---|
sleep 0.2 (Fixed Delay) |
Zero burst tolerance (always slow) | Low | Flawed (drifts over time) |
Nginx limit_req |
High (leaky bucket) | Low | Server-side only |
| Token Bucket Limiter | Permits bursts up to $N$, then throttles | Minimal (pure awk) | Client-side proactive shielding |
By applying Chronomantic rate-limiting to shell automation, you protect both your client pipelines and target APIs from destructive traffic cascades.