Skip to content

Welcome

pgway is a proxy gateway for managing HTTP and SOCKS5 upstream proxies through a single, stable entry point. You register proxies from your providers; clients always talk to pgway. When upstream URLs change, the entry point stays the same.

Client → pgway (Gateway) → Upstream Proxy Pool → Target Server

Experimental

pgway is under active development. The core gateway (Control Plane, Data Plane, CLI, HTTP proxying, routing, and load balancing) is working and covered by tests.

The web dashboard and its REST API are not production-ready. Expect breaking changes, incomplete flows, and rough edges. Prefer pgctl and gRPC for real configuration work until the dashboard matures.

Why pgway?

Upstream proxy providers rotate endpoints and credentials often. pgway gives you:

  • One fixed listen address for your apps and scrapers
  • Declarative pools, routers, and load balancers
  • A split between Control Plane (config) and Data Plane (traffic), so you can run all-in-one or distributed agents

What works today

Area Status
HTTP proxy + CONNECT tunneling Ready
SOCKS5 upstream proxies (client entrypoint remains HTTP) Ready
Entrypoint → Flow → (optional Router) → LoadBalancer → Pool → Proxy Ready
Static and dynamic (label-selector) pools Ready
Load balancing: round-robin, weighted, least-bytes Ready
Router rules (host, path, method, header, composites) Ready
Control Plane / Data Plane over gRPC Ready
Agent registration, heartbeat, config Watch / hot reload Ready
CLI (pgctl) for apply / get / delete Ready
Token auth + user management on gRPC Ready
BadgerDB-backed config store Ready
Web dashboard (Nuxt) + REST surface Experimental — not ready
GitHub Releases + multi-arch GHCR (ghcr.io/aknevrnky/pgway) Ready
OpenTelemetry metrics + tracing (OTLP) Ready
Health checks / auto pool recovery Planned
Homebrew install formula Planned (#100)

Binaries

Binary Role
pgway All-in-one: Control Plane + Data Plane
pgway-cp Standalone Control Plane
pgway-dp Standalone Data Plane (agent)
pgctl CLI against the Control Plane

Architecture at a glance

The Control Plane owns configuration (BadgerDB) and exposes gRPC + REST. The Data Plane serves traffic on entrypoints. In single-process mode they share memory; in distributed mode agents register, heartbeat, and receive config updates over gRPC.

flowchart LR
  Client -->|HTTP / CONNECT| EP[Entrypoint]
  Dashboard -->|REST| CP[Control Plane]
  CLI[pgctl] -->|gRPC| CP
  CP -->|gRPC| DP[Data Plane]
  EP --> DP
  CP -->|read / write| DB[(BadgerDB)]
  DP -->|forward| UP[Upstream Proxy Pool]
  UP --> Target[Target Server]

Resources form a pipeline. A minimal valid path is Entrypoint → LoadBalancer → Pool → Proxy. Multiple entrypoints can listen on different ports in the same process.

flowchart LR
  EP[Entrypoint] --> FL[Flow]
  FL -.optional.-> RT[Router]
  FL --> LB[LoadBalancer]
  RT --> LB
  LB --> PL[Pool]
  PL --> PX[Proxy]
  • Entrypoint — required start of the pipeline (host:port listener)
  • Router — optional; matches on host / path / method / header and picks a target balancer
  • LoadBalancer — required; sits in front of exactly one pool
  • Pool — group of proxies (static list or dynamic label selector)
  • Proxy — single upstream proxy (HTTP or SOCKS5)

Roadmap

Work is organized around GitHub milestones. High-level direction:

  1. API foundation — domain/API polish for dashboard consumers (largely done; leftover test updates remain).
  2. CP ↔ DP communication — agent auth, hot reload, and balancers are largely in place. Still open: proxy health, label-based DP placement, mTLS between CP and DP.
  3. Observability — OpenTelemetry metrics and tracing are in; still open: live log streaming, audit / recent activity.
  4. Production readiness — Docker, GoReleaser / GitHub Releases, GHCR, and CI matrix are done. Still open: E2E / load testing, Helm chart, and later packaging such as Homebrew (#100).
  5. Dashboard — dedicated Nuxt admin UI and REST endpoints; explicitly experimental until these issues land. Prefer finishing this before Homebrew and other install channels.

Other near-term product goals (from the main project README): health checks with automatic pool recovery, and proper auth for REST / dashboard.

Smaller open items live as issues on GitHub and will be tackled as capacity allows.

This documentation site

These docs are a separate home for:

The source code and issue tracker remain at github.com/aknEvrnky/pgway.

License

pgway is released under the Apache License 2.0.