sentinel-agent-ratelimit

Token bucket rate limiting agent for Sentinel reverse proxy.

Features

• Token bucket rate limiting algorithm
• Per-client rate limits (by IP, header, or custom key)
• Configurable burst allowance
• Hot-reloadable configuration
• Prometheus metrics export

Installation

From crates.io

cargo install sentinel-agent-ratelimit

From source

git clone https://github.com/raskell-io/sentinel-agent-ratelimit
cd sentinel-agent-ratelimit
cargo build --release

Usage

sentinel-ratelimit-agent --socket /var/run/sentinel/ratelimit.sock

Command Line Options

Configuration

Configuration File (YAML)

# Global defaults
defaults:
  requests_per_second: 100
  burst_size: 10

# Per-route limits
routes:
  "/api/v1/upload":
    requests_per_second: 10
    burst_size: 2
  "/api/v1/search":
    requests_per_second: 50
    burst_size: 5

# Key extraction (what to rate limit by)
key_extraction:
  type: "ip"  # ip, header, or composite
  # header: "X-API-Key"  # if type is header

Sentinel Proxy Configuration

Add to your Sentinel config.kdl:

agents {
    agent "ratelimit" {
        type "custom"
        transport "unix_socket" {
            path "/var/run/sentinel/ratelimit.sock"
        }
        events ["request_headers"]
        timeout-ms 50
        failure-mode "open"
    }
}

routes {
    route "api" {
        matches { path-prefix "/api" }
        upstream "backend"
        agents ["ratelimit"]
    }
}

Metrics

The agent exposes Prometheus metrics on the configured metrics port:

Response Headers

When a request is rate limited, the agent adds these headers:

• X-RateLimit-Limit: Maximum requests per second
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Unix timestamp when the limit resets
• Retry-After: Seconds until the client can retry (on 429)

Development

# Run with debug logging
RUST_LOG=debug cargo run -- --socket /tmp/test.sock

# Run tests
cargo test

# Run benchmarks
cargo bench

License

MIT OR Apache-2.0