Skip to content

T51 — Forward a box port to the laptop over the session - #1705

Merged
norrietaylor merged 12 commits into
mainfrom
agent/1643-forward-a-box-port-to-the-laptop-over-the-sessio
Sep 25, 2026
Merged

norrietaylor merged 12 commits into
mainfrom
agent/1643-forward-a-box-port-to-the-laptop-over-the-sessio

Conversation

@minimal-foundry

Copy link
Copy Markdown
Contributor

T51 — Forward a box port to the laptop over the session

slice: S12
kind: task
covers: NET-104, NET-105
size: L
est: 400 code, 260 tests
executor: agent
difficulty: needs care
model: strongest
diagnostics: the bundle's daemon log tail shows each direct-tcpip channel opened for a forward with the session and the box port
observability: one info log line per forward opened and closed on the client with the local port and the box port; one per channel on the daemon
layers:
- cli:
- crates/minimal/src/cli.rs: adds the net command with its forward subcommand
- crates/minimal/src/cmd/net.rs (new): a local listener that opens one direct-tcpip channel per accepted connection and exits when the session goes away
- crates/minimal/src/cmd/mod.rs: declares the net module and dispatches it
- crates/minimal/src/tests.rs: adds the forward to the connection inventory
- crates/minimal/tests/cli.rs: hosts the forward tests
- crates/minimal-client/src/lib.rs: a session-scoped connect and an open-direct-tcpip helper
test: cargo nextest run -p minimal net_forward_relays_over_ssh_channel
test: cargo nextest run -p minimal net_forward_closes_with_session
- daemon:
- crates/minimald/src/connection.rs: the direct-tcpip dial runs inside the box's network namespace
- crates/minimald/src/session.rs: aborts the session's forwards at teardown
test: cargo nextest run -p minimald direct_tcpip_dials_inside_box_netns
- docs:
- docs/reference/cli-min.md: documents net forward
produces: none
consumes: none
proof: min net forward web 8080:3000 answers on localhost:8080 over the session and closes with it.
depends on:
- blocked by #1628

Proof

min net forward web 8080:3000 now answers on localhost:8080: it binds the laptop-side loopback, relays each accepted connection over its own direct-tcpip channel on the session's SSH connection to 127.0.0.1:3000 in the box (dialed from inside the box's network namespace for sessions that have their own), and ends on Ctrl-C or when the session goes away, closing the listener, the open relays, and the daemon-side channels with it.

Notes from the agent: The in-box dial for isolated sessions (none/own_ip) runs through HostHandle::command_in_session — the nsenter injection joining the box's namespaces — as an injected socat - TCP:<host>:<port>,connect-timeout=10 relaying the box port onto its piped stdio, which a ChildStdio adapter presents as the relay's stream. socat is a launcher-baseline package (BASELINE_PACKAGES), so every box has it. host_ip sessions keep the daemon's direct dial, so existing semantics (reject with ConnectFailed when the box port refuses) are unchanged there. The daemon test asserts the in-box path via the cfg(test) host-side stand-in for the injected command (MockLauncher); the production path is the same code, but an e2e run against a real box would be the belt-and-braces proof. Also run and green alongside the three test: lines: cargo nextest run -p minimald direct_tcpip (both handler tests), -p minimal every_daemon_connection_is_classified + cli_command_tree_stays_renderable + cli_reference (inventory and docs guards). Clippy is clean on -p minimal and -p minimald, all targets. No files outside the layers were touched.

Tests

line exit tail
cargo nextest run -p minimal net_forward_relays_over_ssh_channel 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-a0f2... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/3be18/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/3be18/tree/crates/args) C
cargo nextest run -p minimal net_forward_closes_with_session 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-ae9c... Compiling stdlib v0.0.20 (/home/runner/.local/state/minimal/sessions/316e2/tree/crates/stdlib) Compiling version v0.6.0 (/home/runner/.local/state/minimal/sessions/316e2/tree/crate
cargo nextest run -p minimald direct_tcpip_dials_inside_box_netns 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-a133... Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/e0701/tree/crates/args) Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/e0701/tree/crates/ot) C

Verify

min task run agent-verify passed ([tasks.verify]).

Base

The base branch moved while the coder worked; it was merged in before the tests ran.

Closes #1643

NET-104: bind localhost:<LOCAL> and relay each accepted connection over
the session's SSH channel to 127.0.0.1:<PORT> in the box, on a
session-scoped connection whose SSH username is the session's UUID so
the daemon knows which box's loopback to dial.

NET-105: the forward stays in the foreground and ends on Ctrl-C or when
its session goes away, taking the listener and every open relay with it.

minimal-client grows the session-scoped connect and the open-direct-tcpip
helper the forward runs on. One info line logs each connection opened and
closed with the local port and the box port; a banner on stderr tells the
person at the terminal the same.
A session with its own netns (`none`, `own_ip`) has a loopback of its
own, so a daemon-side dial would reach the daemon rather than the box. The
dial now goes through the one sanctioned door into the box's namespaces — a
command run in-session — where socat, a baseline package in every box,
relays the box port onto the piped stdio the channel relays against.
`host_ip` boxes keep the daemon's direct dial.

The channel-open info line now records where the dial ran, alongside the
session and the box port it names today.

The session actor also tracks each forwarded relay and aborts them at
teardown, so a session that stops or is destroyed takes its forwards'
channels down with it (NET-105).
The new `min net forward <SESSION> <LOCAL>:<PORT>` section: what it
binds, what it dials (the box's own loopback, from inside the box's netns),
and that the forward ends with its session or a Ctrl-C.
@coderabbitai

coderabbitai Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: f018ec51-0183-4d0d-b486-60da7c296fb6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

@minimal-foundry

minimal-foundry Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor Author

Approved: no findings at 4532625a175a.

Nothing to do.

Verdict APPROVE, posted as a comment: the App cannot review its own pull request; the check and the label carry it.

Clobber: none: git log on the touched files shows no reverted fix, and the refactor of Client::connect into connect_as preserves the minimal-cli username and the retry/handshake behavior verbatim.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approved

Verdict APPROVE — No findings.

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Sep 25, 2026
@norrietaylor

Copy link
Copy Markdown
Member

Babysitter review of 102f5eb against the T51 plan block on #1643. All nine layer intents are met with evidence, no files outside the layers, observability line met (forward opened/closed plus one line per connection with local and box ports; the daemon's open line carries dial=). minimal-review approved with no findings. Verdict: REVISE.

High — the tests job failure is this PR's, deterministic. 2210 of 2211 pass; the one failure is the PR's own test line connection::tests::direct_tcpip_dials_inside_box_netns (crates/minimald/src/connection.rs:1066, ChannelOpenFailure(ConnectFailed)). The test uses a none-mode session, so the daemon takes the new dial_in_box path; under cfg(test) command_in_session (session_host.rs:2532) builds a plain host command, socat, and the ubuntu runner has no socat, so the spawn fails ENOENT and dial_in_box maps it to ConnectFailed (connection.rs:714,734). The status comment showed exit 0 only because the coder's tests ran inside a Minimal session, where socat is a baseline package. Fix in the test or behind the cfg(test) seam: inject the relay program (a shell stand-in on the command's PATH that echoes stdio), not a self-skip when socat is absent, which would hide the failure.

Medium — the in-box path has no real-box proof. Both minimal tests use HostNet, so they exercise only the daemon's direct dial; the none/own_ip path (nsenter plus socat inside the box) is proven only through the mock. docs/reference/cli-min.md still says the command works for every network mode. Either a root-integration proof of one in-box forward, or the doc says which modes are proven.

Low

  • socat's default -t 0.5 closes half a second after the laptop side half-closes, so a slow reply is cut short; pass an explicit longer -t or use -T-free bidirectional shutdown.
  • ensure_host launches the host of a stopped none/own_ip session, so a forward can boot a stopped box; and the client poll only checks the session is listed, so the forward survives min stop and ends only on destroy. Say which is intended for NET-105.
  • open_direct_tcpip is awaited inside the accept arm (crates/minimal/src/cmd/net.rs:91), blocking accept and the session poll while it waits; spawn it.
  • The relay handle list (net.rs:59) is never pruned, so it grows for the life of a long forward.

Round 1 is running on the failed suite. The /revise for the rest follows when it lands.

The direct-tcpip in-box-dial test spawned its relay through the
harness's host-side stand-in for the in-session command, and the host is
not a box: socat is a baseline package in every box, but a bare CI
runner (ubuntu-latest) ships none, so on one the dial had nothing to
spawn — the tests job red while every host with socat installed stayed
green, which is how the failed suite read.

The dial now resolves socat through a PATH the test publishes
(MINIMALD_TEST_RELAY_PATH), pointing at a stand-in implementing exactly
the argv the production dial passes, with the ambient PATH behind it.
Production is unchanged: it still layers nothing over the session's
environment and runs the box's own socat.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Comment thread crates/minimal/src/cmd/net.rs Resolved
@minimal-foundry minimal-foundry Bot removed the review:approved minimal-review approved the current head label Sep 25, 2026
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 1 of 10 on a failed check suite, pushed as 33622dba8e07.

line exit tail
cargo nextest run -p minimal net_forward_relays_over_ssh_channel 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-de81... Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/342ef/tree/crates/args) Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/342ef/tree/crates/ot) C
cargo nextest run -p minimal net_forward_closes_with_session 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-6836... Compiling stdlib v0.0.20 (/home/runner/.local/state/minimal/sessions/c8a91/tree/crates/stdlib) Compiling version v0.6.0 (/home/runner/.local/state/minimal/sessions/c8a91/tree/crate
cargo nextest run -p minimald direct_tcpip_dials_inside_box_netns 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-57ef... Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/06963/tree/crates/ot) Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/06963/tree/crates/args) C

Verify min task run agent-verify passed.

min net forward web 8080:3000 still answers on localhost:8080 over the session and closes with it, and the daemon-side in-box-dial proof now runs on a bare host — the CI runner ships no socat, and the test no longer needs one — so the workspace 'tests' lane the PR failed on goes green.

Notes from the agent: Diagnosis of the failed checks (tests job -> ci-linux-native-success): everything in the job passed on this box, and the branch's only environmental delta was direct_tcpip_dials_inside_box_netns spawning the production socat through the harness's host-side stand-in for the in-session command — the mock session's empty environment makes the bare name resolve through the libc default path /bin:/usr/bin, and ubuntu-latest (verified against the current actions/runner-images Ubuntu 24.04 package list) installs no socat, so on the runner the dial had nothing to spawn and the channel open was rejected. Fix, inside connection.rs only: dial_in_box now calls command_in_session_env, whose extra env is empty in real builds (identical to the old two-argument call) and, under cfg(test), carries the PATH published in MINIMALD_TEST_RELAY_PATH; the test writes a bash stand-in named socat implementing exactly the argv the dial passes ('-' and 'TCP:host:port,connect-timeout=10'), points the dial at it ahead of the ambient PATH, and restores the variable on exit. A negative control (sabotaged stand-in makes the test fail even on this socat-equipped box) confirmed the daemon invokes the stand-in, not the host's socat, so the proof is identical on every host. Production dialing is unchanged: real builds run the box's own baseline socat with the session's environment and nothing layered. native-daemon-e2e and minimald-root-integration were green on the PR and are untouched by this cfg(test)-only change (the bin build is byte-for-byte the same behavior). The one leaky test in the suite predates this branch (present on main; leaks do not fail a nextest run). No deferre…[truncated]

@norrietaylor

Copy link
Copy Markdown
Member

/revise Round 1 (2a1d79f) fixed the High the right way: the socat stand-in rides the cfg(test) seam through a test-only PATH layer, the production dial still inherits the session environment and nothing else, and the tests job is green at 33622db. The rest of the review at 102f5eb stands, plus minimal-review's Low, which is the same item as the last one below.

  1. Medium: no real-box proof for the in-box path. Both minimal tests use HostNet, so the daemon's none/own_ip dial (nsenter plus socat inside the box) is proven only through the mock. Add one root-integration proof of an in-box forward (a none session, a listener in the box, bytes through min net forward), or say in docs/reference/cli-min.md that only the host-address mode is proven end to end.
  2. Low: socat's default -t 0.5 closes half a second after the laptop side half-closes, so a slow reply is cut short. Pass an explicit longer -t on the dial's argv.
  3. Low: ensure_host launches the host of a stopped none/own_ip session, so a forward can boot a stopped box; and the client poll only checks the session is listed, so the forward survives min stop and ends only on destroy. Decide which is intended for NET-105, implement it, and state it in the command's reference.
  4. Low: open_direct_tcpip is awaited inside the accept arm (crates/minimal/src/cmd/net.rs:91), so one slow channel open blocks accept and the session poll. Spawn the open with the relay.
  5. Low (minimal-review, net.rs:112): the relay handle list is never pruned while the forward runs. Retain only unfinished handles on each accept, or use a JoinSet.

Keep the three plan test lines green.

socat's -t defaults to 0.5 s: the moment the laptop side half-closes,
socat shuts the box port's write half down and gives the box's reply
half a second to arrive before exiting, so a reply slower than that is
cut short. The dial now passes an explicit 5 s linger — generous without
holding a dead relay open, since every other end of the dial is bounded
by the box's own refusal, the channel closing, or the child's
kill_on_drop.

The harness stand-in now picks the TCP: address out of its argv by
prefix rather than position and records that argv where the test reads
it, so the test pins the production dial argv — the linger, the stdio
relay, and the box port's address — instead of only that bytes moved.
The channel open moved out of the accept arm into each accepted
connection's own task, so a slow open — a box being brought up for that
connection — delays only its own connection instead of stalling the
listener and the session poll behind it. The scoped SSH connection is
shared behind a mutex, because it answers one channel open at a time;
the relays, once open, still run beside each other.

The relay handle list now keeps live handles only, pruning finished ones
on each accept rather than accumulating one per connection until the
whole forward ends — the same shape the daemon's forward tracking
already uses.

The session poll names which ending it saw: a session that is no longer
listed is its own case, and a list that fails means the daemon is gone,
which is a different ending than the session's and now says so on the
console (the cause goes to the log).

The forward's contract is stated where it lives: it follows the session,
not the box's process, so a box that is down is brought up to serve the
forward exactly as attach brings one up, and what ends it is the session
ending, the daemon going away, or a Ctrl-C.

A new test covers the restructured arm: a connection whose box port
refuses costs that connection alone, and the next connection, once the
box port has a listener, relays through the same forward.
Two things the reference now says about `net forward`:

The forward follows the session, not the box's process. A session whose
box is down is brought up to serve the forward, exactly as attach
brings one up, because a record that outlives its box is the normal
state after `stop` — which keeps records — and a forward that refused
would be stranded against every session that survived a daemon
restart. What ends a forward is a destroy, the daemon going away, or a
Ctrl-C; `stop` is not a destroy and ends a forward only because the
daemon's exit does.

The host-address mode is what the tree proves end to end; the in-box
dial the isolated modes take is exercised by the daemon's harness with a
host-side stand-in relay, and a root-integration proof of that leg is
still owed to the root lane.
A connection whose box port refuses is dropped by the forward with the
bytes the client already sent still unread in its receive queue, and a
socket dropped that way resets rather than ending cleanly — so which of
the two the client sees depends on which side of the race its bytes land
on. Both mean the connection is over, which is what the test pins.
The lifecycle note said every session whose box is down is brought up
to serve the forward. That is only the isolated modes: their dial runs
inside the box's own network namespace, so the daemon mints the box
exactly as session exec does, while a host_ip dial runs from the
daemon's own namespaces — the one the box shares — where no box needs
to exist, so an unstarted session answers with a refused connection.

The channel paragraph claimed the same dial site for every mode, which
was false for host_ip; both it and the reference now say where each
mode's dial runs.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approved

Verdict APPROVE — No findings.

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Sep 25, 2026
@minimal-foundry

Copy link
Copy Markdown
Contributor Author

Round 2 of 10 on a /revise note, pushed as 4532625a175a.

line exit tail
cargo nextest run -p minimal net_forward_relays_over_ssh_channel 0 Applying loadouts: default Running task runtime-implement-test-0 in session task-runtime-implement-test-0-3fc7... Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/7d8e1/tree/crates/args) Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/7d8e1/tree/crates/ot) C
cargo nextest run -p minimal net_forward_closes_with_session 0 Applying loadouts: default Running task runtime-implement-test-1 in session task-runtime-implement-test-1-f2a1... Compiling stdlib v0.0.20 (/home/runner/.local/state/minimal/sessions/02a12/tree/crates/stdlib) Compiling version v0.6.0 (/home/runner/.local/state/minimal/sessions/02a12/tree/crate
cargo nextest run -p minimald direct_tcpip_dials_inside_box_netns 0 Applying loadouts: default Running task runtime-implement-test-2 in session task-runtime-implement-test-2-2d16... Compiling args v0.0.1 (/home/runner/.local/state/minimal/sessions/beb48/tree/crates/args) Compiling ot v0.0.1 (/home/runner/.local/state/minimal/sessions/beb48/tree/crates/ot) C

Verify min task run agent-verify passed.

Review threads the coder judged:

  • 👍 valid — PRRT_kwDOPdfcxM6l_eAP: Pruned the relay handles with relays.retain(|h| !h.is_finished()) on each accept, so the vec holds live relays only, matching the daemon's TrackForward pattern. (not posted on the thread: not an open thread on the pull request)

min net forward web 8080:3000 answers on localhost:8080 over the session and closes with it, and docs/reference/cli-min.md now states the forward's lifecycle: it follows the session record (ending on destroy, daemon loss, or Ctrl-C), boots a box for the dial only where the dial must run inside the box's own namespace, and keeps accepting while a channel opens.

Notes from the agent: Review item 1 (the Medium) was resolved with the directive's second option, not the first: a real-box root-integration proof needs a new crates/minimald/tests/*root_integration.rs harness, which is outside this task's layers, so docs/reference/cli-min.md says what the tree proves — the host-address mode end to end, the in-box leg only through the daemon harness test with a host-side stand-in — and that the root lane still owes the in-box proof. Review item 3 was decided as: the forward keys on the session record, so a min stop that succeeds ends it (the daemon's exit does), and a stopped box is brought up for a dial only in the isolated modes, whose dial must run inside the box's namespace — exactly as min session exec does; a host_ip dial runs in the namespace the box shares with the daemon and needs no box up, so an unstarted session answers with a refused connection. Both halves are stated in the reference and the command's doc comment, and the poll now distinguishes a destroyed session from a lost daemon. Item 2 gave the in-box socat dial an explicit -t5 linger, pinned by the daemon test's argv assertions. Item 4 moved the channel open into the per-connection task (the scoped client is shared as Arc<tokio::sync::Mutex<>> because russh's Handle is not Clone), so a slow open no longer holds the accept arm or the session poll. Item 5 is the judged thread below. The new refused-dial test accepts either EOF or ECONNRESET: the forward drops the accepted socket with the client's bytes unread and Linux may close with a reset rather than a FIN — both endings are the same observa…[truncated]

@norrietaylor norrietaylor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Round 2 verified against the plan block for T51: explicit socat linger with the argv pinned in the harness test, channel open moved into the per-connection task with a refused-dial test, live relay handles only, and the forward's lifecycle decided and documented (follows the session record; isolated modes boot the box for the dial; host-address proven end to end, in-box leg via the stand-in with the root proof owed). minimal-review approves the head, no open threads, three plan test lines green.

@norrietaylor
norrietaylor enabled auto-merge (squash) September 25, 2026 13:19
@norrietaylor
norrietaylor merged commit 93dad7e into main Sep 25, 2026
33 checks passed
@norrietaylor
norrietaylor deleted the agent/1643-forward-a-box-port-to-the-laptop-over-the-sessio branch September 25, 2026 13:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved minimal-review approved the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

T51 — Forward a box port to the laptop over the session

1 participant