novox/hq
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

ADR 0144: anything on a machine may call anything on it, superseding 0143

Browse Source 
Everything should be able to call what runs on the same machine, another machine's
service exposed to the private network, and another machine's service exposed
publicly. Three cases; the filter had two.

The first was expressed as the machines' own addresses on the private network. A
caller on the machine carries such an address; a caller in one of its containers
carries a bridge address and matched nothing — measured, same destination and same
machine: src 10.10.0.1 against src 172.17.0.8. The second case worked by accident,
because the tunnel rewrites a caller's address to the sending machine's. Two of
three working is why it read as correct.

0143 answered the wrong question. It proposed verifying each grant from the
consumer's own network position and went to length about which position, because
whether a caller sat in a container changed the answer — and that difference was the
bug. Observing a configuration error is not its remedy. Superseded, and nothing
replaces it; whether the mesh should check a grant is still open in issue 145 and
must stand on its own.

And a module is not a container: 61 of 72 happen to use one, 11 do not, and a rule
reasoning about containers describes most of the mesh rather than the mesh.
This commit is contained in:
jschoubben
2026-09-29 13:32:01 +02:00
parent 78d4873f4f
commit eba24a72af
5 changed files with 164 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/10-delivery.md
+21 -26
View File
@@ -7,7 +7,6 @@ code:
- mesh-controller internal/inventory/builds.go
updated: 2026-09-29
decisions:
- 02-DECISIONS/0143-a-consumer-verifies-the-grant-it-is-given.md
- 02-DECISIONS/0090-a-failure-that-repeats-is-said-to-be-stuck.md
- 02-DECISIONS/0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md
- 02-DECISIONS/0010-delivery.md
@@ -228,37 +227,33 @@ id, whatever the words; three make the machine stuck, and `status` says so besid
knows, not what the machine is told. *How it is checked:* an inventory test counts three identical
reports, a different one, and a clean apply; the status test asserts the word appears.
## A consumer verifies the grant it is given
## Everything may call what is exposed to it, and local is not a boundary
*2026-09-29, from an outage that ran eleven hours —
[issue 145](../../04-ISSUES/145-a-machine-reads-healthy-while-its-modules-cannot-reach-each-other/00-report.md),
settled by [ADR 0143](../../02-DECISIONS/0143-a-consumer-verifies-the-grant-it-is-given.md).*
settled by [ADR 0144](../../02-DECISIONS/0144-anything-on-a-machine-may-call-anything-on-it.md).*
A grant is four facts and a credential: the provision, the machine, the port, and who the consumer is
when it connects. It is the whole mechanism by which anything in the mesh reaches anything else, and the
mesh asserted it without ever finding out whether it was true.
when it connects. It is the whole mechanism by which anything in the mesh reaches anything else, and it
rests on three things being callable — what runs on the same machine, another machine's service over the
private network where it is exposed there, and another machine's service over the public network where it
is exposed there.
What that cost: a machine was converged, the path from a container to a port on its own machine closed,
and for eleven hours the mesh answered *all heard from, every module current with its source* while a
module logged a connection timeout to its database six thousand times. Every check the mesh makes passed,
because every one is about the relationship between the mesh and a machine — applied, current, running.
None asks whether a consumer can reach what it requires.
The filter had two of those. A service exposed to the private network admitted the machines' own addresses
on it; a caller on the machine carries such an address, and a caller inside one of that machine's
containers carries a bridge address and matched nothing. Measured, same destination and same machine:
`src 10.10.0.1` from the machine, `src 172.17.0.8` from a container on it. So a module reaching its
database on its own machine's name timed out for eleven hours while the mesh called the machine healthy.
**So a consumer verifies its own grants, from its own network position.** Not the control plane, which
reaches the address by a path no consumer uses; not the machine, whose own packets carried a source
address the filter admitted while every container's was refused. The position is the point: a check
somewhere else is testing something nobody asked about.
The second case worked by accident: a caller on another machine arrives over the tunnel carrying that
machine's address, which the rule matched. Two of three working is why this read as correct.
It opens a connection and nothing more. Whether the credential is right or the schema current is the
provider's to answer and the consumer's to discover; a check that spoke each provision's protocol would
be a second implementation of every provision.
**So local is not a boundary this mesh draws, and the filter says so once.** Traffic that did not arrive
from outside the machine and did not arrive over the private network is the machine's own, and is
admitted — for every service there, not per service. Whether the caller is a container, a unit or a shell
decides nothing, because the question is "is this the same machine".
One failure is not news — a provider restarting is ordinary — so a grant reads unreachable only after
consecutive reconciles, and the machine reports the count rather than the last attempt, which is what
separates "briefly away" from "never worked". A consumer that is not running has no position to dial
from: that grant reads unchecked, which is a different sentence from broken and must not be written as
one.
*How it is checked* is stated with the decision, and the first of them is the outage itself: a bed drops
the path from a consumer's position while leaving the machine's own open, and the grant must read
unreachable — which fails both against reporting nothing and against a check run from the machine.
A verification mechanism was drafted for this and withdrawn. It would have reported the outage sooner and
would not have prevented it, and the part of it that was hard — deciding which network position to check
from — existed only because the rule was wrong. Whether the mesh should check that a grant works is still
open, in issue 145; it is not the remedy for a configuration error.