5329b286

feat: the handoff's policy is a step table, not a shape in the driver

a73x 2026-08-29 15:55

Commit message

feat: the handoff's policy is a step table, not a shape in the driver

Which transport to try, in what order and when to give up lived inline
between the effects that perform it — a dial, a spawn, a read, a cache
write — so the only way to reach a row of it was a daemon, an ssh shim and
a blackholed UDP port. Every row now tests as a function call.

`handoff.next` is the whole policy: a phase, the outcome the last step
produced, and the next step to take. The driver is unchanged and does not
call it yet.

Each of the fifteen rows is one named test, and each was mutation-proven
against this commit: flipping the row fails the test that names it, by
name, and nothing else.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017wi2HnuF1EK8HgViU11YLV

src/client/handoff.zig

@@ @@ -1,8 +1,9 @@ @@
+//! The ssh→QUIC handoff's shared vocabulary: the announce line
+//! `mux d endpoint` prints and `mux` parses, the per-host cache file that
+//! remembers it, the strip that turns an ssh destination into a dialable
+//! host, and the step table `next` that orders a handoff out of them.
+//! Pure by design — no sockets, no processes — so the whole surface, the
+//! policy included, tests without a daemon.
+const std = @import("std");
+// Only for the private-parent discipline the cache file shares with the
+// key file. No XDG resolution happens here: writeCache is handed a path.
@@ @@ -344,6 +345,151 @@ pub fn readCache(path: []const u8) !Endpoint { @@
+    return ep orelse error.CacheMalformed;
+// ------------------------------------------------------------ the policy
+// `client.Transport.openHandoff` performs what these steps name, and owns
+// every effect. Each row below is one named test in this file.
+/// One effect for the driver to perform, or the transport it ends on.
+pub const Step = union(enum) {
+    /// Dial these coordinates: `client.Transport.openQuicEndpoint`.
+    dial_quic: Endpoint,
+    /// Run the coordination ssh: `spawnPipe` on the asking argv when the
+    /// user asked and there is one, on the reading argv otherwise.
+    spawn_ssh,
+    /// Read the announce line off that child's stdout.
+    read_announce,
+    /// Remember these coordinates under `cache_write_mu`. A write that
+    /// fails costs a cold attach and nothing else, so its outcome is
+    /// always `.done`.
+    write_cache: Endpoint,
+    /// Terminal: the transport the last dial returned. The driver kills
+    /// the coordination ssh, if it started one.
+    use_quic,
+    /// Terminal: the live ssh child IS the session. True asks for the
+    /// fallback line.
+    ///
+    /// These arms are not a leftover of a bygone network. Through
+    /// `ssh -J gate box` the announced UDP port is unreachable from here
+    /// BY CONSTRUCTION — the jump host is the only route and it carries
+    /// TCP — so the pipe is the only session such a host can ever have.
+    /// Every one of them takes this step.
+    use_pipe: bool,
+    /// Terminal: the error the driver recorded for the step that failed.
+    fail,
+};
+/// What performing a step produced. One vocabulary for all of them: which
+/// arms a step can answer with is the table's business, and an arm no
+/// phase expects is a driver bug rather than an input.
+pub const Outcome = union(enum) {
+    /// `dial_quic` connected, or `spawn_ssh` forked and exec'd.
+    ok,
+    /// The abort key landed inside a dial's wait.
+    user_abort,
+    /// `dial_quic` never came up, or `spawn_ssh` could not start.
+    failed,
+    /// `read_announce`: coordinates.
+    announced: Endpoint,
+    /// `read_announce`: `endpoint none`, the remote saying it has none.
+    none,
+    /// `read_announce`: no line at all — a dead pipe, junk, an abort.
+    announce_failed,
+    /// `write_cache`, always.
+    done,
+};
+/// How far the handoff has got. The driver builds one from its target and
+/// its cache read, then hands it to `next` and touches nothing in it.
+pub const State = struct {
+    /// The coordinates the cache held; null when there is nothing usable
+    /// to try before ssh.
+    cached: ?Endpoint,
+    /// Whether a USER asked for this dial — `client.HandoffTarget.asked`.
+    /// Here it decides one thing: whether the fallback says so out loud.
+    asked: bool,
+    /// Whether there is a cache file to write. Distinct from `cached`: a
+    /// path holding nothing usable is a cold attach that still caches.
+    has_cache: bool,
+    /// The announce being decided on. `write_cache` sits between reading
+    /// one and choosing what to do with it, so it has to outlive that
+    /// step; the phase alone cannot carry it.
+    announced: ?Endpoint = null,
+    phase: enum { init, warm_dial, ssh, announce, cache, cold_dial } = .init,
+};
+/// The next step, given what the last one produced. `null` is the first
+/// call, which has produced nothing yet.
+///
+/// An (outcome, phase) pair no row covers is `unreachable`: the driver is
+/// the only caller, it answers each step from a fixed set, and a pair
+/// outside the table is a bug in the loop rather than input to judge.
+pub fn next(s: *State, o: ?Outcome) Step {
+    const outcome = o orelse {
+        std.debug.assert(s.phase == .init);
+        if (s.cached) |ep| {
+            s.phase = .warm_dial;
+            return .{ .dial_quic = ep };
+        }
+        s.phase = .ssh;
+        return .spawn_ssh;
+    };
+    switch (s.phase) {
+        .init => unreachable,
+        .warm_dial => switch (outcome) {
+            .ok => return .use_quic,
+            .user_abort => return .fail,
+            // ssh is authoritative, so a dead cache is a question it
+            // answers rather than a failure. What the miss cost depends
+            // on how the coordinates were dead: a resolve failure and a
+            // REFUSED port are both instant, while anything SILENT
+            // (blackholed UDP, a listener holding another key) spent the
+            // whole of `deadline_ms` first.
+            .failed => {
+                s.phase = .ssh;
+                return .spawn_ssh;
+            },
+            else => unreachable,
+        },
+        .ssh => switch (outcome) {
+            .ok => {
+                s.phase = .announce;
+                return .read_announce;
+            },
+            .failed => return .fail,
+            else => unreachable,
+        },
+        .announce => switch (outcome) {
+            .none => return .{ .use_pipe = false },
+            .announce_failed => return .fail,
+            .announced => |ep| {
+                if (s.has_cache) {
+                    s.announced = ep;
+                    s.phase = .cache;
+                    return .{ .write_cache = ep };
+                }
+                return afterAnnounce(s, ep);
+            },
+            else => unreachable,
+        },
+        .cache => switch (outcome) {
+            .done => return afterAnnounce(s, s.announced.?),
+            else => unreachable,
+        },
+        .cold_dial => switch (outcome) {
+            .ok => return .use_quic,
+            .user_abort => return .fail,
+            .failed => return .{ .use_pipe = s.asked },
+            else => unreachable,
+        },
+    }
+}
+/// What a fresh announce is worth, once it is safely cached.
+fn afterAnnounce(s: *State, ep: Endpoint) Step {
+    s.phase = .cold_dial;
+    return .{ .dial_quic = ep };
+}
+test "announce: format → parse round-trip, with and without the newline" {
+    var buf: [announce_max_len]u8 = undefined;
+    try std.testing.expectError(CacheError.CacheMalformed, readCache(path));
+/// One step as a word. A failing row prints the step a reader can compare,
+/// not a struct dump; the endpoint shows its port and the first byte of its
+/// key, which is enough to tell two announces apart.
+fn stepStr(buf: []u8, st: Step) ![]const u8 {
+    return switch (st) {
+        .dial_quic => |ep| std.fmt.bufPrint(buf, "dial_quic {d}/{x:0>2}", .{ ep.port, ep.key[0] }),
+        .spawn_ssh => std.fmt.bufPrint(buf, "spawn_ssh", .{}),
+        .read_announce => std.fmt.bufPrint(buf, "read_announce", .{}),
+        .write_cache => |ep| std.fmt.bufPrint(buf, "write_cache {d}/{x:0>2}", .{ ep.port, ep.key[0] }),
+        .use_quic => std.fmt.bufPrint(buf, "use_quic", .{}),
+        .use_pipe => |say| std.fmt.bufPrint(buf, "use_pipe({s})", .{if (say) "line" else "silent"}),
+        .fail => std.fmt.bufPrint(buf, "fail", .{}),
+    };
+}
+fn expectStep(want: []const u8, got: Step) !void {
+    var buf: [64]u8 = undefined;
+    try std.testing.expectEqualStrings(want, try stepStr(&buf, got));
+}
+// Two announces differing in BOTH halves, so a row that compares only ports
+// and a row that compares only keys are equally wrong. One note over the
+// pair: neither endpoint means anything without the other.
+fn epA() Endpoint {
+    return .{ .port = 4433, .key = [_]u8{0xab} ** key_len };
+}
+fn epB() Endpoint {
+    return .{ .port = 5000, .key = [_]u8{0xcd} ** key_len };
+}
+test "handoff step: a usable cache is dialled before anything else runs" {
+    var s: State = .{ .cached = epA(), .asked = false, .has_cache = true };
+    try expectStep("dial_quic 4433/ab", next(&s, null));
+}
+test "handoff step: nothing cached starts at the ssh run" {
+    var s: State = .{ .cached = null, .asked = false, .has_cache = true };
+    try expectStep("spawn_ssh", next(&s, null));
+}
+test "handoff step: a warm dial that connected IS the session" {
+    var s: State = .{ .cached = epA(), .asked = false, .has_cache = true, .phase = .warm_dial };
+    try expectStep("use_quic", next(&s, .ok));
+}
+test "handoff step: the abort key inside the warm dial asked to stop, not to try the next thing" {
+    var s: State = .{ .cached = epA(), .asked = true, .has_cache = true, .phase = .warm_dial };
+    try expectStep("fail", next(&s, .user_abort));
+}
+test "handoff step: a warm dial that failed hands the question to ssh, which is authoritative" {
+    var s: State = .{ .cached = epA(), .asked = false, .has_cache = true, .phase = .warm_dial };
+    try expectStep("spawn_ssh", next(&s, .failed));
+}
+test "handoff step: an ssh that could not start ends the handoff" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .ssh };
+    try expectStep("fail", next(&s, .failed));
+}
+test "handoff step: the ssh that came up is read for its announce" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .ssh };
+    try expectStep("read_announce", next(&s, .ok));
+}
+test "handoff step: `endpoint none` is the ssh pipe, and says nothing about it" {
+    // Even for a user who ASKED: no coordinates were ever in play, so
+    // there is nothing to report as unreachable.
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .announce };
+    try expectStep("use_pipe(silent)", next(&s, .none));
+}
+test "handoff step: an announce that never arrived ends the handoff" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .announce };
+    try expectStep("fail", next(&s, .announce_failed));
+}
+test "handoff step: an announce is cached BEFORE it is dialled" {
+    // The coordinates are true whether or not UDP can carry them. A client
+    // that cached only what it reached would leave every jump-host route
+    // permanently cold.
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .announce };
+    try expectStep("write_cache 5000/cd", next(&s, .{ .announced = epB() }));
+}
+test "handoff step: a host with nowhere to cache dials the announce straight away" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = false, .phase = .announce };
+    try expectStep("dial_quic 5000/cd", next(&s, .{ .announced = epB() }));
+}
+test "handoff step: the announce that was just cached is the one dialled" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .cache, .announced = epB() };
+    try expectStep("dial_quic 5000/cd", next(&s, .done));
+}
+test "handoff step: a cold dial that connected IS the session" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .cold_dial };
+    try expectStep("use_quic", next(&s, .ok));
+}
+test "handoff step: the abort key inside the cold dial ends the handoff" {
+    var s: State = .{ .cached = null, .asked = true, .has_cache = true, .phase = .cold_dial };
+    try expectStep("fail", next(&s, .user_abort));
+}
+test "handoff step: a cold dial that failed is the ssh pipe, and only the user who asked hears why" {
+    // A reconnect re-runs this recipe forever against dropped UDP: one
+    // line per retry would scroll a live session's stderr into the
+    // alternate screen to say what the reconnecting banner already says.
+    for ([_]bool{ false, true }) |asked| {
+        var s: State = .{ .cached = null, .asked = asked, .has_cache = true, .phase = .cold_dial };
+        try expectStep(if (asked) "use_pipe(line)" else "use_pipe(silent)", next(&s, .failed));
+    }
+}
+// Forces semantic analysis of every pub decl under `zig build test`, so an
+// unreferenced decl must at least compile (the silent-module-loss hazard,
+// decisions.md). Pub decls only: std.meta.declarations sees nothing private.