Skip to content

M16: a way in - #20

Merged
youhide merged 2 commits into
mainfrom
feat/m16-demo
Aug 11, 2026
Merged

M16: a way in#20
youhide merged 2 commits into
mainfrom
feat/m16-demo

Conversation

@youhide

@youhide youhide commented Aug 11, 2026

Copy link
Copy Markdown
Owner

Everything written so far was for somebody implementing an init
system. Nothing was for somebody deciding whether to look at one, and the
shortest path to running it needed a Rust toolchain, a musl target, QEMU,
cpio, and a kernel you had to go and find.

Now it is:

docker run --rm --name oxinit-demo -p 8080:8080 ghcr.io/youhide/oxinit:demo

The unit set was the problem

units/ is the test suite. It contains a service that fails forever, one
that hangs, one that ignores SIGTERM, one that requires something
broken, and one that never signals readiness — all deliberate, all
necessary, and all of it reads as a crash to somebody seeing oxinit for
the first time.

demo/ is eight files that work, each showing exactly one idea:
ordering, readiness, logs, a schedule, socket activation.

curl is the demo

listen-probe learned to answer HTTP. Nothing is running on port 8080;
the request is what starts the service; the reply comes back on a
connection that was never refused.

$ curl localhost:8080
oxinit started this service because you connected.
It was not running a moment ago.

That is the shortest path from "what is socket activation" to seeing it.

The demo is tested

M13 found seven behaviours verified once and never again — the worst of
them a unit file whose comment described a test nothing ran. A README's
opening section is the same hazard with a wider blast radius.

cargo xtask test-demo runs every command the README gives a newcomer —
oxctl list, oxctl logs counter, curl localhost:8080, docker stop
and checks that webhook is not running before the request that
starts it. It runs in CI.

Release

Fires on a pushed tag and nothing else: static binaries for both
architectures with checksums, notes generated from the merged pull
requests, and the demo image pushed to ghcr.io.

No tag is cut in this PR. A version number is a claim about
stability, and the person making that claim should be the one typing it.

Also

Two mermaid diagrams in the README — what an init system is, and the
service state machine — and a repair to CONTRIBUTING, where an earlier
edit of mine had broken a sentence and left kernel setup instructions
contradicting the ones above them.

…rts at the beginning

Everything written so far was for somebody implementing an init system.
Nothing was for somebody deciding whether to look at one, and the
shortest path to running it needed a Rust toolchain, a musl target,
QEMU, cpio and a kernel you had to go and find.

The unit set was the problem. units/ is the test suite: a service that
fails forever, one that hangs, one that ignores SIGTERM, one that
requires something broken, one that never signals readiness. All
deliberate, all necessary, and all of it reads as a crash to somebody
seeing oxinit for the first time.

demo/ is eight files that work, each showing one idea — ordering,
readiness, logs, a schedule, socket activation. `cargo xtask demo`
builds and runs it; the published image means the first command a
newcomer types needs Docker and nothing else.

listen-probe learned to answer HTTP, so socket activation can be
demonstrated with curl. Nothing is running on port 8080; the request is
what starts the service; the reply comes back on a connection that was
never refused. That is the shortest path from "what is socket
activation" to seeing it happen.

The demo is tested, and that is the point. M13 found seven behaviours
verified once and never again, the worst of them a unit file whose
comment described a test nothing ran. A README's opening is the same
hazard with a wider blast radius, so `cargo xtask test-demo` runs every
command it gives a newcomer — oxctl list, oxctl logs counter, curl, and
docker stop — and checks that webhook is *not* running before the
request that starts it. It runs in CI.

The release workflow fires on a pushed tag and nothing else: static
binaries for both architectures with checksums, notes generated from the
merged pull requests, and the demo image to ghcr.io. No tag is cut here.
A version number is a claim about stability and the person making that
claim should be the one typing it.

Two mermaid diagrams in the README — what an init system is, and the
service state machine — and a repair to CONTRIBUTING, where an earlier
edit of mine had broken a sentence and left kernel instructions that
contradicted the ones above them.
CI found this while M16 was in review: the distribution suite failed one
assertion that had passed on main and had nothing to do with the demo.
It reproduced as a hang rather than as the missing line it reported.

A unit whose stop *completes* during a shutdown took its restart policy
and went to Restarting. `settled` waits for every unit that is not
Inactive or Failed, and nothing starts one again on the way down, so the
machine sat there until the ninety-second whole-shutdown deadline and
then went down anyway with everything already stopped.

`stop` has always cancelled a pending backoff for exactly this reason,
and the comment saying so is still there. The hole was the stop that
finishes afterwards — reachable only when the cause was a watchdog miss,
because a requested stop overrides the policy and shutdown's own stops
are requested.

Two things came out of it.

The clock that ends a test image is now anchored to the default target
rather than to the start of boot. Counting from boot made the budget the
sum of two unrelated things: how long the machine takes to come up,
which varies with the image and the host, and how long the assertions
need, which does not. M11 made boot wait for each unit to finish
activating rather than merely to be issued, and M13 and M14 added units
to wait for; the number had not moved since M5.

And the bug got a unit. `lingers` misses its watchdog thirteen seconds
after the target and ignores SIGTERM, so only cgroup.kill ends it twelve
seconds later, and the image asks for a shutdown sixteen seconds in —
inside that window with margin on both sides. Reproducing something by
luck once is not a regression test.

42 checks per architecture, 44 against the distribution image.
@youhide
youhide merged commit c0fc4b5 into main Aug 11, 2026
8 checks passed
@youhide
youhide deleted the feat/m16-demo branch August 11, 2026 19:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant