Documentation
¶
Overview ¶
Package proxy is a strangler-fig bridge: it reverse-proxies routes to a legacy upstream (e.g. a Django app being migrated to nexus) AND registers each proxied route on the nexus dashboard, tagged as a proxy. The dashboard then becomes a live migration board — every enumerated route shows whether it's still forwarded to the legacy app or already served by a native nexus handler, and the "Proxied" cluster shrinks toward zero as you migrate.
The key move is auto-yield: at boot, for each configured Route, if a native nexus endpoint already exists at that method+path, the proxy skips it. So migrating a route is purely additive — add the native nexus.AsRest handler, rebuild, and on next boot it wins the path, the proxy drops it, and the dashboard moves that node out of the "Proxied" cluster into its real service. You never edit the proxy config to migrate; the route list stays as the full inventory and the board updates itself.
proxy.Module(proxy.Config{
Upstream: "http://localhost:8000", // the legacy app
Group: "Proxied · Django",
Routes: []proxy.Route{
{Method: "GET", Path: "/api/candidate-placement-details/"},
{Method: "POST", Path: "/api/ussd-request/"},
},
Fallback: &proxy.Fallback{Prefix: "/"}, // one node for the long tail
})
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Command ¶
type Command struct {
Dev []string // argv for dev (NEXUS_DEV=1). Empty → not launched in dev.
Prod []string // argv for prod. Empty → not launched (externally managed).
Dir string // working directory for the child
Env []string // extra env vars, appended to os.Environ()
Name string // log-line prefix + dashboard label; default "upstream"
// StopGrace is how long to wait after an interrupt signal before the child
// is force-killed on shutdown. Default 5s.
StopGrace time.Duration
// Ready optionally gates boot on the upstream answering. Off when zero.
Ready Ready
}
Command describes how to launch and supervise the upstream process (e.g. the legacy Django app) alongside nexus, with distinct dev/prod invocations. Under `nexus dev` (NEXUS_DEV=1) the Dev argv runs; a production binary runs Prod. Either may be empty to mean "don't launch it in this mode" — leave Prod empty when the legacy app is managed by systemd/k8s in production and only sidecar it during development.
proxy.Module(proxy.Config{
Upstream: "http://127.0.0.1:8000",
Command: &proxy.Command{
Dev: []string{"python", "manage.py", "runserver", "127.0.0.1:8000"},
Prod: nil, // managed externally in prod
Dir: "../legacy",
Name: "django",
Ready: proxy.Ready{Path: "/healthz"},
},
Routes: []proxy.Route{ ... },
})
type Config ¶
type Config struct {
// Upstream is the absolute base URL of the legacy app (scheme://host).
Upstream string
// Command, when set, launches and supervises the upstream process
// alongside nexus — Dev argv under `nexus dev`, Prod argv for a production
// binary (either may be empty to mean "externally managed in this mode").
// So one `nexus dev` boots both nexus and the legacy app. Optional.
Command *Command
// Routes is the enumerated, dashboard-visible migration inventory. Each
// flips from "proxied" to "migrated" once a native handler exists at its
// method+path.
Routes []Route
// Fallback, when set, forwards everything else under its prefix as one
// catch-all node. Optional.
Fallback *Fallback
// Group names the dashboard module the proxied routes cluster under (the
// architecture graph draws it as one shrinking box). Default "Proxied".
Group string
// Icon is the lucide-style icon for the proxied nodes. Default
// "arrow-left-right".
Icon string
// SetHeaders adds/overrides request headers sent upstream. Inbound headers
// (Authorization, Cookie, CSRF) already forward unchanged — this is for
// extras (e.g. an internal shared-secret header). Optional.
SetHeaders map[string]string
// RewritePath rewrites the request path before forwarding (e.g. strip a
// prefix the upstream doesn't expect). Optional; identity when nil.
RewritePath func(string) string
// UpstreamHost sends the upstream's own host as the Host header instead of
// the inbound one, and rewrites upstream-origin redirects and cookie
// domains back to the proxy. Set it when the upstream is name-based
// virtual hosting (a PHP site on shared hosting, cPanel/ISPConfig, behind a
// CDN) — without it the upstream's web server picks the wrong site.
UpstreamHost bool
// Transport overrides the HTTP transport used to reach the upstream (custom
// timeouts, TLS, connection pool). Optional; http.DefaultTransport when nil.
Transport http.RoundTripper
}
Config drives proxy.Module. Upstream is required; the rest have defaults.
type Fallback ¶
type Fallback struct {
Prefix string // default "/"
Name string // dashboard label; default "catch-all → upstream"
}
Fallback mounts a single catch-all that forwards everything under Prefix not matched by a native or enumerated route — one dashboard node for the long tail of legacy routes you never intend to enumerate (admin, template pages). Specific routes always win over this wildcard.
type Ready ¶
type Ready struct {
Path string // GET <upstream><Path>; ANY HTTP response counts as up
Timeout time.Duration // default 30s
}
Ready blocks boot until the upstream answers, so nexus doesn't start forwarding to a process that isn't listening yet. Best-effort: a timeout logs a warning and continues — it never aborts boot.
type Route ¶
type Route struct {
Method string
Path string
Name string // optional dashboard label; defaults to "<METHOD> <path>"
}
Route is one legacy path forwarded to the upstream and shown on the dashboard. Method is a REST verb; empty (or "*") forwards every standard method (mounted as Any). Path uses nexus route syntax (":id", "*rest") and should match the eventual native handler's path exactly, so the auto-yield recognizes the migration.