[−][src]Crate http_types

Common types for HTTP operations.

http-types provides shared types for HTTP operations. It combines a performant, streaming interface with convenient methods for creating headers, urls, and other standard HTTP types.

Example

use http_types::{Url, Method, Request, Response, StatusCode};

let mut req = Request::new(Method::Get, Url::parse("https://example.com")?);
req.set_body("Hello, Nori!");

let mut res = Response::new(StatusCode::Ok);
res.set_body("Hello, Chashu!");

How does HTTP work?

We couldn't possibly explain all of HTTP here: there are 5 versions of the protocol now, and lots of extensions. But, at its core, there are only a few concepts you need to know about in order to understand what this crate does.

         request
client ----------> server
       <----------
         response

HTTP is an RPC protocol. A client creates a Request containing a Url, Method, Headers, and optional Body and sends this to a server. The server then decodes this Request, does some work, and sends back a Response.

The Url works as a way to subdivide an IP address/domain into further addressable resources. The Method indicates what kind of operation we're trying to perform (get something, submit something, update something, etc.)

  Request
|-----------------|
| Url             |
| Method          |
| Headers         |
|-----------------|
| Body (optional) |
|-----------------|

A Response consists of a StatusCode, Headers, and optionally a Body. The client then decodes the Response, and can then operate on it. Usually the first thing it does is check the status code to see if its Request was successful or not, and then moves on to the information contained within the headers.

     Response
|-----------------|
| StatusCode      |
| Headers         |
|-----------------|
| Body (optional) |
|-----------------|

Both Request and Response include Headers. This is like key-value metadata for HTTP requests. It needs to be encoded in a specific way (all lowercase ASCII, only some special characters) so we use the HeaderName and HeaderValue structs rather than strings to ensure that. Another interesting thing about this is that it's valid to have multiple instances of the same header name. This is why Headers allows inserting multiple values, and always returns a Vec of headers for each key.

When reading up on HTTP you might frequently hear a lot of jargon related to ther underlying protocols. But even newer HTTP versions (HTTP/2, HTTP/3) still fundamentally use the request/response model we've described so far.

The Body Type

In HTTP, Body types are optional. The content of a Body is a stream of bytes with a specific encoding; this encoding is its Mime type. The Mime can be set using the set_content_type method, and there are many different possible Mime types.

http-types' Body struct can take anything that implements AsyncBufRead and stream it out. Depending on the version of HTTP used, the underlying bytes will be transmitted differently. As a rule, if you know the size of the body it's usually more efficient to declare it up front. But if you don't, things will still work.

Modules

auth	HTTP authentication and authorization.
cache	HTTP caching.
conditional	HTTP conditional headers.
content	HTTP Content headers.
convert	Traits for conversions between types.
cookies	HTTP cookies.
headers	HTTP headers.
mime	IANA Media Types.
other	Miscellaneous HTTP headers.
proxies	Headers that are set by proxies
security	HTTP Security Headers.
server	HTTP Server Context headers.
trace	HTTP timings and traces.
trailers	HTTP trailing headers.
upgrade	`unstable` HTTP protocol upgrades.
url	URL records.

Macros

bail	Return early with an error.
ensure	Return early with an error if a condition is not satisfied.
ensure_eq	Return early with an error if two expressions are not equal to each other.
format_err	Construct an ad-hoc error from a string.

Structs

Body	A streaming HTTP body.
Cookie	Representation of an HTTP cookie.
Error	The error type for HTTP operations.
Extensions	A type to store extra data inside `Request` and `Response`.
Headers	A collection of HTTP Headers.
Mime	An IANA media type.
Request	An HTTP request.
Response	An HTTP response.
Trailers	A collection of trailing HTTP headers.
Url	A parsed URL record.

Enums

Method	HTTP request methods.
StatusCode	HTTP response status codes.
Version	The version of the HTTP protocol in use.

Traits

Status

Provides the status method for Result and Option.

Type Definitions

Result

A specialized Result type for HTTP operations.