openssh_sftp_client/
lib.rs

1//! openssh sftp client, implements [sftp v3] accodring to
2//! [`openssh-portable/sftp-client.c`] and provides
3//! an easy-to-use highlevel API.
4//!
5//! All `async` functions in this module are cancel safe.
6//!
7//! Internally, this is archived by first writing requests into a write buffer
8//! containing [`bytes::Bytes`] and then flush all buffers at once periodically
9//! to archive cancel safety and improve efficiencies.
10//!
11//! However, cancelling the future does not actually has any effect,
12//! since the requests are sent regardless of the cancellation.
13//!
14//! Thus, if you cancel a future that changes the remote filesystem in any way,
15//! then the change would still happen regardless.
16//!
17//! ## Usage
18//!
19//! It is recommended that you use this crate with [openssh].
20//!
21//! You can also use this crate directly by using whatever ssh library
22//! to launch the `sftp` subsystem, then pass the stdin/stdout to
23//! [`Sftp::new`].
24//!
25//! ## Extensions
26//!
27//! This crate support the following extensions:
28//!  - limits
29//!  - expand path
30//!  - fsync
31//!  - hardlink
32//!  - posix rename
33//!  - copy data
34//!
35//! [openssh]: https://crates.io/crates/openssh
36//! [sftp v3]: https://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
37//! [`openssh-portable/sftp-client.c`]: https://github.com/openssh/openssh-portable/blob/19b3d846f06697c85957ab79a63454f57f8e22d6/sftp-client.c
38
39#![warn(
40    missing_docs,
41    missing_debug_implementations,
42    rustdoc::broken_intra_doc_links,
43    rust_2018_idioms,
44    unreachable_pub
45)]
46#![cfg_attr(docsrs, feature(doc_auto_cfg))]
47
48#[cfg(doc)]
49/// Changelog for this crate.
50pub mod changelog;
51
52mod utils;
53
54pub use error::{Error, UnixTimeStampError};
55use openssh_sftp_client_lowlevel as lowlevel;
56pub use openssh_sftp_error as error;
57
58use bytes::BytesMut;
59
60mod unix_timestamp;
61pub use unix_timestamp::UnixTimeStamp;
62
63mod sftp;
64use sftp::SftpHandle;
65#[cfg(feature = "openssh")]
66pub use sftp::{CheckOpensshConnection, OpensshSession};
67pub use sftp::{Sftp, SftpAuxiliaryData};
68
69#[cfg(feature = "openssh")]
70pub use openssh;
71
72mod options;
73pub use options::SftpOptions;
74
75mod queue;
76use queue::MpscQueue;
77
78mod tasks;
79
80mod auxiliary;
81use auxiliary::Auxiliary;
82
83mod cache;
84use cache::WriteEndWithCachedId;
85
86mod handle;
87use handle::OwnedHandle;
88
89/// Module contains types for manipulating files.
90pub mod file;
91
92/// Module contains types for manipulating directories.
93pub mod fs;
94
95/// Module contains types for manipulating metadata of files or directories.
96pub mod metadata;
97
98type Buffer = BytesMut;
99
100type WriteEnd = lowlevel::WriteEnd<Buffer, MpscQueue, Auxiliary>;
101type ReadEnd<R> = lowlevel::ReadEnd<R, Buffer, MpscQueue, Auxiliary>;
102type SharedData = lowlevel::SharedData<Buffer, MpscQueue, Auxiliary>;
103type Id = lowlevel::Id<Buffer>;
104type Data = lowlevel::Data<Buffer>;
105
106fn cancel_error() -> Error {
107    Error::BackgroundTaskFailure(&"read/flush task failed")
108}
openssh_sftp_client/lib.rs

openssh_sftp_client/
lib.rs
