Skip to main content

hyper/
lib.rs

1#![allow(unused)]
2#![deny(missing_docs)]
3#![deny(missing_debug_implementations)]
4#![cfg_attr(test, deny(rust_2018_idioms))]
5#![cfg_attr(all(test, feature = "full"), deny(unreachable_pub))]
6#![cfg_attr(all(test, feature = "full"), deny(warnings))]
7#![cfg_attr(all(test, feature = "nightly"), feature(test))]
8#![cfg_attr(docsrs, feature(doc_cfg))]
9
10//! # hyper
11//!
12//! hyper is a **fast** and **correct** HTTP implementation written in and for Rust.
13//!
14//! ## Features
15//!
16//! - HTTP/1 and HTTP/2
17//! - Asynchronous design
18//! - [Client](client/index.html) and [Server](server/index.html) APIs
19//!
20//! If just starting out, **check out the [Guides](https://hyper.rs/guides/1/)
21//! first.**
22//!
23//! ## "Low-level"
24//!
25//! hyper is a lower-level HTTP library, meant to be a building block
26//! for libraries and applications.
27//!
28//! If looking for just a convenient HTTP client, consider the
29//! [reqwest](https://crates.io/crates/reqwest) crate.
30//!
31//! # Cancel safety
32//!
33//! Futures returned by hyper are cancel safe: dropping a future before it
34//! completes is the supported way to cancel the operation. The protocol in
35//! use changes what that cancellation actually does on the wire:
36//!
37//! - **HTTP/1** has no in-protocol way to abort a single request without
38//!   affecting the shared connection, so dropping an in-flight request future
39//!   closes the underlying TCP connection. Any subsequent call on the same
40//!   `SendRequest` returns a `canceled` error; the connection cannot be
41//!   reused.
42//! - **HTTP/2** resets the single stream with `RST_STREAM` (`CANCEL` error
43//!   code) and notifies the peer immediately rather than continuing to
44//!   deliver a response body that would be discarded. The shared connection
45//!   stays usable for other in-flight and future requests.
46//!
47//! See the documentation on individual futures — for example
48//! `SendRequest::send_request` in `client::conn::http1` and the equivalent
49//! in `client::conn::http2` — for the protocol-specific behavior on
50//! cancellation.
51//!
52//! # Optional Features
53//!
54//! hyper uses a set of [feature flags] to reduce the amount of compiled code.
55//! It is possible to just enable certain features over others. By default,
56//! hyper does not enable any features but allows one to enable a subset for
57//! their use case. Below is a list of the available feature flags. You may
58//! also notice above each function, struct and trait there is listed one or
59//! more feature flags that are required for that item to be used.
60//!
61//! If you are new to hyper it is possible to enable the `full` feature flag
62//! which will enable all public APIs. Beware though that this will pull in
63//! many extra dependencies that you may not need.
64//!
65//! The following optional features are available:
66//!
67//! - `http1`: Enables HTTP/1 support.
68//! - `http2`: Enables HTTP/2 support.
69//! - `client`: Enables the HTTP `client`.
70//! - `server`: Enables the HTTP `server`.
71//!
72//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
73//!
74//! ## Unstable Features
75//!
76//! hyper includes a set of unstable optional features that can be enabled through the use of a
77//! feature flag and a [configuration flag].
78//!
79//! The following is a list of feature flags and their corresponding `RUSTFLAG`:
80//!
81//! - `ffi`: Enables C API for hyper `hyper_unstable_ffi`.
82//! - `tracing`: Enables debug logging with `hyper_unstable_tracing`.
83//!
84//! For example:
85//!
86//! ```notrust
87//! RUSTFLAGS="--cfg hyper_unstable_tracing" cargo build
88//! ```
89//!
90//! [configuration flag]: https://doc.rust-lang.org/reference/conditional-compilation.html
91//!
92//! # Stability
93//!
94//! It's worth talking a bit about the stability of hyper. hyper's API follows
95//! [SemVer](https://semver.org). Breaking changes will only be introduced in
96//! major versions, if ever. New additions to the API, such as new types,
97//! methods, or traits will only be added in minor versions.
98//!
99//! Some parts of hyper are documented as NOT being part of the stable API. The
100//! following is a brief list, you can read more about each one in the relevant
101//! part of the documentation.
102//!
103//! - Downcasting error types from `Error::source()` is not considered stable.
104//! - Private dependencies use of global variables is not considered stable.
105//!   So, if a dependency uses `log` or `tracing`, hyper doesn't promise it
106//!   will continue to do so.
107//! - Behavior from default options is not stable. hyper reserves the right to
108//!   add new options that are enabled by default which might alter the
109//!   behavior, for the purposes of protection. It is also possible to _change_
110//!   what the default options are set to, also in efforts to protect the
111//!   most people possible.
112#[doc(hidden)]
113pub use http;
114
115#[cfg(all(test, feature = "nightly"))]
116extern crate test;
117
118#[doc(no_inline)]
119pub use http::{header, HeaderMap, Method, Request, Response, StatusCode, Uri, Version};
120
121pub use crate::error::{Error, Result};
122
123#[macro_use]
124mod cfg;
125
126#[macro_use]
127mod trace;
128
129pub mod body;
130mod common;
131mod error;
132pub mod ext;
133#[cfg(test)]
134mod test_support;
135pub mod rt;
136pub mod service;
137pub mod upgrade;
138
139#[cfg(feature = "ffi")]
140#[cfg_attr(docsrs, doc(cfg(all(feature = "ffi", hyper_unstable_ffi))))]
141pub mod ffi;
142
143cfg_proto! {
144    mod headers;
145    mod proto;
146}
147
148cfg_feature! {
149    #![feature = "client"]
150
151    pub mod client;
152}
153
154cfg_feature! {
155    #![feature = "server"]
156
157    pub mod server;
158}