1//! A blocking Client API.
2//!
3//! The blocking `Client` will block the current thread to execute, instead
4//! of returning futures that need to be executed on a runtime.
5//!
6//! Conversely, the functionality in `reqwest::blocking` must *not* be executed
7//! within an async runtime, or it will panic when attempting to block. If
8//! calling directly from an async function, consider using an async
9//! [`reqwest::Client`][crate::Client] instead. If the immediate context is only
10//! synchronous, but a transitive caller is async, consider changing that caller
11//! to use [`tokio::task::spawn_blocking`] around the calls that need to block.
12//!
13//! # Optional
14//!
15//! This requires the optional `blocking` feature to be enabled.
16//!
17//! # Making a GET request
18//!
19//! For a single request, you can use the [`get`](get) shortcut method.
20//!
21//! ```rust
22//! # use reqwest::{Error, Response};
23//!
24//! # fn run() -> Result<(), Error> {
25//! let body = reqwest::blocking::get("https://www.rust-lang.org")?
26//! .text()?;
27//!
28//! println!("body = {:?}", body);
29//! # Ok(())
30//! # }
31//! ```
32//!
33//! Additionally, the blocking [`Response`](Response) struct implements Rust's
34//! `Read` trait, so many useful standard library and third party crates will
35//! have convenience methods that take a `Response` anywhere `T: Read` is
36//! acceptable.
37//!
38//! **NOTE**: If you plan to perform multiple requests, it is best to create a
39//! [`Client`](Client) and reuse it, taking advantage of keep-alive connection
40//! pooling.
41//!
42//! # Making POST requests (or setting request bodies)
43//!
44//! There are several ways you can set the body of a request. The basic one is
45//! by using the `body()` method of a [`RequestBuilder`](RequestBuilder). This lets you set the
46//! exact raw bytes of what the body should be. It accepts various types,
47//! including `String`, `Vec<u8>`, and `File`. If you wish to pass a custom
48//! Reader, you can use the `reqwest::blocking::Body::new()` constructor.
49//!
50//! ```rust
51//! # use reqwest::Error;
52//! #
53//! # fn run() -> Result<(), Error> {
54//! let client = reqwest::blocking::Client::new();
55//! let res = client.post("http://httpbin.org/post")
56//! .body("the exact body that is sent")
57//! .send()?;
58//! # Ok(())
59//! # }
60//! ```
61//!
62//! ## And More
63//!
64//! Most features available to the asynchronous `Client` are also available,
65//! on the blocking `Client`, see those docs for more.
66
67mod body;
68mod client;
69#[cfg(feature = "multipart")]
70pub mod multipart;
71mod request;
72mod response;
73mod wait;
74
75pub use self::body::Body;
76pub use self::client::{Client, ClientBuilder};
77pub use self::request::{Request, RequestBuilder};
78pub use self::response::Response;
79
80/// Shortcut method to quickly make a *blocking* `GET` request.
81///
82/// **NOTE**: This function creates a new internal `Client` on each call,
83/// and so should not be used if making many requests. Create a
84/// [`Client`](./struct.Client.html) instead.
85///
86/// # Examples
87///
88/// ```rust
89/// # fn run() -> Result<(), reqwest::Error> {
90/// let body = reqwest::blocking::get("https://www.rust-lang.org")?
91/// .text()?;
92/// # Ok(())
93/// # }
94/// # fn main() { }
95/// ```
96///
97/// # Errors
98///
99/// This function fails if:
100///
101/// - the native TLS backend cannot be initialized,
102/// - the supplied `Url` cannot be parsed,
103/// - there was an error while sending request,
104/// - a redirect loop was detected,
105/// - the redirect limit was exhausted, or
106/// - the total download time exceeds 30 seconds.
107pub fn get<T: crate::IntoUrl>(url: T) -> crate::Result<Response> {
108 Client::builder().build()?.get(url).send()
109}
110