#ftp #ftps #network-protocol #async

bin+lib suppaftp

A super FTP/FTPS client library for Rust

6 stable releases

Uses new Rust 2021

4.4.0 Aug 2, 2022
4.3.0 Jun 27, 2022
4.2.0 Dec 8, 2021
4.1.2 Aug 23, 2021

#35 in Asynchronous

Download history 124/week @ 2022-04-22 151/week @ 2022-04-29 114/week @ 2022-05-06 123/week @ 2022-05-13 64/week @ 2022-05-20 89/week @ 2022-05-27 97/week @ 2022-06-03 35/week @ 2022-06-10 86/week @ 2022-06-17 85/week @ 2022-06-24 67/week @ 2022-07-01 82/week @ 2022-07-08 85/week @ 2022-07-15 104/week @ 2022-07-22 81/week @ 2022-07-29 4269/week @ 2022-08-05

4,588 downloads per month
Used in 9 crates (2 directly)

Apache-2.0/MIT

180KB
3.5K SLoC

SuppaFTP

~ A super FTP/FTPS client library for Rust ~

Documentation ยท Crates.io

Developed by veeso and Matt McCoy

Current version: 4.4.0 (02/08/2022)

License-Apache-2.0/MIT Repo stars Downloads counter Latest version Ko-fi

Linux CI Coveralls Docs



Introduction ๐Ÿ‘‹

SuppaFTP is a FTP/FTPS client library written in Rust, with both support for sync/async programming. It is a fork of the original ftp library "rust-ftp", but since the original library is currently unmaintained, I decided to keep working on this library by myself. Currently, I consider myself as the only maintainer of this project, indeed I've already added some features to the library and improved it with better error handling and test units. Then, feel free to use this library instead of the classic rust-ftp if you want, and if you have any feature request or issue to report, please open an issue on this repository; I will answer you as soon as possible.

Main differences between SuppaFTP and rust-ftp ๐Ÿค”

  • Added methods to work with streams (e.g. put_with_stream) โฌ‡๏ธ
  • suppaftp supports Active mode
  • Added get_welcome_msg method ๐Ÿ‘‹
  • Supports for both sync/async rust ๐Ÿ•™
  • Supports for more commands ๐ŸŒŸ
    • ABOR
    • APPE
    • REST
  • Some extra features, such as the LIST command output parser
  • Replaced OpenSSL with native-tls ๐Ÿ”’
  • Removed deprecated statements โšฐ๏ธ
  • Better error handling ๐Ÿ›
  • Added test units keeping an eye on code coverage ๐Ÿ‘€

Get started ๐Ÿ

To get started, first add suppaftp to your dependencies:

suppaftp = "^4.4.0"

Features

SSL/TLS Support

If you want to enable support for FTPS, you must enable the secure feature in your cargo dependencies. FTPS support is achieved through rust-native-tls, so check if your target systems are compatible.

suppaftp = { version = "^4.4.0", features = ["secure"] }

Async support

If you want to enable async support, you must enable async feature in your cargo dependencies.

suppaftp = { version = "^4.4.0", features = ["async"] }

โš ๏ธ If you want to enable both secure and async you must use the async-secure feature โš ๏ธ

Deprecated methods

If you want to enable deprecated methods of FTPS, please enable the deprecated feature in your cargo dependencies.

This feature enables these methods:

  • connect_secure_implicit(): used to connect via implicit FTPS

Logging

By default, the library will log if there is any log crate consumer on the user implementation. Logging can be if preferred, disabled via the no-log feature.

Example ๐Ÿ“š

extern crate suppaftp;

use std::str;
use std::io::Cursor;
use suppaftp::FtpStream;

fn main() {
    // Create a connection to an FTP server and authenticate to it.
    let mut ftp_stream = FtpStream::connect("127.0.0.1:21").unwrap();
    let _ = ftp_stream.login("username", "password").unwrap();

    // Get the current directory that the client will be reading from and writing to.
    println!("Current directory: {}", ftp_stream.pwd().unwrap());

    // Change into a new directory, relative to the one we are currently in.
    let _ = ftp_stream.cwd("test_data").unwrap();

    // Retrieve (GET) a file from the FTP server in the current working directory.
    let data = ftp_stream.retr_as_buffer("ftpext-charter.txt").unwrap();
    println!("Read file with contents\n{}\n", str::from_utf8(&data.into_inner()).unwrap());

    // Store (PUT) a file from the client to the current working directory of the server.
    let mut reader = Cursor::new("Hello from the Rust \"ftp\" crate!".as_bytes());
    let _ = ftp_stream.put("greeting.txt", &mut reader);
    println!("Successfully wrote greeting.txt");

    // Terminate the connection to the server.
    let _ = ftp_stream.quit();
}

Going Async

use suppaftp::FtpStream;
use suppaftp::async_native_tls::{TlsConnector, TlsStream};
let ftp_stream = FtpStream::connect("test.rebex.net:21").await.unwrap();
// Switch to the secure mode
let mut ftp_stream = ftp_stream.into_secure(TlsConnector::new(), "test.rebex.net").await.unwrap();
ftp_stream.login("demo", "password").await.unwrap();
// Do other secret stuff
// Do all public stuff
assert!(ftp_stream.quit().await.is_ok());

Built-in CLI client ๐Ÿ–ฅ๏ธ

SuppaFTP comes also with a built-in command-line FTP client. This CLI application provides all the commands to interact with a remote FTP server and supports FTPS too. You can also use it as a reference to implement your project. You can find it in the cli/ directory.

You can simply install as any other rust application via Cargo:

cargo install suppaftp --features="secure cli-bin"

Support the developer โ˜•

If you like SuppaFTP, please consider a little donation ๐Ÿฅณ

ko-fi PayPal


Changelog โŒ›

View Changelog here


License ๐Ÿ“œ

Licensed under either of

at your option.


Contribution ๐Ÿค

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

If you want to contribute to this project, please read the Contributing guide first ๐Ÿ™‚.

Dependencies

~2โ€“9MB
~172K SLoC