surf/
lib.rs

1//! ## Surf the web - HTTP client framework
2//!
3//! Surf is a Rust HTTP client built for ease-of-use and multi-HTTP-backend flexibility.
4//! Whether it's a quick script, or a cross-platform SDK, Surf will make it work.
5//!
6//! - Extensible through a powerful middleware system
7//! - Multiple HTTP back-ends that can be chosen
8//! - Reuses connections through a configurable `Client` interface
9//! - Fully streaming requests and responses
10//! - TLS enabled by default (native tls or rustls)
11//! - Built on async-std (with optional tokio support)
12//!
13//! # Examples
14//! ```no_run
15//! # #[async_std::main]
16//! # async fn main() -> surf::Result<()> {
17//! let mut res = surf::get("https://httpbin.org/get").await?;
18//! dbg!(res.body_string().await?);
19//! # Ok(()) }
20//! ```
21//!
22//! It's also possible to skip the intermediate `Response`, and access the response type directly.
23//! ```no_run
24//! # #[async_std::main]
25//! # async fn main() -> surf::Result<()> {
26//! dbg!(surf::get("https://httpbin.org/get").recv_string().await?);
27//! # Ok(()) }
28//! ```
29//!
30//! Both sending and receiving JSON is real easy too.
31//! ```no_run
32//! # use serde::{Deserialize, Serialize};
33//! # #[async_std::main]
34//! # async fn main() -> surf::Result<()> {
35//! #[derive(Deserialize, Serialize)]
36//! struct Ip {
37//!     ip: String
38//! }
39//!
40//! let uri = "https://httpbin.org/post";
41//! let data = &Ip { ip: "129.0.0.1".into() };
42//! let res = surf::post(uri).body_json(data)?.await?;
43//! assert_eq!(res.status(), 200);
44//!
45//! let uri = "https://api.ipify.org?format=json";
46//! let Ip { ip } = surf::get(uri).recv_json().await?;
47//! assert!(ip.len() > 10);
48//! # Ok(()) }
49//! ```
50//!
51//! And even creating streaming proxies is no trouble at all.
52//!
53//! ```no_run
54//! # #[async_std::main]
55//! # async fn main() -> surf::Result<()> {
56//! let req = surf::get("https://img.fyi/q6YvNqP").await?;
57//! let body = surf::http::Body::from_reader(req, None);
58//! let res = surf::post("https://box.rs/upload").body(body).await?;
59//! # Ok(()) }
60//! ```
61//!
62//! Setting configuration on a client is also straightforward.
63//!
64//! ```no_run
65//! # #[async_std::main]
66//! # async fn main() -> surf::Result<()> {
67//! use std::convert::TryInto;
68//! use std::time::Duration;
69//! use surf::{Client, Config};
70//! use surf::Url;
71//!
72//! let client: Client = Config::new()
73//!     .set_base_url(Url::parse("http://example.org")?)
74//!     .set_timeout(Some(Duration::from_secs(5)))
75//!     .try_into()?;
76//!    
77//! let mut res = client.get("/").await?;
78//! println!("{}", res.body_string().await?);
79//! # Ok(()) }
80//! ```
81//!
82//! # Features
83//! The following features are available. The default features are
84//! `curl-client`, `middleware-logger`, and `encoding`
85//! - __`curl-client` (default):__ use `curl` (through `isahc`) as the HTTP backend.
86//! - __`h1-client`:__ use `async-h1` as the HTTP backend with native TLS for HTTPS.
87//! - __`h1-client-rustls`:__ use `async-h1` as the HTTP backend with `rustls` for HTTPS.
88//! - __`hyper-client`:__ use `hyper` (hyper.rs) as the HTTP backend.
89//! - __`wasm-client`:__ use `window.fetch` as the HTTP backend.
90//! - __`middleware-logger` (default):__ enables logging requests and responses using a middleware.
91//! - __`encoding` (default):__ enables support for body encodings other than utf-8.
92
93#![deny(missing_debug_implementations, nonstandard_style)]
94#![warn(missing_docs, unreachable_pub, rust_2018_idioms)]
95// #![warn(missing_docs, missing_doc_code_examples, unreachable_pub)] TODO(yw): re-enable me
96#![cfg_attr(test, deny(warnings))]
97#![doc(html_favicon_url = "https://yoshuawuyts.com/assets/http-rs/favicon.ico")]
98#![doc(html_logo_url = "https://yoshuawuyts.com/assets/http-rs/logo-rounded.png")]
99
100mod client;
101mod config;
102mod request;
103mod request_builder;
104mod response;
105
106pub mod middleware;
107pub mod utils;
108
109pub use http_types::{self as http, Body, Error, Status, StatusCode, Url};
110
111pub use http_client::HttpClient;
112
113pub use client::Client;
114pub use config::Config;
115pub use request::Request;
116pub use request_builder::RequestBuilder;
117pub use response::{DecodeError, Response};
118
119cfg_if::cfg_if! {
120    if #[cfg(feature = "default-client")] {
121        mod one_off;
122        pub use one_off::{connect, delete, get, head, options, patch, post, put, trace};
123
124        /// Construct a new `Client`, capable of sending `Request`s and running a middleware stack.
125        ///
126        /// # Examples
127        ///
128        /// ```rust
129        /// # #[async_std::main]
130        /// # async fn main() -> surf::Result<()> {
131        /// let client = surf::client();
132        ///
133        /// let req = surf::get("https://httpbin.org/get");
134        /// let res = client.send(req).await?;
135        /// # Ok(()) }
136        /// ```
137        pub fn client() -> Client {
138            Client::new()
139        }
140    }
141}
142
143/// A specialized Result type for Surf.
144pub type Result<T = Response> = std::result::Result<T, Error>;
surf/lib.rs

surf/
lib.rs
