Skip to main content

Crate liburlx

Crate liburlx 

Source
Expand description

§liburlx

A memory-safe URL transfer library — a from-scratch Rust reimplementation of libcurl.

liburlx provides both blocking (Easy) and concurrent (Multi) APIs for transferring data over URLs. It supports HTTP/1.0-1.1, HTTP/2, HTTP/3 (QUIC), FTP/FTPS, SFTP/SCP, WebSocket, SMTP, IMAP, POP3, MQTT, DICT, TFTP, Gopher, RTSP, and file://.

Zero unsafe code — all unsafe is confined to the separate liburlx-ffi crate. TLS is provided by rustls with no OpenSSL dependency.

§Quick start

// Simple GET request
let mut easy = liburlx::Easy::new();
easy.url("https://httpbin.org/get")?;
let response = easy.perform()?;

println!("Status: {}", response.status());          // 200
println!("Body: {}", response.body_str()?);          // {"origin": ...}
println!("Content-Type: {:?}", response.content_type()); // Some("application/json")

§POST with headers and authentication

let mut easy = liburlx::Easy::new();
easy.url("https://api.example.com/data")?;
easy.method("POST");
easy.header("Content-Type", "application/json");
easy.body(br#"{"key": "value"}"#);
easy.basic_auth("user", "password");
easy.follow_redirects(true);

let response = easy.perform()?;
assert_eq!(response.status(), 200);

§Concurrent transfers

Multi runs multiple transfers concurrently using tokio under the hood:

let mut multi = liburlx::Multi::new();

let mut a = liburlx::Easy::new();
a.url("https://httpbin.org/get")?;
multi.add(a);

let mut b = liburlx::Easy::new();
b.url("https://httpbin.org/ip")?;
multi.add(b);

let results = multi.perform_blocking()?;
for result in &results {
    match result {
        Ok(resp) => println!("{}: {}", resp.effective_url(), resp.status()),
        Err(e) => eprintln!("Transfer failed: {e}"),
    }
}

§TLS configuration

use std::path::Path;

let mut easy = liburlx::Easy::new();
easy.url("https://internal.corp.example.com/api")?;
easy.ssl_ca_cert(Path::new("/etc/ssl/custom-ca.pem"));
easy.ssl_client_cert(Path::new("client.pem"));
easy.ssl_client_key(Path::new("client-key.pem"));
easy.ssl_pinned_public_key("sha256//YhKJG3phE6xw3TXJdrKg0MF2SHqP2D7jOZ+Buvnb5dA=");

let response = easy.perform()?;

§FTP upload

let mut easy = liburlx::Easy::new();
easy.url("ftp://ftp.example.com/upload/data.csv")?;
easy.basic_auth("ftpuser", "ftppass");
easy.upload_file(std::path::Path::new("data.csv"))?;

let response = easy.perform()?;

§Feature flags

FlagDefaultDescription
httpYesHTTP/1.x protocol
http2YesHTTP/2 via the h2 crate
http3NoHTTP/3 via quinn (QUIC)
rustlsYesTLS via rustls (no OpenSSL)
tls-srpNoTLS-SRP via OpenSSL
sshNoSFTP/SCP via russh
decompressionYesgzip, deflate, brotli, zstd
hickory-dnsNoAsync DNS with DoH/DoT via hickory-resolver

§Architecture

  • Easy — Single-transfer blocking API. Wraps a tokio runtime internally. Configure the request, call Easy::perform, get a Response.
  • Multi — Concurrent transfers. Add multiple Easy handles, execute them all with Multi::perform_blocking.
  • Response — Status, headers, body, and detailed transfer info (timing, connection metadata, TLS certificates).
  • Error — Non-exhaustive error enum with variants for each failure mode (DNS, TLS, timeout, auth, protocol-specific errors).
  • CookieJar / HstsCache / DnsCache — Shared state that can be attached to transfers or shared across handles via Share.

Re-exports§

pub use auth::AuthCredentials;
pub use auth::AuthMethod;
pub use auth::ProxyAuthCredentials;
pub use auth::ProxyAuthMethod;
pub use cookie::CookieJar;
pub use dns::DnsCache;
pub use dns::DnsResolver;
pub use easy::Easy;
pub use easy::HttpVersion;
pub use error::Error;
pub use hsts::HstsCache;
pub use multi::Multi;
pub use multi::PipeliningMode;
pub use progress::make_progress_callback;
pub use progress::ProgressCallback;
pub use progress::ProgressInfo;
pub use protocol::http::multipart::guess_content_type as guess_form_content_type;
pub use protocol::http::multipart::FilenameEscapeMode;
pub use protocol::http::multipart::MultipartForm;
pub use protocol::http::response::PushedResponse;
pub use protocol::http::response::Response;
pub use protocol::http::response::ResponseHttpVersion;
pub use protocol::http::response::TransferInfo;
pub use share::Share;
pub use share::ShareType;
pub use throttle::SpeedLimits;
pub use tls::TlsConfig;
pub use tls::TlsVersion;
pub use url::Url;
pub use protocol::ftp::FtpConfig;
pub use protocol::ftp::FtpMethod;
pub use protocol::ftp::FtpSslMode;
pub use protocol::ftp::UseSsl;

Modules§

auth
HTTP authentication mechanisms.
cookie
Cookie jar engine.
dns
DNS resolution and caching.
easy
Single-transfer blocking API.
error
Error types for liburlx.
glob
URL globbing — pattern expansion for URL templates.
hsts
HTTP Strict Transport Security (HSTS) enforcement.
idn
Internationalized Domain Name (IDN) support.
multi
Concurrent transfer API.
netrc
.netrc file parsing for credential lookup.
progress
Progress reporting for transfers.
protocol
Protocol handler definitions.
proxy
Proxy protocol implementations.
share
Shared state for cross-handle data sharing.
throttle
Transfer speed throttling and enforcement.
tls
TLS connector using rustls.
url
URL parsing with curl compatibility quirks.

Type Aliases§

Result
Convenience result type for liburlx operations.