Crate http_types

Expand description

§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::{Method, Request, Response, StatusCode};

let mut req = Request::new(Method::Get, "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.
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.
transfer: HTTP transfer headers.
upgrade: 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.
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 Aliases§

Result: A specialized Result type for HTTP operations.

Crate http_typesCopy item path