sentinel-agent-ratelimit

Crates.iosentinel-agent-ratelimit
lib.rssentinel-agent-ratelimit
version0.1.0
created_at2025-12-25 12:32:31.25981+00
updated_at2025-12-25 12:32:31.25981+00
descriptionRate limiting agent for Sentinel reverse proxy - token bucket rate limiting
homepagehttps://sentinel.raskell.io
repositoryhttps://github.com/raskell-io/sentinel-agent-ratelimit
max_upload_size
id2004513
size96,317
Raffael Schneider (raffaelschneider)

documentation

https://sentinel.raskell.io/docs/agents/ratelimit

README

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

Option Environment Variable Description Default
--socket AGENT_SOCKET Unix socket path /tmp/sentinel-ratelimit.sock
--config RATELIMIT_CONFIG Configuration file path -
--default-rps RATELIMIT_DEFAULT_RPS Default requests per second 100
--default-burst RATELIMIT_DEFAULT_BURST Default burst size 10
--log-level RUST_LOG Log level info

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:

Metric Type Description
ratelimit_requests_total Counter Total requests processed
ratelimit_limited_total Counter Total requests rate limited
ratelimit_allowed_total Counter Total requests allowed
ratelimit_bucket_tokens Gauge Current tokens in bucket (by key)

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

Commit count: 0

cargo fmt