mesh-lab

72 Commits 1 Branch 0 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
jschoubben	be176bab2e	Automate the lab registry: a sealed machine pulls by digest Closes 04-ISSUES/009. A scenario declares `images:` by tag; the lab stocks a registry on this workstation where there is a network, raises it inside the scenario as scenery, and reports the references a declaration pins -- which are the digests THIS registry assigned, and are not knowable until it is raised. Verified in a sealed machine, confirmed by ping to have no route out: package, service including boot state, a container pinned by digest, and an action inside that container. Applied, idempotent on re-apply, and read back from the machine rather than from the apply's own report. That is the first time the container shape has worked in the lab at all, and it was the shape blocking the substrate bootstrap. Four faults found by running it, three of them mine and one worth keeping: The read-back checked that the catalog endpoint answered, by looking for the substring "repositories" -- which `{"repositories":[]}` also contains. So it passed on a registry holding nothing, and the failure surfaced much later as a container that could not be pulled. It now asks for each image's manifest BY DIGEST, which is what a machine does. A recursive push needs its destination to exist, or incus copies the source's contents rather than the source. The data landed one directory too shallow and the registry found nothing where it looks. The registry writes its blobs as root through a bind mount, so the workstation could not remove its own scratch directory afterwards. Whoever made the files removes them -- the cleanup now runs in a container too. And a cleanup failure no longer fails a raise that succeeded: the scenario is standing and usable, and saying otherwise would be a false report. The base image build did not verify that the runtime trusts the documentation ranges as plain-HTTP registries. Writing the file is not the daemon honouring it, and a base image that looks right fails much later, in a sealed scenario, a long way from its cause. It is now read back from `docker info`.	2026-08-29 00:04:55 +02:00
jschoubben	a6b7d67e19	Gateways sharing an address are one gateway Found by asking what gw-devices and gw-home actually were, in a picture that finally made them easy to see side by side. planRouters grouped on the exact address list, so `home` declaring a v4 and a v6 address and `devices` declaring only the v4 became two router containers — both holding 198.51.100.7 on the same segment. The lab raised it without complaint. Not theoretical. On the raised instance the transit router resolved that one address to two different MACs across a cache flush: 198.51.100.7 -> 02:c9:16:70:23:29 (gw0, which HAS the :443 dnat) 198.51.100.7 -> 02:bd:75:0b:b0:75 (gw1, which has none) So home-server's published port worked or did not depending on which container answered ARP last — intermittent, and it would have presented as a flaky test rather than as a broken scenario. One public address is one box. Checked against the thing this models rather than argued from the model: a bridged modem, a single gateway holding the public address, one network behind it, and every port forward landing on one host at that address. Two routers on one address is not a topology, it is a collision. Gateways to the same segment sharing any address are now one router and their address lists union, so a v6 address declared on only one of the segments it serves is still carried. Where such declarations disagree on nat, forwardable or mapping_ttl, validate refuses — one box cannot behave two ways. the-ordinary-shape now raises 7 machines instead of 8, and gw0 holds the public address on eth0 while serving home on eth1 and devices on eth2.	2026-08-24 23:43:23 +02:00
jschoubben	a27d861d3b	Scenario lifecycle: raise, exec, snapshot, restore, destroy A declaration goes in and a disposable mesh comes out. Verified on a workstation, not asserted: two machines raised and addressed in 14.6s, snapshot 0.28s, restore-to-usable 11.6s, both families pinging with no loss, and the workstation with no route into any of it. The declaration layer implements the model in full — three positions a machine can be in, keyed on forwardability; gateways carrying the address the world sees them as; both address families; multi-homing; MTU; inter-segment policy. It is validated hard because the failures it prevents are silent: a private range on a public segment produces no error, the mesh simply never forms. Public segments are refused unless they use RFC 5737 or RFC 3849 space, and a range wider than the reserved block is refused too. 33 tests, all offline. The runtime implements less than the model, and refuses the difference. A scenario declaring gateways, published ports, policy, inbound deny or place is rejected at raise with every gap named. Raising it would produce a mesh that silently lacks what it declared, which is the fault this lab exists to catch — 04-ISSUES/003, where a firewall key is declared in five manifests and read by no code. Three bugs found by review and by running it, all of one family: The readiness check truthiness-tested incusOk's return. `exec … true` succeeds with EMPTY output, so every machine reported unreachable while incus exec on it worked perfectly. succeeds() now exists so the mistake is not available, and network delete had the same bug — it counted zero segments removed while removing them. list() split instance from machine on the last dash, so a machine called home-server absorbed half the instance id and destroy found nothing. Resources are now found by the metadata they carry, never by name. restore reported success in 0.79s while the machine's agent was still starting, so the next command failed. Both raise and restore now wait for usable and say how long that took — reporting the earlier number is transport reported as effect, which is the fault the lab is being built to find. Two incus behaviours worth recording. Its CLI reads a YAML definition from stdin when stdin is not a terminal, so a spawned command hangs until the timeout kills it and arrives with empty stderr — a failure with no explanation, on a command that works when typed. And it assigns a MAC at runtime without recording it in device config, so MACs are derived and set explicitly, which the guest needs anyway: it names interfaces by bus position, and matching by name configures the wrong one on a multi-homed machine. No build step; Node strips the types. The lifecycle has no unit tests because a fake hypervisor would assert that the fake behaves as expected, which is the shape of test this project exists to stop shipping.	2026-08-24 01:12:49 +02:00

Author

SHA1

Message

Date

jschoubben

be176bab2e

Automate the lab registry: a sealed machine pulls by digest

Closes 04-ISSUES/009. A scenario declares `images:` by tag; the lab stocks a
registry on this workstation where there is a network, raises it inside the
scenario as scenery, and reports the references a declaration pins -- which are
the digests THIS registry assigned, and are not knowable until it is raised.

Verified in a sealed machine, confirmed by ping to have no route out: package,
service including boot state, a container pinned by digest, and an action
inside that container. Applied, idempotent on re-apply, and read back from the
machine rather than from the apply's own report. That is the first time the
container shape has worked in the lab at all, and it was the shape blocking the
substrate bootstrap.

Four faults found by running it, three of them mine and one worth keeping:

The read-back checked that the catalog endpoint answered, by looking for the
substring "repositories" -- which `{"repositories":[]}` also contains. So it
passed on a registry holding nothing, and the failure surfaced much later as a
container that could not be pulled. It now asks for each image's manifest BY
DIGEST, which is what a machine does.

A recursive push needs its destination to exist, or incus copies the source's
contents rather than the source. The data landed one directory too shallow and
the registry found nothing where it looks.

The registry writes its blobs as root through a bind mount, so the workstation
could not remove its own scratch directory afterwards. Whoever made the files
removes them -- the cleanup now runs in a container too. And a cleanup failure
no longer fails a raise that succeeded: the scenario is standing and usable,
and saying otherwise would be a false report.

The base image build did not verify that the runtime trusts the documentation
ranges as plain-HTTP registries. Writing the file is not the daemon honouring
it, and a base image that looks right fails much later, in a sealed scenario,
a long way from its cause. It is now read back from `docker info`.

2026-08-29 00:04:55 +02:00

jschoubben

a6b7d67e19

Gateways sharing an address are one gateway

Found by asking what gw-devices and gw-home actually were, in a picture that
finally made them easy to see side by side.

planRouters grouped on the exact address list, so `home` declaring a v4 and a v6
address and `devices` declaring only the v4 became two router containers — both
holding 198.51.100.7 on the same segment. The lab raised it without complaint.

Not theoretical. On the raised instance the transit router resolved that one
address to two different MACs across a cache flush:

    198.51.100.7 -> 02:c9:16:70:23:29   (gw0, which HAS the :443 dnat)
    198.51.100.7 -> 02:bd:75:0b:b0:75   (gw1, which has none)

So home-server's published port worked or did not depending on which container
answered ARP last — intermittent, and it would have presented as a flaky test
rather than as a broken scenario.

One public address is one box. Checked against the thing this models rather than
argued from the model: a bridged modem, a single gateway holding the public
address, one network behind it, and every port forward landing on one host at
that address. Two routers on one address is not a topology, it is a collision.

Gateways to the same segment sharing any address are now one router and their
address lists union, so a v6 address declared on only one of the segments it
serves is still carried. Where such declarations disagree on nat, forwardable or
mapping_ttl, validate refuses — one box cannot behave two ways.

the-ordinary-shape now raises 7 machines instead of 8, and gw0 holds the public
address on eth0 while serving home on eth1 and devices on eth2.

2026-08-24 23:43:23 +02:00

jschoubben

a27d861d3b

Scenario lifecycle: raise, exec, snapshot, restore, destroy

A declaration goes in and a disposable mesh comes out. Verified on a
workstation, not asserted: two machines raised and addressed in 14.6s,
snapshot 0.28s, restore-to-usable 11.6s, both families pinging with no
loss, and the workstation with no route into any of it.

The declaration layer implements the model in full — three positions a
machine can be in, keyed on forwardability; gateways carrying the address
the world sees them as; both address families; multi-homing; MTU;
inter-segment policy. It is validated hard because the failures it prevents
are silent: a private range on a public segment produces no error, the mesh
simply never forms. Public segments are refused unless they use RFC 5737 or
RFC 3849 space, and a range wider than the reserved block is refused too.
33 tests, all offline.

The runtime implements less than the model, and refuses the difference.
A scenario declaring gateways, published ports, policy, inbound deny or
place is rejected at raise with every gap named. Raising it would produce a
mesh that silently lacks what it declared, which is the fault this lab
exists to catch — 04-ISSUES/003, where a firewall key is declared in five
manifests and read by no code.

Three bugs found by review and by running it, all of one family:

The readiness check truthiness-tested incusOk's return. `exec … true`
succeeds with EMPTY output, so every machine reported unreachable while
incus exec on it worked perfectly. succeeds() now exists so the mistake is
not available, and network delete had the same bug — it counted zero
segments removed while removing them.

list() split instance from machine on the last dash, so a machine called
home-server absorbed half the instance id and destroy found nothing.
Resources are now found by the metadata they carry, never by name.

restore reported success in 0.79s while the machine's agent was still
starting, so the next command failed. Both raise and restore now wait for
usable and say how long that took — reporting the earlier number is
transport reported as effect, which is the fault the lab is being built to
find.

Two incus behaviours worth recording. Its CLI reads a YAML definition from
stdin when stdin is not a terminal, so a spawned command hangs until the
timeout kills it and arrives with empty stderr — a failure with no
explanation, on a command that works when typed. And it assigns a MAC at
runtime without recording it in device config, so MACs are derived and set
explicitly, which the guest needs anyway: it names interfaces by bus
position, and matching by name configures the wrong one on a multi-homed
machine.

No build step; Node strips the types. The lifecycle has no unit tests
because a fake hypervisor would assert that the fake behaves as expected,
which is the shape of test this project exists to stop shipping.

2026-08-24 01:12:49 +02:00