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::clone_on_copy,
82    clippy::cast_sign_loss,
83    clippy::cast_possible_truncation,
84    clippy::missing_fields_in_debug,
85    clippy::must_use_candidate,
86    clippy::missing_errors_doc,
87    clippy::too_many_lines
88)]
89
90macro_rules! proto_err {
91    (conn: $($msg:tt)+) => {
92        log::debug!("connection error PROTOCOL_ERROR -- {};", format_args!($($msg)+))
93    };
94    (stream: $($msg:tt)+) => {
95        log::debug!("stream error PROTOCOL_ERROR -- {};", format_args!($($msg)+))
96    };
97}
98
99mod codec;
100mod config;
101mod connection;
102mod consts;
103pub mod control;
104mod default;
105mod dispatcher;
106mod error;
107mod message;
108mod stream;
109mod window;
110
111pub mod client;
112pub mod frame;
113pub mod hpack;
114pub mod server;
115
116pub use self::codec::Codec;
117pub use self::config::ServiceConfig;
118pub use self::control::{Control, ControlAck};
119pub use self::message::{Message, MessageKind, StreamEof};
120pub use self::stream::{Capacity, Stream, StreamRef};
121pub use crate::error::{ConnectionError, EncoderError, OperationError, StreamError};
122
123#[doc(hidden)]
124#[deprecated]
125pub type ControlMessage<E> = Control<E>;
126#[doc(hidden)]
127#[deprecated]
128pub type ControlResult = ControlAck;
ntex_h2/lib.rs

ntex_h2/
lib.rs
