1 stable release
2.12.0 | Feb 2, 2024 |
---|
#558 in HTTP client
4,039 downloads per month
Used in crux_http
1MB
11K
SLoC
Unmaintained fork of http-types
Do not use. This will be yanked when no longer needed
lib.rs
:
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.
Dependencies
~4–15MB
~209K SLoC