dug

README

DUG

Distributed Unified Gateway — a small API gateway written in Go from first principles.

DUG sits in front of your HTTP services and handles routing, load balancing, retries, health checks, rate limits, and observability — without wrapping NGINX, Envoy, or Kong.

It started as a way to learn production networking by building it. It is usable today for demos, homelabs, and small deployments. It is not a drop-in replacement for Envoy/Kong at scale.

Client ──▶ DUG (:8080) ──▶ Backend A
                      ├──▶ Backend B
                      └──▶ Backend C

---

Quick start

go install github.com/khareutkarshk/dug/cmd/dug@latest

# scaffold a project
dug init my-gateway
cd my-gateway

# start an upstream (from the dug repo) or point edge.yaml at your own
dug run -config configs/edge.yaml

Verify the install:

dug version
dug validate -config configs/edge.yaml

Docker

docker pull ghcr.io/khareutkarshk/dug:latest
docker run --rm -p 8080:8080 \
  -v "$PWD/configs/edge.yaml:/app/configs/edge.yaml:ro" \
  ghcr.io/khareutkarshk/dug:latest \
  run -config configs/edge.yaml

Prefer binaries? See GitHub Releases.

---

Features

Area	What you get
Proxy & routing	YAML routes, header rewrite, CORS, graceful shutdown, config hot-reload
Load balancing	Smooth weighted round robin, least connections
Reliability	Retries + backoff, timeouts, active /health checks, passive failure tracking
Security	TLS, per-IP rate limit, body size limit, gzip, security headers
Observability	slog JSON logs, request IDs, Prometheus /metrics
Tooling	init, run, validate, doctor, version

Details: docs/features.md · Limits: docs/limitations.md

---

CLI

dug init my-gateway                         # bootstrap configs + compose
dug run -config configs/edge.yaml           # start gateway
dug validate -config configs/edge.yaml      # static checks (CI-friendly: -quiet / -json)
dug doctor -config configs/edge.yaml        # port + upstream probes
dug version                                 # build metadata (-short / -json)

---

Configuration

Minimal:

server:
  port: 8080

routes:
  - path: /
    strategy: least_connections
    upstreams:
      - url: http://localhost:3001
        weight: 1

Production-oriented sample (compression, body limits, security headers):

configs/features.yaml

Full field reference: docs/configuration.md

---

Examples

Runnable scenarios live under examples/:

Example	Demonstrates
basic-reverse-proxy	Single upstream
docker-compose	Dual-backend load balancing
microservices	Path routing (/users, /orders, /payments)
nextjs-api	Browser → DUG → APIs
ai-gateway	/openai & /ollama routes
blue-green	Weighted traffic shift

cd examples/docker-compose
docker compose up --build
curl -s http://localhost:8080/hello

---

Architecture

                     Client
                        │
                 HTTP / HTTPS
                        │
                        ▼
              ┌────────────────────┐
              │        DUG         │
              ├────────────────────┤
              │ Reverse Proxy      │
              │ Router             │
              │ Load Balancer      │
              │ Retry Engine       │
              │ Health Checks      │
              │ Rate Limiter       │
              │ Middleware stack   │
              │ Metrics + Logging  │
              └─────────┬──────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
    Backend A       Backend B       Backend C

Everything under internal/ is built in this repository — no gateway framework underneath.

---

Install options

Method	Command
Go	go install github.com/khareutkarshk/dug/cmd/dug@latest
Source	git clone … && make build
Container	docker pull ghcr.io/khareutkarshk/dug:latest
Release binaries	Releases (linux/darwin/windows)

Tagged releases (v*) publish archives + multi-arch images via GoReleaser. See RELEASE.md.

---

Development

make test
make race
make lint
make benchmark   # optional; writes benchmarks/results.md

Contribution guide: CONTRIBUTING.md
Changelog: CHANGELOG.md

---

Status & roadmap

Stable enough for: learning, demos, homelabs, small services behind a single DUG process.

Not aiming at (yet): distributed config, auth plugins, full Envoy parity, multi-node control planes.

Near term

• Keep docs and examples aligned with the code
• Harden WebSocket behavior beyond basic upgrade proxying
• More operational polish (clearer defaults, richer doctor checks)

Later

• JWT / API keys
• OpenTelemetry
• HTTP/2 & HTTP/3
• Response caching
• Kubernetes / Consul discovery
• Plugin system

---

Why the name?

Dug is the golden retriever from Pixar’s Up — friendly, curious, and somehow always talking about squirrels. Same energy: approachable systems software that still digs into the hard parts of networking.

---

Contributing

Bug reports, docs fixes, and focused PRs are welcome.

1. Fork & branch
2. make test && make lint
3. Open a pull request

Please read CONTRIBUTING.md before larger changes.

---

License

MIT