Crate http_types[−][src]

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.