Repository navigation
docs(r10): the capstone fleet — example 41 + chapter 41 (the finale) - #10
Merged
Merged
Conversation
Working plan for the book's finale: pmon supervising chatterd + sysagent + fwatch as a capability-dropped, Landlock-sandboxed, OTLP-observed fleet across two lab VMs. Records the full subcommand contract, the vm-peer topology, the reuse map (the capstone assembles pieces already ported in ex 33/34/36/38/40), the C++/Rust dependency status (C++ ready via the ex38 conan set; Rust deps still stubbed and offline-availability of landlock/inotify crates unverified), the reference-passing approach (verify.lua against Go first, then port by subsystem), the phased steps S1-S6, and the risks. Internal plan (published: false).
Replaces the hello-syscall template check with a full local-loopback
assertion of the fleet's observable contract (following ex23's vm-peer
convention: the verify runs on 127.0.0.1, the real two-host run is the
chapter's demo). 31 assertions across:
- usage/error shapes (exit 2), incl. sysagent saturate's own usage;
- sysagent one-shot metrics line + otel-disabled;
- fwatch snapshot, watch create/modify/delete events, and the Landlock
ruleset (landlock ABI=N enforced -- kernel-level, not self-reported);
- chatterd single-node delivery, then the cross-node BRIDGE (a message
sent on node A is delivered to a listener on node B as
received from=NICK@A -- the @A tag proving it crossed);
- the pmon fleet: capability-bounding-set drop + no_new_privs, all three
services reaching health=up, clean SIGTERM shutdown, exit 0;
- OTLP telemetry: sysagent's cpu_pct gauge reaching Prometheus through
Grafana's proxy (SKIPs if LGTM down).
Verified against the Go reference through the runner: PASS 31 / FAIL 0.
S1 (contract) and S2 (go gate) done; C++/Rust ports next.
landlock 0.4 (ex33), inotify via nix (ex09), opentelemetry-otlp 0.32 (ex38), libc/anyhow — all in the cargo cache. No offline-availability risk remains for the Rust port.
Ports the ~1300-line Go fleet to C++23 across pmon/chatterd/sysagent/ fwatch/proto/caps/telemetry/util, reusing the proven C++ from ex33 (Landlock raw syscalls), ex34 (fork/exec signal-mask unblock before execv), ex36 (/proc math), ex38 (opentelemetry-cpp OTLP + NoopLogHandler + the --start-group link-cycle fix), and ex40 (RAII fd, poll shutdown). Verified on systems-target via the runner: PASS 31 / FAIL 0. pmon is a sigwait()-thread supervisor; chatterd is an RAII-socket TCP hub with the cross-node bridge (received from=NICK@node); sysagent reads /proc and pushes three OTel observable gauges (with RemoveCallback before scope exit); fwatch drives raw Landlock + inotify. Fixed a real bug in the telemetry scaffold (fields were std::shared_ptr but GetTracer/Meter return nostd::shared_ptr — would not have compiled) and the CMake otlp target names. Builds fully offline from the conan cache.
Ports the ~1300-line Go fleet to Rust (edition 2024), same file split as the C++ port, reusing ex33 (landlock crate + raw-syscall ABI probe), ex09 (nix inotify), ex36 (/proc math), ex38 (opentelemetry-otlp 0.32, base OTEL_EXPORTER_OTLP_ENDPOINT so the SDK appends /v1/*, no tracing-subscriber to keep the output contract), and ex40 (raw-fd TCP, OwnedFd, signals). Verified on systems-target via the runner: PASS 31 / FAIL 0. pmon forks/execs via nix; chatterd is a raw-fd TCP hub with the cross-node bridge (received from=NICK@node); sysagent pushes three OTel gauges with a node attribute; fwatch drives nix inotify + the landlock crate. Deps all cached offline (nix 0.31, landlock 0.4, opentelemetry-otlp 0.32, libc, anyhow). Documented divergence: opentelemetry-rust 0.32 surfaces export errors only via tracing events, so the export_errors counter stays 0 (verify asserts the other telemetry lines, not that value).
test-all-examples.py --only 41-capstone-fleet --mode vm prints PASS PASS PASS (verify.lua PASS 31/0 per language). Only chapter 41 (S6) remains.
…ete)
Writes _docs/41-capstone-fleet.md, the book's finale (part "Performance
and Low Latency"): pmon supervising chatterd + sysagent + fwatch as a
capability-dropped, Landlock-sandboxed, OTLP-observed fleet across two
hosts. Ties the six-program arc together — the supervisor (ch11-14),
the chat daemon (ch21-27), the /proc agent (ch36), the file watcher
(ch07-09/33), the two-VM lab (ch02), the sandbox layers (ch32-34), and
OTLP to the LGTM stack (ch03/38).
Three verbatim codetabs (capability-bounding-set drop, pmon's
supervise-and-restart loop, chatterd's cross-host bridge worker) across
cpp/go/rust. Adds Figures 41.1 (two-VM fleet topology) and 41.2 (pmon
supervise lifecycle) + catalogue entries.
Verified footer cites both the loopback gate (test-all-examples PASS PASS
PASS; verify.lua PASS 31/0 per language) and a real two-VM run this
session: cross-host chat received from=dave@target, both guests reaching
health=up, Landlock ABI=7 on the guest vs 9 on the host, and
sysagent_cpu_pct{node=peer}=1.75 reaching the host's Prometheus over the
libvirt gateway. Marks S6 done; the capstone (example 41 + chapter 41) is
complete. validate.py OK.
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
1 participant
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.
The book's finale:
41-capstone-fleet— pmon supervising chatterd + sysagent + fwatch as a capability-dropped, Landlock-sandboxed, OTLP-observed fleet across two hosts.Example 41 (all three languages, PASS 31/0 each)
received from=NICK@node), the pmon fleet (cap-drop, all-up health, clean shutdown), and OTLP telemetry landing in Prometheus. Proven against Go first, then held C++/Rust to it.test-all-examples.py --only 41-capstone-fleet --mode vm→ PASS PASS PASS.Chapter 41 (the finale)
Ties the six-program arc together (supervisor, chat daemon, /proc agent, file watcher, two-VM lab, sandbox layers, OTLP). Three verbatim codetabs, Figures 41.1 (topology) + 41.2 (supervise lifecycle).
Verified — including a real two-VM run
Beyond the loopback gate, a genuine two-host run this session: cross-host chat
received from=dave@target, both guests reachinghealth=up, Landlock ABI=7 on the guest vs 9 on the host, andsysagent_cpu_pct{node=peer}=1.75 reaching the host's Prometheus over the libvirt gateway.validate.py: OK.