pingap

Pingap is a high-performance reverse proxy driven by the Cloudflare Pingora framework. It is built with Rust to ensure memory safety and top-tier performance. It supports HTTP/1.1, HTTP/2, and gRPC-web proxying.

Key capabilities include:

• Dynamic Configuration: Zero-downtime hot updates via TOML files or etcd.
• Extensibility: A powerful plugin system for authentication (JWT, Key Auth), security (CSRF, IP/Referer/UA limits), traffic control (rate limiting, caching), and content modification.
• Observability: Native Prometheus metrics (pull/push), OpenTelemetry integration for distributed tracing, and highly customizable access logs.
• Service Discovery: Built-in support for static lists, DNS, or Docker tags.
• Automated HTTPS: Let's Encrypt integration supporting HTTP-01 and DNS-01 challenges.

The Pingap Location Module provides an intelligent request routing system for reverse proxies and API gateways. It supports routing based on hostnames and URL paths with the following capabilities:

• Dynamic Host Matching: Supports exact matches, wildcard/suffix matches (e.g., *.example.com), and regex matches with named captures.
• Flexible Path Matching: Supports exact matches (=), regex matches (~), and prefix matches (default).
• URL Rewriting: Modify request paths using variables from named captures.
• Request Control: Implement request throttling (concurrency limits) and body size limiting.
• Header Modification: Add or set custom HTTP headers before forwarding to upstream services.
• gRPC-Web Support: Translates gRPC-Web requests to standard gRPC.
• Extensible Plugins: Attach custom logic via a plugin system.

When using the basic_auth plugin, keep the following security and performance considerations in mind:

• Use TLS: Basic authentication sends the password encoded in Base64, not encrypted. Only use this plugin over a TLS connection.
• Delay Performance: The delay option blocks the request task for its duration. On busy listeners, keep this value well under one second, or combine a short delay with the limit plugin instead.
• Credential Privacy: Setting hide_credentials = true is recommended if the upstream server does not need the credentials. This prevents the Authorization header from appearing in upstream logs.

Issued certificates are written back through the configuration storage used by Pingap. The behavior depends on your storage backend:

• etcd: Every instance sharing the backend picks up the new certificate automatically. Only one instance needs to perform the ordering process.
• file: The certificate is saved directly in the configuration directory.
• Quick Start: Certificates are persisted to ~/.pingap/acme/<domains>.toml (owner-readable only) and restored upon restart.

Warning on Rate Limits: Let's Encrypt allows only 5 duplicate certificates per week for the same set of domains. Avoid deleting persisted certificates during restarts or deployments, and be cautious with ephemeral containers that do not persist their configuration directory, as crash loops can quickly exhaust your weekly quota.

Location

The Location is the central struct that encapsulates a complete set of routing rules. It is initialized from a LocationConf and contains the logic to determine if a request matches and how to handle it.

LocationHostIndex and ServerLocationRoute

To optimize performance, Pingap builds a LocationHostIndex when server locations are loaded. For any given request host, the index returns a weight-ordered list of candidates including:

• Exact host matches
• Matching suffixes
• All regex-host locations
• "Any host" locations

This allows the system to skip unrelated hosts and only run full path/condition matching on relevant candidates, ensuring high performance even with diverse hostnames.

The directory plugin allows Pingap to serve static files from a local directory. It includes features like MIME detection, ETag support, Cache-Control headers, HTTP range requests (for partial content), chunked streaming for large files, and an optional HTML directory index.

To use it, register a plugin with category = "directory" and specify a path (the root directory). You can then assign this plugin to specific locations in your configuration.

[plugins.web]
category = "directory"
path = "/var/www/app"
index = "index.html"
chunk_size = "64kb"
max_age = "1h"
charset = "utf-8"
headers = ["X-Content-Type-Options: nosniff"]

[locations.web]
path = "/"
plugins = ["web"]

Pingap supports the HTTP-01 challenge for ACME certificate issuance. The process works as follows:

1. Listening: The service listens for incoming HTTP requests on port 80 specifically targeting the ACME challenge path.
2. Token Retrieval: When a challenge request is received, the service attempts to retrieve the required validation token from a local file (which was previously saved during the authorization step).
3. Validation:
   • If the token is found in the file, the challenge is successful.
   • If the token is not found, the validation fails.

Health checks are configured using a URL-like string where the schema determines the protocol used:

• tcp://<host>: Performs a TCP health check.
• http://<host>/<path>: Performs an HTTP health check.
• https://<host>/<path>: Performs an HTTPS health check.
• grpc://<host>: Performs a gRPC health check.