M16: a way in - #20
Merged
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
The unit set was the problem
units/is the test suite. It contains a service that fails forever, onethat hangs, one that ignores
SIGTERM, one that requires somethingbroken, 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-probelearned 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.
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-demoruns every command the README gives a newcomer —oxctl list,oxctl logs counter,curl localhost:8080,docker stop—and checks that
webhookis not running before the request thatstarts 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.