Show real mapping grammar in --help, make --via repeatable, trim comments

- -l/-r/-d now show their actual grammar as the clap value name
  (<[BIND:]PORT:HOST:PORT>, <[BIND:]PORT>) instead of a generic <SPEC>,
  matching vmic's convention of showing real syntax in --help. The
  grammar is no longer also repeated in the flag's help text, since the
  value name already carries it.
- --via changes from a single comma-separated flag to a repeatable one
  (Vec<String> + value_delimiter = ','), so both `--via a --via b` and
  `--via a,b` work and can be mixed. commands/mod.rs's edits_from_mapping
  no longer needs to split the string itself - clap does it.
- Trimmed CLI help text that restated grammar/rationale already covered
  by the value name or by --via being required.
- Normalized code comments for tone/format consistency: dropped
  cross-references to vmic's own internals as justification (this
  codebase should read as self-contained), removed markdown-style
  *emphasis* asterisks that don't render in plain comments, tightened
  several run-on sentences into plain declarative ones, and fixed one
  comment in wipe.rs that inaccurately described close_instance's force
  path (it sends SIGKILL, not SIGTERM).
- spec/porthole-spec.md's --via row updated to document the repeatable
  form alongside comma-separated.

Cargo.toml/Cargo.lock/atomic.rs also carry an external toml crate bump
and formatting pass picked up from the working tree.
This commit is contained in:
2026-08-13 17:18:33 +02:00
parent 4a8faf1131
commit 4170d51cf5
14 changed files with 105 additions and 115 deletions

View File

@@ -19,8 +19,8 @@ const STABLE_THRESHOLD_SECS: i64 = 60;
/// Consecutive unrecognized (not pattern-matched) failures before porthole
/// gives up on an apparently-permanently-broken profile - spec §4.2.
const MAX_UNRECOGNIZED_STREAK: u32 = 10;
/// How long `ssh` must stay alive before porthole calls it "connected" -
/// see `run_ssh_once`'s doc comment for why this heuristic is used at all.
/// How long `ssh` must stay alive before porthole treats it as connected;
/// see `run_ssh_once` for the heuristic this backs.
const CONNECT_GRACE: Duration = Duration::from_secs(2);
const POLL_INTERVAL: Duration = Duration::from_millis(200);
const LOG_ROTATE_BYTES: u64 = 10 * 1024 * 1024;
@@ -31,12 +31,12 @@ extern "C" fn handle_sigterm(_sig: libc::c_int) {
SHUTDOWN.store(true, Ordering::SeqCst);
}
/// Traps SIGTERM (and SIGINT, for `-f/--foreground`'s Ctrl-C - spec §5.2)
/// into a flag instead of the default terminate-immediately behavior, so
/// `close` is distinguished from a dropped `ssh` connection by *why* the
/// loop is unwinding, not by guessing from `ssh`'s exit status - which is
/// not a reliable signal either way. In foreground mode this function runs
/// in the same process the terminal sends Ctrl-C's SIGINT to, since
/// Traps SIGTERM and SIGINT into a flag instead of the default
/// terminate-immediately behavior. This is how `close` (SIGTERM) and
/// `-f/--foreground`'s Ctrl-C (SIGINT, spec §5.2) are distinguished from a
/// dropped `ssh` connection: by which signal arrived, not by inferring
/// intent from `ssh`'s exit status. In foreground mode this function runs
/// in the process the terminal sends Ctrl-C to directly, since
/// `commands::open` calls `supervisor::run` inline rather than detaching.
fn install_signal_handler() {
unsafe {
@@ -56,8 +56,9 @@ enum Outcome {
Failed { class: Class, message: String },
}
/// Entry point for `porthole __supervise <name>`. Runs until told to stop
/// (SIGTERM) or gives up per §4 - this *is* the supervisor process.
/// Entry point for `porthole __supervise <name>`. This function is the
/// supervisor process: it runs until told to stop (SIGTERM/SIGINT) or
/// gives up per §4.
pub fn run(name: &str) -> Result<()> {
install_signal_handler();
@@ -141,10 +142,10 @@ fn sleep_or_shutdown(dur: Duration) -> bool {
/// Spawns one `ssh` attempt and supervises it until it exits or shutdown is
/// requested. Marks `inst` as `State::Up` once the process has survived
/// `CONNECT_GRACE` - `ssh` gives no more reliable "the forward is actually
/// bound" signal than that without parsing `-v` debug output, and a real
/// failure exits near-instantly under `ExitOnForwardFailure=yes` (§3.1), so
/// staying alive past the grace window is a reasonable proxy for connected.
/// `CONNECT_GRACE`. `ssh` does not report "the forward is bound" directly
/// without parsing `-v` debug output; a real failure exits near-instantly
/// under `ExitOnForwardFailure=yes` (§3.1), so staying alive past the grace
/// window is used as a proxy for connected.
fn run_ssh_once(name: &str, profile: &Profile, inst: &mut Instance) -> Outcome {
rotate_log_if_large(name);