g3proxy

g3proxy is a high‑performance, fully asynchronous forward proxy written in Rust. It supports HTTP/1.x and SOCKS5 client protocols, while also exposing a minimal TCP/TLS streaming layer that can be used for transparent or reverse proxying. The codebase is heavily modular: the core networking engine lives in g3proxy/core, while protocol handlers, TLS engines, and routing logic are split into independent crates. This separation allows developers to drop in alternative TLS backends (OpenSSL, BoringSSL, AWS‑LC, rustls) or replace the routing algorithm without touching the rest of the stack.

Technical Stack

• Language & Runtime: Rust 1.88+ with async‑std/tokio‑compatible runtime; the project ships a lightweight single‑threaded executor that can be bound to any OS thread.
• TLS: Supports multiple backends via the g3tls crate, including OpenSSL, BoringSSL, AWS‑LC, and rustls. The TLS stack is pluggable at compile time; at runtime the proxy can negotiate MITM or plain TLS based on per‑user configuration.
• Networking: Uses the mio crate for non‑blocking I/O and provides a custom TPROXY implementation that works on Linux kernel ≥ 4.13.
• Configuration: YAML‑based declarative config parsed by serde_yaml. The schema is split into global, per‑user, and per‑site sections, enabling fine‑grained ACLs, rate limits, and egress selection.
• Observability: Exposes Prometheus metrics via an HTTP endpoint; integrates with OpenTelemetry for tracing. All internal events are exposed through a structured log format (tracing crate).

Core Capabilities

• Proxy Chaining: Dynamically selects upstream proxies per request, supporting user‑specific routing tables and a pluggable “egress selection agent” that can query external services (e.g., GeoIP, cost‑based routing).
• TLS MITM & Decryption: Generates per‑user certificates on the fly, dumps decrypted traffic to files or an ICAP server. The MITM engine is fully non‑blocking and can operate in a headless mode for high throughput.
• Protocol Interception: Beyond HTTP, the proxy can intercept IMAP/SMTP streams, exposing hooks for custom security scanners via ICAP.
• Load Balancing & Failover: Implements weighted round‑robin, least‑connections, and custom strategies; can be overridden per user or site. Supports graceful reloads of configuration without dropping connections.
• Authentication & ACL: Provides multiple auth backends (basic, bearer token, custom script) and supports per‑user ACLs at ingress/egress boundaries. Rate limiting is exposed as a pluggable middleware.

Deployment & Infrastructure

g3proxy runs natively on Linux (and macOS for development). It ships with a Dockerfile that builds a minimal Alpine image, exposing only the required ports (HTTP/SOCKS5/TCP). The binary is statically linked against musl, making it suitable for container orchestration platforms like Kubernetes, Docker Swarm, or Nomad. For high‑availability setups, the daemon can be run behind a load balancer (e.g., HAProxy) with sticky sessions, and its graceful reload mechanism allows zero‑downtime upgrades.

Integration & Extensibility

• Plugin System: The proxy exposes a g3proxy::plugin trait that allows third‑party crates to hook into request/response pipelines. Examples include custom logging, dynamic ACL updates, or integration with external policy engines.
• Webhooks & Callbacks: Events such as connection open/close, authentication success/failure, and error conditions can trigger HTTP webhooks defined in the config.
• Custom Egress Agent: Developers can implement a Rust or C library that implements the EgressAgent trait, allowing dynamic selection of upstream proxies based on real‑time metrics or external APIs.

Developer Experience

The project follows a well‑structured documentation workflow: Sphinx generates HTML reference docs per application, while the doc/ folder contains high‑level guides. The API surface is intentionally minimal yet expressive, with clear trait boundaries and type safety guarantees from Rust. Community support is active on GitHub Issues and a dedicated Discord channel, and the codebase has extensive unit tests (coverage > 90%) ensuring reliability.

Use Cases

1. Enterprise‑grade Secure Proxy – Deploy g3proxy as a single point of control for all outbound traffic, leveraging MITM to enforce policy and capture telemetry.
2. Transparent TPROXY for Network Isolation – Use the TCP/TPROXY mode to redirect traffic from a subnet without client configuration.
3. Reverse Proxy for Microservices – Combine the basic HTTP reverse proxy with custom routing logic to expose internal services behind a unified entry point.
4. Dynamic Egress Routing – Implement cost‑based or latency‑aware egress selection via the pluggable agent, useful for multi‑cloud environments.

Advantages Over Alternatives

• Performance: Rust’s async runtime and zero‑copy I/O yield throughput comparable to NGINX/HAProxy while offering richer protocol support out of the box.
• Flexibility: Multi‑backend TLS, pluggable routing, and per‑user configuration make it adaptable to complex policy requirements.
• Licensing: Apache 2.0 ensures no licensing constraints for commercial deployments.
• Extensibility: The plugin API and webhooks lower the barrier to integrate with existing security or monitoring