feat: declarative proxy.routes block

[josegonzalez]

Feature request: declarative proxy.routes block

dokku/dokku#8725 adds a proxy:route:* interface that lets users route path prefixes to non-web Procfile processes within a single app. The CLI is designed with set semantics (omitting a flag resets to default) and no-op suppression so a docket-style declarative tool can apply a spec idempotently without diffing against current state.

This issue requests the matching docket schema.

Proposed YAML schema

Under each app, allow a proxy.routes block: a list of routes, each describing a single path prefix and the process it targets.

my-app:
  proxy:
    routes:
      - process: api
        path: /api/v0
        port: 5001
      - process: api
        path: /api/v0/admin
        port: 5001
      - process: ws
        path: /ws
        port: 8080
      - process: tools
        path: /internal
        port: 5000
        strip_prefix: true

Field semantics:

• process (required) - Procfile process name. Cannot be web (which is the implicit catch-all). The dokku CLI rejects web at the command layer; docket may surface the same validation in the spec.
• path (required) - URL path prefix beginning with /. Cannot end with / except for the special root, which is reserved for web.
• port (optional, default 5000) - container port of the target process.
• strip_prefix (optional, default false) - when true, strips the matched prefix before forwarding to the upstream.

Mapping to dokku commands

Each list entry maps 1:1 to a single dokku proxy:route:set invocation - no merging against current state is needed:

dokku proxy:route:set <app> api /api/v0 --port 5001
dokku proxy:route:set <app> api /api/v0/admin --port 5001
dokku proxy:route:set <app> ws /ws --port 8080
dokku proxy:route:set <app> tools /internal --port 5000 --strip-prefix

Routes present on the app but absent from the spec should be removed with dokku proxy:route:remove <app> <path>. The clean-slate operation is dokku proxy:route:clear <app> followed by per-route sets, but reconciliation (delete-then-set) is more compatible with concurrent operators.

Idempotency

The dokku CLI already provides:

• Set semantics: a proxy:route:set invocation is fully determined by its arguments (omitting --port resets to 5000; omitting --strip-prefix resets to false). docket can map a spec entry directly without merge logic.
• No-op suppression: re-applying an already-correct route does not invoke proxy-build-config, so re-running docket against an in-sync app is free of side effects.
• Concurrency: writes serialize through dokku's PropertyMap file lock.

Related

• Configuring path-based routing to specific Procfile processes dokku#8725 - the originating issue and the proposal driving this.