throttlecrab_server/lib.rs
1//! # ThrottleCrab Server
2//!
3//! A high-performance, standalone rate limiting service with multiple protocol support.
4//!
5//! ## Purpose
6//!
7//! ThrottleCrab Server solves the problem of distributed rate limiting by providing
8//! a centralized service that multiple applications can use to enforce rate limits.
9//! Instead of implementing rate limiting logic in every service, you can:
10//!
11//! - **Centralize rate limiting logic** in one place
12//! - **Share rate limit state** across multiple services
13//! - **Enforce consistent policies** across your entire infrastructure
14//! - **Scale independently** from your application services
15//!
16//! ## Use Cases
17//!
18//! - **API Gateway Rate Limiting**: Protect backend services from overload
19//! - **Multi-Service Rate Limiting**: Share rate limits across microservices
20//! - **User Action Throttling**: Prevent abuse across multiple endpoints
21//! - **Resource Protection**: Guard expensive operations with global limits
22//!
23//! ## Installation
24//!
25//! ```bash
26//! cargo install throttlecrab-server
27//! ```
28//!
29//! ## Quick Start
30//!
31//! ```bash
32//! # Show all available options
33//! throttlecrab-server --help
34//!
35//! # Start with http transport on port 8080
36//! throttlecrab-server --http --http-port 8080
37//!
38//! # Enable multiple protocols
39//! throttlecrab-server --http --grpc
40//!
41//! # Custom store configuration
42//! throttlecrab-server --http --http-port 8080 --store adaptive --store-capacity 100000 --store-cleanup-interval 60
43//! ```
44//!
45//! ## Configuration
46//!
47//! Configure via CLI arguments or environment variables (CLI takes precedence):
48//!
49//! ```bash
50//! # Via CLI
51//! throttlecrab-server --http --http-port 9090 --store periodic
52//!
53//! # Via environment variables
54//! export THROTTLECRAB_HTTP=true
55//! export THROTTLECRAB_HTTP_PORT=9090
56//! export THROTTLECRAB_STORE=periodic
57//! throttlecrab-server
58//!
59//! # List all available environment variables
60//! throttlecrab-server --list-env-vars
61//! ```
62//!
63//! ### Key Configuration Options
64//!
65//! - **Transports**: Enable with `--http`, `--grpc` (at least one required)
66//! - **Ports**: `--http-port 8080`, `--grpc-port 50051`
67//! - **Store Type**: `--store periodic|probabilistic|adaptive`
68//! - **Store Capacity**: `--store-capacity 100000`
69//! - **Log Level**: `--log-level error|warn|info|debug|trace`
70//!
71//! ## How It Works
72//!
73//! The server uses GCRA (Generic Cell Rate Algorithm) with a token bucket approach:
74//! - Each key gets a bucket with `max_burst` capacity
75//! - Tokens refill at `count_per_period / period` per second
76//! - Requests consume `quantity` tokens (default: 1)
77//! - Denied requests receive `retry_after` and `reset_after` times
78//!
79//! ## Available Protocols
80//!
81//! - **HTTP/JSON**: Easy integration with any programming language
82//! - **gRPC**: Service mesh and microservices integration
83//!
84//! All protocols share the same underlying rate limiter, ensuring consistent
85//! rate limiting across different client types. RPS are provided for comparison
86//! purposes only.
87//!
88//! ## Architecture
89//!
90//! The server uses an actor-based architecture with Tokio for async I/O:
91//!
92//! ```text
93//! ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
94//! │ HTTP │ │ gRPC │ | Other |
95//! │ Transport │ │ Transport │ │ Transport │
96//! └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
97//! │ │ │
98//! └─────────────────┴─────────────────┘
99//! │
100//! ┌─────▼─────┐
101//! │ Actor │
102//! │ (Shared │
103//! │ State) │
104//! └─────┬─────┘
105//! │
106//! ┌─────▼─────┐
107//! │RateLimiter│
108//! │ Store │
109//! └───────────┘
110//! ```
111//!
112//! ## Performance
113//!
114//! Benchmark results on modern hardware:
115//!
116//! | Protocol | Throughput | P99 Latency | P50 Latency |
117//! |----------|------------|-------------|-------------|
118//! | HTTP | 173K req/s | 309 μs | 177 μs |
119//! | gRPC | 163K req/s | 370 μs | 186 μs |
120//!
121//! ## Usage
122//!
123//! ### Starting the Server
124//!
125//! ```bash
126//! # HTTP protocol only
127//! throttlecrab-server --http --http-port 8080
128//!
129//! # All protocols
130//! throttlecrab-server --http --grpc
131//! ```
132//!
133//! ### Client Examples
134//!
135//! #### HTTP Protocol (curl)
136//! ```bash
137//! curl -X POST http://localhost:8080/throttle \
138//! -H "Content-Type: application/json" \
139//! -d '{"key": "user:123", "max_burst": 10, "count_per_period": 100, "period": 60}'
140//! ```
141//!
142//! #### gRPC Protocol
143//! Use any gRPC client library with the provided protobuf definitions.
144
145pub mod actor;
146pub mod config;
147pub mod metrics;
148pub mod store;
149pub mod transport;
150pub mod types;
151
152// Re-export grpc types for tests
153pub mod grpc {
154 pub use crate::transport::grpc::throttlecrab_proto::*;
155}