feat: route paths to non-web processes via proxy:route
Adds proxy:route:set/remove/clear/report so users can declare path-prefix routes to non-web Procfile processes without hand-writing nginx.conf.sigil. Routes are stored on the proxy plugin as a PropertyMap of path to process:port:strip, with set semantics so each invocation produces a fully-determined state and re-application is idempotent. A proxy-supports-routes capability trigger gates the command per backend - nginx-vhosts, traefik-vhosts, caddy-vhosts, and scheduler-k3s render routes today; openresty-vhosts and haproxy-vhosts refuse until their sidecar images learn a path-prefix vocabulary (tracked in dokku/openresty-docker-proxy#137 and the haproxy sidecar). Closes #8725.
This commit is contained in:
29 files changed
+1539
-7
No files matched your search
@@ -1,5 +1,5 @@
|
||||
SUBCOMMANDS = subcommands/build-config subcommands/clear-config subcommands/disable subcommands/enable subcommands/ports subcommands/ports-add subcommands/ports-clear subcommands/ports-remove subcommands/ports-set subcommands/report subcommands/set
|
||||
TRIGGERS = triggers/install triggers/proxy-is-enabled triggers/proxy-type triggers/post-app-clone-setup triggers/post-app-rename-setup triggers/post-delete triggers/report
|
||||
SUBCOMMANDS = subcommands/build-config subcommands/clear-config subcommands/disable subcommands/enable subcommands/ports subcommands/ports-add subcommands/ports-clear subcommands/ports-remove subcommands/ports-set subcommands/report subcommands/route:clear subcommands/route:remove subcommands/route:report subcommands/route:set subcommands/set
|
||||
TRIGGERS = triggers/install triggers/proxy-is-enabled triggers/proxy-routes-list triggers/proxy-type triggers/post-app-clone-setup triggers/post-app-rename-setup triggers/post-delete triggers/report
|
||||
BUILD = commands subcommands triggers
|
||||
PLUGIN_NAME = proxy
|
||||
|
||||
|
||||
@@ -0,0 +1,212 @@
|
||||
package proxy
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"sort"
|
||||
|
||||
"github.com/dokku/dokku/plugins/common"
|
||||
)
|
||||
|
||||
// CommandRouteSet handles `dokku proxy:route:set <app> <process> <path>
|
||||
// [--port <port>] [--strip-prefix]`. Uses set semantics: a given invocation
|
||||
// produces a fully-determined state from its arguments (omitted flags reset
|
||||
// to defaults), and the command is a no-op when the resulting state is
|
||||
// byte-identical to current storage.
|
||||
func CommandRouteSet(appName string, processName string, path string, port int, stripPrefix bool) error {
|
||||
if err := common.VerifyAppName(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if processName == "" || path == "" {
|
||||
return errors.New("Usage: dokku proxy:route:set <app> <process> <path> [--port <port>] [--strip-prefix]")
|
||||
}
|
||||
|
||||
supported, err := SupportsRoutes(appName)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if !supported {
|
||||
proxyType := getComputedProxyType(appName)
|
||||
return fmt.Errorf("path-based routing is not yet supported with the %s proxy backend", proxyType)
|
||||
}
|
||||
|
||||
if port == 0 {
|
||||
port = DefaultRoutePort
|
||||
}
|
||||
|
||||
route := Route{
|
||||
Path: path,
|
||||
Process: processName,
|
||||
Port: port,
|
||||
StripPrefix: stripPrefix,
|
||||
}
|
||||
changed, err := AddRoute(appName, route)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if scale := getProcessScale(appName, processName); scale == 0 {
|
||||
common.LogWarn(fmt.Sprintf(
|
||||
"Process %q is currently scaled to 0; route %s -> %s will resolve to no upstream until the process is scaled up",
|
||||
processName, path, processName,
|
||||
))
|
||||
}
|
||||
|
||||
if !changed {
|
||||
return nil
|
||||
}
|
||||
if err := BuildConfig(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
warnIfRebuildRequired(appName)
|
||||
return nil
|
||||
}
|
||||
|
||||
// CommandRouteRemove handles `dokku proxy:route:remove <app> <path>`.
|
||||
// Removing a path that does not exist is a successful no-op.
|
||||
func CommandRouteRemove(appName string, path string) error {
|
||||
if err := common.VerifyAppName(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
if path == "" {
|
||||
return errors.New("Usage: dokku proxy:route:remove <app> <path>")
|
||||
}
|
||||
|
||||
changed, err := RemoveRoute(appName, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if !changed {
|
||||
return nil
|
||||
}
|
||||
if err := BuildConfig(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
warnIfRebuildRequired(appName)
|
||||
return nil
|
||||
}
|
||||
|
||||
// CommandRouteClear handles `dokku proxy:route:clear <app>`. Clearing an
|
||||
// empty route set is a successful no-op.
|
||||
func CommandRouteClear(appName string) error {
|
||||
if err := common.VerifyAppName(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
changed, err := ClearRoutes(appName)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if !changed {
|
||||
return nil
|
||||
}
|
||||
if err := BuildConfig(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
warnIfRebuildRequired(appName)
|
||||
return nil
|
||||
}
|
||||
|
||||
// warnIfRebuildRequired prints a notice for label-based proxy backends where
|
||||
// the new route state is only fully applied on the next container start (the
|
||||
// labels are baked in at create-time).
|
||||
func warnIfRebuildRequired(appName string) {
|
||||
switch getComputedProxyType(appName) {
|
||||
case "traefik", "caddy":
|
||||
common.LogWarn(fmt.Sprintf(
|
||||
"Routes are applied via container labels under the %s proxy backend; run `dokku ps:rebuild %s` to recreate containers and pick up the change",
|
||||
getComputedProxyType(appName), appName,
|
||||
))
|
||||
}
|
||||
}
|
||||
|
||||
// CommandRouteReport handles `dokku proxy:route:report [<app>] [--format
|
||||
// stdout|json]`. With no app, iterates every dokku app.
|
||||
func CommandRouteReport(appName string, format string) error {
|
||||
if appName == "" {
|
||||
apps, err := common.DokkuApps()
|
||||
if err != nil {
|
||||
if errors.Is(err, common.NoAppsExist) {
|
||||
common.LogWarn(err.Error())
|
||||
return nil
|
||||
}
|
||||
return err
|
||||
}
|
||||
for _, name := range apps {
|
||||
if err := reportRoutesSingleApp(name, format); err != nil {
|
||||
return err
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
if err := common.VerifyAppName(appName); err != nil {
|
||||
return err
|
||||
}
|
||||
return reportRoutesSingleApp(appName, format)
|
||||
}
|
||||
|
||||
type routeReport struct {
|
||||
Path string `json:"path"`
|
||||
Process string `json:"process"`
|
||||
Port int `json:"port"`
|
||||
StripPrefix bool `json:"strip_prefix"`
|
||||
}
|
||||
|
||||
type routeAppReport struct {
|
||||
App string `json:"app"`
|
||||
Routes []routeReport `json:"routes"`
|
||||
}
|
||||
|
||||
func reportRoutesSingleApp(appName string, format string) error {
|
||||
routes, err := GetRoutes(appName)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
if format == "json" {
|
||||
report := routeAppReport{App: appName, Routes: make([]routeReport, 0, len(routes))}
|
||||
for _, r := range routes {
|
||||
report.Routes = append(report.Routes, routeReport{
|
||||
Path: r.Path,
|
||||
Process: r.Process,
|
||||
Port: r.Port,
|
||||
StripPrefix: r.StripPrefix,
|
||||
})
|
||||
}
|
||||
b, err := json.MarshalIndent(report, "", " ")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fmt.Println(string(b))
|
||||
return nil
|
||||
}
|
||||
|
||||
common.LogInfo2Quiet(appName + " proxy routes information")
|
||||
if len(routes) == 0 {
|
||||
common.LogVerbose("Routes: (none)")
|
||||
return nil
|
||||
}
|
||||
|
||||
keys := make([]string, 0, len(routes))
|
||||
for _, r := range routes {
|
||||
keys = append(keys, r.Path)
|
||||
}
|
||||
sort.Strings(keys)
|
||||
for _, key := range keys {
|
||||
for _, r := range routes {
|
||||
if r.Path != key {
|
||||
continue
|
||||
}
|
||||
strip := ""
|
||||
if r.StripPrefix {
|
||||
strip = " (strip)"
|
||||
}
|
||||
common.LogVerbose(fmt.Sprintf("Route %s -> %s:%d%s", r.Path, r.Process, r.Port, strip))
|
||||
break
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -0,0 +1,257 @@
|
||||
package proxy
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
|
||||
"github.com/dokku/dokku/plugins/common"
|
||||
)
|
||||
|
||||
// DefaultRoutePort is the upstream container port assumed when --port is
|
||||
// omitted on proxy:route:set. It matches the existing default container port
|
||||
// for the web process.
|
||||
const DefaultRoutePort = 5000
|
||||
|
||||
// Route describes a single path-prefix routing rule.
|
||||
type Route struct {
|
||||
Path string
|
||||
Process string
|
||||
Port int
|
||||
StripPrefix bool
|
||||
}
|
||||
|
||||
// Encode returns the colon-delimited storage representation:
|
||||
// "<process>:<port>:<strip>" where <strip> is 0 or 1.
|
||||
func (r Route) Encode() string {
|
||||
strip := "0"
|
||||
if r.StripPrefix {
|
||||
strip = "1"
|
||||
}
|
||||
return fmt.Sprintf("%s:%d:%s", r.Process, r.Port, strip)
|
||||
}
|
||||
|
||||
// Slug returns a deterministic kebab-case identifier derived from the route's
|
||||
// path. Used as a stable name fragment for generated labels and CRDs.
|
||||
// Example: "/api/v0" -> "api-v0".
|
||||
func (r Route) Slug() string {
|
||||
s := strings.Trim(r.Path, "/")
|
||||
s = strings.ReplaceAll(s, "/", "-")
|
||||
s = strings.ToLower(s)
|
||||
if s == "" {
|
||||
return "root"
|
||||
}
|
||||
return s
|
||||
}
|
||||
|
||||
// DecodeRoute parses the storage representation into a Route. The third
|
||||
// (strip) field is optional and defaults to 0 (no strip) when absent.
|
||||
func DecodeRoute(path string, value string) (Route, error) {
|
||||
parts := strings.SplitN(value, ":", 3)
|
||||
if len(parts) < 2 {
|
||||
return Route{}, fmt.Errorf("invalid route value %q for path %s", value, path)
|
||||
}
|
||||
port, err := strconv.Atoi(parts[1])
|
||||
if err != nil {
|
||||
return Route{}, fmt.Errorf("invalid port %q for path %s: %v", parts[1], path, err)
|
||||
}
|
||||
strip := false
|
||||
if len(parts) == 3 && parts[2] == "1" {
|
||||
strip = true
|
||||
}
|
||||
return Route{
|
||||
Path: path,
|
||||
Process: parts[0],
|
||||
Port: port,
|
||||
StripPrefix: strip,
|
||||
}, nil
|
||||
}
|
||||
|
||||
var processNameRE = regexp.MustCompile(`^[a-zA-Z0-9_-]+$`)
|
||||
|
||||
// ValidatePath enforces the path constraints documented in the proposal:
|
||||
// - must start with "/"
|
||||
// - cannot be "/" (reserved for web)
|
||||
// - cannot end with "/" (other than root, already rejected above)
|
||||
func ValidatePath(path string) error {
|
||||
if !strings.HasPrefix(path, "/") {
|
||||
return fmt.Errorf("path must start with /")
|
||||
}
|
||||
if path == "/" {
|
||||
return fmt.Errorf("path / is reserved for the web process")
|
||||
}
|
||||
if strings.HasSuffix(path, "/") {
|
||||
return fmt.Errorf("path must not end with /")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ValidateProcess enforces process-name constraints:
|
||||
// - cannot be empty
|
||||
// - cannot be "web" (which is the implicit catch-all)
|
||||
// - must match Procfile name syntax
|
||||
func ValidateProcess(process string) error {
|
||||
if process == "" {
|
||||
return fmt.Errorf("process name is required")
|
||||
}
|
||||
if process == "web" {
|
||||
return fmt.Errorf("web cannot be a route target; web is the implicit catch-all")
|
||||
}
|
||||
if !processNameRE.MatchString(process) {
|
||||
return fmt.Errorf("process name %q contains invalid characters", process)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// ValidatePort ensures the port is in the legal TCP range.
|
||||
func ValidatePort(port int) error {
|
||||
if port < 1 || port > 65535 {
|
||||
return fmt.Errorf("port %d out of range (1-65535)", port)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// GetRoutes returns the route set for an app, sorted by descending path
|
||||
// length (longest-prefix-first), then alphabetically as a tiebreaker.
|
||||
func GetRoutes(appName string) ([]Route, error) {
|
||||
m, err := common.PropertyMapGet("proxy", appName, "routes")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
routes := make([]Route, 0, len(m))
|
||||
for path, value := range m {
|
||||
route, err := DecodeRoute(path, value)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
routes = append(routes, route)
|
||||
}
|
||||
sort.SliceStable(routes, func(i, j int) bool {
|
||||
if len(routes[i].Path) != len(routes[j].Path) {
|
||||
return len(routes[i].Path) > len(routes[j].Path)
|
||||
}
|
||||
return routes[i].Path < routes[j].Path
|
||||
})
|
||||
return routes, nil
|
||||
}
|
||||
|
||||
// GetRoutesByProcess returns the subset of routes targeting a specific
|
||||
// process, preserving the longest-prefix-first ordering.
|
||||
func GetRoutesByProcess(appName string, processName string) ([]Route, error) {
|
||||
all, err := GetRoutes(appName)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
filtered := make([]Route, 0, len(all))
|
||||
for _, route := range all {
|
||||
if route.Process == processName {
|
||||
filtered = append(filtered, route)
|
||||
}
|
||||
}
|
||||
return filtered, nil
|
||||
}
|
||||
|
||||
// RoutedProcessTypes returns the unique process types referenced by any route.
|
||||
func RoutedProcessTypes(appName string) ([]string, error) {
|
||||
routes, err := GetRoutes(appName)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
seen := map[string]bool{}
|
||||
out := []string{}
|
||||
for _, route := range routes {
|
||||
if !seen[route.Process] {
|
||||
seen[route.Process] = true
|
||||
out = append(out, route.Process)
|
||||
}
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// SupportsRoutes returns true if the proxy backend selected for the app
|
||||
// supports path-based routing, as declared by the proxy-supports-routes
|
||||
// trigger. Backends that do not implement the trigger are treated as not
|
||||
// supporting routes (conservative default).
|
||||
func SupportsRoutes(appName string) (bool, error) {
|
||||
result, err := common.CallPlugnTrigger(common.PlugnTriggerInput{
|
||||
Trigger: "proxy-supports-routes",
|
||||
Args: []string{appName},
|
||||
})
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
return result.StdoutContents() == "true", nil
|
||||
}
|
||||
|
||||
// AddRoute upserts a route. Returns whether the stored state changed.
|
||||
func AddRoute(appName string, route Route) (bool, error) {
|
||||
if err := ValidatePath(route.Path); err != nil {
|
||||
return false, err
|
||||
}
|
||||
if err := ValidateProcess(route.Process); err != nil {
|
||||
return false, err
|
||||
}
|
||||
if err := ValidatePort(route.Port); err != nil {
|
||||
return false, err
|
||||
}
|
||||
|
||||
existing, err := common.PropertyMapGet("proxy", appName, "routes")
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
next := route.Encode()
|
||||
if existing[route.Path] == next {
|
||||
return false, nil
|
||||
}
|
||||
return true, common.PropertyMapSet("proxy", appName, "routes", route.Path, next)
|
||||
}
|
||||
|
||||
// RemoveRoute removes a route by path. Returns whether the stored state
|
||||
// changed (false when the path was absent - removal is idempotent).
|
||||
func RemoveRoute(appName string, path string) (bool, error) {
|
||||
existing, err := common.PropertyMapGet("proxy", appName, "routes")
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
if _, ok := existing[path]; !ok {
|
||||
return false, nil
|
||||
}
|
||||
return true, common.PropertyMapDelete("proxy", appName, "routes", path)
|
||||
}
|
||||
|
||||
// ClearRoutes removes every route for an app. Returns whether anything was
|
||||
// removed (false when the route set was already empty).
|
||||
func ClearRoutes(appName string) (bool, error) {
|
||||
existing, err := common.PropertyMapGet("proxy", appName, "routes")
|
||||
if err != nil {
|
||||
return false, err
|
||||
}
|
||||
if len(existing) == 0 {
|
||||
return false, nil
|
||||
}
|
||||
return true, common.PropertyDelete("proxy", appName, "routes")
|
||||
}
|
||||
|
||||
// getProcessScale returns the configured replica count for a process, or 0
|
||||
// when no scale entry exists. The ps plugin stores scale as a property list
|
||||
// of "<proc>=<count>" entries.
|
||||
func getProcessScale(appName string, processName string) int {
|
||||
lines, err := common.PropertyListGet("ps", appName, "scale")
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
prefix := processName + "="
|
||||
for _, line := range lines {
|
||||
if strings.HasPrefix(line, prefix) {
|
||||
n, err := strconv.Atoi(strings.TrimPrefix(line, prefix))
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
return n
|
||||
}
|
||||
}
|
||||
return 0
|
||||
}
|
||||
@@ -23,6 +23,10 @@ Additional commands:`
|
||||
proxy:disable <app>, Disable proxy for app
|
||||
proxy:enable <app>, Enable proxy for app
|
||||
proxy:report [<app>] [<flag>], Displays a proxy report for one or more apps
|
||||
proxy:route:clear <app>, Removes every path-based route for an app
|
||||
proxy:route:remove <app> <path>, Removes a path-based route from an app
|
||||
proxy:route:report [<app>] [--format json], Displays the path-based routes for an app
|
||||
proxy:route:set <app> <process> <path> [--port port] [--strip-prefix], Adds or updates a path-based route to a non-web process
|
||||
proxy:set <app> <proxy-type>, Set proxy type for app`
|
||||
)
|
||||
|
||||
|
||||
@@ -70,6 +70,32 @@ func main() {
|
||||
value = args.Arg(1)
|
||||
}
|
||||
err = proxy.CommandSet(appName, property, value)
|
||||
case "route:set":
|
||||
args := flag.NewFlagSet("proxy:route:set", flag.ExitOnError)
|
||||
port := args.Int("port", proxy.DefaultRoutePort, "--port: container port of the target process")
|
||||
stripPrefix := args.Bool("strip-prefix", false, "--strip-prefix: strip the matched prefix before forwarding")
|
||||
args.Parse(os.Args[2:])
|
||||
appName := args.Arg(0)
|
||||
processName := args.Arg(1)
|
||||
path := args.Arg(2)
|
||||
err = proxy.CommandRouteSet(appName, processName, path, *port, *stripPrefix)
|
||||
case "route:remove":
|
||||
args := flag.NewFlagSet("proxy:route:remove", flag.ExitOnError)
|
||||
args.Parse(os.Args[2:])
|
||||
appName := args.Arg(0)
|
||||
path := args.Arg(1)
|
||||
err = proxy.CommandRouteRemove(appName, path)
|
||||
case "route:clear":
|
||||
args := flag.NewFlagSet("proxy:route:clear", flag.ExitOnError)
|
||||
args.Parse(os.Args[2:])
|
||||
appName := args.Arg(0)
|
||||
err = proxy.CommandRouteClear(appName)
|
||||
case "route:report":
|
||||
args := flag.NewFlagSet("proxy:route:report", flag.ExitOnError)
|
||||
format := args.String("format", "stdout", "format: [ stdout | json ]")
|
||||
args.Parse(os.Args[2:])
|
||||
appName := args.Arg(0)
|
||||
err = proxy.CommandRouteReport(appName, *format)
|
||||
default:
|
||||
err = fmt.Errorf("Invalid plugin subcommand call: %s", subcommand)
|
||||
}
|
||||
|
||||
@@ -26,6 +26,9 @@ func main() {
|
||||
case "proxy-type":
|
||||
appName := flag.Arg(0)
|
||||
err = proxy.TriggerProxyType(appName)
|
||||
case "proxy-routes-list":
|
||||
appName := flag.Arg(0)
|
||||
err = proxy.TriggerProxyRoutesList(appName)
|
||||
case "post-app-clone-setup":
|
||||
oldAppName := flag.Arg(0)
|
||||
newAppName := flag.Arg(1)
|
||||
|
||||
@@ -64,6 +64,24 @@ func TriggerProxyType(appName string) error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// TriggerProxyRoutesList prints one "process|port|path|strip" line per route,
|
||||
// sorted by descending path length. Backends use this to render path-based
|
||||
// routes in their config or labels.
|
||||
func TriggerProxyRoutesList(appName string) error {
|
||||
routes, err := GetRoutes(appName)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
for _, r := range routes {
|
||||
strip := "0"
|
||||
if r.StripPrefix {
|
||||
strip = "1"
|
||||
}
|
||||
fmt.Printf("%s|%d|%s|%s\n", r.Process, r.Port, r.Path, strip)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// TriggerPostAppCloneSetup creates new proxy files
|
||||
func TriggerPostAppCloneSetup(oldAppName string, newAppName string) error {
|
||||
return common.PropertyClone("proxy", oldAppName, newAppName)
|
||||
|
||||
Reference in new issue
Block a user