Replace HTTP/2.0 by HTTP/2 😅
The protocol is named HTTP/2.
This commit is contained in:
committed by
Sean McArthur
parent
c38c94cb16
commit
f52d5e6290
@@ -1,18 +1,18 @@
|
||||
//! Client implementation of the HTTP/2.0 protocol.
|
||||
//! Client implementation of the HTTP/2 protocol.
|
||||
//!
|
||||
//! # Getting started
|
||||
//!
|
||||
//! Running an HTTP/2.0 client requires the caller to establish the underlying
|
||||
//! Running an HTTP/2 client requires the caller to establish the underlying
|
||||
//! connection as well as get the connection to a state that is ready to begin
|
||||
//! the HTTP/2.0 handshake. See [here](../index.html#handshake) for more
|
||||
//! the HTTP/2 handshake. See [here](../index.html#handshake) for more
|
||||
//! details.
|
||||
//!
|
||||
//! This could be as basic as using Tokio's [`TcpStream`] to connect to a remote
|
||||
//! host, but usually it means using either ALPN or HTTP/1.1 protocol upgrades.
|
||||
//!
|
||||
//! Once a connection is obtained, it is passed to [`handshake`], which will
|
||||
//! begin the [HTTP/2.0 handshake]. This returns a future that completes once
|
||||
//! the handshake process is performed and HTTP/2.0 streams may be initialized.
|
||||
//! begin the [HTTP/2 handshake]. This returns a future that completes once
|
||||
//! the handshake process is performed and HTTP/2 streams may be initialized.
|
||||
//!
|
||||
//! [`handshake`] uses default configuration values. There are a number of
|
||||
//! settings that can be changed by using [`Builder`] instead.
|
||||
@@ -26,16 +26,16 @@
|
||||
//! # Making requests
|
||||
//!
|
||||
//! Requests are made using the [`SendRequest`] handle provided by the handshake
|
||||
//! future. Once a request is submitted, an HTTP/2.0 stream is initialized and
|
||||
//! future. Once a request is submitted, an HTTP/2 stream is initialized and
|
||||
//! the request is sent to the server.
|
||||
//!
|
||||
//! A request body and request trailers are sent using [`SendRequest`] and the
|
||||
//! server's response is returned once the [`ResponseFuture`] future completes.
|
||||
//! Both the [`SendStream`] and [`ResponseFuture`] instances are returned by
|
||||
//! [`SendRequest::send_request`] and are tied to the HTTP/2.0 stream
|
||||
//! [`SendRequest::send_request`] and are tied to the HTTP/2 stream
|
||||
//! initialized by the sent request.
|
||||
//!
|
||||
//! The [`SendRequest::poll_ready`] function returns `Ready` when a new HTTP/2.0
|
||||
//! The [`SendRequest::poll_ready`] function returns `Ready` when a new HTTP/2
|
||||
//! stream can be created, i.e. as long as the current number of active streams
|
||||
//! is below [`MAX_CONCURRENT_STREAMS`]. If a new stream cannot be created, the
|
||||
//! caller will be notified once an existing stream closes, freeing capacity for
|
||||
@@ -131,7 +131,7 @@
|
||||
//! [`SendRequest`]: struct.SendRequest.html
|
||||
//! [`ResponseFuture`]: struct.ResponseFuture.html
|
||||
//! [`SendRequest::poll_ready`]: struct.SendRequest.html#method.poll_ready
|
||||
//! [HTTP/2.0 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
//! [HTTP/2 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
//! [`Builder`]: struct.Builder.html
|
||||
//! [`Error`]: ../struct.Error.html
|
||||
|
||||
@@ -151,7 +151,7 @@ use std::usize;
|
||||
use tokio::io::{AsyncRead, AsyncWrite, AsyncWriteExt};
|
||||
use tracing::Instrument;
|
||||
|
||||
/// Initializes new HTTP/2.0 streams on a connection by sending a request.
|
||||
/// Initializes new HTTP/2 streams on a connection by sending a request.
|
||||
///
|
||||
/// This type does no work itself. Instead, it is a handle to the inner
|
||||
/// connection state held by [`Connection`]. If the associated connection
|
||||
@@ -161,7 +161,7 @@ use tracing::Instrument;
|
||||
/// / threads than their associated [`Connection`] instance. Internally, there
|
||||
/// is a buffer used to stage requests before they get written to the
|
||||
/// connection. There is no guarantee that requests get written to the
|
||||
/// connection in FIFO order as HTTP/2.0 prioritization logic can play a role.
|
||||
/// connection in FIFO order as HTTP/2 prioritization logic can play a role.
|
||||
///
|
||||
/// [`SendRequest`] implements [`Clone`], enabling the creation of many
|
||||
/// instances that are backed by a single connection.
|
||||
@@ -184,10 +184,10 @@ pub struct ReadySendRequest<B: Buf> {
|
||||
inner: Option<SendRequest<B>>,
|
||||
}
|
||||
|
||||
/// Manages all state associated with an HTTP/2.0 client connection.
|
||||
/// Manages all state associated with an HTTP/2 client connection.
|
||||
///
|
||||
/// A `Connection` is backed by an I/O resource (usually a TCP socket) and
|
||||
/// implements the HTTP/2.0 client logic for that connection. It is responsible
|
||||
/// implements the HTTP/2 client logic for that connection. It is responsible
|
||||
/// for driving the internal state forward, performing the work requested of the
|
||||
/// associated handles ([`SendRequest`], [`ResponseFuture`], [`SendStream`],
|
||||
/// [`RecvStream`]).
|
||||
@@ -220,7 +220,7 @@ pub struct ReadySendRequest<B: Buf> {
|
||||
/// // Submit the connection handle to an executor.
|
||||
/// tokio::spawn(async { connection.await.expect("connection failed"); });
|
||||
///
|
||||
/// // Now, use `send_request` to initialize HTTP/2.0 streams.
|
||||
/// // Now, use `send_request` to initialize HTTP/2 streams.
|
||||
/// // ...
|
||||
/// # Ok(())
|
||||
/// # }
|
||||
@@ -274,7 +274,7 @@ pub struct PushPromises {
|
||||
/// Methods can be chained in order to set the configuration values.
|
||||
///
|
||||
/// The client is constructed by calling [`handshake`] and passing the I/O
|
||||
/// handle that will back the HTTP/2.0 server.
|
||||
/// handle that will back the HTTP/2 server.
|
||||
///
|
||||
/// New instances of `Builder` are obtained via [`Builder::new`].
|
||||
///
|
||||
@@ -294,7 +294,7 @@ pub struct PushPromises {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .initial_window_size(1_000_000)
|
||||
@@ -339,7 +339,7 @@ impl<B> SendRequest<B>
|
||||
where
|
||||
B: Buf + 'static,
|
||||
{
|
||||
/// Returns `Ready` when the connection can initialize a new HTTP/2.0
|
||||
/// Returns `Ready` when the connection can initialize a new HTTP/2
|
||||
/// stream.
|
||||
///
|
||||
/// This function must return `Ready` before `send_request` is called. When
|
||||
@@ -387,16 +387,16 @@ where
|
||||
ReadySendRequest { inner: Some(self) }
|
||||
}
|
||||
|
||||
/// Sends a HTTP/2.0 request to the server.
|
||||
/// Sends a HTTP/2 request to the server.
|
||||
///
|
||||
/// `send_request` initializes a new HTTP/2.0 stream on the associated
|
||||
/// `send_request` initializes a new HTTP/2 stream on the associated
|
||||
/// connection, then sends the given request using this new stream. Only the
|
||||
/// request head is sent.
|
||||
///
|
||||
/// On success, a [`ResponseFuture`] instance and [`SendStream`] instance
|
||||
/// are returned. The [`ResponseFuture`] instance is used to get the
|
||||
/// server's response and the [`SendStream`] instance is used to send a
|
||||
/// request body or trailers to the server over the same HTTP/2.0 stream.
|
||||
/// request body or trailers to the server over the same HTTP/2 stream.
|
||||
///
|
||||
/// To send a request body or trailers, set `end_of_stream` to `false`.
|
||||
/// Then, use the returned [`SendStream`] instance to stream request body
|
||||
@@ -601,7 +601,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .initial_window_size(1_000_000)
|
||||
@@ -643,7 +643,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .initial_window_size(1_000_000)
|
||||
@@ -678,7 +678,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .initial_connection_window_size(1_000_000)
|
||||
@@ -693,7 +693,7 @@ impl Builder {
|
||||
self
|
||||
}
|
||||
|
||||
/// Indicates the size (in octets) of the largest HTTP/2.0 frame payload that the
|
||||
/// Indicates the size (in octets) of the largest HTTP/2 frame payload that the
|
||||
/// configured client is able to accept.
|
||||
///
|
||||
/// The sender may send data frames that are **smaller** than this value,
|
||||
@@ -712,7 +712,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .max_frame_size(1_000_000)
|
||||
@@ -752,7 +752,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .max_header_list_size(16 * 1024)
|
||||
@@ -787,7 +787,7 @@ impl Builder {
|
||||
/// a protocol level error. Instead, the `h2` library will immediately reset
|
||||
/// the stream.
|
||||
///
|
||||
/// See [Section 5.1.2] in the HTTP/2.0 spec for more details.
|
||||
/// See [Section 5.1.2] in the HTTP/2 spec for more details.
|
||||
///
|
||||
/// [Section 5.1.2]: https://http2.github.io/http2-spec/#rfc.section.5.1.2
|
||||
///
|
||||
@@ -801,7 +801,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .max_concurrent_streams(1000)
|
||||
@@ -828,7 +828,7 @@ impl Builder {
|
||||
/// Sending streams past the limit returned by the peer will be treated
|
||||
/// as a stream error of type PROTOCOL_ERROR or REFUSED_STREAM.
|
||||
///
|
||||
/// See [Section 5.1.2] in the HTTP/2.0 spec for more details.
|
||||
/// See [Section 5.1.2] in the HTTP/2 spec for more details.
|
||||
///
|
||||
/// [Section 5.1.2]: https://http2.github.io/http2-spec/#rfc.section.5.1.2
|
||||
///
|
||||
@@ -842,7 +842,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .initial_max_send_streams(1000)
|
||||
@@ -859,7 +859,7 @@ impl Builder {
|
||||
|
||||
/// Sets the maximum number of concurrent locally reset streams.
|
||||
///
|
||||
/// When a stream is explicitly reset, the HTTP/2.0 specification requires
|
||||
/// When a stream is explicitly reset, the HTTP/2 specification requires
|
||||
/// that any further frames received for that stream must be ignored for
|
||||
/// "some time".
|
||||
///
|
||||
@@ -887,7 +887,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .max_concurrent_reset_streams(1000)
|
||||
@@ -904,7 +904,7 @@ impl Builder {
|
||||
|
||||
/// Sets the duration to remember locally reset streams.
|
||||
///
|
||||
/// When a stream is explicitly reset, the HTTP/2.0 specification requires
|
||||
/// When a stream is explicitly reset, the HTTP/2 specification requires
|
||||
/// that any further frames received for that stream must be ignored for
|
||||
/// "some time".
|
||||
///
|
||||
@@ -933,7 +933,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .reset_stream_duration(Duration::from_secs(10))
|
||||
@@ -955,7 +955,7 @@ impl Builder {
|
||||
/// false in the initial SETTINGS handshake guarantees that the remote server
|
||||
/// will never send a push promise.
|
||||
///
|
||||
/// This setting can be changed during the life of a single HTTP/2.0
|
||||
/// This setting can be changed during the life of a single HTTP/2
|
||||
/// connection by sending another settings frame updating the value.
|
||||
///
|
||||
/// Default value: `true`.
|
||||
@@ -971,7 +971,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .enable_push(false)
|
||||
@@ -997,22 +997,22 @@ impl Builder {
|
||||
self
|
||||
}
|
||||
|
||||
/// Creates a new configured HTTP/2.0 client backed by `io`.
|
||||
/// Creates a new configured HTTP/2 client backed by `io`.
|
||||
///
|
||||
/// It is expected that `io` already be in an appropriate state to commence
|
||||
/// the [HTTP/2.0 handshake]. The handshake is completed once both the connection
|
||||
/// the [HTTP/2 handshake]. The handshake is completed once both the connection
|
||||
/// preface and the initial settings frame is sent by the client.
|
||||
///
|
||||
/// The handshake future does not wait for the initial settings frame from the
|
||||
/// server.
|
||||
///
|
||||
/// Returns a future which resolves to the [`Connection`] / [`SendRequest`]
|
||||
/// tuple once the HTTP/2.0 handshake has been completed.
|
||||
/// tuple once the HTTP/2 handshake has been completed.
|
||||
///
|
||||
/// This function also allows the caller to configure the send payload data
|
||||
/// type. See [Outbound data type] for more details.
|
||||
///
|
||||
/// [HTTP/2.0 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [HTTP/2 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [`Connection`]: struct.Connection.html
|
||||
/// [`SendRequest`]: struct.SendRequest.html
|
||||
/// [Outbound data type]: ../index.html#outbound-data-type.
|
||||
@@ -1029,7 +1029,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .handshake(my_io);
|
||||
@@ -1049,7 +1049,7 @@ impl Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Result<((SendRequest<&'static [u8]>, Connection<T, &'static [u8]>)), h2::Error>
|
||||
/// # {
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `client_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let client_fut = Builder::new()
|
||||
/// .handshake::<_, &'static [u8]>(my_io);
|
||||
@@ -1076,19 +1076,19 @@ impl Default for Builder {
|
||||
}
|
||||
}
|
||||
|
||||
/// Creates a new configured HTTP/2.0 client with default configuration
|
||||
/// Creates a new configured HTTP/2 client with default configuration
|
||||
/// values backed by `io`.
|
||||
///
|
||||
/// It is expected that `io` already be in an appropriate state to commence
|
||||
/// the [HTTP/2.0 handshake]. See [Handshake] for more details.
|
||||
/// the [HTTP/2 handshake]. See [Handshake] for more details.
|
||||
///
|
||||
/// Returns a future which resolves to the [`Connection`] / [`SendRequest`]
|
||||
/// tuple once the HTTP/2.0 handshake has been completed. The returned
|
||||
/// tuple once the HTTP/2 handshake has been completed. The returned
|
||||
/// [`Connection`] instance will be using default configuration values. Use
|
||||
/// [`Builder`] to customize the configuration values used by a [`Connection`]
|
||||
/// instance.
|
||||
///
|
||||
/// [HTTP/2.0 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [HTTP/2 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [Handshake]: ../index.html#handshake
|
||||
/// [`Connection`]: struct.Connection.html
|
||||
/// [`SendRequest`]: struct.SendRequest.html
|
||||
@@ -1103,7 +1103,7 @@ impl Default for Builder {
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T) -> Result<(), h2::Error>
|
||||
/// # {
|
||||
/// let (send_request, connection) = client::handshake(my_io).await?;
|
||||
/// // The HTTP/2.0 handshake has completed, now start polling
|
||||
/// // The HTTP/2 handshake has completed, now start polling
|
||||
/// // `connection` and use `send_request` to send requests to the
|
||||
/// // server.
|
||||
/// # Ok(())
|
||||
@@ -1455,7 +1455,7 @@ impl Peer {
|
||||
return Err(UserError::MissingUriSchemeAndAuthority.into());
|
||||
} else {
|
||||
// This is acceptable as per the above comment. However,
|
||||
// HTTP/2.0 requires that a scheme is set. Since we are
|
||||
// HTTP/2 requires that a scheme is set. Since we are
|
||||
// forwarding an HTTP 1.1 request, the scheme is set to
|
||||
// "http".
|
||||
pseudo.set_scheme(uri::Scheme::HTTP);
|
||||
|
||||
@@ -7,7 +7,7 @@ use std::{error, fmt, io};
|
||||
|
||||
pub use crate::frame::Reason;
|
||||
|
||||
/// Represents HTTP/2.0 operation errors.
|
||||
/// Represents HTTP/2 operation errors.
|
||||
///
|
||||
/// `Error` covers error cases raised by protocol errors caused by the
|
||||
/// peer, I/O (transport) errors, and errors caused by the user of the library.
|
||||
|
||||
@@ -36,7 +36,7 @@ impl Head {
|
||||
}
|
||||
}
|
||||
|
||||
/// Parse an HTTP/2.0 frame header
|
||||
/// Parse an HTTP/2 frame header
|
||||
pub fn parse(header: &[u8]) -> Head {
|
||||
let (stream_id, _) = StreamId::parse(&header[5..]);
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
use std::fmt;
|
||||
|
||||
/// HTTP/2.0 error codes.
|
||||
/// HTTP/2 error codes.
|
||||
///
|
||||
/// Error codes are used in `RST_STREAM` and `GOAWAY` frames to convey the
|
||||
/// reasons for the stream or connection error. For example,
|
||||
|
||||
@@ -5,7 +5,7 @@ use http::header::{HeaderName, HeaderValue};
|
||||
use http::{Method, StatusCode};
|
||||
use std::fmt;
|
||||
|
||||
/// HTTP/2.0 Header
|
||||
/// HTTP/2 Header
|
||||
#[derive(Debug, Clone, Eq, PartialEq)]
|
||||
pub enum Header<T = HeaderName> {
|
||||
Field { name: T, value: HeaderValue },
|
||||
|
||||
18
src/lib.rs
18
src/lib.rs
@@ -1,6 +1,6 @@
|
||||
//! An asynchronous, HTTP/2.0 server and client implementation.
|
||||
//! An asynchronous, HTTP/2 server and client implementation.
|
||||
//!
|
||||
//! This library implements the [HTTP/2.0] specification. The implementation is
|
||||
//! This library implements the [HTTP/2] specification. The implementation is
|
||||
//! asynchronous, using [futures] as the basis for the API. The implementation
|
||||
//! is also decoupled from TCP or TLS details. The user must handle ALPN and
|
||||
//! HTTP/1.1 upgrades themselves.
|
||||
@@ -24,19 +24,19 @@
|
||||
//! # Handshake
|
||||
//!
|
||||
//! Both the client and the server require a connection to already be in a state
|
||||
//! ready to start the HTTP/2.0 handshake. This library does not provide
|
||||
//! ready to start the HTTP/2 handshake. This library does not provide
|
||||
//! facilities to do this.
|
||||
//!
|
||||
//! There are three ways to reach an appropriate state to start the HTTP/2.0
|
||||
//! There are three ways to reach an appropriate state to start the HTTP/2
|
||||
//! handshake.
|
||||
//!
|
||||
//! * Opening an HTTP/1.1 connection and performing an [upgrade].
|
||||
//! * Opening a connection with TLS and use ALPN to negotiate the protocol.
|
||||
//! * Open a connection with prior knowledge, i.e. both the client and the
|
||||
//! server assume that the connection is immediately ready to start the
|
||||
//! HTTP/2.0 handshake once opened.
|
||||
//! HTTP/2 handshake once opened.
|
||||
//!
|
||||
//! Once the connection is ready to start the HTTP/2.0 handshake, it can be
|
||||
//! Once the connection is ready to start the HTTP/2 handshake, it can be
|
||||
//! passed to [`server::handshake`] or [`client::handshake`]. At this point, the
|
||||
//! library will start the handshake process, which consists of:
|
||||
//!
|
||||
@@ -48,10 +48,10 @@
|
||||
//!
|
||||
//! # Flow control
|
||||
//!
|
||||
//! [Flow control] is a fundamental feature of HTTP/2.0. The `h2` library
|
||||
//! [Flow control] is a fundamental feature of HTTP/2. The `h2` library
|
||||
//! exposes flow control to the user.
|
||||
//!
|
||||
//! An HTTP/2.0 client or server may not send unlimited data to the peer. When a
|
||||
//! An HTTP/2 client or server may not send unlimited data to the peer. When a
|
||||
//! stream is initiated, both the client and the server are provided with an
|
||||
//! initial window size for that stream. A window size is the number of bytes
|
||||
//! the endpoint can send to the peer. At any point in time, the peer may
|
||||
@@ -66,7 +66,7 @@
|
||||
//! Managing flow control for outbound data is done through [`SendStream`]. See
|
||||
//! the struct level documentation for those two types for more details.
|
||||
//!
|
||||
//! [HTTP/2.0]: https://http2.github.io/
|
||||
//! [HTTP/2]: https://http2.github.io/
|
||||
//! [futures]: https://docs.rs/futures/
|
||||
//! [`client`]: client/index.html
|
||||
//! [`server`]: server/index.html
|
||||
|
||||
@@ -21,7 +21,7 @@ where
|
||||
P: Peer,
|
||||
{
|
||||
/// Holds most of the connection and stream related state for processing
|
||||
/// HTTP/2.0 frames associated with streams.
|
||||
/// HTTP/2 frames associated with streams.
|
||||
inner: Arc<Mutex<Inner>>,
|
||||
|
||||
/// This is the queue of frames to be written to the wire. This is split out
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
//! Server implementation of the HTTP/2.0 protocol.
|
||||
//! Server implementation of the HTTP/2 protocol.
|
||||
//!
|
||||
//! # Getting started
|
||||
//!
|
||||
//! Running an HTTP/2.0 server requires the caller to manage accepting the
|
||||
//! Running an HTTP/2 server requires the caller to manage accepting the
|
||||
//! connections as well as getting the connections to a state that is ready to
|
||||
//! begin the HTTP/2.0 handshake. See [here](../index.html#handshake) for more
|
||||
//! begin the HTTP/2 handshake. See [here](../index.html#handshake) for more
|
||||
//! details.
|
||||
//!
|
||||
//! This could be as basic as using Tokio's [`TcpListener`] to accept
|
||||
@@ -12,8 +12,8 @@
|
||||
//! upgrades.
|
||||
//!
|
||||
//! Once a connection is obtained, it is passed to [`handshake`],
|
||||
//! which will begin the [HTTP/2.0 handshake]. This returns a future that
|
||||
//! completes once the handshake process is performed and HTTP/2.0 streams may
|
||||
//! which will begin the [HTTP/2 handshake]. This returns a future that
|
||||
//! completes once the handshake process is performed and HTTP/2 streams may
|
||||
//! be received.
|
||||
//!
|
||||
//! [`handshake`] uses default configuration values. There are a number of
|
||||
@@ -21,7 +21,7 @@
|
||||
//!
|
||||
//! # Inbound streams
|
||||
//!
|
||||
//! The [`Connection`] instance is used to accept inbound HTTP/2.0 streams. It
|
||||
//! The [`Connection`] instance is used to accept inbound HTTP/2 streams. It
|
||||
//! does this by implementing [`futures::Stream`]. When a new stream is
|
||||
//! received, a call to [`Connection::accept`] will return `(request, response)`.
|
||||
//! The `request` handle (of type [`http::Request<RecvStream>`]) contains the
|
||||
@@ -59,9 +59,9 @@
|
||||
//!
|
||||
//! # Example
|
||||
//!
|
||||
//! A basic HTTP/2.0 server example that runs over TCP and assumes [prior
|
||||
//! A basic HTTP/2 server example that runs over TCP and assumes [prior
|
||||
//! knowledge], i.e. both the client and the server assume that the TCP socket
|
||||
//! will use the HTTP/2.0 protocol without prior negotiation.
|
||||
//! will use the HTTP/2 protocol without prior negotiation.
|
||||
//!
|
||||
//! ```no_run
|
||||
//! use h2::server;
|
||||
@@ -77,9 +77,9 @@
|
||||
//! if let Ok((socket, _peer_addr)) = listener.accept().await {
|
||||
//! // Spawn a new task to process each connection.
|
||||
//! tokio::spawn(async {
|
||||
//! // Start the HTTP/2.0 connection handshake
|
||||
//! // Start the HTTP/2 connection handshake
|
||||
//! let mut h2 = server::handshake(socket).await.unwrap();
|
||||
//! // Accept all inbound HTTP/2.0 streams sent over the
|
||||
//! // Accept all inbound HTTP/2 streams sent over the
|
||||
//! // connection.
|
||||
//! while let Some(request) = h2.accept().await {
|
||||
//! let (request, mut respond) = request.unwrap();
|
||||
@@ -104,7 +104,7 @@
|
||||
//!
|
||||
//! [prior knowledge]: http://httpwg.org/specs/rfc7540.html#known-http
|
||||
//! [`handshake`]: fn.handshake.html
|
||||
//! [HTTP/2.0 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
//! [HTTP/2 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
//! [`Builder`]: struct.Builder.html
|
||||
//! [`Connection`]: struct.Connection.html
|
||||
//! [`Connection::poll`]: struct.Connection.html#method.poll
|
||||
@@ -130,7 +130,7 @@ use std::{convert, fmt, io, mem};
|
||||
use tokio::io::{AsyncRead, AsyncWrite, ReadBuf};
|
||||
use tracing::instrument::{Instrument, Instrumented};
|
||||
|
||||
/// In progress HTTP/2.0 connection handshake future.
|
||||
/// In progress HTTP/2 connection handshake future.
|
||||
///
|
||||
/// This type implements `Future`, yielding a `Connection` instance once the
|
||||
/// handshake has completed.
|
||||
@@ -154,10 +154,10 @@ pub struct Handshake<T, B: Buf = Bytes> {
|
||||
span: tracing::Span,
|
||||
}
|
||||
|
||||
/// Accepts inbound HTTP/2.0 streams on a connection.
|
||||
/// Accepts inbound HTTP/2 streams on a connection.
|
||||
///
|
||||
/// A `Connection` is backed by an I/O resource (usually a TCP socket) and
|
||||
/// implements the HTTP/2.0 server logic for that connection. It is responsible
|
||||
/// implements the HTTP/2 server logic for that connection. It is responsible
|
||||
/// for receiving inbound streams initiated by the client as well as driving the
|
||||
/// internal state forward.
|
||||
///
|
||||
@@ -202,7 +202,7 @@ pub struct Connection<T, B: Buf> {
|
||||
/// Methods can be chained in order to set the configuration values.
|
||||
///
|
||||
/// The server is constructed by calling [`handshake`] and passing the I/O
|
||||
/// handle that will back the HTTP/2.0 server.
|
||||
/// handle that will back the HTTP/2 server.
|
||||
///
|
||||
/// New instances of `Builder` are obtained via [`Builder::new`].
|
||||
///
|
||||
@@ -221,7 +221,7 @@ pub struct Connection<T, B: Buf> {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .initial_window_size(1_000_000)
|
||||
@@ -257,7 +257,7 @@ pub struct Builder {
|
||||
/// stream.
|
||||
///
|
||||
/// If the `SendResponse` instance is dropped without sending a response, then
|
||||
/// the HTTP/2.0 stream will be reset.
|
||||
/// the HTTP/2 stream will be reset.
|
||||
///
|
||||
/// See [module] level docs for more details.
|
||||
///
|
||||
@@ -276,7 +276,7 @@ pub struct SendResponse<B: Buf> {
|
||||
/// It can not be used to initiate push promises.
|
||||
///
|
||||
/// If the `SendPushedResponse` instance is dropped without sending a response, then
|
||||
/// the HTTP/2.0 stream will be reset.
|
||||
/// the HTTP/2 stream will be reset.
|
||||
///
|
||||
/// See [module] level docs for more details.
|
||||
///
|
||||
@@ -318,18 +318,18 @@ pub(crate) struct Peer;
|
||||
|
||||
const PREFACE: [u8; 24] = *b"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n";
|
||||
|
||||
/// Creates a new configured HTTP/2.0 server with default configuration
|
||||
/// Creates a new configured HTTP/2 server with default configuration
|
||||
/// values backed by `io`.
|
||||
///
|
||||
/// It is expected that `io` already be in an appropriate state to commence
|
||||
/// the [HTTP/2.0 handshake]. See [Handshake] for more details.
|
||||
/// the [HTTP/2 handshake]. See [Handshake] for more details.
|
||||
///
|
||||
/// Returns a future which resolves to the [`Connection`] instance once the
|
||||
/// HTTP/2.0 handshake has been completed. The returned [`Connection`]
|
||||
/// HTTP/2 handshake has been completed. The returned [`Connection`]
|
||||
/// instance will be using default configuration values. Use [`Builder`] to
|
||||
/// customize the configuration values used by a [`Connection`] instance.
|
||||
///
|
||||
/// [HTTP/2.0 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [HTTP/2 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [Handshake]: ../index.html#handshake
|
||||
/// [`Connection`]: struct.Connection.html
|
||||
///
|
||||
@@ -343,8 +343,8 @@ const PREFACE: [u8; 24] = *b"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n";
|
||||
/// # async fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # {
|
||||
/// let connection = server::handshake(my_io).await.unwrap();
|
||||
/// // The HTTP/2.0 handshake has completed, now use `connection` to
|
||||
/// // accept inbound HTTP/2.0 streams.
|
||||
/// // The HTTP/2 handshake has completed, now use `connection` to
|
||||
/// // accept inbound HTTP/2 streams.
|
||||
/// # }
|
||||
/// #
|
||||
/// # pub fn main() {}
|
||||
@@ -603,7 +603,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .initial_window_size(1_000_000)
|
||||
@@ -642,7 +642,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .initial_window_size(1_000_000)
|
||||
@@ -676,7 +676,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .initial_connection_window_size(1_000_000)
|
||||
@@ -691,7 +691,7 @@ impl Builder {
|
||||
self
|
||||
}
|
||||
|
||||
/// Indicates the size (in octets) of the largest HTTP/2.0 frame payload that the
|
||||
/// Indicates the size (in octets) of the largest HTTP/2 frame payload that the
|
||||
/// configured server is able to accept.
|
||||
///
|
||||
/// The sender may send data frames that are **smaller** than this value,
|
||||
@@ -709,7 +709,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .max_frame_size(1_000_000)
|
||||
@@ -748,7 +748,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .max_header_list_size(16 * 1024)
|
||||
@@ -783,7 +783,7 @@ impl Builder {
|
||||
/// a protocol level error. Instead, the `h2` library will immediately reset
|
||||
/// the stream.
|
||||
///
|
||||
/// See [Section 5.1.2] in the HTTP/2.0 spec for more details.
|
||||
/// See [Section 5.1.2] in the HTTP/2 spec for more details.
|
||||
///
|
||||
/// [Section 5.1.2]: https://http2.github.io/http2-spec/#rfc.section.5.1.2
|
||||
///
|
||||
@@ -796,7 +796,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .max_concurrent_streams(1000)
|
||||
@@ -815,7 +815,7 @@ impl Builder {
|
||||
///
|
||||
/// When a stream is explicitly reset by either calling
|
||||
/// [`SendResponse::send_reset`] or by dropping a [`SendResponse`] instance
|
||||
/// before completing the stream, the HTTP/2.0 specification requires that
|
||||
/// before completing the stream, the HTTP/2 specification requires that
|
||||
/// any further frames received for that stream must be ignored for "some
|
||||
/// time".
|
||||
///
|
||||
@@ -842,7 +842,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .max_concurrent_reset_streams(1000)
|
||||
@@ -861,7 +861,7 @@ impl Builder {
|
||||
///
|
||||
/// When a stream is explicitly reset by either calling
|
||||
/// [`SendResponse::send_reset`] or by dropping a [`SendResponse`] instance
|
||||
/// before completing the stream, the HTTP/2.0 specification requires that
|
||||
/// before completing the stream, the HTTP/2 specification requires that
|
||||
/// any further frames received for that stream must be ignored for "some
|
||||
/// time".
|
||||
///
|
||||
@@ -889,7 +889,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .reset_stream_duration(Duration::from_secs(10))
|
||||
@@ -904,18 +904,18 @@ impl Builder {
|
||||
self
|
||||
}
|
||||
|
||||
/// Creates a new configured HTTP/2.0 server backed by `io`.
|
||||
/// Creates a new configured HTTP/2 server backed by `io`.
|
||||
///
|
||||
/// It is expected that `io` already be in an appropriate state to commence
|
||||
/// the [HTTP/2.0 handshake]. See [Handshake] for more details.
|
||||
/// the [HTTP/2 handshake]. See [Handshake] for more details.
|
||||
///
|
||||
/// Returns a future which resolves to the [`Connection`] instance once the
|
||||
/// HTTP/2.0 handshake has been completed.
|
||||
/// HTTP/2 handshake has been completed.
|
||||
///
|
||||
/// This function also allows the caller to configure the send payload data
|
||||
/// type. See [Outbound data type] for more details.
|
||||
///
|
||||
/// [HTTP/2.0 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [HTTP/2 handshake]: http://httpwg.org/specs/rfc7540.html#ConnectionHeader
|
||||
/// [Handshake]: ../index.html#handshake
|
||||
/// [`Connection`]: struct.Connection.html
|
||||
/// [Outbound data type]: ../index.html#outbound-data-type.
|
||||
@@ -931,7 +931,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut = Builder::new()
|
||||
/// .handshake(my_io);
|
||||
@@ -951,7 +951,7 @@ impl Builder {
|
||||
/// # fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
|
||||
/// # -> Handshake<T, &'static [u8]>
|
||||
/// # {
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2.0
|
||||
/// // `server_fut` is a future representing the completion of the HTTP/2
|
||||
/// // handshake.
|
||||
/// let server_fut: Handshake<_, &'static [u8]> = Builder::new()
|
||||
/// .handshake(my_io);
|
||||
|
||||
10
src/share.rs
10
src/share.rs
@@ -16,7 +16,7 @@ use std::task::{Context, Poll};
|
||||
/// # Overview
|
||||
///
|
||||
/// A `SendStream` is provided by [`SendRequest`] and [`SendResponse`] once the
|
||||
/// HTTP/2.0 message header has been sent sent. It is used to stream the message
|
||||
/// HTTP/2 message header has been sent sent. It is used to stream the message
|
||||
/// body and send the message trailers. See method level documentation for more
|
||||
/// details.
|
||||
///
|
||||
@@ -35,7 +35,7 @@ use std::task::{Context, Poll};
|
||||
///
|
||||
/// # Flow control
|
||||
///
|
||||
/// In HTTP/2.0, data cannot be sent to the remote peer unless there is
|
||||
/// In HTTP/2, data cannot be sent to the remote peer unless there is
|
||||
/// available window capacity on both the stream and the connection. When a data
|
||||
/// frame is sent, both the stream window and the connection window are
|
||||
/// decremented. When the stream level window reaches zero, no further data can
|
||||
@@ -44,7 +44,7 @@ use std::task::{Context, Poll};
|
||||
///
|
||||
/// When the remote peer is ready to receive more data, it sends `WINDOW_UPDATE`
|
||||
/// frames. These frames increment the windows. See the [specification] for more
|
||||
/// details on the principles of HTTP/2.0 flow control.
|
||||
/// details on the principles of HTTP/2 flow control.
|
||||
///
|
||||
/// The implications for sending data are that the caller **should** ensure that
|
||||
/// both the stream and the connection has available window capacity before
|
||||
@@ -115,7 +115,7 @@ pub struct StreamId(u32);
|
||||
/// Receives the body stream and trailers from the remote peer.
|
||||
///
|
||||
/// A `RecvStream` is provided by [`client::ResponseFuture`] and
|
||||
/// [`server::Connection`] with the received HTTP/2.0 message head (the response
|
||||
/// [`server::Connection`] with the received HTTP/2 message head (the response
|
||||
/// and request head respectively).
|
||||
///
|
||||
/// A `RecvStream` instance is used to receive the streaming message body and
|
||||
@@ -168,7 +168,7 @@ pub struct RecvStream {
|
||||
///
|
||||
/// # Scenarios
|
||||
///
|
||||
/// Following is a basic scenario with an HTTP/2.0 connection containing a
|
||||
/// Following is a basic scenario with an HTTP/2 connection containing a
|
||||
/// single active stream.
|
||||
///
|
||||
/// * A new stream is activated. The receive window is initialized to 1024 (the
|
||||
|
||||
@@ -521,7 +521,7 @@ async fn request_with_connection_headers() {
|
||||
("keep-alive", "5"),
|
||||
("proxy-connection", "bar"),
|
||||
("transfer-encoding", "chunked"),
|
||||
("upgrade", "HTTP/2.0"),
|
||||
("upgrade", "HTTP/2"),
|
||||
("te", "boom"),
|
||||
];
|
||||
|
||||
|
||||
@@ -536,7 +536,7 @@ async fn recv_connection_header() {
|
||||
client
|
||||
.send_frame(req(7, "transfer-encoding", "chunked"))
|
||||
.await;
|
||||
client.send_frame(req(9, "upgrade", "HTTP/2.0")).await;
|
||||
client.send_frame(req(9, "upgrade", "HTTP/2")).await;
|
||||
client.recv_frame(frames::reset(1).protocol_error()).await;
|
||||
client.recv_frame(frames::reset(3).protocol_error()).await;
|
||||
client.recv_frame(frames::reset(5).protocol_error()).await;
|
||||
|
||||
Reference in New Issue
Block a user