Skip to content
SHC Docs

A port selector for url() / host() / path() (proposal)

Status: open design. url(), host() and path() still take the service alone. Written 2026-08-03 alongside the shc half of the path() rename. Verified against ce at d85d540 (refactor(jinja): the prefix helper is path(), not paths()) and the shc catalogue on branch path-migration. No production estate was contacted.

The operator asked for this. The rest of the document is about what it can and cannot buy.


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.yaml spells its ports literally because “url('kubo', 5001) and url('kubo', 8080) both render to the SAME portless authority, which would have silently collapsed the API and gateway endpoints into one”; fleet/fleet.socket.yaml and ethereum/ethereum.socket.yaml say the same thing about their own services.
  • One file walked INTO it: hyperswitch/hyperswitch.exporter.yaml calls {{ 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 the 8080 on the floor. (That call site is wrong a second, independent way: the compose service is hyperswitch-server with a HYPHEN, so it also misses publicHosts and 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.

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

Four 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:

wantdo
one canonical origin, other names still reachablekeep one --host as the template origin, add the rest as routes; templates read the canonical one (today’s behavior, made explicit)
genuinely per-hostname configrender 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.

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: read args[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:

  1. A two-binding service resolves each port to ITS OWN host and prefix.
  2. 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.
  3. Every existing service-only call site renders byte-identically to before the change.