A port selector for url() / host() / path() (proposal)
Status: open design.
url(),host()andpath()still take the service alone. Written 2026-08-03 alongside the shc half of thepath()rename. Verified against ce atd85d540(refactor(jinja): the prefix helper is path(), not paths()) and the shc catalogue on branchpath-migration. No production estate was contacted.
The operator asked for this. The rest of the document is about what it can and cannot buy.
The gap
Section titled “The gap”Routing keys a public binding on a pair. Templates key it on half the pair.
--host parses to HostSpec{Hostname, Path, Service, Port} and resolves
against IngressCandidate{Service, Port}, one routable compose service
and one TCP container port (ce/modules/app/host_spec.go:34).
ResolveHostSpec demands a UNIQUE surviving candidate: zero matches is
X400936HSTNOP, two or more is X400937HSTAMB (host_spec.go:954). And
resolveHostSpecs writes the resolved candidate BACK onto the spec:
spec.Service = candidate.Service; spec.Port = candidate.Port
(host_spec.go:516), so by the time anything downstream sees a spec, its
port is concrete even when the operator never typed one.
The template projection then throws that half away.
buildHostRenderCtxFromSpecs builds two map[string]string keyed by
service name, and skips any declaration for a service already present:
// host()/url()/paths() have one value per service. When several// public declarations route to one service, the first declaration is// its stable template origin while every declaration remains a route.if _, exists := hr.PublicHosts[spec.Service]; exists { continue}(ce/modules/app/install_runner.go:4238.) BuildHostFunc, BuildURLFunc
and BuildPathFunc all index those maps by args[0] alone. So for
shc install myapp --host web:[email protected] --host web:[email protected]both routes are created and both work in the browser, while url('web')
renders https://api.example.com for every consumer in every template,
including the one that meant the UI. Nothing warns. The comment quoted
above is honest about it, which is why this is a gap and not a bug: the
collapse is deliberate, documented, and load-bearing for the far more
common one-binding case.
BuildHostFunc and BuildURLFunc already accept args ...any and their
doc comments already advertise host('svc', [port]) / url('svc', [port])
(install_runner.go:4079, :4117), while BuildPathFunc’s comment
advertised paths('svc', [port]) even before the rename. All three
ignore the second argument today. The signature was reserved; the
behavior was never built. A template that passes a port right now is
silently answered as if it had not.
The catalogue has already paid for this twice, in both directions:
- Three socket files work AROUND it in comments:
kubo/ipfs.socket.yamlspells its ports literally because “url('kubo', 5001)andurl('kubo', 8080)both render to the SAME portless authority, which would have silently collapsed the API and gateway endpoints into one”;fleet/fleet.socket.yamlandethereum/ethereum.socket.yamlsay the same thing about their own services. - One file walked INTO it:
hyperswitch/hyperswitch.exporter.yamlcalls{{ url('hyperswitch_server', 8080) }}twice, and exporter jobs do get the host callables (ce/modules/export/cli_runner.go:548), so the call resolves, dropping the8080on the floor. (That call site is wrong a second, independent way: the compose service ishyperswitch-serverwith a HYPHEN, so it also missespublicHostsand falls through to a tenant alias for a service that does not exist. Both faults are pre-existing and out of scope for this document; neither is fixed by this feature alone.)
An author reaching for the second argument is therefore not hypothetical. It has already happened, and the surface answered by pretending it had not.
The proposal
Section titled “The proposal”Give all three helpers an optional second argument naming the CONTAINER
port of the binding, the same number --host web:8080@… selects, the
same number IngressCandidate.Port holds:
{{ url('web', 8080) }} → https://api.example.com{{ url('web', 3000) }} → https://ui.example.com{{ path('web', 3000) }} → the path prefix of THAT binding{{ host('web', 8080) }} → api.example.comFour requirements, in the order they matter.
1. A missing binding for that port is a HARD render error
Section titled “1. A missing binding for that port is a HARD render error”Never an empty string, never a fallback to the service-only value.
This is the whole point of the feature. An operator reaches for the port
form precisely because the service is ambiguous; answering an unmatched
port with "" would bake an empty authority into a container’s config and
surface as a broken link days later, which is exactly the failure class
url() returning "" in socket contexts already cost this project (see
the comment blocks at the head of apps/*/*.socket.yaml). Answering
it with the service-only value would be worse: it would return the FIRST
binding, the very value the caller wrote a port to avoid.
An unresolvable helper call must fail the render with a coded error naming the service, the requested port, and the ports that ARE bound for that service. The render already treats an unknown callable as fatal, so failing here is consistent with the surface’s existing contract rather than new strictness.
This makes hyperswitch a landing prerequisite, not a follow-up. Its
two url('hyperswitch_server', 8080) calls are ignored today and would
become hard render failures the day the second argument starts meaning
something, correctly, since hyperswitch_server has no binding under any
spelling, but a catalogue app that cannot render is a release blocker. Fix
that call site (service name AND whatever it actually wants for a port) in
the same change, or before it.
Note the asymmetry with port(): BuildPortFunc returns "" for an
unmapped service today (install_runner.go:4151). That is a different
helper reading a different map (--port publishes, not --host
bindings), and this proposal does not change it. It is called out only so
the difference is a decision on the record and not an oversight.
2. The service-only form keeps working, unchanged
Section titled “2. The service-only form keeps working, unchanged”url('web') must continue to resolve to the first binding for web, with
byte-identical output, including the case where web has no --host at
all and falls through to localhost:<port> or the tenant alias. Nearly
the entire catalogue is written in the service-only form (after the
path() migration, 67 url(), 16 host() and 7 path() rendered calls,
of which exactly the two hyperswitch calls above pass a second argument)
and none of them should have to change for this to land.
Concretely: the port-keyed lookup is an ADDITIONAL index, not a
replacement. HostRenderCtx grows a (service, port) → hostname/path
projection beside the existing service → … maps, both populated in the
same loop over the same resolved specs. With one binding per service the
two indexes agree by construction, so the service-only path cannot drift
from the port-keyed one.
3. Zero arguments and a non-numeric second argument stay defined
Section titled “3. Zero arguments and a non-numeric second argument stay defined”url() with no arguments resolves service "default" today
(install_runner.go:4131). That stays. A second argument that is not a
port number is an author bug and should fail the render the same way an
unmatched port does, not be stringified and silently missed.
4. It does NOT fix two hostnames on the same (service, port)
Section titled “4. It does NOT fix two hostnames on the same (service, port)”This is the limit to state plainly, because it is the case a reader will assume the feature covers.
shc install myapp --host web:[email protected] --host web:[email protected]Both routes are created. Both work. url('web', 8080) still has to pick
one, and no richer selector helps, because the ambiguity is not in the
key; it is in the question. A template renders ONCE per deployment and
its output is baked into a container’s configuration. “Which hostname did
this user arrive on” is answerable only PER REQUEST, at the edge, long
after the render is over. There is no argument you could add to url()
that would make a single rendered string be two hostnames.
That is irreducible at template level, and the honest options are:
| want | do |
|---|---|
| one canonical origin, other names still reachable | keep one --host as the template origin, add the rest as routes; templates read the canonical one (today’s behavior, made explicit) |
| genuinely per-hostname config | render per route; the app, not the template surface, has to be multi-origin aware |
A wildcard host is NOT among the options: normalizeHTTPHostname
(host_spec.go:168) admits only letters, digits and - per label, so
--host *.example.com is refused at parse time. Allowing one would be its
own proposal, and it would not change this section either; a wildcard
route still renders to exactly one string.
A future --host could grow a “this one is canonical” marker so the
template origin is chosen rather than order-dependent. That is a separate
proposal, and it does not change the paragraph above: it picks WHICH one
string, it does not make the string plural.
Why this is small
Section titled “Why this is small”The routing layer already carries the port through parse, resolve, persist, replay and Traefik injection. Nothing about ingress needs to change. The change is confined to:
HostRenderCtx: one more projection, filled in the loop that already walks the resolved specs.BuildHostFunc/BuildURLFunc/BuildPathFunc: readargs[1]when present, which their signatures already allow.- One new coded error for the unmatched-port case.
BuildURLFunc composes BuildHostFunc and appends publicPaths[svc]
(install_runner.go:4128), so the path side must be ported in the same
change or url('web', 3000) would return the right host with the first
binding’s prefix, a silent wrong answer of exactly the kind requirement 1
exists to forbid.
The same gate the path() rename used, for the same reason it was the
decisive one there: TestCatalogComposeStrictUndefined
(tests/unit/modules/app/catalog_render_strict_test.go) renders every
shipped app’s compose under a strict-undefined pass (76 apps) against a
render context built by hand to mirror app.ExecuteCompose. It goes red
on an unresolvable callable, which is what makes it able to prove a
helper-surface change did not break the catalogue.
For this feature specifically, three cases have to be pinned, and the third is the one that would otherwise rot:
- A two-binding service resolves each port to ITS OWN host and prefix.
- An unmatched port FAILS the render, asserted on the error, not on the output, so a future refactor that reintroduces an empty-string fallback cannot pass by rendering something harmless-looking.
- Every existing service-only call site renders byte-identically to before the change.