[−][src]Crate chttp
The practical HTTP client that is fun to use.
Sending requests
Sending requests is as easy as calling a single function. Let's make a simple GET request to an example website:
use chttp::prelude::*; let mut response = chttp::get("https://example.org")?; println!("{}", response.text()?);
By default, sending a request will wait for the response, up until the
response headers are received. The returned response struct includes the
response body as an open stream implementing Read
.
Sending a POST request is also easy, and takes an additional argument for the request body:
let response = chttp::post("https://httpbin.org/post", "make me a salad")?;
cHTTP provides several other simple functions for common HTTP request types:
chttp::put("https://httpbin.org/put", "have a salad")?; chttp::head("https://httpbin.org/get")?; chttp::delete("https://httpbin.org/delete")?;
Custom requests
cHTTP is not limited to canned HTTP verbs; you can customize requests by
creating your own Request
object and then send
ing that.
use chttp::prelude::*; let response = Request::post("https://httpbin.org/post") .header("Content-Type", "application/json") .body(r#"{ "speed": "fast", "cool_name": true }"#)? .send()?;
Request configuration
There are a number of options involved in request execution that can be
configured for a request, such as timeouts, proxies, and other connection
and protocol configuration. These can be customized by using extension
methods provided by the RequestBuilderExt
trait:
use chttp::prelude::*; use std::time::Duration; let response = Request::get("https://httpbin.org/get") .timeout(Duration::from_secs(5)) .body(())? .send()?;
Configuration related to sending requests is stored inside the request
struct using http::Extensions
.
Custom clients
The free-standing functions for sending request delegate to a shared client instance that is lazily instantiated with the default options. You can also create custom client instances of your own, which allows you to set default options for all requests and group related connections together. Each client has its own connection pool and event loop, so separating certain requests into separate clients can ensure that they are isolated from each other.
See the documentation for HttpClient
and HttpClientBuilder
for more
details on creating custom clients.
Asynchronous API and execution
Requests are always executed asynchronously under the hood. This allows a single client to execute a large number of requests concurrently with minimal overhead.
If you are writing an asynchronous application, you can additionally benefit
from the async nature of the client by using the asynchronous methods
available to prevent blocking threads in your code. All request methods have
an asynchronous variant that ends with _async
in the name. Here is our
first example rewritten to use async/await syntax (nightly Rust only):
use chttp::prelude::*; let mut response = chttp::get_async("https://httpbin.org/get").await?; println!("{}", response.text_async().await?);
Logging
cHTTP logs quite a bit of useful information at various levels using the log crate.
If you set the log level to Trace
for the chttp::wire
target, cHTTP will
also log all incoming and outgoing data while in flight. This may come in
handy if you are debugging code and need to see the exact data being sent to
the server and being received.
Re-exports
pub use http; |
Modules
config | Definition of all client and request configuration options. |
cookies | Cookie state management. |
middleware | HTTP client middleware API. |
prelude | A "prelude" for importing common cHTTP types. |
Structs
Body | Contains the body of an HTTP request or response. |
HttpClient | An HTTP client for making requests. |
HttpClientBuilder | An HTTP client builder, capable of creating custom |
ResponseFuture | A future for a request being executed. |
Enums
Error | All possible types of errors that can be returned from cHTTP. |
Functions
delete | Send a DELETE request to the given URI. |
delete_async | Send a DELETE request to the given URI asynchronously. |
get | Send a GET request to the given URI. |
get_async | Send a GET request to the given URI asynchronously. |
head | Send a HEAD request to the given URI. |
head_async | Send a HEAD request to the given URI asynchronously. |
post | Send a POST request to the given URI with a given request body. |
post_async | Send a POST request to the given URI asynchronously with a given request body. |
put | Send a PUT request to the given URI with a given request body. |
put_async | Send a PUT request to the given URI asynchronously with a given request body. |
send | Send an HTTP request and return the HTTP response. |
send_async | Send an HTTP request and return the HTTP response asynchronously. |
version | Gets a human-readable string with the version number of cHTTP and its dependencies. |