README
¶
prox
A modular reverse proxy with config-driven routing, load balancing, L4/L7 dispatching, hot reload, and plugin middleware.
Documentation · Getting Started · Configuration · Plugins · Deployment
Install
go install github.com/labostack/prox/cmd/prox@latest
Usage
prox serve -config config.json5
Minimal configuration:
{
services: {
web: {
listen: ":8080",
routes: [
{ match: { domain: "api.example.com", path: "/v1/*" }, action: "api" },
{ match: { domain: "*.example.com" }, action: "site" },
],
},
},
actions: {
api: { type: "proxy", upstream: "localhost:3000" },
site: { type: "serve", root: "./public" },
},
}
Features
- JSON5 routing — services, routes, actions, and resources
- Domain wildcards —
*.example.com,cdn-*.** - L4 + L7 — SNI-based TCP pass-through alongside HTTP on the same port
- Load balancing — round-robin, random, least-connections
- Speed limiting — per-route, per-connection, or shared bandwidth caps
- Plugin middleware — auth, response modification, service discovery via Go SDK
- Hot reload — zero-downtime config swap via file watcher or SIGHUP
- Admin API — optional REST API for health checks, reload, and runtime inspection
- WebSocket & HTTP/2 — transparent proxying with h2c upstream support
- TLS — multi-cert SNI with directory-based certificate loading
- Automatic HTTPS — ACME certificates via Let's Encrypt / ZeroSSL with Cloudflare DNS for wildcard support
Performance
~88K req/s — 2.87 ms avg latency (HTTP/1.1, no TLS, single node).
| Proxy | Req/s | Avg | P99 |
|---|---|---|---|
| HAProxy | 90,080 | 2.78 ms | 4.12 ms |
| prox | 88,643 | 2.87 ms | 3.96 ms |
| Nginx | 87,768 | 2.90 ms | 3.74 ms |
| Traefik | 82,737 | 3.08 ms | 5.84 ms |
Details
Apple M4 Pro, 12-core, 24 GB · wrk -t4 -c256 -d10s · Go upstream (200 OK, 2 bytes) · bash bench/run.sh
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
prox
command
prox is a modular reverse proxy with config-driven routing.
|
prox is a modular reverse proxy with config-driven routing. |
|
internal
|
|
|
acme
Package acme manages automatic TLS certificate issuance and renewal.
|
Package acme manages automatic TLS certificate issuance and renewal. |
|
action
Package action implements request handlers (proxy, static, serve, pass, drop).
|
Package action implements request handlers (proxy, static, serve, pass, drop). |
|
admin
Package admin provides an optional HTTP management API for prox.
|
Package admin provides an optional HTTP management API for prox. |
|
balancer
Package balancer implements load balancing strategies for upstream selection.
|
Package balancer implements load balancing strategies for upstream selection. |
|
config
Package config defines the configuration model for prox.
|
Package config defines the configuration model for prox. |
|
dispatcher
Package dispatcher implements L4 TCP dispatching based on TLS SNI.
|
Package dispatcher implements L4 TCP dispatching based on TLS SNI. |
|
logger
Package logger provides colorized console logging and file-based access/error logging.
|
Package logger provides colorized console logging and file-based access/error logging. |
|
plugin
Package plugin implements external plugin process management.
|
Package plugin implements external plugin process management. |
|
resource
Package resource resolves named resources into their content.
|
Package resource resolves named resources into their content. |
|
router
Package router implements first-match HTTP request routing.
|
Package router implements first-match HTTP request routing. |
|
server
Package server manages HTTP/HTTPS listener lifecycle and hot reload.
|
Package server manages HTTP/HTTPS listener lifecycle and hot reload. |
|
throttle
Package throttle implements token-bucket bandwidth limiting for proxy connections.
|
Package throttle implements token-bucket bandwidth limiting for proxy connections. |
|
watcher
Package watcher monitors config files for changes using stat-based polling.
|
Package watcher monitors config files for changes using stat-based polling. |
Click to show internal directories.
Click to hide internal directories.