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