Rates¶

A Rate answers one question: how many requests are allowed in how much time?

Traffik allows you express that in two ways. Either a human-friendly string, or the Rate object itself. Both end up in exactly the same.

String format¶

The string format is the fastest path to a working rate limit. Traffik parses it once and caches the result.

rate = "100/min"     # 100 requests per minute
rate = "5/s"         # 5 per second
rate = "10/10s"      # 10 per 10 seconds
rate = "2 per second"
rate = "500/hour"
rate = "1000/500ms"  # sub-second windows work too

The general grammar is:

<limit>/<period><unit>
<limit> per <period><unit>
<limit>/<period> <unit>

Where <period> is an optional integer multiplier (defaults to 1) and <unit> is one of the values in the table below.

Supported units¶

Rate string reference¶

The Rate object¶

When you need a period that spans multiple units, for example 5 minutes and 30 seconds, or when you want to construct a rate programmatically, use Rate directly.

from traffik.rates import Rate

# Simple: 100 requests per minute
rate = Rate(limit=100, minutes=1)

# Combined units: 100 requests per 5 minutes and 30 seconds
rate = Rate(limit=100, minutes=5, seconds=30)

# Sub-second: 50 requests per 500 milliseconds
rate = Rate(limit=50, milliseconds=500)

Rate accepts the following keyword arguments (all default to 0):

All time parameters are additive, the expire period is their sum in milliseconds.

Rate objects are immutable and final (subclassing is forbidden). Once created, every attribute, limit, expire, rps, rpm, rph, rpd, is_subsecond, unlimited, is frozen.

Parsing with Rate.parse()¶

Internally, string rates go through Rate.parse(), which wraps an LRU-cached internal parser with a capacity of 512 entries. This means the thousandth time you hit "100/min", the parse cost is effectively zero.

rate = Rate.parse("100/min")
rate = Rate.parse("2/5s")
rate = Rate.parse("10 per second")

Parsing is case-insensitive. "100/MIN" and "100/min" hit the same cache entry.

Dynamic rate functions¶

Sometimes the right rate limit depends on the request itself. Maybe free users get "10/min" and pro users get "1000/min". Traffik supports async rate functions that receive the current connection and context, and return a Rate.

from traffik.rates import Rate
from starlette.requests import Request

async def my_rate(connection: Request, context: dict | None) -> Rate:
    user = connection.state.user    # Possibly set by a middleware or dependency
    if user and user.plan == "pro":
        return Rate.parse("1000/min")
    return Rate.parse("10/min")

Pass the function anywhere a rate is accepted:

from traffik import HTTPThrottle

throttle = HTTPThrottle(
    uid="dynamic-rate",
    rate=my_rate,  # async function, not a string or Rate
)

Unlimited rates¶

To explicitly mark something as unlimited (no throttling at all), construct a bare Rate with no arguments:

Rate()  # Unlimited. No limit, no period, no throttling

Rate() produces rate.unlimited == True. Traffik's strategies detect this flag and short-circuit immediately with zero backend I/O, almost zero overhead.