nordisk/Skidbladnir

Sockets — guide

Design: socket-deployment.md. Feature: sockets (off by default).

skidbladnir = { version = "0.1", features = ["sockets"] }

The whole lifecycle

use skidbladnir::socket::{socket_for, BuildThingType, Mode, FixtureKind, FixtureHealth};

// 1. Type in, socket out. No per-cell config — this is the registry the pane calls.
let ty = BuildThingType::from_kind("tunnr-appliance").unwrap();   // from build-variants.toml
let socket = socket_for(ty);

// 2. The plan + topology render BEFORE anything boots (so the pane is never empty).
let plan = socket.plan(Mode::Test);
for row in plan.topology() {
    println!("{:<16} {:<28} {}", row.kind.as_str(), row.detail,
             row.endpoint.as_deref().unwrap_or("-"));
}

// 3. Light it. Fixtures are realized; health is Ready / NotApplicable / Down / NotImplemented.
let mut dep = socket.light(Mode::Test);
let netdev = dep.qemu_netdev_arg().expect("this socket runs on a shared net");
// -> "user,id=n0,net=10.9.0.0/24,host=10.9.0.1,restrict=off,dhcpstart=10.9.0.100,dns=10.9.0.1"
// Prepend `-netdev ` and pair it with `-device virtio-net` on the guest.

// 4. The operator adds a WireGuard key (Test mode only).
dep.add_wg_peer(peer_pubkey_b64, Some("10.9.0.1:51820".into()), vec!["10.9.0.0/24".into()])?;

// 5. Feed the captured boot console back in. THIS is what turns things green.
dep.confirm(&console);
assert_eq!(dep.fixture(FixtureKind::Dhcp).unwrap().health, FixtureHealth::Serving);

// 6. Assert against the node.
for probe in socket.probes() {
    let v = probe.run(&console);
    println!("{}: {} — {}", v.probe, if v.passed { "PASS" } else { "FAIL" }, v.detail);
}

// 7. Render, then tear down (consumes it; the operator's keys go with it).
let json = dep.json();
let order = dep.teardown();

Reading the health of a fixture

dep.all_ok() is true only if every fixture is in the top three. dep.refusals() gives you (kind, why) for the bottom two — render that, not a spinner. Every why carries a TO FIX: clause (socket::REMEDY_MARKER); split on it to show the remedy as its own line.

Reading the evidence

confirm() classifies the console per fixture into an Evidence:

The readers are public and independently testable: NetSpec::dhcp_evidence, wg_evidence, dns_evidence, plus NetSpec::leased_address / in_dhcp_pool and parse_handshake_age_secs.

WireGuard peer states

Handshake::STALE_AFTER_SECS is 180 — WireGuard's own REJECT_AFTER_TIME. Staleness can only be detected when the console carries a wg show capture (latest handshake: … ago); a plain boot console has no age signal, so confirm records the observation as fresh.

Adding things

A fixture: impl Fixture (at minimum kind(); override runtime() and light_health() if it has preconditions or its own runtime) → add one arm to fixture_for_kind. If a socket should compose it, add the kind to that socket's arm in SocketPlan::for_type. Nothing else — the plan and the deployment stay in lockstep automatically.

A socket: add an arm to SocketPlan::for_type (its fixture list, console count) → impl Socket (usually just accepts + plan; override probes() if it has cluster-level assertions) → add an arm to socket_for. Zero pane changes.

A probe: impl Probe { fn name(&self) -> &str; fn run(&self, console: &str) -> ProbeVerdict } → return it from the relevant socket's probes().

A network backend: impl NetworkBackend. Override is_test_grade() -> false only if it really is production-fit — the default is true, and Mode::Prod refuses every fixture a test-grade backend realizes.

Gotchas

• light() never returns Serving. If you expected green and got Ready, you have not called confirm() with a console yet.
• Mode::Prod on TunnrTestSocket is all_ok() == false on purpose. The only net backend is slirp, which is test-grade. Read refusals(); it explains each one. See the design doc.
• net is an Option. Single-boot sockets (exe/console/kvm/iso/container) have none, and qemu_netdev_arg() returns None for them.
• confirm() can go backwards. Failure evidence downgrades even a Serving fixture, and takes the peer rows with it (Established → Lost). Deliberate: a tunnel that dropped is not still serving.
• Silence changes nothing. An uninformative console leaves every fixture exactly as it was — and Evidence::Unknown(why) tells you what it looked for.
• An attempt is not a success. udhcpc: broadcasting select for 10.9.0.157 is a DHCPREQUEST, not a lease; Sending handshake_initiation is not a completed handshake. If you are writing a fake console for a test, use lease of … obtained and Received handshake_response, or crib from the transcripts module.
• A stale handshake is not up. Past 180 s (REJECT_AFTER_TIME) is_up() is false.