PingSIX

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.

✨ Features

• 🚀 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

📚 Documentation

• 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

🚀 Quick Start

Prerequisites

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

Installation

# 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

Basic Configuration

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

🔌 Plugin Ecosystem

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

🔐 Authentication & Security

• 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

🚦 Traffic Management

• 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

📊 Observability

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

🗜️ Performance

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

🛠️ Utilities & Testing

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

📖 For detailed plugin configuration, see the Plugin Documentation

🏗️ Architecture

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

🔧 Configuration

PingSIX supports both static and dynamic configuration:

Static Configuration (YAML)

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

Dynamic Configuration (etcd + Admin API)

# 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

🚀 Performance

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

| Metric | Performance | |--------|-------------| | Requests/sec | 100K+ RPS | | Latency (P99) | < 10ms | | Memory Usage | < 50MB | | CPU Usage | < 30% (4 cores) |

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

🌐 Use Cases

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

🤝 Community & Support

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

🛠️ Development

Building from Source

# 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

Creating Custom Plugins

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

📄 License

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

🤝 Contributing

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

Development Guidelines

• 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

Reporting Issues

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

🙏 Acknowledgments

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.

---

<div align="center">

Documentation • Examples • Contributing • License

Made with ❤️ by the PingSIX team

</div>