pingora-limits

Active contributors: yuchen

Purpose

Counting and rate-limiting primitives. Three small modules: a sliding-window estimator, an in-flight counter, and a token-bucket rate limiter. Used to implement rate limiting in user proxy code (see docs/user_guide/rate_limiter.md).

Directory layout

pingora-limits/src/
├── lib.rs              Re-exports
├── estimator.rs        Sliding-window approximate counter
├── inflight.rs         Concurrent in-flight gauge
└── rate.rs             Token-bucket rate limiter

Key abstractions

Type	File	What it is
Estimator	pingora-limits/src/estimator.rs	Approximate sliding-window counter (count-min sketch flavor)
Inflight	pingora-limits/src/inflight.rs	A guarded in-flight counter (RAII drop-decrement)
Rate	pingora-limits/src/rate.rs	Per-key token-bucket rate limiter

How it works

Rate

Keyed sliding-window rate limiter. For a key (e.g. client IP), counts events in the current window and rolls the window forward. Returns RateLimitResult::Hit { remaining } or RateLimitResult::Reject so the user can return 429 with a Retry-After header.

The user guide walks through plugging this into request_filter to rate-limit by client IP. See docs/user_guide/rate_limiter.md.

Estimator

A multi-bucket counter that estimates "how many times have I seen this key" without storing every key. Useful for cardinality-bounded counters (top-N requesters, etc.).

Inflight

An atomic counter with an RAII guard. Useful for limiting concurrent requests per peer or globally.

Integration points

• Pure utility crate — depended on directly by user code.
• No internal Pingora consumers.

Entry points for modification

• New rate-limit algorithm (leaky bucket, GCRA) → add a module here.
• Different bucket-resolution tradeoffs → tune the constants in estimator.rs.

Key source files

File	Purpose
pingora-limits/src/rate.rs	Rate token bucket
pingora-limits/src/estimator.rs	Estimator sketch counter
pingora-limits/src/inflight.rs	Inflight gauge