Edge Proxy is an experimental, runtime-configurable edge security gateway written in Go. It combines reverse proxy routing, atomic configuration updates, backend health tracking, rate limiting, and Prometheus observability in a compact codebase intended for research, learning, and open-source collaboration.
The long-term direction is a security-focused gateway with explainable adaptive load balancing.
The project focuses on two areas that are useful to explore together:
- runtime security policies that can be updated without restarting the proxy;
- adaptive traffic distribution driven by measured backend behavior.
The current runtime publishes validated configuration snapshots atomically. Requests either use the previous complete state or the next complete state, without observing a partially applied update.
- Host-based and path-based reverse proxy routing.
- Optional path-prefix stripping.
- Least-connections load balancing.
- Active backend health checks and runtime backend status tracking.
- Authenticated HTTP admin API backed by an authenticated gRPC control plane.
- Atomic runtime configuration updates.
- Per-virtual-host rate limiting.
- Trusted-proxy-aware client IP resolution.
- Request IDs and forwarded request metadata.
- One retry on an alternate backend for retryable requests.
- Prometheus metrics and a provisioned Grafana dashboard.
- Docker Compose development environment with two mock backends.
The next development milestones focus on:
- adaptive load balancing based on latency EWMA, error rate, active connections, backend health, and recovery behavior;
- per-virtual-host IP allowlists and denylists;
- configurable request size, URL, and header limits;
- structured security decision logs;
- JWT/OIDC authentication and authorization;
- Coraza and OWASP Core Rule Set integration;
- configuration schema versioning, JSON validation, and optional YAML support.
See CONTRIBUTING.md for ways to participate.
flowchart LR
Client["Client"] --> Proxy["Reverse proxy"]
Admin["Admin HTTP API"] --> GRPC["Authenticated gRPC control plane"]
GRPC --> Runtime["Atomic runtime state"]
Runtime --> Proxy
Proxy --> LB["Load balancer"]
LB --> A["Backend A"]
LB --> B["Backend B"]
Health["Health checker"] --> A
Health --> B
Proxy --> Metrics["Prometheus metrics"]
Metrics --> Grafana["Grafana"]
cmd/
admin-api/ HTTP API for runtime configuration
mock-backend/ Demo backend used by Docker Compose
reverse-proxy/ Main proxy process
internal/
admin/ HTTP handlers and gRPC control plane
api/ Protocol Buffers definition and generated Go code
config/ Loading, validation, persistence, and snapshots
health/ Backend health checking
lb/ Load-balancing strategies
metrics/ Runtime and Prometheus metrics
middleware/ Request middleware and client IP resolution
proxy/ Proxy runtime, orchestration, and handlers
Requirements:
- Go 1.25 or newer, matching
go.mod; - Docker and Docker Compose for the complete local stack.
Create a local environment file:
cp .env.example .envReplace the example secrets in .env, then start the stack:
docker compose up --buildThe stack exposes:
| Service | Address |
|---|---|
| Reverse proxy | http://localhost:8080 |
| Admin API | http://localhost:8081 |
| Prometheus | http://localhost:9090 |
| Grafana | http://localhost:3000 |
Send a request through the configured virtual host:
curl -H "Host: app.example.local" http://localhost:8080/Backends may remain unavailable briefly until the first health check succeeds.
The default configuration is stored in configs/config.json. Additional
examples are available in configs/examples/.
Values prefixed with env: are resolved from environment variables:
{
"url": "env:BACKEND1_URL",
"weight": 1,
"enabled": true
}Important fields:
| Field | Purpose |
|---|---|
server.proxy_port |
Public proxy HTTP port |
server.admin_grpc_port |
Internal admin gRPC port |
load_balancing.strategy |
Load-balancing strategy; currently least-connections |
backends |
Upstream backend definitions with stable id values |
virtual_hosts |
Host-based routing policies using backend_ids |
path_routes |
Optional path-specific backend selection |
health_check |
Health-check interval, timeout, path, and status codes |
timeouts |
Outbound HTTP transport timeouts |
logging |
Log level and asynchronous logging settings |
security.policies |
Reusable security policies referenced by security_policy_id |
Runtime changes made through the admin API are persisted to the configured JSON file. Mount that file as a volume when configuration must survive container replacement.
Authentication is enabled by default. Configure separate HTTP and gRPC tokens:
ADMIN_AUTH_ENABLED=true
ADMIN_API_TOKEN=replace-with-a-random-value
ADMIN_GRPC_TOKEN=replace-with-another-random-valueSet ADMIN_AUTH_ENABLED=false only in an isolated local environment. The gRPC
token is always required, and the unencrypted gRPC transport must remain on a
trusted private network.
Main routes:
GET|POST /api/backend
GET|PUT|DELETE /api/backend/{id}
GET|POST /api/vhost
GET|PUT|DELETE /api/vhost/{domain}
GET|PUT /api/vhost/{domain}/security
GET /api/security/policies
PUT /api/security/policies/{id}
GET|PUT /api/config/server
GET|PUT /api/config/lb
Example:
curl http://localhost:8081/api/backend \
-H "Authorization: Bearer $ADMIN_API_TOKEN"Prometheus scrapes the internal operational endpoint:
http://reverse-proxy:9091/metrics/prometheus
The public proxy port exposes only a minimal /health response. Detailed
operational endpoints are kept on the internal OPS_ADDR.
When another proxy is placed in front of Edge Proxy, configure
TRUSTED_PROXY_CIDRS with only its network ranges. Forwarded client IP headers
from other peers are ignored.
Run the complete quality suite:
gofmt -l .
go vet ./...
go test ./...
go test -race ./...Run the proxy outside Docker:
go run ./cmd/reverse-proxyEdge Proxy is pre-alpha. It is suitable for local experiments, education, benchmarking, and collaborative development. It has not completed a security audit and should not be presented as a production-ready security boundary.
The project originated from an engineering thesis. The current repository is a substantial refactor with a consolidated Go module, immutable configuration snapshots, atomic runtime publication, a backend state registry, and a hardened control plane. Historical adaptive load-balancing experiments will be reproduced against this architecture.
- Read CONTRIBUTING.md before opening a pull request.
- Use GitHub Issues for bugs and feature proposals.
- Report vulnerabilities according to SECURITY.md, not through a public issue.
Edge Proxy is available under the MIT License.