SuppaFTP

SuppaFTP uses Cargo features to manage optional functionality like FTPS (SSL/TLS) and asynchronous runtimes.

SSL/TLS Support

To enable FTPS, you must select a TLS backend. native-tls is recommended for compatibility. To link libssl statically, use the -vendored variant.

Async Support

You must enable either the smol or tokio feature to use asynchronous APIs.

Feature Combinations

When combining TLS and Async, you must use the specific combined features to avoid conflicts:

• Tokio + native-tls: use tokio-async-native-tls (or tokio-async-native-tls-vendored for static linking).
• Tokio + rustls: use tokio-rustls-aws-lc-rs or tokio-rustls-ring.
• Smol + native-tls: use smol-async-native-tls (or smol-async-native-tls-vendored for static linking).
• Smol + rustls: use smol-rustls-aws-lc-rs or smol-rustls-ring.

# Example: Tokio with native-tls
suppaftp = { version = "^11", features = ["tokio-async-native-tls"] }

# Example: Sync with rustls
suppaftp = { version = "^11", features = ["rustls-aws-lc-rs"] }

When using smol with suppaftp, data transfers (uploads and downloads) are managed via a TransferStream. This stream implements AsyncRead and AsyncWrite, but it is not complete just because you have finished reading or writing the data.

To successfully complete a transfer and verify its outcome, you must call .finish().await on the TransferStream. This method closes the data connection and reads the server's completion reply (e.g., a 226 response) on the control connection.

Important considerations:

• Uploads: A transfer is only successful if the write side is closed cleanly. A close error during finish() will result in an FtpError::ConnectionError.
• Downloads: The server's completion reply is the authoritative source of success, as the payload has already been fully read.
• Concurrency: While a TransferStream is alive, the client will refuse to open another data connection, returning FtpError::DataConnectionAlreadyOpen.
• Dropping without finishing: If you simply drop the stream instead of calling finish(), the data socket is closed, but the completion reply is left in the control connection buffer. This reply will be consumed by the next command you issue on the client, which can lead to lost transfer results or unexpected behavior. Always prefer finish().await.

use smol::io::AsyncWriteExt;
use suppaftp::smol::AsyncFtpStream;

async fn run() {
    let mut ftp = AsyncFtpStream::connect("127.0.0.1:21").await.unwrap();
    ftp.login("test", "test").await.unwrap();
    
    // Obtain the TransferStream
    let mut upload = ftp.put_with_stream("hello.txt").await.unwrap();
    
    // Perform the data transfer
    upload.write_all(b"hello, world!").await.unwrap();
    
    // CRITICAL: Finalize the transfer to read the server's completion reply
    upload.finish().await.unwrap();
    
    // Now the control connection is ready for the next command
    assert_eq!(ftp.size("hello.txt").await.unwrap(), 13);
}

You can convert raw strings from FTP directory listings into File instances using several methods.

Automatic Parsing (Recommended for general use)

Implementations of FromStr and TryFrom<&str> allow you to parse a line by attempting multiple formats in sequence. The parser will try formats in this order:

1. POSIX
2. DOS
3. MLSD
4. MLST

// Using parse() via FromStr
let file: File = "-rw-r--r-- 1 user group 1234 Nov 5 2018 example.txt".parse().unwrap();

// Using try_from()
let file = File::try_from("04-08-14  03:09PM  8192 omar.txt").unwrap();

Explicit Parsing (Recommended for performance/certainty)

If you know the specific format of the listing, use the ListParser methods directly to avoid the overhead of trial-and-error parsing:

• ListParser::parse_posix(line)
• ListParser::parse_dos(line)
• ListParser::parse_mlsd(line)
• ListParser::parse_mlst(line)

Note: Several direct File::from_*_line methods (like from_posix_line) are deprecated since version 7.1.0. Use ListParser instead.

// Automatic parsing via FromStr
let file: File = "-rw-r--r-- 1 user group 1234 Nov 5 2018 example.txt".parse().unwrap();

// Explicit parsing via ListParser (preferred over deprecated File methods)
let file = ListParser::parse_posix("-rw-r--r-- 1 user group 1234 Nov 5 2018 example.txt").unwrap();

The ListParser struct provides methods to convert raw string lines from various FTP LIST command formats into File objects. Because FTP server implementations vary, you must choose the parser method that matches the output format of your specific server.

Supported formats:

• POSIX: Standard Unix-style listings (e.g., -rw-r--r-- ...). Use parse_posix.
• DOS: Windows-style listings (e.g., 04-08-14 03:09PM <DIR> ...). Use parse_dos.
• MLSD/MLST: Modern machine-readable listings (e.g., type=dir;modify=...;). Use parse_mlsd or parse_mlst (they are functionally identical).

Parsing returns a ParseResult<File>, which is a Result<File, ParseError>.

use suppaftp::list::{File, ListParser};

// Example: Parsing a POSIX line
let line = "-rw-r--r-- 1 user group 1234 Nov 5 13:46 example.txt";
let file = ListParser::parse_posix(line).expect("failed to parse LIST line");

assert_eq!(file.name(), "example.txt");

When using streaming methods like put_with_stream, append_with_stream, or retr_as_stream, the returned TransferStream must be explicitly finalized to ensure the transfer was successful.

Calling .finish() closes the data socket and reads the server's completion reply (e.g., 226 or 250) on the control connection. This is the only reliable way to confirm the transfer succeeded. If you do not call .finish(), the stream will attempt to finalize on Drop, but this is a best-effort operation that logs errors instead of returning them, and the transfer outcome may be lost.

Important:

• You must call .finish() before issuing any other command on the FTP client.
• If using buffered writers, ensure you flush() them before calling .finish().
• While a TransferStream is alive, the client will return FtpError::DataConnectionAlreadyOpen if you attempt to open another data connection.

use std::io::Write;
use suppaftp::FtpStream;

let mut ftp = FtpStream::connect("127.0.0.1:21").unwrap();
ftp.login("test", "test").unwrap();

// Start an upload stream
let mut upload = ftp.put_with_stream("hello.txt").unwrap();

// Write data to the stream
upload.write_all(b"hello, world!").unwrap();

// CRITICAL: Finalize the transfer to read the server's completion reply
// and make the control connection ready for the next command.
upload.finish().unwrap();

assert_eq!(ftp.size("hello.txt").unwrap(), 13);

The FtpStream type provides a synchronous API for interacting with FTP servers. You can connect, login, navigate directories, and transfer files using standard blocking calls.

use std::io::Cursor;
use std::str;
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
    println!("Current directory: {}", ftp_stream.pwd().unwrap());

    // Change directory
    let _ = ftp_stream.cwd("test_data").unwrap();

    // Retrieve (GET) a file
    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
    let mut reader = Cursor::new("Hello from the Rust \"ftp\" crate!".as_bytes());
    let _ = ftp_stream.put_file("greeting.txt", &mut reader);
    println!("Successfully wrote greeting.txt");

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