Skip to content
/ surf Public
forked from http-rs/surf

Surf the web – HTTP client framework

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Notifications You must be signed in to change notification settings

cjpearce/surf

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Surf

Surf the web

Built with 🌊 by The http-rs team

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

use async_std::task;

fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync + 'static>> {
    task::block_on(async {
        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.

use async_std::task;

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

Both sending and receiving JSON is real easy too.

use async_std::task;
use serde::{Deserialize, Serialize};

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

    task::block_on(async {
        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.

use async_std::task;

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

Installation

Install OpenSSL -

  • Ubuntu - sudo apt install libssl-dev
  • Fedora - sudo dnf install openssl-devel

Make sure your rust is up to date using: rustup update

With cargo add installed :

$ 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:

See Also

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

About

Surf the web – HTTP client framework

Resources

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT

Code of conduct

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Rust 100.0%