ntex_h2/
lib.rs

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//! ntex-h2 = "0.1"
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 octets).
44//! * Both the client and the server sending a SETTINGS frame.
45//!
46//! See the [Starting HTTP/2] in the specification for more details.
47//!
48//! # Flow control
49//!
50//! [Flow control] is a fundamental feature of HTTP/2. The `h2` library
51//! exposes flow control to the user.
52//!
53//! An HTTP/2 client or server may not send unlimited data to the peer. When a
54//! stream is initiated, both the client and the server are provided with an
55//! initial window size for that stream.  A window size is the number of bytes
56//! the endpoint can send to the peer. At any point in time, the peer may
57//! increase this window size by sending a `WINDOW_UPDATE` frame. Once a client
58//! or server has sent data filling the window for a stream, no further data may
59//! be sent on that stream until the peer increases the window.
60//!
61//! There is also a **connection level** window governing data sent across all
62//! streams.
63//!
64//! Managing flow control for inbound data is done through [`FlowControl`].
65//! Managing flow control for outbound data is done through [`SendStream`]. See
66//! the struct level documentation for those two types for more details.
67//!
68//! [HTTP/2]: https://http2.github.io/
69//! [futures]: https://docs.rs/futures/
70//! [Starting HTTP/2]: http://httpwg.org/specs/rfc7540.html#starting
71//! [upgrade]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Protocol_upgrade_mechanism
72// #![allow(clippy::let_underscore_future)]
73#![deny(
74    rust_2018_idioms,
75    warnings,
76    unreachable_pub,
77    missing_debug_implementations,
78    clippy::pedantic
79)]
80#![allow(
81    clippy::cast_sign_loss,
82    clippy::cast_possible_truncation,
83    clippy::missing_fields_in_debug,
84    clippy::must_use_candidate,
85    clippy::missing_errors_doc,
86    clippy::too_many_lines
87)]
88
89macro_rules! proto_err {
90    (conn: $($msg:tt)+) => {
91        log::debug!("connection error PROTOCOL_ERROR -- {};", format_args!($($msg)+))
92    };
93    (stream: $($msg:tt)+) => {
94        log::debug!("stream error PROTOCOL_ERROR -- {};", format_args!($($msg)+))
95    };
96}
97
98mod codec;
99mod config;
100mod connection;
101mod consts;
102pub mod control;
103mod default;
104mod dispatcher;
105mod error;
106mod message;
107mod stream;
108mod window;
109
110pub mod client;
111pub mod frame;
112pub mod hpack;
113pub mod server;
114
115pub use self::codec::Codec;
116pub use self::config::ServiceConfig;
117pub use self::control::{Control, ControlAck};
118pub use self::message::{Message, MessageKind, StreamEof};
119pub use self::stream::{Capacity, Stream, StreamRef};
120pub use crate::error::{ConnectionError, EncoderError, OperationError, StreamError};
121
122#[doc(hidden)]
123#[deprecated]
124pub type ControlMessage<E> = Control<E>;
125#[doc(hidden)]
126#[deprecated]
127pub type ControlResult = ControlAck;
ntex_h2/lib.rs

ntex_h2/
lib.rs
