Home

Awesome

<h1 align="center">Surf</h1> <div align="center"> <strong> Surf the web </strong> </div> <br /> <div align="center"> <!-- Crates version --> <a href="https://crates.io/crates/surf"> <img src="https://img.shields.io/crates/v/surf.svg?style=flat-square" alt="Crates.io version" /> </a> <!-- Downloads --> <a href="https://crates.io/crates/surf"> <img src="https://img.shields.io/crates/d/surf.svg?style=flat-square" alt="Download" /> </a> <!-- docs.rs docs --> <a href="https://docs.rs/surf"> <img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /> </a> </div> <div align="center"> <h3> <a href="https://docs.rs/surf"> API Docs </a> <span> | </span> <a href="https://github.com/http-rs/surf/blob/main/.github/CONTRIBUTING.md"> Contributing </a> <span> | </span> <a href="https://discord.com/invite/x2gKzst"> Chat </a> </h3> </div> <div align="center"> <sub>Built with 🌊 by <a href="https://github.com/http-rs">The http-rs team</a> </div> <br/>

Surf the web - HTTP client framework

Surf is a Rust HTTP client built for ease-of-use and multi-HTTP-backend flexibility. Whether it's a quick script, or a cross-platform SDK, Surf will make it work.

Examples

let mut res = surf::get("https://httpbin.org/get").await?;
dbg!(res.body_string().await?);

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

dbg!(surf::get("https://httpbin.org/get").recv_string().await?);

Both sending and receiving JSON is real easy too.

#[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);

And even creating streaming proxies is no trouble at all.

let req = surf::get("https://img.fyi/q6YvNqP").await?;
let body = surf::http::Body::from_reader(req, None);
let res = surf::post("https://box.rs/upload").body(body).await?;

Setting configuration on a client is also straightforward.

use std::convert::TryInto;
use std::time::Duration;
use surf::{Client, Config};
use surf::Url;

let client: Client = Config::new()
    .set_base_url(Url::parse("http://example.org")?)
    .set_timeout(Some(Duration::from_secs(5)))
    .try_into()?;

let mut res = client.get("/").await?;
println!("{}", res.body_string().await?);

Features

The following features are available. The default features are curl-client, middleware-logger, and encoding

Installation

Install OpenSSL -

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