{"id":30412984,"url":"https://github.com/lazureykis/throttlecrab","last_synced_at":"2025-08-22T02:13:36.601Z","repository":{"id":307585682,"uuid":"1028547611","full_name":"lazureykis/throttlecrab","owner":"lazureykis","description":"High-performance GCRA rate limiter for Rust. Multi-protocol server (HTTP, gRPC, Redis/RESP) with advanced metrics, or embed as a minimal library. Self-tuning memory management 🦀","archived":false,"fork":false,"pushed_at":"2025-08-18T16:35:24.000Z","size":512,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-18T18:12:29.634Z","etag":null,"topics":["api-gateway","api-protection","cloudnative","cloudnative-services","ddos-protection","docker","gcra","grpc","microservices","rate-limit","rate-limiter","rate-limiting","rate-limits","ratelimit","ratelimiter","ratelimiting","redis","rust","security","throttling"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/throttlecrab-server","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lazureykis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T17:34:12.000Z","updated_at":"2025-08-18T16:35:27.000Z","dependencies_parsed_at":"2025-08-01T03:15:38.766Z","dependency_job_id":"dd7a3ff6-ace7-495a-8ccb-4f2f183b1ff2","html_url":"https://github.com/lazureykis/throttlecrab","commit_stats":null,"previous_names":["lazureykis/throttlecrab"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/lazureykis/throttlecrab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazureykis%2Fthrottlecrab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazureykis%2Fthrottlecrab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazureykis%2Fthrottlecrab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazureykis%2Fthrottlecrab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lazureykis","download_url":"https://codeload.github.com/lazureykis/throttlecrab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lazureykis%2Fthrottlecrab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271574431,"owners_count":24783319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","api-protection","cloudnative","cloudnative-services","ddos-protection","docker","gcra","grpc","microservices","rate-limit","rate-limiter","rate-limiting","rate-limits","ratelimit","ratelimiter","ratelimiting","redis","rust","security","throttling"],"created_at":"2025-08-22T02:13:36.142Z","updated_at":"2025-08-22T02:13:36.588Z","avatar_url":"https://github.com/lazureykis.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ThrottleCrab 🦀\n\n[![CI](https://github.com/lazureykis/throttlecrab/actions/workflows/ci.yml/badge.svg)](https://github.com/lazureykis/throttlecrab/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/throttlecrab.svg)](https://crates.io/crates/throttlecrab)\n[![Docker](https://img.shields.io/docker/v/lazureykis/throttlecrab?label=docker)](https://hub.docker.com/r/lazureykis/throttlecrab)\n[![Documentation](https://docs.rs/throttlecrab/badge.svg)](https://docs.rs/throttlecrab)\n[![License](https://img.shields.io/crates/l/throttlecrab.svg)](LICENSE)\n\nHigh-performance rate limiting for any application. Choose between an embedded Rust library or a standalone server supporting HTTP, gRPC, and Redis protocols.\n\n## Choose Your Path\n\n### 🚀 Need rate limiting in 30 seconds?\n\n```bash\n# Install and run the server\ncargo install throttlecrab-server\nthrottlecrab-server --http --http-port 8080\n\n# Test it with curl\ncurl -X POST http://localhost:8080/throttle \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"key\": \"test\", \"max_burst\": 3, \"count_per_period\": 10, \"period\": 60}'\n```\n\n### 📦 Building a Rust application?\n\n```toml\n[dependencies]\nthrottlecrab = \"0.4\"\n```\n\n```rust\nuse throttlecrab::{RateLimiter, AdaptiveStore};\nuse std::time::SystemTime;\n\nlet mut limiter = RateLimiter::new(AdaptiveStore::new());\nlet (allowed, result) = limiter\n    .rate_limit(\"user:123\", 10, 100, 60, 1, SystemTime::now())\n    .unwrap();\n\nif allowed {\n    println!(\"✅ Request allowed! {} remaining\", result.remaining);\n} else {\n    println!(\"❌ Rate limited! Retry in {}s\", result.retry_after);\n}\n```\n\n### 🐳 Want to use Docker?\n\n```bash\ndocker run -d -p 8080:8080 lazureykis/throttlecrab:latest\n```\n\n## What is ThrottleCrab?\n\nThrottleCrab implements the **Generic Cell Rate Algorithm (GCRA)** for smooth, precise rate limiting without sudden bursts or unfair rejections. It's available as:\n\n- **`throttlecrab`** - Embedded Rust library for in-process rate limiting\n- **`throttlecrab-server`** - Standalone server supporting HTTP, gRPC, and Redis protocols\n\n## Quick Examples\n\n### HTTP API (Any Language)\n\n```python\nimport requests\n\n# Check rate limit\nresponse = requests.post('http://localhost:8080/throttle', json={\n    'key': 'user:123',\n    'max_burst': 10,\n    'count_per_period': 100,\n    'period': 60\n})\n\nresult = response.json()\nif result['allowed']:\n    print(f\"✅ Request allowed! {result['remaining']} remaining\")\nelse:\n    print(f\"❌ Rate limited! Retry in {result['retry_after']}s\")\n```\n\n### Redis Protocol (Maximum Performance)\n\n```python\nimport redis\n\nr = redis.Redis(host='localhost', port=6379)\nresult = r.execute_command('THROTTLE', 'user:123', 10, 100, 60)\n# Returns: [allowed (0/1), limit, remaining, reset_after, retry_after]\n```\n\n### JavaScript/Node.js\n\n```javascript\nconst response = await fetch('http://localhost:8080/throttle', {\n    method: 'POST',\n    headers: { 'Content-Type': 'application/json' },\n    body: JSON.stringify({\n        key: 'user:123',\n        max_burst: 10,\n        count_per_period: 100,\n        period: 60\n    })\n});\n\nconst result = await response.json();\nconsole.log(result.allowed ? '✅ Allowed' : '❌ Rate limited');\n```\n\n## Performance\n\n| Protocol | Throughput | P99 Latency | P50 Latency |\n|----------|------------|-------------|-------------|\n| Redis    | 184K req/s | 275 μs      | 170 μs      |\n| HTTP     | 175K req/s | 327 μs      | 176 μs      |\n| gRPC     | 163K req/s | 377 μs      | 188 μs      |\n\nYou can run the same benchmark yourself with `cd integration-tests \u0026\u0026 ./run-transport-test.sh -t all -T 32 -r 10000`\n\n## Server Installation Options\n\n### Binary\n```bash\ncargo install throttlecrab-server\nthrottlecrab-server --http --http-port 8080\n```\n\n### Docker\n```bash\ndocker run -d -p 8080:8080 -p 6379:6379 \\\n  -e THROTTLECRAB_HTTP=true \\\n  -e THROTTLECRAB_REDIS=true \\\n  lazureykis/throttlecrab:latest\n```\n\n### Docker Compose\n```yaml\nversion: '3.8'\nservices:\n  throttlecrab:\n    image: lazureykis/throttlecrab:latest\n    ports:\n      - \"8080:8080\"   # HTTP\n      - \"6379:6379\"   # Redis\n      - \"50051:50051\" # gRPC\n    environment:\n      THROTTLECRAB_LOG_LEVEL: info\n    restart: unless-stopped\n```\n\n### Systemd\n```ini\n[Unit]\nDescription=ThrottleCrab Rate Limiting Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/throttlecrab-server --http --redis\nRestart=always\n\n[Install]\nWantedBy=multi-user.target\n```\n\n## Configuration\n\nAll options can be set via CLI flags or environment variables:\n\n```bash\n# CLI flags\nthrottlecrab-server --http --http-port 8080 --store adaptive\n\n# Environment variables\nexport THROTTLECRAB_HTTP=true\nexport THROTTLECRAB_HTTP_PORT=8080\nexport THROTTLECRAB_STORE=adaptive\nthrottlecrab-server\n```\n\n### Store Types\n\n| Store | Best For | Cleanup Strategy |\n|-------|----------|------------------|\n| `adaptive` | Variable load (default) | Self-tuning |\n| `periodic` | Predictable load | Fixed intervals |\n| `probabilistic` | High throughput | Random sampling |\n\n## Monitoring\n\n- **Health**: `GET /health`\n- **Metrics**: `GET /metrics` (Prometheus format)\n\nKey metrics:\n- `throttlecrab_requests_total` - Total requests\n- `throttlecrab_requests_allowed` - Allowed requests\n- `throttlecrab_requests_denied` - Denied requests\n- `throttlecrab_top_denied_keys` - Top denied keys\n\n## Protocol Reference\n\n### HTTP API\n```bash\nPOST /throttle\n{\n  \"key\": \"string\",           # Unique identifier\n  \"max_burst\": 10,          # Maximum burst capacity\n  \"count_per_period\": 100,  # Allowed requests per period\n  \"period\": 60,             # Period in seconds\n  \"quantity\": 1             # Optional, default 1\n}\n```\n\n### Redis Commands\n```\nTHROTTLE key max_burst count_per_period period [quantity]\nPING\nQUIT\n```\n\n### gRPC\nSee [`throttlecrab-server/proto/throttlecrab.proto`](throttlecrab-server/proto/throttlecrab.proto)\n\n## Advanced Topics\n\n### Key Design\nFor best performance, use short keys:\n- ✅ Good: `u:123`, `ip:1.2.3.4`\n- ❌ Avoid: `user_id:123`, `ip_address:1.2.3.4`\n\n### Memory Usage\nEach entry stores:\n- Key string: varies by length\n- Value: i64 (8 bytes) + Option\u003cSystemTime\u003e (24 bytes) = 32 bytes\n- HashMap overhead: ~32 bytes per entry\n\nTotal per entry: ~64 bytes + key length\n\nWith 1M keys:\n- 10-char keys: ~74 MB\n- 50-char keys: ~114 MB\n- 100-char keys: ~164 MB\n\n### Scaling\n- **Vertical**: Single instance handles 180K+ req/s\n- **Horizontal**: Use client-side sharding by key\n\n## Contributing\n\nContributions welcome! Please feel free to submit a Pull Request.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flazureykis%2Fthrottlecrab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flazureykis%2Fthrottlecrab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flazureykis%2Fthrottlecrab/lists"}