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::{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.
• 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.
• 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.
• 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 Aliases

• Result
  A specialized Result type for HTTP operations.