Module tide::http

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, as there's 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.

         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 perform (get something, submit something, update something, etc.)

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

A Response consists of a StatusCode, Headers, and optional 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 it was successful or not, and then operates on 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. Also another interesting thing about this is that it's valid to have multiple instances of the same header name. Which is why Headers allows inserting multiple values, and always returns a vector 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. But funamentally they're streams of bytes with a specific encoding, also known as Mime type. The Mime can be set using the set_content_type method, and there are many different Mime types possible.

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. But 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

cookies	HTTP cookies.
headers	HTTP headers.
mime	IANA Media Types.
trailers	HTTP trailing headers.
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.
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.
TypeMap	Store and retrieve values by TypeId.
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.