Module tunnel 

SSH tunnel support — types and lifecycle.

SshConfig is the validated output of merging profile keys and CLI flags. It is the type backends consume to set up a tunnel before opening their underlying connection.

The russh-backed transport (session, channel, port forwarding, TunneledConnection wrapper) lives behind the ssh Cargo feature. The hybrid transport architecture is documented inline at TunnelTransport:

• LocalListener — binds 127.0.0.1:0, pumps bytes through an SSH direct-tcpip channel. Used by every backend whose driver does not expose a custom-stream injection API (mysql_async, tiberius, rusqlite, oracle).
• Stream — hands back a TunnelStream suitable for tokio_postgres::Config::connect_raw. Avoids the local TCP hop for Postgres specifically.

Structs

ClientHandler

russh client handler.

SshConfig

Resolved SSH tunnel configuration.

SshSession

Holds the russh session for the tunnel’s lifetime. Dropping this terminates the session and tears down all channels using it — standard Rust ownership instead of an explicit close protocol.

TunnelHandle

Outcome of setup_tunnel. The session is held alongside the transport-specific resources so callers only need to keep one value alive — when TunnelHandle drops, the SSH session and (for path a) the forwarder task drop with it.

TunnelStream

AsyncRead + AsyncWrite wrapper around a russh direct-tcpip channel. Suitable for feeding into tokio_postgres::Config::connect_raw.

TunneledConnection

Wraps a backend AsyncConnection (the crate-private async driver trait) plus the SSH session (and, for the LocalListener transport, the forwarder task) so the entire stack drops together.

Enums

KeySource

Where the SSH session sources its private key from. The CLI’s resolution stack collapses --ssh-key, profile entries, FERRULE_<NAME>_SSH_KEY, default identity files, and SSH_AUTH_SOCK into one of these variants before reaching setup_tunnel.

TunnelError

Errors raised by the tunnel layer.

TunnelTransport

Selects which transport setup_tunnel returns. See the module-level docs for when to pick each.

TunnelTransportResult

Transport-specific resources returned alongside the SSH session.

Functions

check_host_key

Check host:port against the user’s ~/.ssh/known_hosts.

learn_host_key

Write a host’s public key into ~/.ssh/known_hosts (TOFU).

ssh_key_needs_passphrase

Probe whether an SSH private key file requires a passphrase.