Limitar una API por plan en Rust: GCRA, Redis y tower-rate-tierRate limiting an API by plan in Rust: GCRA, Redis and tower-rate-tier

El problema: limitar por plan#

Casi cualquier API de pago acaba teniendo planes: uno gratuito con un límite bajo, uno de pago con un límite más alto y, a veces, uno sin límite. Limitar las peticiones por IP no sirve para eso. Hay que saber quién hace la petición y qué plan tiene, y eso solo se sabe mirando la petición: una clave de API, un token o una consulta a la base de datos.

Y no todas las peticiones pesan lo mismo. Pedir un dato cuesta poco; generar un informe o una exportación cuesta mucho más, así que debería gastar más cuota. Además, en cuanto el servicio corre en varias instancias, cada una con su propio contador en memoria, el límite se multiplica por el número de instancias.

Para eso escribí tower-rate-tier, un middleware de Tower que limita las peticiones según el plan de cada usuario. Funciona con Axum, con Hyper y con cualquier servicio de Tower cuya respuesta se pueda construir a partir de un String (Tonic, de momento, no), y la versión 0.3.0, publicada el 2 de octubre de 2026, añade los límites compartidos a través de Redis. En esta entrada cuento cómo se usa, qué algoritmo hay debajo y cómo se comparte el límite entre instancias, con un servicio de ejemplo y salidas reales.

Un servicio con planes#

Este es el servicio de ejemplo de la entrada, completo. Tiene dos planes, free y pro, tres rutas con distinto coste y guarda los límites en Redis:

// Un servicio con planes. La clave de API decide el plan, Redis guarda
// los límites (los comparten todas las instancias) y cada ruta tiene su
// coste. Uso: cargo run --example server -- <puerto>
use std::sync::Arc;

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

// En un servicio real, esto saldría de la base de datos.
fn plan_of(api_key: &str) -> Option<&'static str> {
    match api_key {
        "key_ana" => Some("free"),
        "key_bea" => Some("pro"),
        "key_eva" => Some("gold"), // un plan que el limitador no conoce
        _ => 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")
        // Sin clave, o con una clave que no existe: 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, // más de lo que el plan free da en un minuto
            _ => 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(())
}

Por partes:

• Los planes se declaran con un nombre y una cuota: Quota::per_minute(10) son 10 peticiones por minuto. default_tier("free") es el plan de reserva para los casos que veremos más abajo.
• identifier_fn recibe las cabeceras y devuelve quién es el usuario y su plan, o None si no lo sabe. Aquí la clave de API decide el plan; en un servicio real saldría de la base de datos, y para eso existe el trait TierIdentifier, que es asíncrono.
• cost_fn decide cuánto cuesta cada petición: /data gasta 1 de la cuota, /report gasta 5 y /backup, 50.
• on_event avisa de lo que el limitador resuelve por su cuenta, como un plan desconocido. Sirve para logs y métricas.

cost_fn se ejecuta dentro del middleware, y eso importa con Axum. El crate también tiene una capa tier_cost(n), pero si se pone en una ruta con .layer(...) mientras el limitador se añade con Router::layer, la capa de la ruta se ejecuta después del limitador: el coste llega tarde y se ignora. Hasta la 0.2, el README y el ejemplo de Axum hacían justo eso, así que todas las peticiones costaban 1 sin que nadie lo notara. La 0.3 lo corrige con cost_fn.

GCRA: por qué no una ventana fija#

La forma más sencilla de limitar es una ventana fija: un contador por minuto que vuelve a cero cuando cambia el minuto. El problema está justo en ese cambio. Este programa lo compara con lo que hace tower-rate-tier, con el mismo límite de 10 por minuto y las mismas 20 peticiones: 10 en el segundo 59 y otras 10 en el 60.

// Ventana fija frente a GCRA, con el mismo límite: 10 por minuto.
// Llegan 10 peticiones en el segundo 59 y otras 10 en el 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)];

    // Ventana fija: un contador por minuto que vuelve a 0 al cambiar.
    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, con tower-rate-tier y un reloj falso.
    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");
}

Esta es la salida real, en Linux con Rust 1.94:

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

Con la ventana fija pasan las 20 en dos segundos, el doble del límite, porque las 10 primeras cuentan en un minuto y las 10 siguientes en otro. Es la ráfaga en el borde de la ventana.

tower-rate-tier usa GCRA (Generic Cell Rate Algorithm), un algoritmo que viene del mundo de las redes ATM. En vez de contar peticiones, guarda un solo número por usuario: el TAT (theoretical arrival time), el momento en el que el cubo del usuario volvería a estar lleno. Con 10 peticiones por minuto:

• cada petición mueve el TAT 6 segundos hacia el futuro (60 / 10), multiplicados por su coste;
• la petición se acepta si, después de moverlo, el TAT no queda más de 60 segundos por delante de ahora;
• si no hay TAT guardado, o ya ha pasado, se parte de ahora.

Así se comporta, paso a paso, con un reloj falso:

// GCRA paso a paso: 10 peticiones por minuto, con un reloj falso.
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();

    // (segundos que espera, peticiones que lanza después)
    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")
                }
            }
        }
    }
}

Esta es la salida real, en Linux con Rust 1.94:

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

Las 10 primeras peticiones llevan el TAT del segundo 0 al 60. La undécima lo llevaría al 66, más de 60 segundos por delante, así que se rechaza: tiene que esperar 6 segundos. En el segundo 6 cabe justo una más, y el TAT pasa al 66. En el segundo 36 el TAT sigue en el 66, solo 30 segundos por delante: quedan 30 segundos libres, y a 6 segundos por petición son 5 peticiones.

Es decir, el usuario puede gastar todo su límite de golpe, pero luego la cuota vuelve poco a poco, al ritmo del plan, y no de una vez al cambiar el minuto.

El reloj falso, FakeClock, es parte del crate. Con él, los tests no dependen de la hora real ni tienen que esperar: avanzan el reloj 6 segundos y comprueban el resultado al instante, siempre igual.

Varias instancias, un solo límite: Redis#

Con la feature redis, RedisStorage guarda el TAT de cada usuario en Redis en vez de en memoria, así que todas las instancias comparten el mismo límite. Para comprobarlo, arranqué el servicio dos veces, en los puertos 3000 y 3001, contra el mismo Redis, y Ana, con el plan free, va alternando entre las dos:

# Ana (plan free, 10 por minuto) alterna entre las dos instancias.
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

Esta es la salida real, en Linux con Redis 7.0:

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

Diez peticiones aceptadas entre las dos instancias y la undécima rechazada: el límite es uno, no uno por instancia. La respuesta completa de un rechazo es esta:

curl -si -H "x-api-key: key_ana" localhost:3000/data

Esta es la salida real, en Linux con Redis 7.0:

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 dice cuántos segundos esperar, y el cuerpo lo repite en JSON. X-RateLimit-Reset es la hora Unix en la que la cuota estará llena otra vez. Retry-After se redondea hacia arriba. En la 0.2 se redondeaba hacia abajo, y un cliente que esperaba exactamente lo que le decían volvía a recibir un 429.

¿Qué queda en Redis? Una clave por usuario y plan:

# La clave del cubo de Ana: el plan y el SHA-1 del identificador.
key="trt:free:$(printf key_ana | sha1sum | cut -c1-40)"
redis-cli --scan --pattern 'trt:*'
redis-cli PTTL "$key"

Esta es la salida real, en Linux con Redis 7.0:

trt:free:33d2315cbeb866b8b237240a98d605f2e6e41b8a
59841

La clave es trt:<plan>:<sha1(usuario)>, así que el identificador no se guarda en claro. Si los identificadores tienen poca entropía, como direcciones IP o correos, el SHA-1 se puede revertir probando valores, y para eso existe .key_secret(secreto), que calcula la clave con HMAC-SHA1 y un secreto. El segundo número es PTTL: la clave caduca en unos 60 segundos, justo cuando el cubo de Ana vuelve a estar lleno. No hay que limpiar nada.

Cada comprobación es un script de Lua que Redis ejecuta de forma atómica: mientras corre, ningún otro comando toca la clave, así que dos instancias no pueden leer el mismo TAT y aceptar las dos la última petición. Esta es la parte final de gcra.lua, donde se decide:

-- 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 }

El script es la misma lógica que el GCRA en Rust, con tres detalles que solo aparecen al llevarlo a Redis:

• El reloj es el de Redis. El script lee la hora con TIME, así que da igual que los relojes de las instancias no coincidan.
• La caducidad se redondea hacia arriba (math.ceil en el PX). Si se redondeara hacia abajo, la clave podría desaparecer un milisegundo antes de tiempo y regalar peticiones.
• Si el reloj de Redis va hacia atrás (por ejemplo, al pasar a una réplica con el reloj atrasado), el TAT se recorta a un cubo lleno y se guarda así. Sin eso, el usuario se quedaría bloqueado todo el tiempo que el reloj retrocedió.

El script se prueba dos veces: en un Lua 5.1 embebido, la misma versión que usa Redis, sin necesidad de un servidor, y contra un Redis real en CI. Si Redis tarda más de 100 ms en responder, la comprobación cuenta como un error de almacenamiento, del que hablo más abajo.

Peticiones que cuestan más#

Bea tiene el plan pro, 100 por minuto. Pide un dato y luego un informe:

# Bea (plan pro, 100 por minuto): /data cuesta 1 y /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

Esta es la salida real, en Linux con Redis 7.0:

/data 200 remaining 99
/report 200 remaining 94

/data gasta 1 y deja 99; /report gasta 5 y deja 94. Para GCRA, una petición de coste 5 es como cinco peticiones a la vez: mueve el TAT 5 intervalos de golpe.

Valores por defecto seguros#

Lo más delicado de un limitador no es el algoritmo, sino lo que hace cuando algo no encaja. Eva tiene una clave válida, pero su plan, gold, no está configurado:

# Eva tiene un plan que el limitador no conoce.
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
# Sin clave de API.
curl -s -o /dev/null -w "/data %{http_code}\n" localhost:3000/data

Esta es la salida real, en Linux con Redis 7.0:

/data 200 limit 10
/backup 403
/data 401

Y esto es lo que escribió el servicio por la salida de error, desde on_event:

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

Tres casos, tres decisiones:

• Un plan desconocido no da acceso ilimitado. Eva recibe la cuota del plan por defecto (limit 10) en su propio cubo, y on_event avisa de cada petición. Un plan desconocido puede ser una errata, un plan nuevo que el limitador aún no conoce o, peor, un valor que el cliente controla. Hasta la 0.2, una petición con un plan desconocido pasaba sin ningún límite; en la 0.3 está corregido y anotado como fallo de seguridad en el changelog. Si no hay plan por defecto, la respuesta es 403, y también se puede elegir Deny o un Allow explícito con OnUnknownTier.
• Una petición que nunca podría pasar no recibe un 429. /backup cuesta 50 y el plan free da 10 por minuto: ningún tiempo de espera la haría posible. Por eso responde 403 Forbidden, sin Retry-After y sin tocar Redis.
• Sin identificar, se decide explícitamente. Aquí, con OnMissing::Deny y el estado UNAUTHORIZED, una petición sin clave recibe 401. Por defecto (OnMissing::UseDefault) recibiría el plan por defecto.

Lo que viene#

La hoja de ruta de la 0.4 se centra en la operación:

• cambiar los planes en caliente, sin reiniciar el servicio;
• métricas compatibles con Prometheus;
• soporte para Tonic y gRPC;
• seguir limitando en memoria local mientras Redis está caído, y un circuit breaker para que un Redis caído no cueste a cada petición sus 100 ms de espera.

Si alguna de estas versiones trae algo que merezca la pena contar, lo contaré aquí.

Lo que me llevo#

• Limitar por plan es, sobre todo, identificar bien. El algoritmo es la parte fácil; saber quién pide y con qué plan, y qué hacer cuando no se sabe, es lo que decide si el límite sirve.
• GCRA hace mucho con muy poco. Con un solo número por usuario reparte la cuota al ritmo del plan y hasta dice cuánto esperar.
• Con varias instancias, el estado y el reloj tienen que ser compartidos. Un script atómico en Redis y la hora de Redis resuelven las dos cosas a la vez.
• Los valores por defecto son decisiones de seguridad. Un plan desconocido, una petición sin identificar o un Redis caído necesitan una respuesta pensada, no la que salga por accidente.
• Un reloj inyectable hace que el tiempo se pueda testear. Los tests no esperan a que pase un minuto: mueven el reloj y comprueban.