prox

Modular reverse proxy with config-driven routing, load balancing, L4/L7 dispatching, hot reload, and plugin middleware.

Documentation · Getting Started · Configuration · Plugins · Deployment

Quick Start

go install github.com/dortanes/prox/cmd/prox@latest

prox serve -config config.json5

Or build from source:

go build -o prox ./cmd/prox

Features

• Config-driven routing — JSON5 config with services, actions, and resources
• Domain matching — segment wildcards (*.example.com, cdn-*.**)
• L4 dispatching — SNI-based TCP pass-through alongside HTTP on the same port
• Load balancing — round-robin, random, least-connections with connection tracking
• Plugin middleware — auth, response modification, L4 gating via Go SDK
• Dynamic targets — plugin-based service discovery with grouped targeting
• Hot reload — zero-downtime config changes with file watcher
• WebSocket — transparent proxy with session pinning
• TLS — multi-cert SNI, directory-based cert loading
• HTTP/2 — full-duplex h2c upstream support

Config

{
  services: {
    web: {
      listen: ":8080",
      routes: [
        { match: { domain: "api.example.com", path: "/v1/*" }, action: "api" },
        { match: { domain: "*.example.com" }, action: "site" },
        { action: { type: "drop" } },
      ],
    },
  },
  actions: {
    api: { type: "proxy", upstream: "localhost:3000", timeout: "5s" },
    site: { type: "serve", root: "./public" },
  },
}

Action	Description
proxy	Reverse proxy with WebSocket, load balancing, custom headers
static	Fixed response with status, headers, template variables
serve	File server — directory or single file (SPA)
pass	L4 TCP pass-through — raw TLS relay
drop	Silently close the connection

Plugins

Extend prox with auth, response modification, and L4 gating via the Go SDK:

p := sdk.New()
p.OnRequest(func(req *sdk.Request) *sdk.Response {
    if req.Header("Authorization") == "" {
        return sdk.Deny(401, "Unauthorized")
    }
    return sdk.Allow()
})
p.Run()

{
  match: { domain: "*.example.com", path: "/api/*" },
  plugins: ["./plugins/auth.go"],
  plugin_timeout: "2s",
  action: { type: "proxy", upstream: "localhost:3000" },
}

Docker

services:
  prox:
    image: ghcr.io/dortanes/prox:latest
    ports:
      - "443:443"
      - "8080:8080"
    volumes:
      - ./config/:/etc/prox/config/
      - ./certs/:/etc/prox/certs/
    command: ["serve", "-config", "/etc/prox/config/"]

License

MIT