Crates.io | surf |
lib.rs | surf |
version | 2.3.2 |
source | src |
created_at | 2019-04-09 20:44:00.39744 |
updated_at | 2021-11-01 19:42:02.284631 |
description | Surf the web - HTTP client framework |
homepage | |
repository | https://github.com/http-rs/surf |
max_upload_size | |
id | 126882 |
size | 241,052 |
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.
Client
interfacelet 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?);
The following features are available. The default features are
curl-client
, middleware-logger
, and encoding
curl-client
(default): use curl
(through isahc
) as the HTTP backend.h1-client
: use async-h1
as the HTTP backend with native TLS for HTTPS.h1-client-rustls
: use async-h1
as the HTTP backend with rustls
for HTTPS.hyper-client
: use hyper
(hyper.rs) as the HTTP backend.wasm-client
: use window.fetch
as the HTTP backend.middleware-logger
(default): enables logging requests and responses using a middleware.encoding
(default): enables support for body encodings other than utf-8.Install OpenSSL -
sudo apt install libssl-dev
sudo dnf install openssl-devel
Make sure your rust is up to date using:
rustup update
With cargo add installed :
$ cargo add surf
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.
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