Surf

Surf the web

API Docs | Contributing | Chat

_{Built with 🌊 by The Rust Async Ecosystem WG}

Surf is a friendly HTTP client built for casual Rustaceans and veterans alike. It's completely modular, and built directly for async/await. Whether it's a quick script, or a cross-platform SDK, Surf will make it work.

Multi-platform out of the box
Extensible through a powerful middleware system
Reuses connections through the Client interface
Fully streaming requests and responses
TLS/SSL enabled by default
Swappable HTTP backends
HTTP/2 enabled by default

Examples

#[runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    let mut res = surf::get("https://httpbin.org/get").await?;
    dbg!(res.body_string().await?);
    Ok(()) 
}

It's also possible to skip the intermediate Response, and access the response type directly.

#[runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    dbg!(surf::get("https://httpbin.org/get").recv_string().await?);
    Ok(()) 
}

Both sending and receiving JSON is real easy too.

use serde::{Deserialize, Serialize};
#[runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    #[derive(Deserialize, Serialize)]
    struct Ip {
        ip: String
    }

    let uri = "https://httpbin.org/post";
    let data = &Ip { ip: "129.0.0.1".into() };
    let res = surf::post(uri).body_json(data)?.await?;
    assert_eq!(res.status(), 200);

    let uri = "https://api.ipify.org?format=json";
    let Ip { ip } = surf::get(uri).recv_json().await?;
    assert!(ip.len() > 10);
    Ok(())
}

And even creating streaming proxies is no trouble at all.

#[runtime::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    let reader = surf::get("https://img.fyi/q6YvNqP").await?;
    let res = surf::post("https://box.rs/upload").body(reader).await?;
    Ok(())
}

Installation

$ cargo add surf

Safety

This crate makes use of a single instance of unsafe in order to make the WASM backend work despite the Send bounds. This is safe because WASM targets currently have no access to threads. Once they do we'll be able to drop this implementation, and use a parked thread instead and move to full multi-threading in the process too.

Contributing

Want to join us? Check out our "Contributing" guide and take a look at some of these issues:

Thanks

Special thanks to prasannavl for donating the crate name, and sagebind for creating an easy to use async curl client that saved us countless hours.

License

MIT OR Apache-2.0

Nehliin/surf