Bài 78: Rate Limiting — governor + Per-IP, Per-User

Sau bài học, bạn sẽ:

• Hiểu 4 thuật toán rate limiting: fixed window, sliding window, token bucket, leaky bucket — biết khi nào chọn cái nào.
• Cài và dùng governor crate v0.6 — Rust idiomatic token bucket implementation.
• Implement per-IP rate limit cho endpoint nhạy cảm (/auth/login, /users/register) chống brute force.
• Implement per-user rate limit cho endpoint mutation (/orders, /cart/checkout) theo authenticated identity.
• Response chuẩn 429 Too Many Requests kèm header Retry-After (RFC 6585) cho client biết khi nào retry.
• Hiểu pitfall in-memory rate limit với multi-instance app + plan migration Redis-backed G15.
• Thêm pattern AppError::TooManyRequests variant mới — bump 20 → 21 variant.

Rate limiting có 4 thuật toán cổ điển; mỗi cái trade-off độ chính xác, memory, behavior burst riêng. Bảng so sánh nhanh:

Algorithm        | Pros                        | Cons
-----------------|-----------------------------|--------------------------------
Fixed window     | đơn giản, ít memory         | spike boundary (20 req/2s ở giữa
                 |                             | 2 window 10 req)
Sliding window   | smooth không spike boundary | memory grow O(N) timestamp lưu
Token bucket     | burst-friendly + refill     | phức tạp impl hơn fixed
                 | steady (industry standard)  |
Leaky bucket     | smooth output rate          | latency tăng (queue chờ slot)

Fixed window đếm số request trong cửa sổ N giây, reset đầu mỗi window. Cài đặt đơn giản (1 counter + 1 timestamp) nhưng có pitfall boundary spike: nếu limit 10 req/phút, attacker bắn 10 req lúc 59 giây cuối window 1 + 10 req lúc 1 giây đầu window 2 → effective 20 req/2 giây vượt rate spec.

Sliding window track timestamp từng request, đếm số timestamp nằm trong rolling N giây vừa qua. Khắc phục boundary spike nhưng memory grow O(N) — mỗi user/IP lưu list timestamp, traffic cao = RAM nặng.

Token bucket dùng bucket chứa N token, refill rate K token/giây, mỗi request consume 1 token. Bucket đầy = cho phép short burst (vd 60 token cho 60 request liên tiếp), refill steady đảm bảo long-term rate; bucket cạn = reject. Đây là industry standard dùng bởi AWS API Gateway, Stripe API, Cloudflare.

Leaky bucket queue request, process steady rate (output mượt). Server dễ control downstream load nhưng client phải chờ → latency tăng, không phù hợp REST API cần response nhanh.

Lock decision Shop API: token bucket qua governor crate. Lý do: burst-friendly cho legitimate user (refresh page nhanh, batch cart add 5 item), refill steady đảm bảo long-term quota, industry standard nên client dev đã quen pattern Retry-After.

Crate governor v0.6 là Rust port của Stripe rate limiter Java, dùng GCRA (Generic Cell Rate Algorithm — token bucket variant tối ưu). API đơn giản, không phụ thuộc tokio runtime (sync + async đều dùng được).

Thêm vào workspace root shop/Cargo.toml:

# File: shop/Cargo.toml — workspace root
[workspace.dependencies]
governor = "0.6"

Thêm dep vào crate shop-api:

# File: crates/shop-api/Cargo.toml
[dependencies]
governor = { workspace = true }

Tạo file mới crates/shop-api/src/middleware/rate_limit.rs chứa 2 type alias + 2 builder function:

// File: crates/shop-api/src/middleware/rate_limit.rs
use std::net::IpAddr;
use std::num::NonZeroU32;
use std::sync::Arc;

use governor::{
    clock::DefaultClock,
    state::keyed::DefaultKeyedStateStore,
    Quota, RateLimiter,
};

/// Per-IP rate limiter — key IpAddr, in-memory state.
pub type IpRateLimiter = Arc<RateLimiter<IpAddr, DefaultKeyedStateStore<IpAddr>, DefaultClock>>;

/// Per-user rate limiter — key user_id (i64 = BIGSERIAL PG), in-memory state.
pub type UserRateLimiter = Arc<RateLimiter<i64, DefaultKeyedStateStore<i64>, DefaultClock>>;

/// Build limiter per-IP với quota requests/phút.
pub fn build_ip_limiter(requests_per_minute: u32) -> IpRateLimiter {
    let quota = Quota::per_minute(
        NonZeroU32::new(requests_per_minute)
            .expect("requests_per_minute phải > 0"),
    );
    Arc::new(RateLimiter::keyed(quota))
}

/// Build limiter per-user với quota requests/phút.
pub fn build_user_limiter(requests_per_minute: u32) -> UserRateLimiter {
    let quota = Quota::per_minute(
        NonZeroU32::new(requests_per_minute)
            .expect("requests_per_minute phải > 0"),
    );
    Arc::new(RateLimiter::keyed(quota))
}

Quota types governor support đa dạng đơn vị:

• Quota::per_second(N) — N request/giây.
• Quota::per_minute(N) — N request/phút (lock Shop API).
• Quota::per_hour(N) — N request/giờ.
• Quota::with_period(Duration::from_millis(N)) — custom interval.

Shop API lock Quota::per_minute làm đơn vị mặc định — đủ granular cho web API thông thường, số dễ đọc trong config (60 thay vì 1.0).

RateLimiter::keyed trả về limiter sharing 1 quota cho mỗi key riêng biệt — IP A có 60 quota, IP B có 60 quota khác hoàn toàn, không chia sẻ. Backing state store mặc định là DashMap concurrent in-memory.

Sau B73 (variant Forbidden(String)), AppError có 20 variant. B78 thêm 1 variant mới TooManyRequests { retry_after_seconds: u64 } bump 20 → 21 variant. Field retry_after_seconds chứa thời gian client phải chờ trước khi retry — middleware tính từ limiter response.

// File: crates/shop-common/src/error.rs (snippet — chỉ phần thêm B78)
#[derive(Debug, thiserror::Error)]
pub enum AppError {
    // ... 20 variant cũ B10/B16/B48/B55/B73 ...

    #[error("too many requests, retry after {retry_after_seconds}s")]
    TooManyRequests { retry_after_seconds: u64 },
}

Cập nhật impl IntoResponse for AppError thêm match arm với Retry-After header chuẩn RFC 6585 — client biết chính xác bao nhiêu giây nữa quota refill xong, có thể implement exponential backoff hoặc UI countdown timer:

// File: crates/shop-common/src/error.rs — impl IntoResponse (snippet)
use axum::{
    http::{HeaderValue, StatusCode},
    response::{IntoResponse, Response},
    Json,
};
use serde_json::json;

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        match self {
            // ... 20 arm cũ ...

            AppError::TooManyRequests { retry_after_seconds } => {
                let body = json!({
                    "error": format!("rate limit exceeded, retry after {retry_after_seconds}s"),
                    "code": "TOO_MANY_REQUESTS",
                    "request_id": null,
                    "detail": {
                        "retry_after_seconds": retry_after_seconds,
                    }
                });
                let mut response = (StatusCode::TOO_MANY_REQUESTS, Json(body)).into_response();
                response.headers_mut().insert(
                    "Retry-After",
                    HeaderValue::from_str(&retry_after_seconds.to_string())
                        .unwrap_or(HeaderValue::from_static("60")),
                );
                response
            }
        }
    }
}

Cũng cần update 2 helper exhaustive match status_code() và code() (mỗi cái thêm 1 arm) — compiler bắt thiếu arm sẽ báo lỗi build, không có chuyện quên.

Pattern envelope thống nhất với 20 variant cũ:

• error: human message kèm số giây retry — hiển thị frontend được luôn.
• code: SCREAMING_SNAKE_CASE constant TOO_MANY_REQUESTS — client check programmatic.
• request_id: null placeholder (middleware B39 sẽ enrich từ Extension<RequestId>).
• detail.retry_after_seconds: structured field — client parse JSON lấy số trực tiếp không phải regex header.

Note: B55 từng preview pattern RateLimited map sang ServiceUnavailable 503 — B78 official lock thành 429 với variant riêng (semantic chuẩn HTTP hơn 503 vốn để dành cho maintenance/outage).

Use case: endpoint nhạy cảm như register và login cần limit theo IP — chống brute force credential stuffing (attacker dùng 1 tài khoản test 10 nghìn password lần lượt từ cùng IP).

Extend file middleware/rate_limit.rs thêm middleware function:

// File: crates/shop-api/src/middleware/rate_limit.rs (extend)
use std::net::SocketAddr;

use axum::{
    extract::{ConnectInfo, Request, State},
    middleware::Next,
    response::Response,
};
use shop_common::error::AppError;

pub async fn ip_rate_limit_middleware(
    State(limiter): State<IpRateLimiter>,
    ConnectInfo(addr): ConnectInfo<SocketAddr>,
    req: Request,
    next: Next,
) -> Result<Response, AppError> {
    let ip = addr.ip();

    match limiter.check_key(&ip) {
        Ok(_) => Ok(next.run(req).await),
        Err(negative) => {
            let wait = negative.wait_time_from(governor::clock::Clock::now(&DefaultClock::default()));
            Err(AppError::TooManyRequests {
                retry_after_seconds: wait.as_secs().max(1),
            })
        }
    }
}

3 điểm pattern lock vĩnh viễn:

• ConnectInfo<SocketAddr> — axum extract IP client từ TCP connection. Cần bind app với into_make_service_with_connect_info::<SocketAddr>() thay into_make_service() default, nếu không extract sẽ panic runtime.
• State<IpRateLimiter> — inject limiter qua axum state (Arc bên trong nên clone rẻ). Tách state riêng với AppState chính vì wire qua from_fn_with_state per-route.
• negative.wait_time_from(...) — governor trả Negative outcome khi bucket cạn, tính chính xác thời gian chờ token refill. .max(1) đảm bảo retry-after ≥ 1 giây (tránh client retry ngay trong cùng millisecond).

Wire trong router với specific routes:

// File: crates/shop-api/src/router.rs (snippet — B78 thêm rate_limit per-route)
use axum::{middleware, routing::post, Router};

use crate::middleware::rate_limit::{
    build_ip_limiter, build_user_limiter, ip_rate_limit_middleware,
};

pub fn build_router(state: AppState) -> Router {
    // B78 — limiter per-IP cho auth endpoint (60 req/min đủ legitimate user).
    let ip_limiter = build_ip_limiter(60);

    let auth_routes = Router::new()
        .route("/users/register", post(routes::users::register))
        .route("/auth/login", post(routes::auth::login)) // B112
        .layer(middleware::from_fn_with_state(
            ip_limiter.clone(),
            ip_rate_limit_middleware,
        ));

    // ... wire auth_routes vào /api/v1 nest ...
}

Lock pattern: 60 request/phút mỗi IP cho auth endpoint — đủ legitimate user thao tác (login retry typo password 5-10 lần là cao), block brute force (10K req/phút từ 1 IP).

Bind main app với ConnectInfo để extract chạy được:

// File: crates/shop-api/src/main.rs (snippet — B78 update bind)
let listener = tokio::net::TcpListener::bind(&config.server_bind).await?;
axum::serve(
    listener,
    app.into_make_service_with_connect_info::<SocketAddr>(),
)
.with_graceful_shutdown(shutdown_signal())
.await?;

Use case: endpoint mutation cần auth — POST /orders, POST /cart/checkout — limit theo user_id sau khi B112 wire JWT auth. Per-user fair hơn per-IP (1 IP có thể là office NAT của 100 user legitimate).

Middleware preview B112 (chưa có Extension<CurrentUser> nên placeholder user_id = 1):

// File: crates/shop-api/src/middleware/rate_limit.rs (extend)
pub async fn user_rate_limit_middleware(
    State(limiter): State<UserRateLimiter>,
    // TODO B112: Extension<CurrentUser> sẽ inject user_id từ JWT claims sau auth middleware.
    req: Request,
    next: Next,
) -> Result<Response, AppError> {
    // Placeholder B78 — sau B112 đổi thành: req.extensions().get::<CurrentUser>().map(|u| u.id).unwrap_or(0)
    let user_id = 1i64;

    match limiter.check_key(&user_id) {
        Ok(_) => Ok(next.run(req).await),
        Err(negative) => {
            let wait = negative.wait_time_from(governor::clock::Clock::now(&DefaultClock::default()));
            Err(AppError::TooManyRequests {
                retry_after_seconds: wait.as_secs().max(1),
            })
        }
    }
}

Wire cho /orders và /cart/checkout:

// File: crates/shop-api/src/router.rs (snippet — tiếp B78)
// B78 — limiter per-user cho mutation endpoint (300 req/min = 5 req/s đủ cao).
let user_limiter = build_user_limiter(300);

let order_routes = Router::new()
    .route("/orders", post(routes::orders::create_order))
    .route("/cart/checkout", post(routes::cart::checkout))
    .layer(middleware::from_fn_with_state(
        user_limiter.clone(),
        user_rate_limit_middleware,
    ));

Lock pattern: 300 request/phút mỗi authenticated user cho mutation — đủ cao cho legitimate flow (cart add 10 item liên tục, retry checkout 3 lần), block bot scraping data theo identity user.

Sau B112, replace user_id = 1i64 placeholder:

// Sau B112 (preview):
let user_id = req
    .extensions()
    .get::<CurrentUser>()
    .map(|u| u.id)
    .ok_or(AppError::Unauthenticated)?;

Nếu request đi qua per-user limiter mà chưa authenticate → reject 401 luôn (chain với auth middleware order: auth INNER hơn rate_limit per-user).

governor::RateLimiter dùng DashMap in-memory backing store — nhanh (latency 0ms) nhưng có 3 pitfall production-grade:

• Per-instance state: mỗi instance app có limiter riêng. Deploy 5 replica = quota nhân 5 (300 × 5 = 1500 req/min thực tế cho 1 user). Attacker target multi-instance bypass limit dễ.
• Reset on restart: app restart (deploy mới, crash, OOM kill) reset toàn bộ state limiter. Attacker biết thời điểm deploy → exploit window quota mới.
• Single point of failure: instance fail/network partition = state mất, không recover được.

Solution G15 Redis-backed:

• Redis SETEX + atomic INCR cho counter — cross-instance share state.
• Persistent across restart (AOF/RDB snapshot).
• Industry pattern: crate redis-rate-limit hoặc tự build qua fred client (lock G18 Redis adapter).

Lock decision Shop API:

• Local dev / staging single-instance: governor in-memory OK (B78 wire).
• Production multi-instance: Redis-backed migrate G15 deploy phase.
• Trade-off: governor 0ms latency (in-memory) vs Redis 1-5ms (network round-trip). Cho rate limit, 5ms hoàn toàn chấp nhận được — không phải hot path.

Pattern lock cho migration: design abstraction RateLimiter trait ngay B78 → swap impl runtime ở G15 không phá API:

// Preview G15 — RateLimiter trait abstraction.
#[async_trait::async_trait]
pub trait RateLimiter<K>: Send + Sync {
    async fn check(&self, key: &K) -> Result<(), Duration>;
}

// B78 impl in-memory (governor wrapper):
pub struct InMemoryLimiter<K> { /* Arc<governor::RateLimiter<...>> */ }

// G15 impl Redis-backed:
pub struct RedisLimiter<K> { pool: RedisPool, key_prefix: String }

B78 chưa cần trait này thực tế (impl direct với governor) — lock note để G15 refactor không phá callsite middleware.

Khởi động Shop API local:

cargo run -p shop-api
# > shop-api listening addr=0.0.0.0:3000 environment=Local
# > rate_limit ip_limiter=60req/min user_limiter=300req/min

Test 1 — Per-IP rate limit register (60 req/min, gửi 70):

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -X POST http://localhost:3000/api/v1/users/register \
    -H 'Content-Type: application/json' \
    -d '{"email":"test'$i'@x.com","password":"Pass1234","display_name":"X"}'
done | sort | uniq -c

# Expected output:
#   60 201
#   10 429

Test 2 — Verify 429 response body + Retry-After header:

curl -i -X POST http://localhost:3000/api/v1/users/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"Pass1234","display_name":"X"}'

# Expected sau khi hết quota:
# HTTP/1.1 429 Too Many Requests
# content-type: application/json
# retry-after: 30
#
# {
#   "error": "rate limit exceeded, retry after 30s",
#   "code": "TOO_MANY_REQUESTS",
#   "request_id": null,
#   "detail": { "retry_after_seconds": 30 }
# }

Test 3 — Per-user rate limit (300 req/min, placeholder user_id = 1 chờ B112):

for i in {1..350}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    -X POST http://localhost:3000/api/v1/orders \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: '"$(uuidgen)" \
    -d '{"items":[{"product_id":1,"quantity":1}],"payment_method":{"type":"cod","phone":"+84912345678"}}'
done | sort | uniq -c

# Expected output:
#  300 201
#   50 429

Test 4 — IP khác reset quota:

# Spoof X-Forwarded-For (chỉ test local — production phải validate proxy whitelist):
curl -X POST http://localhost:3000/api/v1/users/register \
  -H 'X-Forwarded-For: 192.168.1.100' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"Pass1234","display_name":"X"}'

# Note: ConnectInfo extract IP TCP layer, KHÔNG đọc X-Forwarded-For
# → spoof header KHÔNG bypass được limiter local test.
# Production behind reverse proxy (nginx, fly.io edge) cần middleware
# trust proxy whitelist + đọc X-Forwarded-For đúng layer (G18 deploy).

Note pitfall X-Forwarded-For production: nếu app đứng sau load balancer/CDN, ConnectInfo trả IP proxy (cùng IP cho mọi user) → rate limit toàn cục thay vì per-user IP. Production phải:

• Validate trusted proxy whitelist — chỉ trust IP proxy đã biết.
• Đọc X-Forwarded-For trong middleware riêng, lấy left-most IP từ proxy đã trust.
• Reject request có header X-Forwarded-For nếu request đến từ IP không trong whitelist (chống spoofing).

Chi tiết wire trusted proxy pattern ở G18 (Deploy & Operations) khi setup load balancer config.

• 4 thuật toán rate limit: fixed window, sliding window, token bucket (chọn), leaky bucket.
• governor crate v0.6 lock — Rust idiomatic token bucket (GCRA), industry standard.
• 2 strategy Shop API: per-IP 60 req/min cho auth + per-user 300 req/min cho mutation.
• IpRateLimiter + UserRateLimiter type alias với keyed state store.
• Quota::per_minute(N) lock đơn vị phút cho mọi rate spec Shop API.
• AppError::TooManyRequests { retry_after_seconds } variant 21 (bump 20 → 21).
• Response 429 + Retry-After header chuẩn RFC 6585 — client biết chính xác lúc nào retry.
• ConnectInfo<SocketAddr> axum extract IP — cần into_make_service_with_connect_info.
• State<IpRateLimiter> inject limiter qua state (Arc clone rẻ).
• In-memory pitfall: per-instance state, reset on restart → multi-instance production cần Redis (G15).
• Pattern abstraction RateLimiter trait preview G15 — swap in-memory ↔ Redis runtime không phá callsite.
• X-Forwarded-For pitfall: production phải validate trusted proxy whitelist (G18 deploy).
• File path lock: NEW middleware/rate_limit.rs; AppError +1 variant; router wire 2 specific endpoint group.
• Stack giờ 7 layer (6 cũ B77 + rate_limit per-route, KHÔNG global).

Tự trả lời, đáp án ở cuối:

1. 4 thuật toán rate limit — pros/cons mỗi cách? Tại sao Shop API chọn token bucket?
2. Per-IP vs per-user — khi nào dùng cái nào? Cho ví dụ scenario register vs order.
3. Retry-After header — pros so với chỉ status 429? Client side handling pattern.
4. In-memory governor pitfall multi-instance — scenario attack exploit? Solution Redis G15.
5. X-Forwarded-For spoofing pitfall — production cần validate gì? Trusted proxy whitelist là gì?

Bài 79: Body Limit Per-Route — Refactor B47 — refactor body limit pattern (B47 4-layer defense), DefaultBodyLimit per-route lock, decompression layer body limit pitfall (B50), middleware composition cho /products/import.ndjson 10MB + /products/upload 100MB.