remotefs_ssh/ssh/
backend.rs

1//! Defines the main trait for SSH Backends to be used with the clients and the backend implementations
2//! to support different SSH libraries (e.g. libssh2, libssh)
3
4#[cfg(feature = "libssh")]
5#[cfg_attr(docsrs, doc(cfg(feature = "libssh")))]
6mod libssh;
7
8#[cfg(feature = "libssh2")]
9#[cfg_attr(docsrs, doc(cfg(feature = "libssh2")))]
10mod libssh2;
11
12use std::io::{Read, Write};
13use std::path::{Path, PathBuf};
14
15use remotefs::fs::{Metadata, ReadStream, WriteStream};
16use remotefs::{File, RemoteResult};
17
18#[cfg(feature = "libssh")]
19#[cfg_attr(docsrs, doc(cfg(feature = "libssh")))]
20pub use self::libssh::LibSshSession;
21#[cfg(feature = "libssh2")]
22#[cfg_attr(docsrs, doc(cfg(feature = "libssh2")))]
23pub use self::libssh2::LibSsh2Session;
24use crate::SshOpts;
25
26/// SSH session trait.
27///
28/// Provides SSH channel functions
29pub trait SshSession: Sized {
30    type Sftp: Sftp;
31
32    /// Connects to the SSH server and establishes a new [`SshSession`]
33    fn connect(opts: &SshOpts) -> RemoteResult<Self>;
34
35    /// Disconnect from the server
36    fn disconnect(&self) -> RemoteResult<()>;
37
38    /// Get the SSH server banner.
39    fn banner(&self) -> RemoteResult<Option<String>>;
40
41    /// Check if the session is authenticated.
42    fn authenticated(&self) -> RemoteResult<bool>;
43
44    /// Executes a command on the SSH server and returns the exit code and the output.
45    fn cmd<S>(&mut self, cmd: S) -> RemoteResult<(u32, String)>
46    where
47        S: AsRef<str>;
48
49    /// Executes a command on the SSH server at a specific path and returns the exit code and the output.
50    fn cmd_at<S>(&mut self, cmd: S, path: &Path) -> RemoteResult<(u32, String)>
51    where
52        S: AsRef<str>,
53    {
54        self.cmd(format!("cd \"{}\"; {}", path.display(), cmd.as_ref()))
55    }
56
57    /// Receives a file over SCP.
58    ///
59    /// Returns a channel can be read from server.
60    fn scp_recv(&self, path: &Path) -> RemoteResult<Box<dyn Read + Send>>;
61
62    /// Send a file over SCP.
63    ///
64    /// Returns a channel which can be written to send data
65    fn scp_send(
66        &self,
67        remote_path: &Path,
68        mode: i32,
69        size: u64,
70        times: Option<(u64, u64)>,
71    ) -> RemoteResult<Box<dyn Write + Send>>;
72
73    /// Returns a SFTP client
74    fn sftp(&self) -> RemoteResult<Self::Sftp>;
75}
76
77/// Sftp provider for a [`SshSession`] implementation via the [`SshSession::sftp`] method.
78pub trait Sftp {
79    /// Creates a new directory at the specified `path` with the given `mode`.
80    fn mkdir(&self, path: &Path, mode: i32) -> RemoteResult<()>;
81
82    /// Opens a file for reading at the specified `path`.
83    fn open_read(&self, path: &Path) -> RemoteResult<ReadStream>;
84
85    /// Open a file for write at the specified `path` with the given `flags`. If the file is created, set the mode.
86    fn open_write(&self, path: &Path, flags: WriteMode, mode: i32) -> RemoteResult<WriteStream>;
87
88    /// Lists the contents of a directory at `dirname` and returns the listed [`File`] for it.
89    fn readdir<T>(&self, dirname: T) -> RemoteResult<Vec<File>>
90    where
91        T: AsRef<Path>;
92
93    /// Resolve the real path for `path`.
94    #[allow(dead_code)]
95    fn realpath(&self, path: &Path) -> RemoteResult<PathBuf>;
96
97    /// Renames a file from `src` to `dest`.
98    fn rename(&self, src: &Path, dest: &Path) -> RemoteResult<()>;
99
100    /// Removes a directory at `path`.
101    fn rmdir(&self, path: &Path) -> RemoteResult<()>;
102
103    /// Set the [`Metadata`] for a file at `path`.
104    fn setstat(&self, path: &Path, metadata: Metadata) -> RemoteResult<()>;
105
106    /// Get the [`File`] metadata for a file.
107    fn stat(&self, filename: &Path) -> RemoteResult<File>;
108
109    /// Creates a symlink at `path` pointing to `target`.
110    fn symlink(&self, path: &Path, target: &Path) -> RemoteResult<()>;
111
112    /// Deletes a file at `path`.
113    fn unlink(&self, path: &Path) -> RemoteResult<()>;
114}
115
116#[derive(Debug, Clone, Copy, PartialEq, Eq)]
117/// Open modes for reading and writing files.
118pub enum WriteMode {
119    Append,
120    Truncate,
121}
remotefs_ssh/ssh/backend.rs

remotefs_ssh/ssh/
backend.rs
