API Docs | Contributing | Chat
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
Clientinterface - Fully streaming requests and responses
- TLS/SSL enabled by default
- Swappable HTTP backends
- HTTP/2 enabled by default
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(())
});
}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 surfThis 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.
Want to join us? Check out our "Contributing" guide and take a look at some of these issues:
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.
MIT OR Apache-2.0
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent