A module names its endpoints, and a route names the one it serves #138

2026-09-29T07:28:40Z

mesh-admin commented

2026-09-29 07:28:40 +00:00

ADR 0138's remaining half. The words ship one release before any manifest uses them, so nothing in
the catalogue changes and no build is affected.

A port number is not a name. Three facts have to be said about an endpoint when a module is
assigned — which machine port it lands on, the subdomain a proxy serves it under, and how far it
reaches — and they were said in three places keyed by the port: ports, the route's label, and
reach. A module with two endpoints of different shapes cannot be configured that way without a
reader joining numbers by hand. The example that made it concrete: a media server with a web surface
behind the proxy, whose port only the proxy need reach, and a protocol port clients dial directly
because the client expects that exact number — which the manifest already marks fixed.

A listen carries a name: lowercase, unique within the module, the module's to choose like the
route's label.
A route carries endpoint instead of repeating a port. A route and a listen both carried a port and
nothing said they were the same thing; now one of them does.
Two endpoints with one name are refused — an assignment configuring one would silently configure
whichever the mesh read last.
A route naming an endpoint the module does not declare is refused where it is written, rather than
resolving to no port and serving nothing.
A name that is not a name is refused: it ends up in something a person types.

An unnamed endpoint stays valid and a route repeating a port still resolves, which is every module in
the catalogue today.

Eight tests, including the two-endpoint case end to end: the routed endpoint's reach asks for names
and leaves its port to the proxy, the directly-dialled one's reach governs its port, and both are
configured by one statement each. Proved by removing the name lookup once — exactly the two tests that
depend on it fail.

Next, and not here: the endpoints settings key, so those three facts are one block per endpoint
rather than three keys joined by a number.

ADR 0138's remaining half. The words ship one release before any manifest uses them, so nothing in the catalogue changes and no build is affected. **A port number is not a name.** Three facts have to be said about an endpoint when a module is assigned — which machine port it lands on, the subdomain a proxy serves it under, and how far it reaches — and they were said in three places keyed by the port: `ports`, the route's `label`, and `reach`. A module with two endpoints of different shapes cannot be configured that way without a reader joining numbers by hand. The example that made it concrete: a media server with a web surface behind the proxy, whose port only the proxy need reach, and a protocol port clients dial directly because the client expects that exact number — which the manifest already marks `fixed`. - A listen carries a `name`: lowercase, unique within the module, the module's to choose like the route's label. - A route carries `endpoint` instead of repeating a port. A route and a listen both carried a port and nothing said they were the same thing; now one of them does. - Two endpoints with one name are refused — an assignment configuring one would silently configure whichever the mesh read last. - A route naming an endpoint the module does not declare is refused where it is written, rather than resolving to no port and serving nothing. - A name that is not a name is refused: it ends up in something a person types. An unnamed endpoint stays valid and a route repeating a port still resolves, which is every module in the catalogue today. Eight tests, including the two-endpoint case end to end: the routed endpoint's reach asks for names and leaves its port to the proxy, the directly-dialled one's reach governs its port, and both are configured by one statement each. Proved by removing the name lookup once — exactly the two tests that depend on it fail. Next, and not here: the `endpoints` settings key, so those three facts are one block per endpoint rather than three keys joined by a number.

mesh-admin added 1 commit 2026-09-29 07:28:40 +00:00

A module names its endpoints, and a route names the one it serves bdf965dab6

novox/hq ADR 0138's remaining half, and the words ship one release before any
manifest uses them.

A port number is not a name. Three facts have to be said about an endpoint when a
module is assigned — which machine port it lands on, the subdomain a proxy serves
it under, and how far it reaches — and they were said in three places keyed by the
port. A module with two endpoints of different shapes cannot be configured that way
without a reader joining numbers by hand: a web surface behind the proxy, whose
port only the proxy need reach, and a protocol port clients dial directly because
the client expects that number.

So a listen carries a name, lowercase and unique within the module, and a route
names the endpoint it serves instead of repeating its port. Two endpoints with one
name are refused, because an assignment configuring one would silently configure
whichever the mesh read last. A route naming an endpoint the module does not declare
is refused where it is written rather than resolving to no port and serving nothing.

An unnamed endpoint stays valid and a route repeating a port still resolves, which
is every module in the catalogue today.

mesh-admin merged commit a5209bd849 into main

2026-09-29 07:28:41 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/mesh-controller#138