{"id":30192063,"url":"https://github.com/awesomeapibrasil/gateway","last_synced_at":"2025-08-12T22:10:09.768Z","repository":{"id":306504126,"uuid":"1026418790","full_name":"awesomeapibrasil/gateway","owner":"awesomeapibrasil","description":"WIP: Easy-to-use API Gateway focused on Security, Traffic Management and WAF protection for modern applications.","archived":false,"fork":false,"pushed_at":"2025-08-02T03:16:09.000Z","size":416,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T04:48:38.123Z","etag":null,"topics":["api-gateway","reverse-proxy","security","traffic-management","waf"],"latest_commit_sha":null,"homepage":"","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/awesomeapibrasil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-25T21:21:40.000Z","updated_at":"2025-08-02T02:29:46.000Z","dependencies_parsed_at":"2025-07-26T04:53:34.730Z","dependency_job_id":null,"html_url":"https://github.com/awesomeapibrasil/gateway","commit_stats":null,"previous_names":["awesomeapibrasil/gateway"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/awesomeapibrasil/gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awesomeapibrasil%2Fgateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awesomeapibrasil%2Fgateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awesomeapibrasil%2Fgateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awesomeapibrasil%2Fgateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/awesomeapibrasil","download_url":"https://codeload.github.com/awesomeapibrasil/gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/awesomeapibrasil%2Fgateway/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270143450,"owners_count":24534721,"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-12T02:00:09.011Z","response_time":80,"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","reverse-proxy","security","traffic-management","waf"],"created_at":"2025-08-12T22:10:06.558Z","updated_at":"2025-08-12T22:10:09.736Z","avatar_url":"https://github.com/awesomeapibrasil.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gateway - High Performance API Gateway focused on Security/WAF\n\nGateway is a high-performance API Gateway and Ingress Controller built with Rust, designed for cloud-native environments. It provides comprehensive Web Application Firewall (WAF) capabilities, distributed caching, and enterprise-grade features.\n\n\u003e **⚡ New: Pingora Integration** - Gateway now includes direct integration with Cloudflare's Pingora framework for maximum performance and reliability. See the [Pingora Integration](#-pingora-integration) section for details.\n\n## 🚀 Features\n\n### Core Features\n- **High Performance**: Built with Rust for maximum performance and minimal resource usage\n- **Web Application Firewall (WAF)**: Comprehensive L7 filtering with rate limiting\n- **Distributed Caching**: Production-ready distributed cache with UDP multicast clustering, advanced LRU algorithms, and real-time coherence\n- **Load Balancing**: Multiple algorithms with health checks and circuit breakers\n- **Protocol Support**: HTTP/HTTPS/HTTP2/HTTP3, gRPC, WebSocket\n- **Enterprise Security**: Authentication, authorization, and audit logging\n\n### WAF Capabilities\n- IP-based allow/block lists with CIDR support\n- Header and User-Agent filtering\n- URL pattern matching and malicious content detection\n- Distributed rate limiting with multiple storage backends\n- Complex rule engine similar to OPA\n- Real-time rule updates without restarts\n\n### Distributed Caching System\n- **Advanced Memory Cache Algorithms**: \n  - Segmented LRU Cache with reduced lock contention and memory safety\n  - Approximated LRU Cache with Redis-inspired random sampling (~95% efficiency)\n- **UDP Multicast Clustering**: \n  - Automatic node discovery and cluster formation\n  - Real system monitoring with platform-specific load/memory metrics\n  - Message reliability with checksums, sequence numbers, and acknowledgments\n- **Cache Coherence Strategies**: \n  - Write-through, write-behind, and conflict resolution with vector clocks\n  - Real-time cache invalidation across cluster nodes\n  - Eventual consistency with configurable conflict resolution\n- **Production-Ready Safety**:\n  - Memory safety with comprehensive null pointer checks\n  - Panic prevention with safe fallbacks for all operations\n  - Enhanced error handling with Result-based APIs\n  - Background task resilience and graceful failure handling\n\n### Database Support\n- **Serverless Databases**: Oracle Tables, DynamoDB, Firebase\n- **Traditional Databases**: PostgreSQL, MySQL, MongoDB\n- **Cloud Databases**: TiDB, MongoDB Atlas\n- **Connection Pooling**: Automatic failover and load balancing\n\n### Observability\n- **Metrics**: Prometheus-compatible metrics\n- **Logging**: Structured logging with multiple levels\n- **Tracing**: OpenTelemetry integration\n- **Health Checks**: Comprehensive health monitoring\n\n### Deployment\n- **Docker**: Optimized production-ready images\n- **Kubernetes**: Helm charts for easy deployment\n- **CI/CD**: GitHub Actions pipeline with automated testing\n- **Cloud**: Support for GCP, AWS, Azure\n\n## 📋 Requirements\n\n- **Runtime**: Linux x86_64 or ARM64\n- **Memory**: 512MB minimum, 1GB recommended\n- **CPU**: 1 core minimum, 2+ cores recommended\n- **Storage**: 1GB for logs and cache\n\n### Optional Dependencies\n- **Redis**: For distributed rate limiting and caching\n- **Database**: PostgreSQL, MySQL, or MongoDB for persistence\n- **Kubernetes**: 1.20+ for Helm deployment\n\n## 🔧 Quick Start\n\n### Docker\n```bash\n# Run with default configuration\ndocker run -p 8080:8080 -p 9090:9090 ghcr.io/awesomeapibrasil/gateway:latest\n\n# Run with custom configuration\ndocker run -p 8080:8080 -p 9090:9090 \\\n  -v $(pwd)/config:/app/config \\\n  ghcr.io/awesomeapibrasil/gateway:latest\n```\n\n### Native Binary with Pingora\n```bash\n# Build the gateway with Pingora support\ncargo build --release\n\n# Run basic Pingora example server\ncargo run --bin gateway -- --pingora-example\n\n# Run with standard gateway configuration\ncargo run --bin gateway -- --config config/gateway.yaml\n```\n\n### Kubernetes with Helm\n```bash\n# Add the Helm repository\nhelm repo add gateway https://github.com/awesomeapibrasil/gateway/releases/download/helm-charts\n\n# Install the chart\nhelm install gateway gateway/gateway\n\n# Install with custom values\nhelm install gateway gateway/gateway -f values.yaml\n```\n\n## ⚙️ Configuration\n\nGateway uses YAML configuration files. See the [Configuration Guide](docs/configuration/README.md) for detailed information.\n\n### Basic Configuration\n```yaml\nserver:\n  bind_address: \"0.0.0.0:8080\"\n  worker_threads: 4\n\nwaf:\n  enabled: true\n  rate_limiting:\n    enabled: true\n    requests_per_minute: 1000\n\nupstream:\n  backends:\n    - name: \"backend-1\"\n      address: \"http://localhost:3000\"\n      weight: 1\n```\n\n### Distributed Cache Configuration\n```yaml\ncache:\n  enabled: true\n  \n  # Segmented LRU Cache Configuration\n  segmented_lru:\n    max_size: 10000\n    segments: 16\n    cleanup_frequency: \"5min\"\n    \n  # Approximated LRU Cache Configuration  \n  approximated_lru:\n    max_size: 50000\n    sample_size: 10\n    eviction_batch_size: 5\n    \n  # UDP Multicast Clustering\n  cluster:\n    enabled: true\n    multicast_address: \"239.255.0.1:7648\"\n    node_timeout: \"30s\"\n    heartbeat_interval: \"5s\"\n    \n    # System Monitoring\n    monitoring:\n      load_threshold: 0.8\n      memory_threshold: 0.9\n      \n    # Cache Coherence\n    coherence:\n      strategy: \"write_through\"  # write_through, write_behind\n      conflict_resolution: \"vector_clock\"\n      max_vector_clock_size: 100\n```\n\n### Environment Variables\n- `GATEWAY_CONFIG`: Configuration file path (default: `config/gateway.yaml`)\n- `RUST_LOG`: Log level (default: `info`)\n- `DATABASE_URL`: Database connection string\n- `JWT_SECRET`: JWT signing secret\n- `CACHE_MULTICAST_ADDR`: UDP multicast address for cache clustering (default: `239.255.0.1:7648`)\n- `CACHE_NODE_TIMEOUT`: Cache node timeout duration (default: `30s`)\n- `CACHE_MAX_SIZE`: Maximum cache size per node (default: `10000`)\n\n## 🛡️ Security Features\n\n### WAF Protection\n- **SQL Injection**: Pattern-based detection and blocking\n- **XSS**: Cross-site scripting prevention\n- **CSRF**: Cross-site request forgery protection\n- **Directory Traversal**: Path-based attack prevention\n- **Rate Limiting**: Distributed rate limiting with burst protection\n- **ModSecurity Integration**: OWASP Core Rule Set (CRS) compatible engine\n\n### ModSecurity Integration\n\nGateway includes a native Rust implementation of ModSecurity-compatible rules engine:\n\n- **OWASP TOP 10 Coverage**: Built-in rules covering all OWASP Top 10 vulnerabilities\n- **Dynamic Rule Updates**: Update rules without restarting the gateway\n- **Custom Rules**: Support for custom ModSecurity-style rules\n- **Performance Optimized**: Native Rust implementation for maximum performance\n- **OWASP CRS Compatible**: Supports OWASP Core Rule Set syntax\n\n#### Quick ModSecurity Setup\n\n```yaml\nwaf:\n  enabled: true\n  modsecurity:\n    enabled: true\n    rules_path: \"config/modsecurity/custom\"\n    owasp_crs_path: \"config/modsecurity/owasp-crs\"\n    blocking_mode: true\n    rule_update_interval: 300\n```\n\n```bash\n# Create ModSecurity directory structure\nmkdir -p config/modsecurity/{custom,owasp-crs/rules}\n\n# Start the gateway with ModSecurity protection\ncargo run -- --config config/gateway.yaml\n```\n\n#### Supported Rule Syntax\n\n```\nSecRule VARIABLES \"OPERATOR\" \"ACTIONS\"\n\n# Examples:\nSecRule ARGS \"@detectSQLi\" \"id:100001,msg:'SQL Injection',severity:CRITICAL,block\"\nSecRule REQUEST_URI \"@rx \\.\\./.*\" \"id:100002,msg:'Path Traversal',severity:ERROR,block\"\n```\n\nSee [ModSecurity Configuration Guide](config/modsecurity/README.md) for detailed setup instructions.\n\n### Authentication \u0026 Authorization\n- **JWT**: JSON Web Token support\n- **OAuth2**: OAuth2 integration\n- **LDAP**: LDAP authentication\n- **RBAC**: Role-based access control\n\n### Network Security\n- **TLS**: TLS 1.2+ with configurable cipher suites\n- **mTLS**: Mutual TLS for backend communication\n- **IP Filtering**: CIDR-based IP allow/block lists\n- **Network Policies**: Kubernetes network policy support\n\n## 📊 Monitoring\n\n### Metrics\nGateway exposes Prometheus-compatible metrics on `/metrics`:\n- Request rate and latency\n- Error rates and status codes\n- WAF blocks and rate limits\n- Backend health and response times\n- Cache hit/miss rates and cluster health\n- Distributed cache node statistics and coherence metrics\n- Memory usage and eviction rates per cache algorithm\n\n### Health Checks\n- **Liveness**: `/health` endpoint\n- **Readiness**: Component health status\n- **Startup**: Initialization progress\n\n### Logging\nStructured JSON logging with configurable levels:\n```json\n{\n  \"timestamp\": \"2024-01-15T10:30:00Z\",\n  \"level\": \"INFO\",\n  \"message\": \"Request processed\",\n  \"request_id\": \"req-123\",\n  \"method\": \"GET\",\n  \"uri\": \"/api/users\",\n  \"status\": 200,\n  \"latency_ms\": 45\n}\n```\n\n## 🏗️ Architecture\n\nGateway is built with a modular architecture, now featuring direct integration with Cloudflare's Pingora framework:\n\n```\n┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐\n│   Client        │────│   Gateway       │────│   Backend       │\n│   Requests      │    │   (Rust/Pingora)│    │   Services      │\n└─────────────────┘    └─────────────────┘    └─────────────────┘\n                              │\n                    ┌─────────┼─────────┐\n                    │         │         │\n            ┌───────▼──┐ ┌────▼───┐ ┌───▼────┐\n            │   WAF    │ │Distrib.│ │  Auth  │\n            │ Engine   │ │ Cache  │ │Manager │\n            └──────────┘ └────┬───┘ └────────┘\n                              │\n                        ┌─────▼─────┐\n                        │ UDP       │\n                        │ Multicast │\n                        │ Cluster   │\n                        └───────────┘\n```\n\n### Components\n- **Gateway Core**: Main proxy engine powered by Pingora\n- **WAF Engine**: Web Application Firewall with ModSecurity integration\n- **Distributed Cache Manager**: Multi-algorithm cache system with UDP clustering\n  - Segmented LRU Cache for reduced lock contention\n  - Approximated LRU Cache with Redis-inspired sampling\n  - UDP Multicast clustering for automatic node discovery\n  - Vector clock-based conflict resolution and cache coherence\n- **Auth Manager**: Authentication and authorization\n- **Database Manager**: Database abstraction layer\n- **Monitoring Manager**: Metrics and observability\n- **Plugin Manager**: Extensible plugin system\n- **Pingora Adapter**: Direct integration with Cloudflare's Pingora framework\n- **ModSecurity Engine**: OWASP CRS compatible rule engine\n\n## 🚀 Pingora Integration\n\nGateway now includes direct integration with Cloudflare's Pingora framework for maximum performance and reliability. This integration provides:\n\n- **High-Performance Networking**: Leverage Pingora's optimized network stack\n- **Advanced Load Balancing**: Use Pingora's proven load balancing algorithms\n- **Better Connection Management**: Benefit from Pingora's connection pooling\n- **Production-Grade Reliability**: Built on the same foundation as Cloudflare's edge network\n\n### Running with Pingora\n\n```bash\n# Build with Pingora support\ncargo build --release\n\n# Run the basic Pingora example\ncargo run --bin gateway -- --pingora-example\n\n# Or integrate Pingora in your code\nuse gateway_core::pingora_adapter::PingoraGateway;\n\nlet gateway = PingoraGateway::new(\"MyGateway\")?;\ngateway.run_forever();\n```\n\n### Pingora Integration Status\n\n- [x] **Basic Integration**: Pingora dependency added and basic server setup\n- [x] **Configuration Foundation**: Server configuration structure in place\n- [ ] **HTTP Service Integration**: Connect HTTP handlers with WAF processing\n- [ ] **Proxy Service Integration**: Full proxy implementation with load balancing\n- [ ] **SSL/TLS Integration**: Certificate management and termination\n- [ ] **Monitoring Integration**: Metrics collection and observability hooks\n- [ ] **Configuration Migration**: Integrate with existing gateway configuration system\n\n### ModSecurity Integration Status\n\n- [x] **Core Engine**: Native Rust ModSecurity-compatible rule engine implemented\n- [x] **OWASP TOP 10 Rules**: Built-in rules covering all OWASP Top 10 vulnerabilities\n- [x] **Rule Parsing**: Support for ModSecurity SecRule syntax\n- [x] **Dynamic Updates**: Runtime rule updates without restart\n- [x] **Configuration**: YAML configuration with examples\n- [x] **Documentation**: Comprehensive setup and usage guide\n- [x] **Testing**: Full test suite for rule engine and detection\n- [x] **WAF Integration**: Seamless integration with existing WAF pipeline\n\n## 🗄️ Distributed Cache System\n\nGateway includes a production-ready distributed caching system designed for high-performance, fault-tolerant operation across multiple nodes.\n\n### Key Features\n\n#### Advanced Memory Algorithms\n- **Segmented LRU Cache**: Partitioned cache reducing lock contention by dividing entries across multiple segments\n- **Approximated LRU Cache**: Redis-inspired random sampling approach achieving ~95% of true LRU efficiency with significantly better performance\n\n#### UDP Multicast Clustering\n- **Automatic Node Discovery**: Nodes automatically discover and join clusters via UDP multicast\n- **Real System Monitoring**: Platform-specific monitoring using `/proc/loadavg` and `/proc/meminfo` on Linux with cross-platform fallbacks\n- **Message Reliability**: Comprehensive checksums, sequence numbers, and acknowledgments for reliable communication\n\n#### Cache Coherence Strategies\n- **Write-Through**: Immediate synchronization of cache writes across all cluster nodes\n- **Write-Behind**: Asynchronous write propagation for improved write performance\n- **Vector Clocks**: Conflict resolution using vector clocks for eventual consistency\n- **Real-time Invalidation**: Immediate cache invalidation across cluster nodes\n\n### Production-Ready Safety\n\n```rust\n// Memory-safe operations with comprehensive null checks\nunsafe fn add_to_front(\u0026mut self, node: *mut LRUNode\u003cK, V\u003e) {\n    if node.is_null() || self.head.is_null() {\n        return; // Safe early return prevents crashes\n    }\n    // ... safe operations only when all pointers are valid\n}\n\n// Consistent error handling throughout\nlet timestamp = SystemTime::now()\n    .duration_since(UNIX_EPOCH)\n    .unwrap_or_default(); // Safe fallback prevents panics\n```\n\n### Performance Characteristics\n- **Latency**: 100K+ cache operations per second per node\n- **Memory Efficiency**: Configurable limits with automatic eviction\n- **Network Overhead**: UDP multicast reduces broadcast overhead vs TCP mesh\n- **Scalability**: Linear performance scaling with cluster size\n\n### Quick Setup\n\n```yaml\ncache:\n  enabled: true\n  cluster:\n    enabled: true\n    multicast_address: \"239.255.0.1:7648\"\n    \n  segmented_lru:\n    max_size: 10000\n    segments: 16\n    \n  approximated_lru:\n    max_size: 50000\n    sample_size: 10\n```\n\n```bash\n# Start gateway with distributed caching\ncargo run -- --config config/gateway.yaml\n\n# Monitor cache metrics\ncurl http://localhost:9090/metrics | grep cache_\n```\n\n### Distributed Cache Integration Status\n\n- [x] **Core Algorithms**: Segmented LRU and Approximated LRU implementations\n- [x] **UDP Clustering**: Multicast-based node discovery and communication\n- [x] **Cache Coherence**: Vector clock-based conflict resolution\n- [x] **System Monitoring**: Real-time load and memory monitoring\n- [x] **Safety Enhancements**: Memory safety and panic prevention\n- [x] **Production Testing**: Comprehensive test suite with 26+ unit tests\n- [x] **CI/CD Integration**: Full formatting, linting, and testing pipeline\n- [x] **Documentation**: Complete API documentation and usage examples\n\n## 🔌 Plugin System\n\nGateway supports a flexible plugin system for extending functionality:\n\n```rust\nuse gateway_plugins::{Plugin, PluginResult, RequestContext};\n\n#[derive(Default)]\npub struct CustomPlugin;\n\nimpl Plugin for CustomPlugin {\n    fn name(\u0026self) -\u003e \u0026str {\n        \"custom-plugin\"\n    }\n\n    async fn on_request(\u0026self, ctx: \u0026mut RequestContext) -\u003e PluginResult {\n        // Custom request processing logic\n        Ok(())\n    }\n}\n```\n\n## 📚 Documentation\n\n- [Installation Guide](docs/installation/README.md)\n- [Configuration Reference](docs/configuration/README.md)\n- [Deployment Guide](docs/deployment/README.md)\n- [API Reference](docs/api/README.md)\n- [Plugin Development](docs/plugins/README.md)\n- [Troubleshooting](docs/troubleshooting/README.md)\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n```bash\n# Clone the repository\ngit clone https://github.com/awesomeapibrasil/gateway.git\ncd gateway\n\n# Build the project\ncargo build\n\n# Run tests\ncargo test\n\n# Test Pingora integration\ncargo run --bin gateway -- --pingora-example\n\n# Run the standard gateway\ncargo run -- --config config/gateway.yaml\n```\n\n### Testing\n```bash\n# Unit tests\ncargo test --lib\n\n# Integration tests\ncargo test --test integration\n\n# WAF tests\ncargo test -p gateway-waf\n\n# Distributed cache tests\ncargo test -p gateway-cache\n\n# Performance benchmarks\ncargo bench\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🆘 Support\n\n- **GitHub Issues**: [Report bugs and feature requests](https://github.com/awesomeapibrasil/gateway/issues)\n- **Discussions**: [Community discussions](https://github.com/awesomeapibrasil/gateway/discussions)\n- **Documentation**: [Comprehensive guides and references](docs/)\n\n## 🏆 Acknowledgments\n\n- **Cloudflare**: For the Pingora framework\n- **Rust Community**: For the amazing ecosystem\n- **Contributors**: Everyone who helps improve the project\n\n---\n\nBuilt with ❤️ by AwesomeAPI","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawesomeapibrasil%2Fgateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fawesomeapibrasil%2Fgateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fawesomeapibrasil%2Fgateway/lists"}