Crate surf[−][src]

surf the web.

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

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(surf::Body::from_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?;

Features

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

Re-exports

pub use http_types as http;

Modules

middleware	Middleware types
utils	Miscellaneous utilities.

Structs

Body	A streaming HTTP body.
Client	An HTTP client, capable of sending `Request`s and running a middleware stack.
DecodeError	An error occurred while decoding a response body to a string.
Error	The error type for HTTP operations.
Request	An HTTP request, returns a `Response`.
RequestBuilder	Request Builder
Response	An HTTP response, returned by `Request`.
Url	A parsed URL record.

Enums

StatusCode

HTTP response status codes.

Traits

HttpClient	An abstract HTTP client.
Status	Provides the `status` method for `Result` and `Option`.

Functions

client	Construct a new `Client`, capable of sending `Request`s and running a middleware stack.
connect	Perform a one-off `CONNECT` request.
delete	Perform a one-off `DELETE` request.
get	Perform a one-off `GET` request.
head	Perform a one-off `HEAD` request.
options	Perform a one-off `OPTIONS` request.
patch	Perform a one-off `PATCH` request.
post	Perform a one-off `POST` request.
put	Perform a one-off `PUT` request.
trace	Perform a one-off `TRACE` request.

Type Definitions

Result

A specialized Result type for Surf.