Surf
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
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