feat: declarative proxy.routes block

Feature request: declarative proxy.routes block

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

This issue requests the matching docket schema.

Still blocked, despite the upstream issue being closed. dokku/dokku#8725 was closed on 2026-06-01, but the interface it proposed was never built: there is no proxy:route anywhere in dokku's plugins/ or docs/, and plugins/proxy/subcommands/ has no route subcommand. Everything below describes a CLI that does not exist yet, so nothing here can be implemented until it does. Noting this because a closed blocker reads as "unblocked" at a glance.

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 properties below are what the proposal committed to. They need re-confirming against the CLI as actually built, whenever it is built:

• 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.

Implementation note

This adds a registered task, so it bumps the exact-match count assertion in tasks/main_test.go and the task-count sentence in docs/ansible-dokku.md. Chain it behind anything else that adds a task rather than opening both at once.

Related

• dokku/dokku#8725 - the originating proposal. Closed 2026-06-01 without the interface being implemented.

First verify that dokku has implemented proxy:route:set, proxy:route:remove, and proxy:route:clear, since this issue states the docket task is blocked until that interface exists. Once available, inspect existing task registration and schema patterns, then update tasks/main_test.go and docs/ansible-dokku.md; done means the routes validate, reconcile to the documented commands, and tests pass.