An assignment configures an endpoint as one thing #139

2026-09-29T09:25:54Z

mesh-admin commented

2026-09-29 09:25:54 +00:00

Completes ADR 0138. One block per endpoint instead of three keys joined by a port number:

{"endpoints": {"web":    {"port": 20009, "label": "cinema", "reach": "both"},
               "stream": {"reach": "internal"}}}

Which machine port it lands on, the subdomain a proxy serves it under, and how far it reaches are the
three things an operator says when a module is assigned. They were said in ports, in the route's
label and in reach, each keyed by the port — so a module with two endpoints of different shapes
could only be configured by a reader who knew which number was which. That was the whole complaint.

Every field is optional. A block that says only a reach leaves the port to the mesh and the label to
the module, which is the ordinary case.
An endpoint name the module does not declare is refused, and the refusal lists what it does declare
— including telling a module with no named endpoints that it has none, which is every module in the
catalogue today.
A port or a reach said both here and through the older key is refused rather than merged. Two places
saying one thing is what this key exists to end; merging would follow whichever was read last.
The label an assignment gives wins over the module's own, because where a thing lives under a domain
is the operator's to choose and used to mean editing the module.

Eight tests. One of them is worth calling out: the reach assertion deliberately narrows what the
manifest says, because a reach that agrees with the manifest proves nothing about whether the block was
read at all. I wrote the weaker version first, reverted the implementation to check the test bit, and
watched it pass — the test was vacuous. It now fails when the block is ignored, along with the label and
port assertions.

Completes ADR 0138. One block per endpoint instead of three keys joined by a port number: ```json {"endpoints": {"web": {"port": 20009, "label": "cinema", "reach": "both"}, "stream": {"reach": "internal"}}} ``` Which machine port it lands on, the subdomain a proxy serves it under, and how far it reaches are the three things an operator says when a module is assigned. They were said in `ports`, in the route's `label` and in `reach`, each keyed by the port — so a module with two endpoints of different shapes could only be configured by a reader who knew which number was which. That was the whole complaint. - Every field is optional. A block that says only a reach leaves the port to the mesh and the label to the module, which is the ordinary case. - An endpoint name the module does not declare is refused, and the refusal lists what it does declare — including telling a module with no named endpoints that it has none, which is every module in the catalogue today. - A port or a reach said both here and through the older key is refused rather than merged. Two places saying one thing is what this key exists to end; merging would follow whichever was read last. - The label an assignment gives wins over the module's own, because where a thing lives under a domain is the operator's to choose and used to mean editing the module. Eight tests. One of them is worth calling out: the reach assertion deliberately **narrows** what the manifest says, because a reach that agrees with the manifest proves nothing about whether the block was read at all. I wrote the weaker version first, reverted the implementation to check the test bit, and watched it pass — the test was vacuous. It now fails when the block is ignored, along with the label and port assertions.

mesh-admin added 1 commit 2026-09-29 09:25:54 +00:00

An assignment configures an endpoint as one thing c68d3a7432

novox/hq ADR 0138, completing it. One block per endpoint instead of three keys
joined by a port number:

  {"endpoints": {"web":    {"port": 20009, "label": "cinema", "reach": "both"},
                 "stream": {"reach": "internal"}}}

Which machine port it lands on, the subdomain a proxy serves it under, and how far
it reaches are the three things an operator says when a module is assigned, and they
were said in ports, in the route's label and in reach — each keyed by the port. A
module with two endpoints of different shapes could only be configured by a reader
who knew which number was which.

Every field is optional; a block that says only a reach leaves the port to the mesh
and the label to the module, which is the ordinary case. A name the module does not
declare is refused, and the refusal lists what it does declare. A port or a reach
said both here and through the older key is refused rather than merged — two places
saying one thing is what this key exists to end, and merging would follow whichever
was read last.

Eight tests. The reach assertion deliberately narrows what the manifest says, because
a reach that agrees with the manifest proves nothing about whether the block was read
— which I found by writing the weaker version first and watching a revert not fail.

mesh-admin merged commit aaad02fd38 into main

2026-09-29 09:25:55 +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#139