| body |
|
|
- |
| cfg.rs |
|
864 |
- |
| client |
|
|
- |
| common |
|
|
- |
| error.rs |
Error and Result module. |
24659 |
- |
| ext |
|
|
- |
| ffi |
|
|
- |
| headers.rs |
|
4906 |
- |
| lib.rs |
# hyper
hyper is a **fast** and **correct** HTTP implementation written in and for Rust.
## Features
- HTTP/1 and HTTP/2
- Asynchronous design
- Leading in performance
- Tested and **correct**
- Extensive production use
- [Client](client/index.html) and [Server](server/index.html) APIs
If just starting out, **check out the [Guides](https://hyper.rs/guides/1/)
first.**
## "Low-level"
hyper is a lower-level HTTP library, meant to be a building block
for libraries and applications.
If looking for just a convenient HTTP client, consider the
[reqwest](https://crates.io/crates/reqwest) crate.
# Optional Features
hyper uses a set of [feature flags] to reduce the amount of compiled code.
It is possible to just enable certain features over others. By default,
hyper does not enable any features but allows one to enable a subset for
their use case. Below is a list of the available feature flags. You may
also notice above each function, struct and trait there is listed one or
more feature flags that are required for that item to be used.
If you are new to hyper it is possible to enable the `full` feature flag
which will enable all public APIs. Beware though that this will pull in
many extra dependencies that you may not need.
The following optional features are available:
- `http1`: Enables HTTP/1 support.
- `http2`: Enables HTTP/2 support.
- `client`: Enables the HTTP `client`.
- `server`: Enables the HTTP `server`.
[feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
## Unstable Features
hyper includes a set of unstable optional features that can be enabled through the use of a
feature flag and a [configuration flag].
The following is a list of feature flags and their corresponding `RUSTFLAG`:
- `ffi`: Enables C API for hyper `hyper_unstable_ffi`.
- `tracing`: Enables debug logging with `hyper_unstable_tracing`.
For example:
```notrust
RUSTFLAGS="--cfg hyper_unstable_tracing" cargo build
```
[configuration flag]: https://doc.rust-lang.org/reference/conditional-compilation.html
# Stability
It's worth talking a bit about the stability of hyper. hyper's API follows
[SemVer](https://semver.org). Breaking changes will only be introduced in
major versions, if ever. New additions to the API, such as new types,
methods, or traits will only be added in minor versions.
Some parts of hyper are documented as NOT being part of the stable API. The
following is a brief list, you can read more about each one in the relevant
part of the documentation.
- Downcasting error types from `Error::source()` is not considered stable.
- Private dependencies use of global variables is not considered stable.
So, if a dependency uses `log` or `tracing`, hyper doesn't promise it
will continue to do so.
- Behavior from default options is not stable. hyper reserves the right to
add new options that are enabled by default which might alter the
behavior, for the purposes of protection. It is also possible to _change_
what the default options are set to, also in efforts to protect the
most people possible. |
4427 |
- |
| mock.rs |
|
6213 |
- |
| proto |
|
|
- |
| rt |
|
|
- |
| server |
|
|
- |
| service |
|
|
- |
| trace.rs |
|
2551 |
- |
| upgrade.rs |
HTTP Upgrades
This module deals with managing [HTTP Upgrades][mdn] in hyper. Since
several concepts in HTTP allow for first talking HTTP, and then converting
to a different protocol, this module conflates them into a single API.
Those include:
- HTTP/1.1 Upgrades
- HTTP `CONNECT`
You are responsible for any other pre-requisites to establish an upgrade,
such as sending the appropriate headers, methods, and status codes. You can
then use [`on`][] to grab a `Future` which will resolve to the upgraded
connection object, or an error if the upgrade fails.
[mdn]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism
# Client
Sending an HTTP upgrade from the [`client`](super::client) involves setting
either the appropriate method, if wanting to `CONNECT`, or headers such as
`Upgrade` and `Connection`, on the `http::Request`. Once receiving the
`http::Response` back, you must check for the specific information that the
upgrade is agreed upon by the server (such as a `101` status code), and then
get the `Future` from the `Response`.
# Server
Receiving upgrade requests in a server requires you to check the relevant
headers in a `Request`, and if an upgrade should be done, you then send the
corresponding headers in a response. To then wait for hyper to finish the
upgrade, you call `on()` with the `Request`, and then can spawn a task
awaiting it.
# Example
See [this example][example] showing how upgrades work with both
Clients and Servers.
[example]: https://github.com/hyperium/hyper/blob/master/examples/upgrades.rs |
11791 |
- |