Skip to content

feat(ssh): add connection multiplexing runtime (#286) - #312

Merged
inureyes merged 1 commit into
mainfrom
feature/issue-286-connection-multiplexing
Aug 31, 2026
Merged

inureyes merged 1 commit into
mainfrom
feature/issue-286-connection-multiplexing

Conversation

@inureyes

Copy link
Copy Markdown
Member

Summary

  • Add a private same-user Unix control socket runtime that reuses one authenticated SSH transport for multiple passenger session channels.
  • Resolve ControlMaster, ControlPath, and ControlPersist from CLI and ssh_config with OpenSSH-compatible precedence, integer duration parsing, required path token expansion, explicit ControlPath none, and actionable path-length errors.
  • Support -M, -O check|forward|cancel|exit|stop, long-form --control-path, runtime local/remote/dynamic forwarding changes, graceful stop, immediate exit, and finite persist timer reset.
  • Bound control handshakes, confirmation waits, frame sizes, data chunks, and concurrent handlers; verify peer credentials; preserve non-socket paths; and fall back before session submission when a master is dead or unresponsive.

Implementation notes

The control protocol is a versioned bssh-to-bssh protocol rather than OpenSSH mux v4. Passenger attach is attempted before key selection, password prompting, or network authentication, and LocalCommand remains in the invoking process after a compatible handshake.

Independent audit findings were incorporated for repeated -M semantics, ControlPath none, strict ControlPersist parsing, dead-master timeout fallback, passenger TERM propagation, stalled-handler limits, child-task cancellation, and remote-forward cancellation error reporting.

Validation

  • cargo fmt --all -- --check
  • cargo check --lib --bin bssh
  • cargo clippy --lib --bin bssh --test control_multiplexing_live_test --no-deps -- -D warnings
  • cargo test --lib — 1,684 passed, 7 ignored
  • cargo test --test control_multiplexing_live_test — 3 passed
  • cargo test --test forwarding_live_test — 9 passed

Dependency boundary

Refs #286. This PR intentionally does not auto-close the issue: the canonical -S/-N/-f invocation, persistent-master background lifecycle, and pinned regression harness gates depend on the short-flag/background work in #287. The #287 delivery will close both issues after those combined acceptance criteria pass.

Add a private Unix control socket protocol that reuses one authenticated SSH transport for passenger sessions and runtime forwarding control.

Implement typed ControlMaster, ControlPath, and ControlPersist policy resolution, bounded same-user handshakes, stale-socket handling, exact forwarding registration, and check, forward, cancel, exit, and stop commands.

Cover authentication reuse, persist timer reset, graceful and immediate shutdown, socket safety, parser boundaries, and forwarding teardown with unit and live SSH tests.

Refs #286
@inureyes inureyes added status:review Under review type:enhancement New feature or request priority:medium Medium priority issue labels Aug 31, 2026
@inureyes
inureyes merged commit 71ba28b into main Aug 31, 2026
5 checks passed
@inureyes
inureyes deleted the feature/issue-286-connection-multiplexing branch August 31, 2026 20:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

priority:medium Medium priority issue status:review Under review type:enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant