License Rust Build Status

A high-performance, cloud-native API gateway built with Rust

PingSIX is a modern API gateway designed for cloud-native environments, offering exceptional performance, flexibility, and reliability. Inspired by industry leaders like Cloudflare Pingora and Apache APISIX, PingSIX leverages Rust's safety and performance characteristics to deliver enterprise-grade reverse proxying and API management capabilities.

• 🚀 High Performance: Built with Rust and Tokio for exceptional throughput and low latency
• 🔄 Dynamic Configuration: Real-time configuration updates via etcd integration
• 🛣️ Advanced Routing: Flexible request matching based on host, path, methods, and priorities
• 🔌 Rich Plugin Ecosystem: 20+ built-in plugins with easy extensibility
• 📊 Observability: Built-in Prometheus metrics and Sentry integration
• 🔒 Security: JWT/API key authentication, IP restrictions, CORS support
• ⚡ Load Balancing: Multiple algorithms with active health checking
• 🌐 SSL/TLS: Dynamic certificate loading with SNI support
• 📝 Admin API: RESTful API compatible with Apache APISIX specification

• User Guide - Comprehensive documentation with examples and best practices
• Configuration Reference - Detailed configuration options
• Plugin Documentation - Complete plugin reference and usage
• Admin API - RESTful API for dynamic configuration
• Examples - Real-world usage scenarios

• Rust 1.70 or later
• (Optional) etcd for dynamic configuration

# Clone the repository
git clone https://github.com/zhu327/pingsix.git
cd pingsix
# Build the project
cargo build --release
# Run with configuration
./target/release/pingsix -c config.yaml

Create a config.yaml file:

pingora:
 version: 1
 threads: 4
pingsix:
 listeners:
 - address: 0.0.0.0:8080
routes:
 - id: "1"
 uri: /
 upstream:
 nodes:
 "httpbin.org:80": 1
 type: roundrobin

Start PingSIX:

./target/release/pingsix -c config.yaml

Test the gateway:

curl http://localhost:8080/get

PingSIX includes 20+ built-in plugins organized by category:

• jwt-auth - JWT token validation with multiple algorithms
• key-auth - API key authentication with rotation support
• basic-auth - HTTP Basic Authentication with constant-time comparison
• csrf - CSRF protection using double-submit cookie pattern
• ip-restriction - IP allowlist/blocklist with CIDR support
• cors - Cross-Origin Resource Sharing with regex patterns

• limit-count - Request rate limiting with flexible keys
• traffic-split - A/B testing and canary deployments with weighted traffic distribution
• proxy-rewrite - Request modification
• response-rewrite - Response headers modification
• redirect - HTTP redirects with regex support
• cache - Response caching with TTL and conditions

• prometheus - Metrics collection and exposition
• file-logger - Structured access logging
• request-id - Request tracing with unique IDs

• gzip / brotli - Response compression
• grpc-web - gRPC-Web protocol support

• echo - Testing and debugging responses
• fault-injection - Chaos engineering with delay and abort injection

📖 For detailed plugin configuration, see the Plugin Documentation

PingSIX is built on a modular architecture with the following key components:

• Core Engine: Built on Cloudflare's Pingora framework for high-performance HTTP handling
• Plugin System: Extensible plugin architecture with 15+ built-in plugins
• Configuration Management: Support for both static YAML and dynamic etcd-based configuration
• Admin API: RESTful API for runtime configuration management
• Observability: Built-in metrics, logging, and error tracking

PingSIX supports both static and dynamic configuration:

pingora:
 version: 1
 threads: 4
pingsix:
 listeners:
 - address: 0.0.0.0:8080
 prometheus:
 address: 0.0.0.0:9091
routes:
 - id: "api-gateway"
 uri: /api/*
 upstream:
 nodes:
 "backend1.example.com:8080": 1
 "backend2.example.com:8080": 1
 type: roundrobin
 plugins:
 limit-count:
 key_type: vars
 key: remote_addr
 time_window: 60
 count: 100

# Create a route via Admin API
curl -X PUT http://127.0.0.1:9181/apisix/admin/routes/1 \
 -H "X-API-KEY: your-api-key" \
 -H "Content-Type: application/json" \
 -d '{
 "uri": "/api/*",
 "upstream": {
 "type": "roundrobin",
 "nodes": {
 "backend1.example.com:8080": 1
 }
 }
 }'

📖 For complete configuration reference, see the Configuration Guide

PingSIX is designed for high performance:

• Zero-copy: Efficient request/response handling with minimal memory allocation
• Async I/O: Built on Tokio for excellent concurrency
• Connection Pooling: Efficient upstream connection management
• Health Checking: Automatic failover for unhealthy backends
• Caching: Built-in response caching with configurable TTL

📊 Benchmarks performed on AWS c5.xlarge instance with 4 vCPUs and 8GB RAM

PingSIX is ideal for:

• API Gateway: Centralized API management and routing
• Reverse Proxy: High-performance load balancing and proxying
• Microservices: Service mesh and inter-service communication
• CDN Edge: Content delivery and caching at the edge
• Security Gateway: Authentication, authorization, and traffic filtering

• GitHub Issues: Report bugs and request features
• Discussions: Community discussions and Q&A
• Documentation: Comprehensive user guide

# Clone the repository
git clone https://github.com/zhu327/pingsix.git
cd pingsix
# Install dependencies
cargo build
# Run tests
cargo test
# Run with development config
cargo run -- -c config.yaml

use async_trait::async_trait;
use crate::plugins::ProxyPlugin;
pub struct MyCustomPlugin {
 config: MyPluginConfig,
}
#[async_trait]
impl ProxyPlugin for MyCustomPlugin {
 fn name(&self) -> &str {
 "my-custom-plugin"
 }
 fn priority(&self) -> i32 {
 1000
 }
 async fn request_filter(
 &self,
 session: &mut Session,
 ctx: &mut ProxyContext,
 ) -> Result<bool> {
 // Custom plugin logic here
 Ok(false)
 }
}

📖 For plugin development guide, see Plugin Development

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes: Follow our coding standards and add tests
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to the branch: git push origin feature/amazing-feature
6. Open a Pull Request

• Follow Rust best practices and idioms
• Add tests for new functionality
• Update documentation for API changes
• Ensure all tests pass: cargo test
• Format code: cargo fmt
• Run clippy: cargo clippy

• Use GitHub Issues for bug reports and feature requests
• Provide detailed reproduction steps for bugs
• Include system information and PingSIX version

PingSIX is built on the shoulders of giants:

• Cloudflare Pingora - High-performance HTTP proxy framework
• Apache APISIX - API gateway design patterns and Admin API compatibility
• Tokio - Asynchronous runtime for Rust
• etcd - Distributed configuration storage

Special thanks to all contributors and the Rust community for making this project possible.