:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { Counter } from 'prom-client'
import { RedisV2, getRedisPipelineResults } from '~/common/redis/redis-v2'
const requestsTotal = new Counter({
name: 'keyed_rate_limiter_requests_total',
help: 'Per-input rate-limit decisions, labelled by outcome.',
labelNames: ['name', 'method', 'outcome'],
})
const redisCallsTotal = new Counter({
name: 'keyed_rate_limiter_redis_calls_total',
help: 'Lua script dispatches. requests/redis_calls = grouping ratio.',
labelNames: ['name', 'method'],
})
/**
* Token-bucket rate limiter keyed by an arbitrary string id, backed by Redis.
* Multiple limiters can share a Redis via different `name` prefixes.
*/
export interface KeyedRateLimiterConfig {
/** Logical name; produces `@posthog/<name>/tokens/<id>` keys (`@posthog-test/...` under NODE_ENV=test). */
name: string
/** Default bucket params; per-request overrides take precedence. */
bucketSize?: number
refillRate?: number
ttlSeconds?: number
/** When false, throw if the Redis pipeline returns null instead of fail-open allowing all. Default: true (fail open). */
failOpen?: boolean
scriptVersion?: 'v2' | 'v3'
}
export interface KeyedRateLimitRequest {
id: string
cost: number
/** Used by guard-style limiters to scope per-team state. Ignored by the base service. */
teamId?: number
bucketSize?: number
refillRate?: number
ttlSeconds?: number
/** Override the request timestamp (seconds). Default: `Math.round(Date.now() / 1000)`. Used for lag-aware rate limiting where the timestamp comes from message headers. */
now?: number
}
export type KeyedRateLimit = {
/** Pre-deduction token count — uncapped accrued credit (PR 57920 contract). */
tokensBefore: number
/** Post-deduction token count. -1 when the cost exceeded the available budget. */
tokens: number
isRateLimited: boolean
}
export interface KeyedRateLimiter {
/**
* Rate-limit a batch of requests.
*
* Contract: the resolved array is a 1:1 positional mapping to `requests` —
* same length, exactly one decision per input request, in input order.
* Callers (e.g. `createKeyedRateLimiterStep`) correlate results by index, so
* implementations must not deduplicate, group, or reorder the returned array.
*/
rateLimitGrouped(requests: KeyedRateLimitRequest[]): Promise<[string, KeyedRateLimit][]>
}
const buildKeyPrefix = (name: string): string => {
const root = process.env.NODE_ENV === 'test' ? '@posthog-test' : '@posthog'
return `${root}/${name}/tokens`
}
export class KeyedRateLimiterService implements KeyedRateLimiter {
private readonly keyPrefix: string
constructor(
private readonly config: KeyedRateLimiterConfig,
private readonly redis: RedisV2
) {
this.keyPrefix = buildKeyPrefix(config.name)
}
public getKeyPrefix(): string {
return this.keyPrefix
}
private rateLimitArgs(req: KeyedRateLimitRequest): [string, number, number, number, number, number] {
const nowSeconds = req.now ?? Math.round(Date.now() / 1000)
const bucketSize = req.bucketSize ?? this.config.bucketSize
const refillRate = req.refillRate ?? this.config.refillRate
const ttlSeconds = req.ttlSeconds ?? this.config.ttlSeconds
if (bucketSize == null || refillRate == null || ttlSeconds == null) {
throw new Error(
`KeyedRateLimiterService(${this.config.name}): missing bucketSize/refillRate/ttlSeconds for ${req.id}`
)
}
return [`${this.keyPrefix}/${req.id}`, nowSeconds, req.cost, bucketSize, refillRate, ttlSeconds]
}
public async rateLimitMany(requests: KeyedRateLimitRequest[]): Promise<[string, KeyedRateLimit][]> {
if (requests.length === 0) {
return []
}
const bucketSizes = requests.map((req) => {
const bucketSize = req.bucketSize ?? this.config.bucketSize
if (bucketSize == null) {
throw new Error(`KeyedRateLimiterService(${this.config.name}): missing bucketSize for ${req.id}`)
}
return bucketSize
})
const useV3 = this.config.scriptVersion === 'v3'
const res = await this.redis.usePipeline(
{ name: `keyed-rate-limiter:${this.config.name}`, failOpen: true },
(pipeline) => {
requests.forEach((req) => {
const args = this.rateLimitArgs(req)
if (useV3) {
pipeline.checkRateLimitV3(...args)
} else {
pipeline.checkRateLimitV2(...args)
}
})
}
)
redisCallsTotal.inc({ name: this.config.name, method: 'rateLimitMany' }, requests.length)
if (!res) {
if (this.config.failOpen === false) {
throw new Error(`KeyedRateLimiterService(${this.config.name}): rate-limit pipeline failed`)
}
requestsTotal.inc({ name: this.config.name, method: 'rateLimitMany', outcome: 'allowed' }, requests.length)
return requests.map((req, i) => [
req.id,
{ tokensBefore: bucketSizes[i], tokens: bucketSizes[i], isRateLimited: false },
])
}
let allowed = 0
let limited = 0
const out: [string, KeyedRateLimit][] = requests.map((req, index) => {
const [tokenRes] = getRedisPipelineResults(res, index, 1)
const tokensBefore = Number(tokenRes[1]?.[0] ?? bucketSizes[index])
const tokensAfter = Number(tokenRes[1]?.[1] ?? bucketSizes[index])
const isRateLimited = tokensAfter <= 0
if (isRateLimited) {
limited++
} else {
allowed++
}
return [req.id, { tokensBefore, tokens: tokensAfter, isRateLimited }]
})
if (allowed > 0) {
requestsTotal.inc({ name: this.config.name, method: 'rateLimitMany', outcome: 'allowed' }, allowed)
}
if (limited > 0) {
requestsTotal.inc({ name: this.config.name, method: 'rateLimitMany', outcome: 'limited' }, limited)
}
return out
}
/**
* Coalesced variant of rateLimitMany — N inputs across M unique ids → M Redis calls.
* Per-input decisions fan out client-side from each id's `tokensBefore`.
*
* Boundary differs from rateLimitMany: an input whose cost lands exactly on
* the local budget (`next === 0`) is allowed here, rate-limited there. Per-id
* bucket params come from the first request seen for that id.
*/
public async rateLimitGrouped(requests: KeyedRateLimitRequest[]): Promise<[string, KeyedRateLimit][]> {
if (requests.length === 0) {
return []
}
const grouped = new Map<string, KeyedRateLimitRequest>()
for (const req of requests) {
const existing = grouped.get(req.id)
if (existing) {
existing.cost += req.cost
} else {
grouped.set(req.id, { ...req })
}
}
const items = [...grouped.values()]
const bucketSizes = items.map((req) => {
const bucketSize = req.bucketSize ?? this.config.bucketSize
if (bucketSize == null) {
throw new Error(`KeyedRateLimiterService(${this.config.name}): missing bucketSize for ${req.id}`)
}
return bucketSize
})
const res = await this.redis.usePipeline(
{ name: `keyed-rate-limiter-grouped:${this.config.name}`, failOpen: true },
(pipeline) => {
items.forEach((req) => {
pipeline.checkRateLimitV3(...this.rateLimitArgs(req))
})
}
)
redisCallsTotal.inc({ name: this.config.name, method: 'rateLimitGrouped' }, items.length)
if (!res) {
if (this.config.failOpen === false) {
throw new Error(`KeyedRateLimiterService(${this.config.name}): rate-limit pipeline failed`)
}
// Fail-open: allow every request, no fan-out deduction. The earlier shape
// here seeded `budgetById` with bucketSize and then ran the fan-out, which
// wrongly rate-limited any id whose total cost exceeded bucketSize.
const bucketSizeById = new Map(items.map((req, i) => [req.id, bucketSizes[i]]))
requestsTotal.inc(
{ name: this.config.name, method: 'rateLimitGrouped', outcome: 'allowed' },
requests.length
)
return requests.map((req) => {
const bucketSize = bucketSizeById.get(req.id) ?? 0
return [req.id, { tokensBefore: bucketSize, tokens: bucketSize, isRateLimited: false }]
})
}
const budgetById = new Map<string, number>()
items.forEach((req, index) => {
const [tokenRes] = getRedisPipelineResults(res, index, 1)
const tokensBefore = tokenRes[1]?.[0]
budgetById.set(req.id, tokensBefore != null ? Number(tokensBefore) : bucketSizes[index])
})
let allowed = 0
let limited = 0
const out: [string, KeyedRateLimit][] = requests.map((req) => {
const tokensBefore = budgetById.get(req.id) ?? 0
// Boundary is `next < 0`, not `<= 0` — needed so the lua's floor-drain of
// one token under sustained overload actually lets that input through.
if (tokensBefore >= req.cost) {
const next = tokensBefore - req.cost
budgetById.set(req.id, next)
allowed++
return [req.id, { tokensBefore, tokens: next, isRateLimited: false }]
}
limited++
return [req.id, { tokensBefore, tokens: -1, isRateLimited: true }]
})
if (allowed > 0) {
requestsTotal.inc({ name: this.config.name, method: 'rateLimitGrouped', outcome: 'allowed' }, allowed)
}
if (limited > 0) {
requestsTotal.inc({ name: this.config.name, method: 'rateLimitGrouped', outcome: 'limited' }, limited)
}
return out
}
}