Rust · Rust

Rate limiting an API by plan in Rust: GCRA, Redis and tower-rate-tier

On this page
  1. The problem: limiting by plan
  2. A service with plans
  3. GCRA: why not a fixed window
  4. Several instances, one limit: Redis
  5. Requests that cost more
  6. Safe defaults
  7. What's next
  8. What I take away

The problem: limiting by plan#

Almost every paid API ends up with plans: a free one with a low limit, a paid one with a higher limit and, sometimes, one with no limit at all. Limiting requests by IP doesn't help with that. You need to know who is making the request and which plan they're on, and you only learn that by looking at the request: an API key, a token or a database lookup.

And not every request weighs the same. Fetching a piece of data is cheap; generating a report or an export costs much more, so it should use up more quota. On top of that, as soon as the service runs on several instances, each with its own in-memory counter, the limit gets multiplied by the number of instances.

That's what I wrote tower-rate-tier for: a Tower middleware that limits requests according to each user's plan. It works with Axum, with Hyper and with any Tower service whose response can be built from a String (not Tonic, for now), and version 0.3.0, released on 2 October 2026, adds limits shared through Redis. In this post I cover how to use it, the algorithm underneath, and how the limit is shared between instances, with an example service and real outputs.

A service with plans#

This is the post's example service, in full. It has two plans, free and pro, three routes with different costs, and it keeps the limits in Redis:

server.rs
// A service with plans. The API key decides the plan, Redis keeps
// the limits (every instance shares them) and each route has its
// cost. Usage: cargo run --example server -- <port>
use std::sync::Arc;

use axum::http::StatusCode;
use axum::{Router, routing::get};
use tower_rate_tier::{
    LimitEvent, OnMissing, Quota, RateTier, RedisStorage, TierIdentity,
    TierLimitLayer,
};

// In a real service, this would come from the database.
fn plan_of(api_key: &str) -> Option<&'static str> {
    match api_key {
        "key_ana" => Some("free"),
        "key_bea" => Some("pro"),
        "key_eva" => Some("gold"), // a plan the limiter doesn't know
        _ => None,
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let port = std::env::args().nth(1).unwrap_or("3000".into());
    let conn = redis::Client::open("redis://127.0.0.1:6379")?
        .get_connection_manager()
        .await?;

    let tiers = RateTier::builder()
        .tier("free", Quota::per_minute(10))
        .tier("pro", Quota::per_minute(100))
        .default_tier("free")
        // No key, or a key that doesn't exist: 401.
        .on_missing(OnMissing::Deny(StatusCode::UNAUTHORIZED))
        .storage(Arc::new(RedisStorage::new(conn)))
        .build();

    let layer = TierLimitLayer::new(tiers)
        .identifier_fn(|headers| {
            let key = headers.get("x-api-key")?.to_str().ok()?;
            Some(TierIdentity::new(key, plan_of(key)?))
        })
        .cost_fn(|req| match req.uri.path() {
            "/report" => 5,
            "/backup" => 50, // more than the free plan gives in a minute
            _ => 1,
        })
        .on_event(|event| {
            if let LimitEvent::UnknownTier { user_id, tier, .. } = event {
                eprintln!("unknown tier {tier:?} for {user_id}");
            }
        });

    let app = Router::new()
        .route("/data", get(|| async { "data\n" }))
        .route("/report", get(|| async { "report\n" }))
        .route("/backup", get(|| async { "backup\n" }))
        .layer(layer);

    let addr = format!("127.0.0.1:{port}");
    let listener = tokio::net::TcpListener::bind(addr).await?;
    axum::serve(listener, app).await?;
    Ok(())
}

Piece by piece:

  • Plans are declared with a name and a quota: Quota::per_minute(10) means 10 requests per minute. default_tier("free") is the fallback plan for the cases we'll see further down.
  • identifier_fn receives the headers and returns who the user is and their plan, or None if it can't tell. Here the API key decides the plan; in a real service it would come from the database, and that's what the TierIdentifier trait is for, since it's asynchronous.
  • cost_fn decides what each request costs: /data uses 1 from the quota, /report uses 5 and /backup, 50.
  • on_event reports what the limiter resolves on its own, such as an unknown plan. It's there for logs and metrics.

cost_fn runs inside the middleware, and that matters with Axum. The crate also has a tier_cost(n) layer, but if you put it on a route with .layer(...) while the limiter is added with Router::layer, the route's layer runs after the limiter: the cost arrives too late and is ignored. Up to 0.2, the README and the Axum example did exactly that, so every request cost 1 without anyone noticing. 0.3 fixes it with cost_fn.

GCRA: why not a fixed window#

The simplest way to limit is a fixed window: a counter per minute that goes back to zero when the minute changes. The trouble is right at that change. This program compares it with what tower-rate-tier does, with the same limit of 10 per minute and the same 20 requests: 10 at second 59 and another 10 at second 60.

window.rs
// Fixed window versus GCRA, with the same limit: 10 per minute.
// 10 requests arrive at second 59 and another 10 at second 60.
use std::time::Duration;

use tower_rate_tier::clock::FakeClock;
use tower_rate_tier::{Quota, RateTier};

#[tokio::main]
async fn main() {
    let arrivals = [(59, 10), (60, 10)];

    // Fixed window: a counter per minute that resets when it changes.
    let (mut minute, mut used, mut fixed) = (0, 0, 0);
    for (t, count) in arrivals {
        if t / 60 != minute {
            (minute, used) = (t / 60, 0);
        }
        let ok = count.min(10 - used);
        used += ok;
        fixed += ok;
    }

    // GCRA, with tower-rate-tier and a fake clock.
    let clock = FakeClock::new();
    let limiter = RateTier::builder()
        .clock(clock.clone())
        .tier("free", Quota::per_minute(10))
        .build();
    let (mut now, mut gcra) = (0, 0);
    for (t, count) in arrivals {
        clock.advance(Duration::from_secs(t - now));
        now = t;
        for _ in 0..count {
            if limiter.check("ana", "free", 1).await.unwrap().is_ok() {
                gcra += 1;
            }
        }
    }

    println!("fixed window: {fixed} of 20 allowed in 2 seconds");
    println!("GCRA:         {gcra} of 20 allowed in 2 seconds");
}

This is the real output, on Linux with Rust 1.94:

output
fixed window: 20 of 20 allowed in 2 seconds
GCRA:         10 of 20 allowed in 2 seconds

With the fixed window all 20 get through in two seconds, twice the limit, because the first 10 count towards one minute and the next 10 towards another. That's the burst at the window boundary.

FIXED WINDOW 20 allowed in 2 s the counter resets 0 s 60 s 120 s GCRA 10 allowed, 10 rejected; then 1 every 6 s 0 s 60 s 120 s allowed rejected
Fig. 1 — The same limit, 10 per minute, and the same 20 requests at seconds 59 and 60. The fixed window allows twice as many at the minute boundary; GCRA never lets through more than the rate allows.

tower-rate-tier uses GCRA (Generic Cell Rate Algorithm), an algorithm that comes from ATM networking. Instead of counting requests, it keeps a single number per user: the TAT (theoretical arrival time), the moment the user's bucket would be full again. With 10 requests per minute:

  • each request moves the TAT 6 seconds into the future (60 / 10), multiplied by its cost;
  • the request is allowed if, after moving it, the TAT is no more than 60 seconds ahead of now;
  • if there's no stored TAT, or it's already in the past, it starts from now.

This is how it behaves, step by step, with a fake clock:

gcra.rs
// GCRA step by step: 10 requests per minute, with a fake clock.
use std::time::Duration;

use tower_rate_tier::clock::FakeClock;
use tower_rate_tier::{Quota, RateTier};

#[tokio::main]
async fn main() {
    let clock = FakeClock::new();
    let limiter = RateTier::builder()
        .clock(clock.clone())
        .tier("free", Quota::per_minute(10))
        .build();

    // (seconds it waits, requests it sends afterwards)
    let mut t = 0;
    for (wait, count) in [(0, 11), (6, 2), (30, 6)] {
        clock.advance(Duration::from_secs(wait));
        t += wait;
        for _ in 0..count {
            match limiter.check("ana", "free", 1).await.unwrap() {
                Ok(info) => {
                    let left = info.remaining;
                    println!("t={t:>2}s  200  remaining {left}")
                }
                Err(limited) => {
                    let wait = limited.retry_after_secs();
                    println!("t={t:>2}s  429  retry after {wait} s")
                }
            }
        }
    }
}

This is the real output, on Linux with Rust 1.94:

output
t= 0s  200  remaining 9
t= 0s  200  remaining 8
t= 0s  200  remaining 7
t= 0s  200  remaining 6
t= 0s  200  remaining 5
t= 0s  200  remaining 4
t= 0s  200  remaining 3
t= 0s  200  remaining 2
t= 0s  200  remaining 1
t= 0s  200  remaining 0
t= 0s  429  retry after 6 s
t= 6s  200  remaining 0
t= 6s  429  retry after 6 s
t=36s  200  remaining 4
t=36s  200  remaining 3
t=36s  200  remaining 2
t=36s  200  remaining 1
t=36s  200  remaining 0
t=36s  429  retry after 6 s

The first 10 requests take the TAT from second 0 to 60. The eleventh would take it to 66, more than 60 seconds ahead, so it's rejected: it has to wait 6 seconds. At second 6 exactly one more fits, and the TAT moves to 66. At second 36 the TAT is still at 66, only 30 seconds ahead: that leaves 30 free seconds, and at 6 seconds per request that's 5 requests.

In other words, a user can spend the whole limit at once, but then the quota comes back little by little, at the plan's rate, rather than all at once when the minute changes.

In one sentence

GCRA keeps a single number per user, the moment their quota would be full again, and uses it to decide every request: no counters that reset and no bursts at the minute boundary.

The fake clock, FakeClock, is part of the crate. With it, tests don't depend on the real time and don't have to wait: they move the clock forward 6 seconds and check the result instantly, the same every time.

Several instances, one limit: Redis#

With the redis feature, RedisStorage keeps each user's TAT in Redis instead of in memory, so every instance shares the same limit. To check it, I started the service twice, on ports 3000 and 3001, against the same Redis, and Ana, on the free plan, alternates between them:

1-shared.sh
# Ana (free plan, 10 per minute) alternates between both instances.
for i in $(seq 1 11); do
  port=$((3000 + i % 2))
  curl -s -o /dev/null -w "$port %{http_code}\n" \
    -H "x-api-key: key_ana" "localhost:$port/data"
done

This is the real output, on Linux with Redis 7.0:

output
3001 200
3000 200
3001 200
3000 200
3001 200
3000 200
3001 200
3000 200
3001 200
3000 200
3001 429

Ten requests allowed across both instances and the eleventh rejected: there's one limit, not one per instance. This is the full response to a rejection:

2-limited.sh
curl -si -H "x-api-key: key_ana" localhost:3000/data

This is the real output, on Linux with Redis 7.0:

output
HTTP/1.1 429 Too Many Requests
content-type: application/json
retry-after: 6
x-ratelimit-limit: 10
x-ratelimit-remaining: 0
x-ratelimit-reset: 1790947155
content-length: 61
date: Fri, 02 Oct 2026 13:18:14 GMT

{"error":"rate limit exceeded","tier":"free","retry_after":6}

Retry-After says how many seconds to wait, and the body repeats it in JSON. X-RateLimit-Reset is the Unix time at which the quota will be full again. Retry-After is rounded up. In 0.2 it was rounded down, and a client that waited exactly as long as it was told got another 429.

What's left in Redis? One key per user and plan:

3-redis.sh
# Ana's bucket key: the plan and the SHA-1 of the user id.
key="trt:free:$(printf key_ana | sha1sum | cut -c1-40)"
redis-cli --scan --pattern 'trt:*'
redis-cli PTTL "$key"

This is the real output, on Linux with Redis 7.0:

output
trt:free:33d2315cbeb866b8b237240a98d605f2e6e41b8a
59841

The key is trt:<plan>:<sha1(user)>, so the identifier isn't stored in the clear. If identifiers have little entropy, like IP addresses or emails, the SHA-1 can be reversed by trying values, and that's what .key_secret(secret) is for: it computes the key with HMAC-SHA1 and a secret. The second number is PTTL: the key expires in about 60 seconds, exactly when Ana's bucket is full again. There's nothing to clean up.

Every check is a Lua script that Redis runs atomically: while it runs, no other command touches the key, so two instances can't read the same TAT and both allow the last request. This is the last part of gcra.lua, where the decision is made:

gcra.lua
-- A key of another type makes GET fail; pcall turns that into an error
-- table, which tonumber() reads as nil. Not an integer (this includes NaN)
-- means a corrupted value too: start fresh.
local stored = redis.pcall("GET", KEYS[1])
if type(stored) == "table" then
  stored = nil
end
local tat = tonumber(stored)
local capped = false
if tat == nil or tat ~= math.floor(tat) or tat < now then
  tat = now
elseif tat > now + burst_offset then
  tat = now + burst_offset
  capped = true
end

local increment = emission_interval * cost
if increment > MAX_EXACT - tat then
  return fail("time values exceed the exact range of Lua numbers")
end
local new_tat = tat + increment
local allow_at = new_tat - burst_offset

if allow_at > now then
  if capped then
    redis.call("SET", KEYS[1], tat, "PX", math.ceil((tat - now) / 1000))
  end
  return { 0, 0, allow_at - now, tat - now }
end

if new_tat > now then
  redis.call("SET", KEYS[1], new_tat, "PX", math.ceil((new_tat - now) / 1000))
end

local remaining = math.floor((burst_offset - (new_tat - now)) / emission_interval)
return { 1, remaining, 0, new_tat - now }

The script is the same logic as the GCRA in Rust, with three details that only show up when you move it to Redis:

  • The clock is Redis's. The script reads the time with TIME, so it doesn't matter that the instances' clocks disagree.
  • The expiry is rounded up (math.ceil in the PX). If it were rounded down, the key could vanish a millisecond early and give away requests.
  • If Redis's clock goes backwards (for example, on failover to a replica whose clock is behind), the TAT is capped at a full bucket and stored that way. Without that, the user would stay locked out for as long as the clock went back.
Fun fact

The script works in microseconds, not nanoseconds like the Rust side. Lua numbers are doubles, exact for integers up to 253: in microseconds since 1970 that reaches the year 2255; in nanoseconds it wouldn't even cover today's date.

The script is tested twice: in an embedded Lua 5.1, the same version Redis uses, with no server needed, and against a real Redis in CI. If Redis takes longer than 100 ms to answer, the check counts as a storage error, which I cover further down.

Requests that cost more#

Bea is on the pro plan, 100 per minute, and fetches some data and then a report:

4-cost.sh
# Bea (pro plan, 100 per minute): /data costs 1 and /report, 5.
for path in data report; do
  curl -s -o /dev/null -H "x-api-key: key_bea" \
    -w "/$path %{http_code} remaining %header{x-ratelimit-remaining}\n" \
    "localhost:3000/$path"
done

This is the real output, on Linux with Redis 7.0:

output
/data 200 remaining 99
/report 200 remaining 94

/data uses 1 and leaves 99; /report uses 5 and leaves 94. For GCRA, a request costing 5 is like five requests at once: it moves the TAT 5 intervals in one go.

Safe defaults#

The trickiest part of a limiter isn't the algorithm, it's what it does when something doesn't fit. Eva has a valid key, but Eva's plan, gold, isn't configured:

5-policies.sh
# Eva has a plan the limiter doesn't know.
curl -s -o /dev/null -H "x-api-key: key_eva" \
  -w "/data %{http_code} limit %header{x-ratelimit-limit}\n" \
  localhost:3000/data
curl -s -o /dev/null -H "x-api-key: key_eva" \
  -w "/backup %{http_code}\n" localhost:3000/backup
# No API key.
curl -s -o /dev/null -w "/data %{http_code}\n" localhost:3000/data

This is the real output, on Linux with Redis 7.0:

output
/data 200 limit 10
/backup 403
/data 401

And this is what the service wrote to standard error, from on_event:

output
unknown tier "gold" for key_eva
unknown tier "gold" for key_eva

Three cases, three decisions:

  • An unknown plan doesn't grant unlimited access. Eva gets the default plan's quota (limit 10) in Eva's own bucket, and on_event reports every request. An unknown plan might be a typo, a new plan the limiter doesn't know yet or, worse, a value the client controls. Up to 0.2, a request with an unknown plan went through with no limit at all; 0.3 fixes it and the changelog lists it as a security fix. If there's no default plan, the answer is 403, and OnUnknownTier can also choose Deny or an explicit Allow.
  • A request that could never succeed doesn't get a 429. /backup costs 50 and the free plan gives 10 per minute: no amount of waiting would make it possible. So it answers 403 Forbidden, with no Retry-After and without touching Redis.
  • Unidentified requests get an explicit decision. Here, with OnMissing::Deny and the UNAUTHORIZED status, a request with no key gets 401. By default (OnMissing::UseDefault) it would get the default plan.
Watch out for storage errors

If Redis fails or takes longer than 100 ms, by default the request goes through (OnStorageError::Allow): better not to limit during an outage than to take the whole API down. If you prefer the opposite, OnStorageError::Deny answers 503. Either way, on_event receives a LimitEvent::StorageError, so a Redis outage doesn't go unnoticed.

What's next#

The 0.4 roadmap focuses on operations:

  • changing plans on the fly, without restarting the service;
  • Prometheus-compatible metrics;
  • support for Tonic and gRPC;
  • keeping the limit in local memory while Redis is down, and a circuit breaker so a down Redis doesn't cost every request its 100 ms timeout.

If any of these releases brings something worth telling, I'll tell it here.

What I take away#

  • Limiting by plan is mostly about identifying well. The algorithm is the easy part; knowing who's asking and on which plan, and what to do when you don't know, is what decides whether the limit is any use.
  • GCRA does a lot with very little. With a single number per user it spreads the quota at the plan's rate and even tells you how long to wait.
  • With several instances, both the state and the clock have to be shared. An atomic script in Redis and Redis's own time solve both at once.
  • Defaults are security decisions. An unknown plan, an unidentified request or a Redis outage need a deliberate answer, not whatever happens by accident.
  • An injectable clock makes time testable. Tests don't wait for a minute to pass: they move the clock and check.
Personal note

tower-rate-tier is a crate of mine, licensed under MIT or Apache 2.0. 0.1.0 came out on 11 March 2026 and 0.3.0 on 2 October 2026. Everything in this post is 0.3.0 as downloaded from crates.io: the example service and the outputs were run on Linux, with Rust 1.94 and Redis 7.0.

References

  1. tower-rate-tier on crates.iocrates.io · crates.io
  2. tower-rate-tier documentationdocs.rs · docs.rs
  3. tower-rate-tier: source codeGitHub · github.com
  4. tower-rate-tier: changelogGitHub · github.com
  5. tower-rate-tier: roadmapGitHub · github.com
  6. Generic cell rate algorithmWikipedia · en.wikipedia.org
  7. Scripting with LuaRedis · redis.io
  8. TIMERedis · redis.io
  9. RFC 6585: Additional HTTP Status Codes (429 Too Many Requests)IETF · rfc-editor.org
  10. RFC 9110: HTTP Semantics (Retry-After)IETF · rfc-editor.org

Share

Keep reading

Rust

Using C++ from Rust: how a safe wrapper turns a use-after-free into a compile error

A C++ library used from Rust: what unsafe really is, how to design the C boundary, why a C++ bug stops compiling with the right wrapper, and what happens to exceptions and panics. With real code.

· 17 min

Rust

Why Rust remains the safest language in 2026

Analysis of Rust's memory safety features and why it dominates in critical systems.

· 5 min

Need Rust development?

Secure, high-performance software development with Rust for your business. Consulting, training, and custom projects.

Let's talk→

Comments

Commenting requires a GitHub account. Comments live in GitHub Discussions (SoftDryzz/blog-comments) and are moderated: no promotional links.