ratelimit v0.3.0

Migration Guide

Zentinel now includes comprehensive rate limiting natively. Here’s how to migrate:

Before (Agent)

agent "ratelimit" {
    socket "/var/run/zentinel/ratelimit.sock"
    timeout 100ms

    config {
        default-limit 100
        window-seconds 60
        burst-size 20
        key-type "ip"
    }
}

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

After (Built-in)

rate-limit "api-limit" {
    limit 100
    window 60s
    burst 20
    key client-ip
    action reject
}

route {
    match { path-prefix "/api/" }
    rate-limit "api-limit"
    upstream "backend"
}

Built-in Rate Limiting Features

Zentinel’s native rate limiting offers more capabilities than this agent:

Distributed Rate Limiting

The built-in rate limiter supports distributed backends for multi-instance deployments:

rate-limit "global-api-limit" {
    limit 10000
    window 60s
    key api-key
    action reject

    backend redis {
        url "redis://localhost:6379"
        key-prefix "zentinel:ratelimit:"
    }
}

Multiple Actions

Built-in rate limiting supports multiple actions beyond simple rejection:

rate-limit "login-limit" {
    limit 5
    window 60s
    key client-ip
    action challenge  // Issue CAPTCHA challenge instead of blocking
}

rate-limit "api-throttle" {
    limit 100
    window 1s
    key client-ip
    action delay 100ms  // Slow down instead of rejecting
}

Scope-Aware Limits

Apply rate limits per namespace or service:

namespace "tenant-a" {
    rate-limit "tenant-limit" {
        limit 1000
        window 60s
        key client-ip
    }
}

Documentation

For complete documentation on built-in rate limiting, see:

• Rate Limiting Configuration
• Features: Rate Limiting

Legacy Documentation

The following documentation is preserved for users still migrating from the agent.

Protocol v2 Features

As of v0.2.0, the rate limiter agent supports protocol v2 with:

• Capability negotiation: Reports supported features during handshake
• Health reporting: Exposes health status with load metrics
• Metrics export: Counter and gauge metrics for monitoring
• gRPC transport: Optional high-performance gRPC transport
• Lifecycle hooks: Graceful shutdown and drain handling
• Flow control: Backpressure-aware request handling

Overview

The Rate Limiter agent provides flexible traffic control using the token bucket algorithm. Protect your upstream services from traffic spikes and abuse.

Features

• Token Bucket Algorithm: Industry-standard rate limiting with burst support
• Multiple Key Types: Limit by IP, route, header value, or custom extractors
• Sliding Window: Accurate rate limiting with sliding window counters
• Graceful Handling: Configurable behavior for limit exceeded scenarios

Installation

Using Bundle (Recommended)

The easiest way to install this agent is via the Zentinel bundle command:

# Install just this agent
zentinel bundle install ratelimit

# Or install all available agents
zentinel bundle install --all

The bundle command automatically downloads the correct binary for your platform and places it in ~/.zentinel/agents/.

Using Cargo

cargo install zentinel-agent-ratelimit

Using Docker

docker pull ghcr.io/zentinelproxy/zentinel-agent-ratelimit:latest

CLI Options

Configuration

Add the agent to your Zentinel configuration:

agent "ratelimit" {
    socket "/var/run/zentinel/ratelimit.sock"
    timeout 100ms
    fail-open false

    config {
        default-limit 100
        window-seconds 60
        burst-size 20
        key-type "ip"
    }
}

gRPC Transport (v2)

For higher throughput, use gRPC transport:

agent "ratelimit" {
    grpc "localhost:50051"
    timeout 100ms
    fail-open false
    protocol "v2"

    config {
        default-limit 100
        window-seconds 60
        burst-size 20
        key-type "ip"
    }
}

Configuration Options

Response Headers

When enabled, the agent adds standard rate limit headers: