1 | //! An asynchronous, HTTP/2 server and client implementation. |
2 | //! |
3 | //! This library implements the [HTTP/2] specification. The implementation is |
4 | //! asynchronous, using [futures] as the basis for the API. The implementation |
5 | //! is also decoupled from TCP or TLS details. The user must handle ALPN and |
6 | //! HTTP/1.1 upgrades themselves. |
7 | //! |
8 | //! # Getting started |
9 | //! |
10 | //! Add the following to your `Cargo.toml` file: |
11 | //! |
12 | //! ```toml |
13 | //! [dependencies] |
14 | //! h2 = "0.3" |
15 | //! ``` |
16 | //! |
17 | //! # Layout |
18 | //! |
19 | //! The crate is split into [`client`] and [`server`] modules. Types that are |
20 | //! common to both clients and servers are located at the root of the crate. |
21 | //! |
22 | //! See module level documentation for more details on how to use `h2`. |
23 | //! |
24 | //! # Handshake |
25 | //! |
26 | //! Both the client and the server require a connection to already be in a state |
27 | //! ready to start the HTTP/2 handshake. This library does not provide |
28 | //! facilities to do this. |
29 | //! |
30 | //! There are three ways to reach an appropriate state to start the HTTP/2 |
31 | //! handshake. |
32 | //! |
33 | //! * Opening an HTTP/1.1 connection and performing an [upgrade]. |
34 | //! * Opening a connection with TLS and use ALPN to negotiate the protocol. |
35 | //! * Open a connection with prior knowledge, i.e. both the client and the |
36 | //! server assume that the connection is immediately ready to start the |
37 | //! HTTP/2 handshake once opened. |
38 | //! |
39 | //! Once the connection is ready to start the HTTP/2 handshake, it can be |
40 | //! passed to [`server::handshake`] or [`client::handshake`]. At this point, the |
41 | //! library will start the handshake process, which consists of: |
42 | //! |
43 | //! * The client sends the connection preface (a predefined sequence of 24 |
44 | //! octets). |
45 | //! * Both the client and the server sending a SETTINGS frame. |
46 | //! |
47 | //! See the [Starting HTTP/2] in the specification for more details. |
48 | //! |
49 | //! # Flow control |
50 | //! |
51 | //! [Flow control] is a fundamental feature of HTTP/2. The `h2` library |
52 | //! exposes flow control to the user. |
53 | //! |
54 | //! An HTTP/2 client or server may not send unlimited data to the peer. When a |
55 | //! stream is initiated, both the client and the server are provided with an |
56 | //! initial window size for that stream. A window size is the number of bytes |
57 | //! the endpoint can send to the peer. At any point in time, the peer may |
58 | //! increase this window size by sending a `WINDOW_UPDATE` frame. Once a client |
59 | //! or server has sent data filling the window for a stream, no further data may |
60 | //! be sent on that stream until the peer increases the window. |
61 | //! |
62 | //! There is also a **connection level** window governing data sent across all |
63 | //! streams. |
64 | //! |
65 | //! Managing flow control for inbound data is done through [`FlowControl`]. |
66 | //! Managing flow control for outbound data is done through [`SendStream`]. See |
67 | //! the struct level documentation for those two types for more details. |
68 | //! |
69 | //! [HTTP/2]: https://http2.github.io/ |
70 | //! [futures]: https://docs.rs/futures/ |
71 | //! [`client`]: client/index.html |
72 | //! [`server`]: server/index.html |
73 | //! [Flow control]: http://httpwg.org/specs/rfc7540.html#FlowControl |
74 | //! [`FlowControl`]: struct.FlowControl.html |
75 | //! [`SendStream`]: struct.SendStream.html |
76 | //! [Starting HTTP/2]: http://httpwg.org/specs/rfc7540.html#starting |
77 | //! [upgrade]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism |
78 | //! [`server::handshake`]: server/fn.handshake.html |
79 | //! [`client::handshake`]: client/fn.handshake.html |
80 | |
81 | #![doc (html_root_url = "https://docs.rs/h2/0.3.22" )] |
82 | #![deny ( |
83 | missing_debug_implementations, |
84 | missing_docs, |
85 | clippy::missing_safety_doc, |
86 | clippy::undocumented_unsafe_blocks |
87 | )] |
88 | #![allow (clippy::type_complexity, clippy::manual_range_contains)] |
89 | #![cfg_attr (test, deny(warnings))] |
90 | |
91 | macro_rules! proto_err { |
92 | (conn: $($msg:tt)+) => { |
93 | tracing::debug!("connection error PROTOCOL_ERROR -- {};" , format_args!($($msg)+)) |
94 | }; |
95 | (stream: $($msg:tt)+) => { |
96 | tracing::debug!("stream error PROTOCOL_ERROR -- {};" , format_args!($($msg)+)) |
97 | }; |
98 | } |
99 | |
100 | macro_rules! ready { |
101 | ($e:expr) => { |
102 | match $e { |
103 | ::std::task::Poll::Ready(r) => r, |
104 | ::std::task::Poll::Pending => return ::std::task::Poll::Pending, |
105 | } |
106 | }; |
107 | } |
108 | |
109 | #[cfg_attr (feature = "unstable" , allow(missing_docs))] |
110 | mod codec; |
111 | mod error; |
112 | mod hpack; |
113 | |
114 | #[cfg (not(feature = "unstable" ))] |
115 | mod proto; |
116 | |
117 | #[cfg (feature = "unstable" )] |
118 | #[allow (missing_docs)] |
119 | pub mod proto; |
120 | |
121 | #[cfg (not(feature = "unstable" ))] |
122 | mod frame; |
123 | |
124 | #[cfg (feature = "unstable" )] |
125 | #[allow (missing_docs)] |
126 | pub mod frame; |
127 | |
128 | pub mod client; |
129 | pub mod ext; |
130 | pub mod server; |
131 | mod share; |
132 | |
133 | #[cfg (fuzzing)] |
134 | #[cfg_attr (feature = "unstable" , allow(missing_docs))] |
135 | pub mod fuzz_bridge; |
136 | |
137 | pub use crate::error::{Error, Reason}; |
138 | pub use crate::share::{FlowControl, Ping, PingPong, Pong, RecvStream, SendStream, StreamId}; |
139 | |
140 | #[cfg (feature = "unstable" )] |
141 | pub use codec::{Codec, SendError, UserError}; |
142 | |