Struct SshClient 

pub struct SshClient {
    pub session: Handle<ClientHandler>,
    /* private fields */
}

Available on crate feature ssh-real only.

Real SSH client backed by russh (default feature ssh-real). Active SSH client with an authenticated session.

Fields

session: Handle<ClientHandler>

Authenticated SSH session for low-level operations.

Implementations

impl SshClient

pub fn timeout_ms(&self) -> u64

Wall-clock timeout (ms) from connection config (CLI/XDG) — G-SFTP-R05.

impl SshClient

pub async fn connect(cfg: ConnectionConfig) -> SshCliResult<Self>

Connects and authenticates. The full flow (TCP + handshake + auth) honors the configuration timeout_ms.

Errors

• SshCliError::InvalidArgument if the configuration is invalid.
• SshCliError::SshTimeout if the total timeout is exceeded.
• SshCliError::ConnectionFailed on TCP/handshake failures.
• SshCliError::HostKeyChanged when TOFU rejects a divergent host key.
• SshCliError::AuthenticationFailed if the server rejects password/key/agent (try --key, --use-agent, --password-stdin, or --key-passphrase-stdin).

pub async fn run_command( &mut self, command: &str, max_chars: usize, stdin_data: Option<Vec<u8>>, ) -> SshCliResult<ExecutionOutput>

Runs a remote shell command and captures stdout/stderr in parallel.

impl SshClient

pub async fn upload( &self, local: &Path, remote: &Path, ) -> SshCliResult<TransferResult>

Uploads a local file to the remote host via SCP (OpenSSH sink protocol).

One-shot: stream in chunks (without loading the whole file into RAM).

Errors

• SshCliError::FileNotFound if the local file does not exist.
• SshCliError::InvalidArgument if the local path is not a regular file.
• SshCliError::ChannelFailed if opening the SCP channel or remote status fails.
• SshCliError::SshTimeout if the deadline expires.

pub async fn download( &self, remote: &Path, local: &Path, ) -> SshCliResult<TransferResult>

Downloads a remote file to the local path via SCP (OpenSSH source protocol).

Writes to {local}.ssh-cli.partial and renames atomically (SCP-022).

Errors

• SshCliError::Io if the local file cannot be written.
• SshCliError::ChannelFailed if opening the SCP channel or remote status fails.
• SshCliError::SshTimeout if the deadline expires.

impl SshClient

pub async fn disconnect(&self) -> SshCliResult<()>

Cleanly closes the SSH session.

Errors

Propagates transport errors returned by disconnect.

pub async fn open_tunnel_channel( &self, remote_host: &str, remote_port: u16, origin_addr: &str, origin_port: u16, ) -> SshCliResult<Box<dyn TunnelChannel>>

Opens a direct-tcpip channel for SSH forwarding.

pub async fn open_streamlocal_channel( &self, socket_path: &str, ) -> SshCliResult<Box<dyn TunnelChannel>>

Opens a direct-streamlocal@openssh.com channel to a remote Unix socket.

G-TUN-R03. The OpenSSH extension carries no origin fields, so unlike direct-tcpip there is nothing to advertise about the local side.

Errors

SshCliError::ChannelFailed when the server refuses the extension or the socket path — servers without it reply with a plain open failure, so “not supported” and “no such socket” are indistinguishable on the wire.

pub async fn request_remote_forward( &self, address: &str, port: u16, ) -> SshCliResult<u16>

Asks the server to listen on address:port and returns the bound port.

G-TUN-R01. Passing 0 lets the server allocate, and the reply carries the real port — which is why the return value must be surfaced rather than echoing the request back to the caller.

Errors

SshCliError::ChannelFailed when the server denies tcpip-forward (commonly AllowTcpForwarding no in sshd_config).

pub async fn cancel_remote_forward( &self, address: &str, port: u16, ) -> SshCliResult<()>

Cancels a remote forward previously granted by the server.

Errors

SshCliError::ChannelFailed when the cancel request is refused.

pub async fn accept_forwarded_channel(&self) -> Option<Box<dyn TunnelChannel>>

Waits for the next channel the server opens on an active reverse forward.

Returns None once the session ends and no further channels can arrive, which is what lets the reverse accept loop terminate instead of hanging.

pub async fn open_sftp(&self) -> SshCliResult<SftpSession>

Opens one SFTP subsystem session (reuse for multi-file / multi-op).

pub async fn sftp_upload( &self, local: &Path, remote: &str, ) -> SshCliResult<TransferResult>

One-shot SFTP upload of a regular file (opens+closes subsystem).

pub async fn sftp_download( &self, remote: &str, local: &Path, ) -> SshCliResult<TransferResult>

One-shot SFTP download of a regular file.

pub async fn sftp_upload_tree( &self, local_dir: &Path, remote_dir: &str, ) -> SshCliResult<TransferResult>

One-shot recursive SFTP upload tree.

pub async fn sftp_download_tree( &self, remote_dir: &str, local_dir: &Path, ) -> SshCliResult<TransferResult>

One-shot recursive SFTP download tree.

Trait Implementations

impl Debug for SshClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl SshClientTrait for SshClient

fn connect<'async_trait>( cfg: ConnectionConfig, ) -> Pin<Box<dyn Future<Output = Result<Box<Self>, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait,

Connects to an SSH server and authenticates with the provided credentials.

fn run_command<'life0, 'life1, 'async_trait>( &'life0 mut self, cmd: &'life1 str, max_chars: usize, stdin_data: Option<Vec<u8>>, ) -> Pin<Box<dyn Future<Output = Result<ExecutionOutput, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Runs a remote shell command and returns the captured output.

fn upload<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, local: &'life1 Path, remote: &'life2 Path, ) -> Pin<Box<dyn Future<Output = Result<TransferResult, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Uploads a local file to the remote server via SCP.

fn download<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, remote: &'life1 Path, local: &'life2 Path, ) -> Pin<Box<dyn Future<Output = Result<TransferResult, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Downloads a remote file to the local filesystem via SCP.

fn open_tunnel_channel<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, remote_host: &'life1 str, remote_port: u16, origin_addr: &'life2 str, origin_port: u16, ) -> Pin<Box<dyn Future<Output = Result<Box<dyn TunnelChannel>, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Opens a direct-tcpip channel for tunnel forwarding.

fn open_streamlocal_channel<'life0, 'life1, 'async_trait>( &'life0 self, socket_path: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Box<dyn TunnelChannel>, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Opens a direct-streamlocal@openssh.com channel to a remote Unix socket.

fn request_remote_forward<'life0, 'life1, 'async_trait>( &'life0 self, address: &'life1 str, port: u16, ) -> Pin<Box<dyn Future<Output = Result<u16, SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Requests a server-side listener, returning the port the server bound.

fn cancel_remote_forward<'life0, 'life1, 'async_trait>( &'life0 self, address: &'life1 str, port: u16, ) -> Pin<Box<dyn Future<Output = Result<(), SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Cancels a server-side listener previously requested.

fn accept_forwarded_channel<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Option<Box<dyn TunnelChannel>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Waits for the next channel opened by the server on an active reverse forward.

fn disconnect<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), SshCliError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Cleanly closes the SSH connection.