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
91macro_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
100macro_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))]
110mod codec;
111mod error;
112mod hpack;
113
114#[cfg(not(feature = "unstable"))]
115mod proto;
116
117#[cfg(feature = "unstable")]
118#[allow(missing_docs)]
119pub mod proto;
120
121#[cfg(not(feature = "unstable"))]
122mod frame;
123
124#[cfg(feature = "unstable")]
125#[allow(missing_docs)]
126pub mod frame;
127
128pub mod client;
129pub mod ext;
130pub mod server;
131mod share;
132
133#[cfg(fuzzing)]
134#[cfg_attr(feature = "unstable", allow(missing_docs))]
135pub mod fuzz_bridge;
136
137pub use crate::error::{Error, Reason};
138pub use crate::share::{FlowControl, Ping, PingPong, Pong, RecvStream, SendStream, StreamId};
139
140#[cfg(feature = "unstable")]
141pub use codec::{Codec, SendError, UserError};
142