Agent skill · posthog
using-redis-token-buckets
Use when adding a bucket-like rate limit backed by Redis: a per-caller budget with burst capacity and continuous refill, a refund path for requests that did no work, or a limit whose Retry-After must be a real wait rather than a window edge. `posthog/token_bucket.py` provides an atomic Lua token bucket (`consume`, `refund`, `peek`) over `posthog.redis.get_client()`. Choose it over DRF `SimpleRateThrottle`/fixed-window cache counters when boundary bursts, top-of-window lockouts, or charge-then-refund semantics matter. Trigger terms: token bucket, rate limit, burst, refill, quota, Retry-After, fixed window, throttle.
What it needs
About 4k tokens when loaded.
What this skill does
Using Redis token buckets posthog/tokenbucket.py is the repo's primitive for bucket-like limits in Redis. A bucket holds up to burst tokens and refills continuously at perhour / 3600 tokens per second. Every operation is atomic (a server-side Lua script), so concurrent web workers cannot double-spend a token. Use this skill when Adding a rate limit where callers legitimately burst but must be capped on sustained rate A limit needs a refund path: charge on entry, give the token back when the request provably did no work Retry-After must be the real per-caller wait for the next token, not "seconds until the top of the hour" Replacing a fixed-window cache counter that suffers 2x boundary bursts or full-window lockouts Exposing RateLimit-Limit/Remaining/Reset headers or a quota introspection endpoint (use peek) When NOT to use it Per-IP or per-user request throttling on ordinary DRF endpoints: subclass the existing throttles in posthog/ratelimit.py (IPThrottle, UserRateThrottle, PersonalApiKeyRateThrottle). They integrate with DRF's lifecycle and the RATELIMITENABLED instance setting. Outbound third-party API calls: use posthog/egress/ and its limits-library sliding-window limiter (posthog/egress/limiter/), which carries priorities and degraded fallbacks. Hard quotas that must survive a Redis flush: a bucket is best-effort (eviction or failover hands the caller a fresh budget). Pair it with a durable Postgres count for the few operations where that matters, and treat the bucket as the fast path. Concurrency caps (how many at once, not how often): see the sorted-set gate in posthog/clickhouse/client/limit.py. limits (vendored library) vs this module The repo also vendors the limits library (used by posthog/egress/limiter/backends.py). Pick by the semantics you need, not by familiarity: Use limits when a plain window answers the question "no more than N per window" and nothing ever needs to be un-counted. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills posthog/using-redis-token-buckets