feat!: Support for multiple SSH backends. Support for libssh.org

Added new feature to enable **libssh2** backend; Added a new feature to enable **libssh** backend. Renamed ssh2-vendored feature to libssh2-vendored. Removed `new`; use `libssh2` and `libssh` constructors instead. By default libssh2 feature is enabled. See README for more details

BREAKING CHANGE: Removed `From<SshOpts>`; Removed `new`; use `libssh2` and `libssh` constructors instead; Renamed ssh2-vendored feature to libssh2-vendored

Author: veeso

.cargo/config.toml

@@ -0,0 +1,3 @@
+[alias]
+lint = "clippy --features libssh2 -- -Dwarnings"
+test-all = "test --features libssh2"

.github/workflows/linux.yml

@@ -12,20 +12,18 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - name: Install dependencies
-        run: sudo apt update && sudo apt install -y libssh2-1-dev libssl-dev
+        run: sudo apt update && sudo apt install -y libssh2-1-dev libssh-dev libssl-dev
       - uses: dtolnay/rust-toolchain@stable
         with:
           toolchain: stable
           components: rustfmt, clippy
       - name: Build
         run: cargo build --all-features
-      - name: Build (unsecure)
-        run: cargo build --no-default-features
       - name: Format
         run: cargo fmt --all -- --check
       - name: Clippy
-        run: cargo clippy --features find -- -Dwarnings
+        run: cargo lint
       - name: Run tests
-        run: cargo test --all-features --features find,github-actions
+        run: cargo test-all
         env:
           RUST_LOG: trace

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 - [Changelog](#changelog)
+  - [0.7.0](#070)
   - [0.6.4](#064)
   - [0.6.3](#063)
   - [0.6.2](#062)
@@ -22,6 +23,17 @@
 
 ---
 
+## 0.7.0
+
+Released on 16/08/2025
+
+- **BREAKING**: Support for multiple SSH backends:
+  - Added new feature to enable **libssh2** backend:
+    - Use `libssh2` feature to enable the backend
+    - Use `libssh2-vendored` to build the backend with vendored libssh2
+  - Removed `new`; use `libssh2` and `libssh` constructors instead.
+  - Removed `From<SshOpts>`
+
 ## 0.6.4
 
 Released on 15/08/2025

Cargo.toml

@@ -10,7 +10,7 @@ license = "MIT"
 name = "remotefs-ssh"
 readme = "README.md"
 repository = "https://github.com/remotefs-rs/remotefs-rs-ssh"
-version = "0.6.4"
+version = "0.7.0"
 rust-version = "1.85.1"
 
 [dependencies]
@@ -19,7 +19,7 @@ lazy-regex = "3"
 log = "^0.4"
 remotefs = "^0.3"
 ssh2-config = "^0.6"
-ssh2 = "^0.9"
+ssh2 = { version = "^0.9", optional = true }
 
 [dev-dependencies]
 env_logger = "^0.11"
@@ -29,13 +29,11 @@ tempfile = "^3"
 testcontainers = { version = "0.25", features = ["blocking"] }
 
 [features]
-default = ["find"]
-# misc
+default = ["find", "libssh2"]
 find = ["remotefs/find"]
+libssh2 = ["dep:ssh2"]
+libssh2-vendored = ["libssh2", "ssh2/vendored-openssl"]
 no-log = ["log/max_level_off"]
-ssh2-vendored = ["ssh2/vendored-openssl"]
-# tests
-github-actions = []
 
 [target."cfg(target_os = \"windows\")"]
 [target."cfg(target_os = \"windows\")".dependencies]

README.md

@@ -11,7 +11,7 @@
 <p align="center">~ Remotefs SSH client ~</p>
 
 <p align="center">Developed by <a href="https://veeso.github.io/" target="_blank">@veeso</a></p>
-<p align="center">Current version: 0.6.4 (15/08/2025)</p>
+<p align="center">Current version: 0.7.0 (16/08/2025)</p>
 
 <p align="center">
   <a href="https://opensource.org/licenses/MIT"
@@ -72,14 +72,35 @@ First of all, add `remotefs-ssh` to your project dependencies:
 
 ```toml
 remotefs = "0.3"
-remotefs-ssh = "^0.6"
+remotefs-ssh = "^0.7"
 ```
 
+> ![NOTE]
+> The library supports multiple ssh backends.
+> Currently `libssh2` and `libssh` are supported.
+>
+> By default the library is using `libssh2`.
+
+### Available backends
+
+Each backend can be set as a feature in your `Cargo.toml`. Multiple backends can be enabled at the same time.
+
+- `libssh2`: The default backend, using the `libssh2` library for SSH connections.
+- `libssh`: An alternative backend, using the `libssh` library for SSH connections.
+
+Each backend can be built with the vendored version, using the vendored feature instead:
+
+- `libssh2-vendored`: Build the `libssh2` backend with the vendored version of the library.
+- `libssh-vendored`: Build the `libssh` backend with the vendored version of the library.
+
+If the vendored feature is **NOT** provided, you will need to have the corresponding system libraries installed on your machine.
+
+### Other features
+
 these features are supported:
 
 - `find`: enable `find()` method on client (*enabled by default*)
 - `no-log`: disable logging. By default, this library will log via the `log` crate.
-- `ssh2-vendored`: build with static libssl
 
 ---
 

src/lib.rs

@@ -66,7 +66,7 @@ extern crate log;
 mod ssh;
 pub use ssh::{
     KeyMethod, MethodType, ParseRule as SshConfigParseRule, ScpFs, SftpFs, SshAgentIdentity,
-    SshKeyStorage, SshOpts,
+    SshKeyStorage, SshOpts, SshSession,
 };
 
 // -- utils

src/mock/mod.rs renamed to src/mock.rs

@@ -14,6 +14,7 @@ pub fn logger() {
         let _ = env_logger::builder()
             .filter_level(log::LevelFilter::Trace)
             .is_test(true)
+            .format_source_path(true)
             .format_line_number(true)
             .try_init();
     });

src/ssh/mod.rs renamed to src/ssh.rs

@@ -7,19 +7,20 @@ use std::path::{Path, PathBuf};
 use std::time::Duration;
 
 // -- modules
-mod commons;
+mod backend;
 mod config;
 #[cfg(test)]
 mod container;
+mod key_method;
 mod scp;
 mod sftp;
-mod stream;
-// -- export
-pub use scp::ScpFs;
-pub use sftp::SftpFs;
-pub use ssh2::MethodType as SshMethodType;
+
 pub use ssh2_config::ParseRule;
-use stream::{SftpReadStream, SftpWriteStream};
+
+pub use self::backend::SshSession;
+pub use self::key_method::{KeyMethod, MethodType};
+pub use self::scp::ScpFs;
+pub use self::sftp::SftpFs;
 
 // -- Ssh key storage
 
@@ -29,30 +30,6 @@ pub trait SshKeyStorage: Send + Sync {
     fn resolve(&self, host: &str, username: &str) -> Option<PathBuf>;
 }
 
-// -- key method
-
-/// Ssh key method.
-/// Defined by [`MethodType`] (see ssh2 docs) and the list of supported algorithms.
-pub struct KeyMethod {
-    pub(crate) method_type: MethodType,
-    algos: Vec<String>,
-}
-
-impl KeyMethod {
-    /// Instantiates a new [`KeyMethod`]
-    pub fn new(method_type: MethodType, algos: &[String]) -> Self {
-        Self {
-            method_type,
-            algos: algos.to_vec(),
-        }
-    }
-
-    /// Get preferred algos in ssh protocol syntax
-    pub(crate) fn prefs(&self) -> String {
-        self.algos.join(",")
-    }
-}
-
 // -- ssh options
 
 /// Ssh agent identity
@@ -216,42 +193,6 @@ impl SshOpts {
     }
 }
 
-impl From<SshOpts> for SftpFs {
-    fn from(opts: SshOpts) -> Self {
-        SftpFs::new(opts)
-    }
-}
-
-impl From<SshOpts> for ScpFs {
-    fn from(opts: SshOpts) -> Self {
-        ScpFs::new(opts)
-    }
-}
-
-/// Re-implementation of ssh key method, in order to use `Eq`
-#[derive(Debug, Clone, Copy, Eq, PartialEq)]
-pub enum MethodType {
-    CryptClientServer,
-    CryptServerClient,
-    HostKey,
-    Kex,
-    MacClientServer,
-    MacServerClient,
-}
-
-impl From<MethodType> for SshMethodType {
-    fn from(t: MethodType) -> Self {
-        match t {
-            MethodType::CryptClientServer => SshMethodType::CryptCs,
-            MethodType::CryptServerClient => SshMethodType::CryptSc,
-            MethodType::HostKey => SshMethodType::HostKey,
-            MethodType::Kex => SshMethodType::Kex,
-            MethodType::MacClientServer => SshMethodType::MacCs,
-            MethodType::MacServerClient => SshMethodType::MacSc,
-        }
-    }
-}
-
 #[cfg(test)]
 mod test {
 
@@ -332,14 +273,4 @@ mod test {
         assert!(opts.key_storage.is_some());
         assert_eq!(opts.methods.len(), 1);
     }
-
-    #[test]
-    fn should_build_sftp_client() {
-        let _: SftpFs = SshOpts::new("localhost").into();
-    }
-
-    #[test]
-    fn should_build_scp_client() {
-        let _: ScpFs = SshOpts::new("localhost").into();
-    }
 }

src/ssh/backend.rs

@@ -0,0 +1,111 @@
+//! Defines the main trait for SSH Backends to be used with the clients and the backend implementations
+//! to support different SSH libraries (e.g. libssh2, libssh)
+
+#[cfg(feature = "libssh2")]
+mod libssh2;
+
+use std::io::{Read, Write};
+use std::path::{Path, PathBuf};
+
+use remotefs::fs::{Metadata, ReadStream, WriteStream};
+use remotefs::{File, RemoteResult};
+
+#[cfg(feature = "libssh2")]
+pub use self::libssh2::LibSsh2Session;
+use crate::SshOpts;
+
+/// SSH session trait.
+///
+/// Provides SSH channel functions
+pub trait SshSession: Sized {
+    type Sftp: Sftp;
+
+    /// Connects to the SSH server and establishes a new [`SshSession`]
+    fn connect(opts: &SshOpts) -> RemoteResult<Self>;
+
+    /// Disconnect from the server
+    fn disconnect(&self) -> RemoteResult<()>;
+
+    /// Get the SSH server banner.
+    fn banner(&self) -> RemoteResult<Option<String>>;
+
+    /// Check if the session is authenticated.
+    fn authenticated(&self) -> RemoteResult<bool>;
+
+    /// Executes a command on the SSH server and returns the exit code and the output.
+    fn cmd<S>(&mut self, cmd: S) -> RemoteResult<(u32, String)>
+    where
+        S: AsRef<str>;
+
+    /// Executes a command on the SSH server at a specific path and returns the exit code and the output.
+    fn cmd_at<S>(&mut self, cmd: S, path: &Path) -> RemoteResult<(u32, String)>
+    where
+        S: AsRef<str>,
+    {
+        self.cmd(format!("cd \"{}\"; {}", path.display(), cmd.as_ref()))
+    }
+
+    /// Receives a file over SCP.
+    ///
+    /// Returns a channel can be read from server.
+    fn scp_recv(&self, path: &Path) -> RemoteResult<Box<dyn Read + Send>>;
+
+    /// Send a file over SCP.
+    ///
+    /// Returns a channel which can be written to send data
+    fn scp_send(
+        &self,
+        remote_path: &Path,
+        mode: i32,
+        size: u64,
+        times: Option<(u64, u64)>,
+    ) -> RemoteResult<Box<dyn Write + Send>>;
+
+    /// Returns a SFTP client
+    fn sftp(&self) -> RemoteResult<Self::Sftp>;
+}
+
+/// Sftp provider for a [`SshSession`] implementation via the [`SshSession::sftp`] method.
+pub trait Sftp {
+    /// Creates a new directory at the specified `path` with the given `mode`.
+    fn mkdir(&self, path: &Path, mode: i32) -> RemoteResult<()>;
+
+    /// Opens a file for reading at the specified `path`.
+    fn open_read(&self, path: &Path) -> RemoteResult<ReadStream>;
+
+    /// Open a file for write at the specified `path` with the given `flags`. If the file is created, set the mode.
+    fn open_write(&self, path: &Path, flags: WriteMode, mode: i32) -> RemoteResult<WriteStream>;
+
+    /// Lists the contents of a directory at `dirname` and returns the listed [`File`] for it.
+    fn readdir<T>(&self, dirname: T) -> RemoteResult<Vec<File>>
+    where
+        T: AsRef<Path>;
+
+    /// Resolve the real path for `path`.
+    fn realpath(&self, path: &Path) -> RemoteResult<PathBuf>;
+
+    /// Renames a file from `src` to `dest`.
+    fn rename(&self, src: &Path, dest: &Path) -> RemoteResult<()>;
+
+    /// Removes a directory at `path`.
+    fn rmdir(&self, path: &Path) -> RemoteResult<()>;
+
+    /// Set the [`Metadata`] for a file at `path`.
+    fn setstat(&self, path: &Path, metadata: Metadata) -> RemoteResult<()>;
+
+    /// Get the [`File`] metadata for a file.
+    fn stat(&self, filename: &Path) -> RemoteResult<File>;
+
+    /// Creates a symlink at `path` pointing to `target`.
+    fn symlink(&self, path: &Path, target: &Path) -> RemoteResult<()>;
+
+    /// Deletes a file at `path`.
+    fn unlink(&self, path: &Path) -> RemoteResult<()>;
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+/// Open modes for reading and writing files.
+pub enum WriteMode {
+    Append,
+    Truncate,
+}