Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
780c2b6e58 |
@@ -124,32 +124,6 @@ This corrects a fact, not the decision: one statement per endpoint, three things
|
|||||||
none of them deciding on its own, all stand. The table in the decision should be read with the filter
|
none of them deciding on its own, all stand. The table in the decision should be read with the filter
|
||||||
column applying to an unrouted endpoint.
|
column applying to an unrouted endpoint.
|
||||||
|
|
||||||
## Progressive insight — 2026-10-02, from issue 191
|
|
||||||
|
|
||||||
**For a routed endpoint, "the proxy serves the internal name" has to mean "serves it to the private
|
|
||||||
network", and only the proxy can make it mean that.** The decision says `internal` means the proxy
|
|
||||||
serves the internal name and not the public one. It does not say to whom, and the proxy answered
|
|
||||||
every name it routes to any request that carried it, on the same listeners as its public names. A
|
|
||||||
name being internal kept nobody out: a request from the internet only had to send it. While every
|
|
||||||
routed endpoint also had a public name, nothing showed it. Once an endpoint could be internal alone
|
|
||||||
([issue 191](../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md)), serving
|
|
||||||
its name to everyone would have published exactly what `internal` was chosen to keep private.
|
|
||||||
|
|
||||||
The earlier insight above says the port is not the path for a routed endpoint. This is its other
|
|
||||||
half: the proxy is the path, so the proxy is where `internal` is enforced. It serves an internal name
|
|
||||||
only to the machines of the mesh and to the machine itself
|
|
||||||
([ADR 0144](0144-anything-on-a-machine-may-call-anything-on-it.md)). Who the mesh is, it is told,
|
|
||||||
not left to work out: its membership carries the same list of machine addresses the filter's "from the
|
|
||||||
mesh" is rendered from ([ADR 0167](0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)).
|
|
||||||
To anyone else, the name is answered as one never routed, in the handshake and in the request, and not
|
|
||||||
listed among the names it serves. This holds for the internal name of a `both` endpoint too, whose
|
|
||||||
outsiders have its public name.
|
|
||||||
|
|
||||||
The decision, the options and the consequences stand: one statement per endpoint, three things
|
|
||||||
derived from it. Checked in the proxy's own tests: an internal-only name is served to a machine the
|
|
||||||
membership names and to loopback, and refused, unlisted and uncertified for any other request; until
|
|
||||||
the mesh is issued, it is served to the machine alone.
|
|
||||||
|
|
||||||
## Consequences
|
## Consequences
|
||||||
|
|
||||||
- **A manifest gains endpoint names, and a route contribution names an endpoint instead of a port.**
|
- **A manifest gains endpoint names, and a route contribution names an endpoint instead of a port.**
|
||||||
|
|||||||
-99
@@ -1,99 +0,0 @@
|
|||||||
---
|
|
||||||
topic: the mesh
|
|
||||||
status: accepted
|
|
||||||
date: 2026-10-02
|
|
||||||
deciders: jochen
|
|
||||||
reconstructed: false
|
|
||||||
extends: 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# 167. A membership carries what its module receives, and who the mesh is
|
|
||||||
|
|
||||||
## Context
|
|
||||||
|
|
||||||
A provider learns what it is given from a file. The controller composes every consumer's contribution
|
|
||||||
to a requirement, and the node's declaration writes them into the provider's received file. The route
|
|
||||||
proxy reads its routes that way: one JSON file, re-read every two seconds.
|
|
||||||
|
|
||||||
[Issue 191](../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md) showed what
|
|
||||||
that file leaves out. Since [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md),
|
|
||||||
a route whose endpoint reaches only the private network carries an internal name and no public one.
|
|
||||||
The proxy dropped it. Serving it was not enough either: the proxy answers public and internal names on
|
|
||||||
the same listeners, so an internal name served to every request is public under a guessable name. To
|
|
||||||
serve it correctly the proxy needs a second fact, **who the mesh is**, and nothing gave it one.
|
|
||||||
|
|
||||||
The first attempt had the proxy work it out: the mesh's range from an environment variable written by
|
|
||||||
the catalogue, and the machine's container bridges read from its own interfaces. That is a second
|
|
||||||
definition of "the mesh", kept by one module, beside the one the packet filter already uses. The
|
|
||||||
controller resolves "from the mesh" to every machine's address on the private network, and the filter
|
|
||||||
is rendered from that list. Two definitions agree until one changes.
|
|
||||||
|
|
||||||
[ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
|
|
||||||
already gives every assignment one document on the bus, its membership, read once at connect and
|
|
||||||
followed. It says what the assignment serves and reaches. It does not yet say what it is given.
|
|
||||||
|
|
||||||
## Considered Options
|
|
||||||
|
|
||||||
1. **Keep the file, add the mesh to it.** The proxy keeps polling a file, and the controller writes the
|
|
||||||
mesh's addresses beside the routes. It fixes the definition, but delivery stays a file re-read on a
|
|
||||||
timer, written by a separate path from the one every other fact a module is told now takes.
|
|
||||||
2. **Have the proxy work it out** from a range in its environment and the machine's interfaces. Rejected:
|
|
||||||
it is the second definition this record exists to remove.
|
|
||||||
3. **The membership carries it.** What each module receives, from the same composition its received
|
|
||||||
file is written from, and the mesh's addresses, from the same list the filter is rendered from. The
|
|
||||||
proxy follows its membership and serves exactly that.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
|
|
||||||
**Option 3.**
|
|
||||||
|
|
||||||
- **A membership carries what its module receives**, by requirement: the contributions every consumer
|
|
||||||
made, exactly as composed for its received file. A requirement nobody contributed to is an empty
|
|
||||||
list, never absent, for the reason the file is written empty: "nothing asked" and "never told" want
|
|
||||||
different responses.
|
|
||||||
- **A membership carries who the mesh is**: every machine's address on the private network, the list
|
|
||||||
a rule saying "from the mesh" resolves to. One list, two readers: the filter and any module that
|
|
||||||
must tell the mesh from the world.
|
|
||||||
- **The route proxy reads its routes and the mesh from its membership**, with the bus account every
|
|
||||||
module that speaks on the bus is given. It serves an internal name only to the machines the mesh
|
|
||||||
names and to the machine itself, and answers anyone else as it answers a name it never routed: in
|
|
||||||
the request, in the handshake, and in the list of names it serves.
|
|
||||||
- **The file stays until the bus has spoken.** While a proxy has read no membership that carries routes,
|
|
||||||
it serves the file, and an internal name only to its own machine: refused, never opened. A
|
|
||||||
membership from a controller that issues no routes changes nothing.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
|
|
||||||
- Every membership grows two fields. A machine joining or leaving republishes every membership, which
|
|
||||||
a push already does.
|
|
||||||
- A provider that receives something is told it twice for now, in its file and on the bus. The file
|
|
||||||
goes when every provider reads its membership; that is its own change.
|
|
||||||
- The route proxy needs a bus account. It is issued like any module's, so a machine running the proxy
|
|
||||||
cannot be composed between the catalogue declaring the account and the operator issuing it. The
|
|
||||||
machine keeps what it runs meanwhile.
|
|
||||||
- The internal name of a route that also has a public one is now served to the mesh only. Outsiders
|
|
||||||
have the public name.
|
|
||||||
- A container on the same machine that calls that machine's own internal name arrives from its
|
|
||||||
container network, not from a mesh address, and is refused. Calls between machines are unaffected:
|
|
||||||
they leave by the machine's mesh address. Whether the mesh should also issue each machine's container
|
|
||||||
networks is left open, because the mesh does not record them today.
|
|
||||||
|
|
||||||
## How this is checked
|
|
||||||
|
|
||||||
| Rule | Checked by |
|
|
||||||
|---|---|
|
|
||||||
| What a provider receives on the bus is what its received file says, same-node port fix included | a controller test composing a provider and a consumer on one machine and comparing the two |
|
|
||||||
| An internal name is served to the machines the membership names and to loopback, and to nobody else | the proxy's tests: served from a named address and from loopback; refused, unlisted and uncertified from any other |
|
|
||||||
| A membership that carries no routes, or a mesh that cannot be read, changes nothing | the proxy's tests |
|
|
||||||
| Until the mesh is issued, an internal name is served to the machine alone | the proxy's tests |
|
|
||||||
| Live: an internal-only route answers over the mesh and is refused from outside | by hand, after the release |
|
|
||||||
|
|
||||||
## References
|
|
||||||
|
|
||||||
- [ADR 0160](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md) —
|
|
||||||
the membership this extends
|
|
||||||
- [ADR 0138](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md) — reach, and the
|
|
||||||
insight of 2026-10-02 that the proxy is where internal reach is kept
|
|
||||||
- [ADR 0144](0144-anything-on-a-machine-may-call-anything-on-it.md) — the machine itself is always inside
|
|
||||||
- [Issue 191](../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md) — what
|
|
||||||
found it
|
|
||||||
@@ -177,7 +177,6 @@ python3 00-META/checks/index.py fail if stale
|
|||||||
- **0161** — [What deserves a seat: a role of a module is a seat, a singular fact about machines is a placement with a capacity of one, and a holder's software is the machine's](0161-what-deserves-a-seat.md)
|
- **0161** — [What deserves a seat: a role of a module is a seat, a singular fact about machines is a placement with a capacity of one, and a holder's software is the machine's](0161-what-deserves-a-seat.md)
|
||||||
- **0162** — [A merge produces a tiered plan the mesh keeps, and a module's dependencies are one relation in the catalogue](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
|
- **0162** — [A merge produces a tiered plan the mesh keeps, and a module's dependencies are one relation in the catalogue](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
|
||||||
- **0163** — [Taking a module over is a comparison: what it compares, what it refuses, and what it carries](0163-taking-a-module-over-is-a-comparison.md)
|
- **0163** — [Taking a module over is a comparison: what it compares, what it refuses, and what it carries](0163-taking-a-module-over-is-a-comparison.md)
|
||||||
- **0167** — [A membership carries what its module receives, and who the mesh is](0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
|
|
||||||
|
|
||||||
### Its tiers, from the bottom up
|
### Its tiers, from the bottom up
|
||||||
|
|
||||||
|
|||||||
@@ -7,9 +7,8 @@ code:
|
|||||||
- mesh-controller internal/identity/authority.go
|
- mesh-controller internal/identity/authority.go
|
||||||
- mesh-host internal/identity/serving.go
|
- mesh-host internal/identity/serving.go
|
||||||
- mesh-host internal/apply (the service that reflects a rule set)
|
- mesh-host internal/apply (the service that reflects a rule set)
|
||||||
updated: 2026-10-02
|
updated: 2026-09-30
|
||||||
decisions:
|
decisions:
|
||||||
- 02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md
|
|
||||||
- 02-DECISIONS/0148-the-meshs-names-are-resolved-not-copied-into-containers.md
|
- 02-DECISIONS/0148-the-meshs-names-are-resolved-not-copied-into-containers.md
|
||||||
- 02-DECISIONS/0151-a-routes-internal-name-is-composed-under-the-node-that-serves-it.md
|
- 02-DECISIONS/0151-a-routes-internal-name-is-composed-under-the-node-that-serves-it.md
|
||||||
- 02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md
|
- 02-DECISIONS/0147-a-module-anchors-the-meshs-authority.md
|
||||||
@@ -843,18 +842,6 @@ One value, three readers:
|
|||||||
| `public` | the machine port, to anywhere | the public name | the public authority |
|
| `public` | the machine port, to anywhere | the public name | the public authority |
|
||||||
| `both` | the machine port, to anywhere | both names | each name's own authority |
|
| `both` | the machine port, to anywhere | both names | each name's own authority |
|
||||||
|
|
||||||
*2026-10-02.* **The proxy serves an internal name to the private network only**
|
|
||||||
([ADR 0138](../../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md),
|
|
||||||
its insight of this date). It answers public and internal names on the same listeners, so the name a
|
|
||||||
request carries is the request's own claim, not where the request came from. An internal name is
|
|
||||||
served to the machines of the mesh and to the machine itself; to anyone else it is answered as a name
|
|
||||||
never routed, in the handshake as well as the request. Without this, an endpoint with reach `internal`
|
|
||||||
would be public under a name that is easy to guess
|
|
||||||
([issue 191](../../04-ISSUES/191-a-route-with-only-an-internal-name-is-dropped/00-report.md)).
|
|
||||||
The proxy is told who the mesh is, and its routes, in its membership on the bus — the same machine
|
|
||||||
addresses the filter's "from the mesh" is rendered from
|
|
||||||
([ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)).
|
|
||||||
|
|
||||||
**An endpoint that is not routed is reached and never named.** No route contribution means no name is
|
**An endpoint that is not routed is reached and never named.** No route contribution means no name is
|
||||||
composed and no certificate requested, while the filter still acts on it. That is the case the model
|
composed and no certificate requested, while the filter still acts on it. That is the case the model
|
||||||
could not express at all, and it is the ordinary case for anything that is not HTTP.
|
could not express at all, and it is the ordinary case for anything that is not HTTP.
|
||||||
|
|||||||
@@ -7,9 +7,8 @@ code:
|
|||||||
- mesh-tools src/broker-amqp.ts (to be replaced)
|
- mesh-tools src/broker-amqp.ts (to be replaced)
|
||||||
- mesh-catalog modules/nats (to be written)
|
- mesh-catalog modules/nats (to be written)
|
||||||
- mesh-sdk src (the protocol's NATS binding, step 3)
|
- mesh-sdk src (the protocol's NATS binding, step 3)
|
||||||
updated: 2026-10-02
|
updated: 2026-10-01
|
||||||
decisions:
|
decisions:
|
||||||
- 02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md
|
|
||||||
- 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
|
- 02-DECISIONS/0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md
|
||||||
- 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
|
- 02-DECISIONS/0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md
|
||||||
- 02-DECISIONS/0106-the-bus-is-nats.md
|
- 02-DECISIONS/0106-the-bus-is-nats.md
|
||||||
@@ -95,12 +94,6 @@ list; the account's grant is the same membership read the other way; the console
|
|||||||
tool's subject. The one rule a runtime keeps is the membership's own subject, from the two names in its
|
tool's subject. The one rule a runtime keeps is the membership's own subject, from the two names in its
|
||||||
credential.
|
credential.
|
||||||
|
|
||||||
**Revised 2026-10-02** ([ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)):
|
|
||||||
a membership also carries **what its module receives**, by requirement — the contributions its
|
|
||||||
received file is written from, from the same composition — and **who the mesh is**, every machine's
|
|
||||||
address on the private network, the list the filter's "from the mesh" is rendered from. The route
|
|
||||||
proxy is the first reader of both.
|
|
||||||
|
|
||||||
**Revised 2026-09-27** ([ADR 0129](../../02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md)):
|
**Revised 2026-09-27** ([ADR 0129](../../02-DECISIONS/0129-a-seat-carries-the-protocol-of-its-role.md)):
|
||||||
**`mesh.build.request`, `mesh.control.built` and the BUILDS stream are gone.** A build is work submitted to a role, and the
|
**`mesh.build.request`, `mesh.control.built` and the BUILDS stream are gone.** A build is work submitted to a role, and the
|
||||||
mesh already has a shape for that — a seat's `accept` subjects, on a work queue with a queue group of
|
mesh already has a shape for that — a seat's `accept` subjects, on a work queue with a queue group of
|
||||||
|
|||||||
@@ -1,80 +0,0 @@
|
|||||||
---
|
|
||||||
status: resolved
|
|
||||||
opened: 2026-10-01
|
|
||||||
located-in: [mesh-controller examples/route-proxy/main.go (routesFrom requires a route's public `name` and treats `internal-name` only as an alias of it; the handler serves every routed name to any source), mesh-controller internal/broker/membership.go (a membership says nothing of what its module receives or who the mesh is)]
|
|
||||||
fixed-by: mesh-controller PR 207 (the membership carries what a module receives and who the mesh is; the proxy follows it and serves internal names to the mesh only), mesh-catalog PR 211 (the proxy's bus account), mesh-controller PR 208 (the issue verb that delivers it), live 2026-10-02
|
|
||||||
amended-design: [03-DESIGN/01-to-be/08-connectivity.md, 03-DESIGN/01-to-be/25-the-bus-on-nats.md]
|
|
||||||
---
|
|
||||||
|
|
||||||
# 191 — A route with only an internal name is dropped as naming nothing
|
|
||||||
|
|
||||||
## What was observed
|
|
||||||
|
|
||||||
A module whose endpoint reaches only the private network could not be reached by its internal name.
|
|
||||||
The module ran and answered on its own port. Its route's internal name resolved to the serving node.
|
|
||||||
The request failed during the TLS handshake:
|
|
||||||
|
|
||||||
```
|
|
||||||
http: TLS handshake error from …: no public route for "unifi.home-server.internal" in this mesh,
|
|
||||||
so no certificate is asked for
|
|
||||||
```
|
|
||||||
|
|
||||||
The proxy's own log said why, every time it re-read its routes:
|
|
||||||
|
|
||||||
```
|
|
||||||
unifi on home-server asked for a route and named nothing; skipped
|
|
||||||
```
|
|
||||||
|
|
||||||
The route it skipped was not empty. The mesh had given it an endpoint, a port, a scheme and an internal
|
|
||||||
name, and no public name:
|
|
||||||
|
|
||||||
| route | `name` | `internal-name` | served |
|
|
||||||
|---|---|---|---|
|
|
||||||
| home-assistant | a public name | `home-assistant.home-server.internal` | under both |
|
|
||||||
| unifi | — | `unifi.home-server.internal` | under neither |
|
|
||||||
|
|
||||||
Three other modules on the same node were skipped with the same line on the same pass.
|
|
||||||
|
|
||||||
## Why it matters
|
|
||||||
|
|
||||||
**Reach is decided in one place, and the proxy reads the old shape of the decision.**
|
|
||||||
[ADR 0138](../../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md)
|
|
||||||
made an endpoint's reach decide which names exist. The controller composes the public name, the
|
|
||||||
internal name, or both, and composes no name that nobody asked for
|
|
||||||
([issue 140](../140-an-endpoints-reach-is-not-declared/01-resolution.md)). An endpoint that reaches
|
|
||||||
only the private network is the ordinary case for anything that should not face the internet. It is
|
|
||||||
exactly the case the proxy drops.
|
|
||||||
|
|
||||||
**The failure is quiet and points the wrong way.** Nothing marks the module unhealthy. The handshake
|
|
||||||
error says *no public route*, which reads as a certificate fault on the reader's side. The line that
|
|
||||||
gives the real cause is one of four identical lines repeated every few seconds in a log nobody reads
|
|
||||||
until they already suspect the proxy.
|
|
||||||
|
|
||||||
**The opposite move is not a workaround.** Giving the endpoint public reach makes the proxy serve it.
|
|
||||||
It also publishes an administration interface to the internet to get a name on the private network.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
|
|
||||||
- Should the proxy refuse a route it cannot serve in a way the controller or an operator sees, not
|
|
||||||
only in its own log? The same silent skip covers a route with no usable port or an unknown scheme.
|
|
||||||
- What checks that what the controller composes and what the proxy serves stay the same shape? ADR
|
|
||||||
0138 changed one side and nothing failed on the other.
|
|
||||||
|
|
||||||
## Resolved (2026-10-02)
|
|
||||||
|
|
||||||
Built as [ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
|
|
||||||
decided, and live on both machines that run the proxy. Each logs that its routes now come from its
|
|
||||||
membership, and serves internal names to the four machines the mesh names. Checked by hand:
|
|
||||||
|
|
||||||
- the internal-only route answers through the proxy from the serving machine and from two other
|
|
||||||
machines of the mesh, over a certificate from the mesh's own authority that each verifies;
|
|
||||||
- the same name asked from an address outside the mesh is answered as a name never routed, over plain
|
|
||||||
HTTP, and refused in the TLS handshake; the list of served names it is shown leaves out every internal
|
|
||||||
name.
|
|
||||||
|
|
||||||
Two things the rollout found are their own records: the proxy's bus account could be issued only from
|
|
||||||
the controller's command line, until mesh-controller PR 208 added the `issue` verb, and the status line
|
|
||||||
counting every module as a bus user without a credential is
|
|
||||||
[issue 195](../195-every-assigned-module-is-counted-as-a-bus-user-without-a-credential/00-report.md).
|
|
||||||
The serving machine also lacked the certificate-trust module, so it could not verify the mesh's own
|
|
||||||
certificates until it was assigned there.
|
|
||||||
@@ -1,75 +0,0 @@
|
|||||||
# Diagnosis
|
|
||||||
|
|
||||||
*2026-10-01.*
|
|
||||||
|
|
||||||
**Ruled out first: the module itself.** Its container was up and had not restarted. The controller's
|
|
||||||
status endpoint answered on its own port with `"up": true`. The tool wrapper beside it was serving
|
|
||||||
all its tools.
|
|
||||||
|
|
||||||
**Ruled out: name resolution.** The internal name resolved to the serving node's private-network
|
|
||||||
address, which is where the proxy listens. Plain HTTP to the name reached the proxy and got a 404.
|
|
||||||
HTTPS failed in the handshake, and the proxy logged that it had no route for the name.
|
|
||||||
|
|
||||||
**The route as the proxy received it.** The mesh-written route file held a complete contribution
|
|
||||||
for the module: endpoint `web`, port, scheme `https`, `insecure`, a label, and `internal-name`. It had
|
|
||||||
no `name`. That is what the controller composes for an endpoint whose reach stops at the private
|
|
||||||
network (ADR 0138, `composeName`). The contribution was correct.
|
|
||||||
|
|
||||||
**Located: `routesFrom` in the proxy.** It reads `name` first and skips the contribution if `name`
|
|
||||||
is empty. It reads `internal-name` only at the end, as a second host for a rule that already has a
|
|
||||||
public one. So the proxy can serve an internal name only next to a public one. That matched the
|
|
||||||
mesh before ADR 0138, when both names were always composed. It has been wrong since then.
|
|
||||||
|
|
||||||
The other half of the proxy already handles the case. Certificates for a host are split by whether it
|
|
||||||
is in the public set: hosts outside it go to the internal authority, and only hosts inside it are
|
|
||||||
eligible for ACME. A host that is only ever an internal name falls on the correct side of both checks
|
|
||||||
without change. For certificates, only reading the route was wrong; who may reach the route is the next section.
|
|
||||||
|
|
||||||
**The fix.** `routesFrom` takes a route that names either host, serves each name it carries, and
|
|
||||||
marks only the public one as public. It still skips a route that names neither, with the same log line.
|
|
||||||
A test proves an internal-only route is served, certified by the internal authority, and refused by
|
|
||||||
the public one. That test fails against the code before the change.
|
|
||||||
|
|
||||||
## The first fix would have made the name public — 2026-10-02, from review
|
|
||||||
|
|
||||||
Serving the dropped route was not enough. The proxy picks a route from the name a request carries
|
|
||||||
and never from where the request came from, and it answers public and internal names on the same
|
|
||||||
listeners. Its public names resolve to an address the internet reaches. So once the internal-only
|
|
||||||
route was served, any request from the internet carrying `unifi.home-server.internal` — a name of a
|
|
||||||
fixed, guessable shape — would have reached an administration interface that reach `internal` was
|
|
||||||
chosen to keep private. Before the fix the route was unreachable from everywhere. After it, it would
|
|
||||||
have been reachable from everywhere. Two more leaks came with it: the proxy's answer for an unrouted
|
|
||||||
name listed every name it serves, internal ones included, and the handshake handed a certificate
|
|
||||||
naming the internal host to any client.
|
|
||||||
|
|
||||||
Nothing showed this while every routed endpoint also had a public name: its internal name exposed
|
|
||||||
nothing the public one did not. It is a gap in the decision's wording, not only in the proxy — ADR
|
|
||||||
0138 says the proxy *serves* the internal name without saying to whom — so it is recorded there as a
|
|
||||||
progressive insight and in the to-be connectivity design.
|
|
||||||
|
|
||||||
**Where "inside" is decided: told, not worked out.** The first correction had the proxy work it out
|
|
||||||
for itself — the mesh's range from an environment variable the catalogue wrote, and the machine's
|
|
||||||
container bridges from its own interfaces. That was a second definition of "the mesh", kept by one
|
|
||||||
module beside the one the controller already has: it resolves "from the mesh" to every machine's
|
|
||||||
address on the private network, and the packet filter is rendered from that list. Reviewed, it was
|
|
||||||
replaced: [ADR 0167](../../02-DECISIONS/0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
|
|
||||||
has every membership on the bus carry what its module receives and that list, and the proxy follows
|
|
||||||
its membership. One composition, read by the filter and by the proxy.
|
|
||||||
|
|
||||||
The proxy reads the source address, where the guard reads the interface, because it cannot see the
|
|
||||||
interface a request arrived on. A claimed source does not carry here: a connection needs its replies,
|
|
||||||
and replies to a mesh address leave by the tunnel.
|
|
||||||
|
|
||||||
**What changed with it.** The internal name of a route that also has a public one is now served to the
|
|
||||||
mesh only, like any other internal name. Outsiders have the public name, so nothing they could reach is
|
|
||||||
lost. A container calling its own machine's internal name arrives from its container network and is
|
|
||||||
refused; whether the mesh should issue those networks too is left open in ADR 0167.
|
|
||||||
|
|
||||||
**Order of release.**
|
|
||||||
|
|
||||||
1. The catalogue change, which gives the proxy a bus account. A machine running the proxy is not
|
|
||||||
composed until its account is issued, so the account is issued straight after
|
|
||||||
(`module issue route-proxy --node <machine>`), and then the machine is pushed.
|
|
||||||
2. The controller and proxy change. The push after it publishes memberships that carry the routes and
|
|
||||||
the mesh, and each proxy takes them. Until then, a proxy serves its file, and internal names to its
|
|
||||||
own machine alone.
|
|
||||||
@@ -0,0 +1,64 @@
|
|||||||
|
---
|
||||||
|
status: located
|
||||||
|
opened: 2026-10-02
|
||||||
|
located-in: [mesh-host internal/apply (removeOrphan: a former target of a kind with no removal was fatal), mesh-host internal/store (Record keeps a former target for every kind, the host's own archive included)]
|
||||||
|
fixed-by:
|
||||||
|
amended-design:
|
||||||
|
---
|
||||||
|
|
||||||
|
# 194 — The host's own former archive stops every machine applying anything
|
||||||
|
|
||||||
|
## What was observed
|
||||||
|
|
||||||
|
2026-10-02, 00:34Z, on all four machines of this mesh, the first time a host carrying former
|
||||||
|
targets ([ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rule 5,
|
||||||
|
built in mesh-host 63) replaced itself with a newer host (mesh-host 64).
|
||||||
|
|
||||||
|
The host delivers its own successor as an archive whose target is a versioned directory
|
||||||
|
([ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md)): every new version
|
||||||
|
is the same resource with a new target. Since mesh-host 63 the record keeps a resource's former
|
||||||
|
target so the next apply removes what the host wrote under it
|
||||||
|
([issue 097](../097-a-resource-that-changes-target-leaves-the-old-one-behind/00-report.md)). So
|
||||||
|
the new host's first apply found the previous version's directory as a former target of its own
|
||||||
|
archive, and asked the removal for an archive — which does not exist
|
||||||
|
([issue 162](../162-an-archive-cannot-be-undeclared/00-report.md)):
|
||||||
|
|
||||||
|
```
|
||||||
|
applying "mesh-host.next@former:/usr/lib/nox-mesh-host/versions/3c906749ad27": no way to remove a "archive"
|
||||||
|
0 resource(s) were applied and remain
|
||||||
|
```
|
||||||
|
|
||||||
|
Orphans are removed before any resource is applied on a converged machine, so the refusal ended
|
||||||
|
every apply at its first step. Every machine reported `failed`, applied nothing, and would have
|
||||||
|
gone on doing so: a host fix is itself an archive the same apply would have to write, and the apply
|
||||||
|
never reached it. The machines kept running what they had; nothing new from the mesh could land.
|
||||||
|
|
||||||
|
## Why it matters beyond this instance
|
||||||
|
|
||||||
|
Two rules that are each right met in the one resource the host cannot afford to stop on. Rule 5
|
||||||
|
says a former target is removed and said; issue 162 says an archive has no removal, deliberately,
|
||||||
|
so an unassignment nothing can undo is never reported as done. Neither rule was wrong; their
|
||||||
|
meeting was never tested, because the bed that would have found it is a host replacing itself
|
||||||
|
under the new rule, and the first such replacement was the live one. The fix is narrow: a former
|
||||||
|
target of a kind the host cannot remove is left in place, said, and forgotten — never fatal,
|
||||||
|
because nobody dropped it. An archive the declaration dropped still refuses, as 162 has it.
|
||||||
|
|
||||||
|
## What it took to recover
|
||||||
|
|
||||||
|
The broken host cannot apply its own fix: the fix is delivered as an archive, and the apply fails
|
||||||
|
before writing anything. On each machine the host's record (`/var/lib/mesh-host/state.json`) had to
|
||||||
|
lose the one `@former:` entry by hand, once, so that the next push could write the fixed archive and
|
||||||
|
stand aside for it. A manual edit of the host's record is otherwise never done; it is written here
|
||||||
|
because the alternative was four machines that could apply nothing.
|
||||||
|
|
||||||
|
## Open questions
|
||||||
|
|
||||||
|
- Should `Record` keep a former target for a kind the host cannot remove at all? The trace is
|
||||||
|
useful; the removal it implies is not. Keeping it and letting the apply forget it is what the fix
|
||||||
|
does; not recording it would be quieter.
|
||||||
|
- Should the host's own versions directory be cleaned by the launcher rather than by the apply —
|
||||||
|
the one archive whose former targets are genuinely removable, by the thing that knows which one
|
||||||
|
runs?
|
||||||
|
- Is there a bed that replaces a host under the current rules before the live mesh does
|
||||||
|
(the proof row of [ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md) was
|
||||||
|
a single crossover, before former targets existed)?
|
||||||
-62
@@ -1,62 +0,0 @@
|
|||||||
---
|
|
||||||
status: open
|
|
||||||
opened: 2026-10-02
|
|
||||||
located-in: []
|
|
||||||
fixed-by:
|
|
||||||
amended-design:
|
|
||||||
---
|
|
||||||
|
|
||||||
# 195 — Every assigned module is counted as a bus user without a credential, and the real gaps are lost in the count
|
|
||||||
|
|
||||||
## What was observed
|
|
||||||
|
|
||||||
`status`, and `plan` for any machine, open with one line before anything else:
|
|
||||||
|
|
||||||
```
|
|
||||||
the bus's user list leaves out 49 user(s) the mesh has minted no credential for: <node>.<module>, …
|
|
||||||
Each is a user that cannot connect until one is issued
|
|
||||||
```
|
|
||||||
|
|
||||||
The 49 are spread over four machines and name 26 distinct modules. Checked against the catalogue on
|
|
||||||
2026-10-02:
|
|
||||||
|
|
||||||
| what the module's definition says | modules |
|
|
||||||
|---|---|
|
|
||||||
| declares an own secret named `broker` | 1 — the route proxy, which needed a bus account for issue 191 |
|
|
||||||
| declares no `broker` secret, and emits, consumes and serves nothing on the bus | 17 — the packet filter, the intrusion filter, the ssh daemon, the resolver configuration, the certificate authority, the broker itself and others |
|
|
||||||
| declares no `broker` secret, and **emits events** | 1 |
|
|
||||||
| not in this catalogue, so not checked | 7 |
|
|
||||||
|
|
||||||
So the line counts every module assigned anywhere as a bus user. For almost all of them that is not a
|
|
||||||
missing credential. A module with no `broker` secret has nowhere to receive one, and the mesh already
|
|
||||||
says an account nothing reads is an orphan ([issue 078](../078-a-delivered-secret-is-accepted-under-any-name/00-report.md)).
|
|
||||||
|
|
||||||
Two real gaps sit inside the count and cannot be told from the noise:
|
|
||||||
|
|
||||||
- **A declared `broker` secret was filled with a value that is not an account.** Before its account was
|
|
||||||
issued, the route proxy's plan on both machines already carried a sealed `broker` file, while the same
|
|
||||||
status line said no credential had been minted for it. A push had made the declared secret the way it
|
|
||||||
makes any own secret. The module would have started with a credential the bus does not know, and
|
|
||||||
nothing would have said why. It was found only because the account was being issued by hand.
|
|
||||||
- **A module that emits events declares no way to reach the bus.** Its events can go nowhere, and no
|
|
||||||
check refuses that.
|
|
||||||
|
|
||||||
## Why it matters
|
|
||||||
|
|
||||||
**A warning that is always on is read as never on.** The line names 49 users on every `status` and every
|
|
||||||
`plan`. An operator, or an agent, learns to scroll past it. The one entry that was a real fault looked
|
|
||||||
exactly like the 48 that were not.
|
|
||||||
|
|
||||||
**The fault that was real is the silent kind.** A module whose broker credential is a generated value
|
|
||||||
starts, fails to authenticate, and reports that three layers away from the cause. That is the failure
|
|
||||||
the composition already refuses for a secret that was never made at all ("declared and not made"). Here
|
|
||||||
a value was made, so the refusal never fired.
|
|
||||||
|
|
||||||
## Open questions
|
|
||||||
|
|
||||||
- Should a bus user be composed for a module that declares no `broker` secret at all? If not, the line
|
|
||||||
shrinks to the modules that can actually use an account.
|
|
||||||
- Is a `broker` secret ever correctly made by the generic generator? If not, should composition refuse
|
|
||||||
a declared `broker` until it is issued, or should the mesh issue it as part of placing the module?
|
|
||||||
- Should a module that emits, consumes or serves on the bus be refused when it declares no `broker`
|
|
||||||
secret?
|
|
||||||
Reference in New Issue
Block a user