Crate hyper[−][src]
Hyper
Hyper is a fast, modern HTTP implementation written in and for Rust. It is a low-level typesafe abstraction over raw HTTP, providing an elegant layer over "stringly-typed" HTTP.
Hyper offers both a Client and a Server which can be used to drive complex web applications written entirely in Rust.
Internal Design
Hyper is designed as a relatively low-level wrapper over raw HTTP. It should allow the implementation of higher-level abstractions with as little pain as possible, and should not irrevocably hide any information from its users.
Common Functionality
Functionality and code shared between the Server and Client implementations
can be found in src directly - this includes NetworkStreams, Methods,
StatusCode, and so on.
Methods
Methods are represented as a single enum to remain as simple as possible.
Extension Methods are represented as raw Strings. A method's safety and
idempotence can be accessed using the safe and idempotent methods.
StatusCode
Status codes are also represented as a single, exhaustive, enum. This
representation is efficient, typesafe, and ergonomic as it allows the use of
match to disambiguate known status codes.
Headers
Hyper's header representation is likely the most complex API exposed by Hyper.
Hyper's headers are an abstraction over an internal HashMap and provides a
typesafe API for interacting with headers that does not rely on the use of
"string-typing."
Each HTTP header in Hyper has an associated type and implementation of the
Header trait, which defines an HTTP headers name as a string, how to parse
that header, and how to format that header.
Headers are then parsed from the string representation lazily when the typed representation of a header is requested and formatted back into their string representation when headers are written back to the client.
NetworkStream and NetworkAcceptor
These are found in src/net.rs and define the interface that acceptors and
streams must fulfill for them to be used within Hyper. They are by and large
internal tools and you should only need to mess around with them if you want to
mock or replace TcpStream and TcpAcceptor.
Server
Server-specific functionality, such as Request and Response
representations, are found in in src/server.
Handler + Server
A Handler in Hyper accepts a Request and Response. This is where
user-code can handle each connection. The server accepts connections in a
task pool with a customizable number of threads, and passes the Request /
Response to the handler.
Request
An incoming HTTP Request is represented as a struct containing
a Reader over a NetworkStream, which represents the body, headers, a remote
address, an HTTP version, and a Method - relatively standard stuff.
Request implements Reader itself, meaning that you can ergonomically get
the body out of a Request using standard Reader methods and helpers.
Response
An outgoing HTTP Response is also represented as a struct containing a Writer
over a NetworkStream which represents the Response body in addition to
standard items such as the StatusCode and HTTP version. Response's Writer
implementation provides a streaming interface for sending data over to the
client.
One of the traditional problems with representing outgoing HTTP Responses is tracking the write-status of the Response - have we written the status-line, the headers, the body, etc.? Hyper tracks this information statically using the type system and prevents you, using the type system, from writing headers after you have started writing to the body or vice versa.
Hyper does this through a phantom type parameter in the definition of Response,
which tracks whether you are allowed to write to the headers or the body. This
phantom type can have two values Fresh or Streaming, with Fresh
indicating that you can write the headers and Streaming indicating that you
may write to the body, but not the headers.
Client
Client-specific functionality, such as Request and Response
representations, are found in src/client.
Request
An outgoing HTTP Request is represented as a struct containing a Writer over
a NetworkStream which represents the Request body in addition to the standard
information such as headers and the request method.
Outgoing Requests track their write-status in almost exactly the same way as outgoing HTTP Responses do on the Server, so we will defer to the explanation in the documentation for server Response.
Requests expose an efficient streaming interface instead of a builder pattern, but they also provide the needed interface for creating a builder pattern over the API exposed by core Hyper.
Response
Incoming HTTP Responses are represented as a struct containing a Reader over
a NetworkStream and contain headers, a status, and an http version. They
implement Reader and can be read to get the data out of a Response.
Re-exports
pub use client::Client; |
pub use error::Result; |
pub use error::Error; |
pub use method::Method::Get; |
pub use method::Method::Head; |
pub use method::Method::Post; |
pub use method::Method::Delete; |
pub use status::StatusCode::Ok; |
pub use status::StatusCode::BadRequest; |
pub use status::StatusCode::NotFound; |
pub use server::Server; |
Modules
| client |
HTTP Client |
| error |
Error and Result module. |
| header |
Headers container, and common header fields. |
| http |
Pieces pertaining to the HTTP message protocol. |
| method |
The HTTP request method |
| mime |
Re-exporting the mime crate, for convenience. |
| net |
A collection of traits abstracting over Listeners and Streams. |
| server |
HTTP Server |
| status |
HTTP status codes |
| uri |
HTTP RequestUris |
| version |
HTTP Versions enum |
Macros
| __hyper__deref | |
| __hyper__tm | |
| __hyper_generate_header_serialization | |
| bench_header | |
| header | |
| test_header |
Structs
| LanguageTag |
A language tag as described in BCP47. |
| Url |
The parsed representation of an absolute URL. |