impl Builder

fn new() -> Builder

Returns a new server builder instance initialized with default configuration values.

Configuration methods can be chained on the return value.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .initial_window_size(1_000_000)
    .max_concurrent_streams(1000)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn initial_window_size(self: &mut Self, size: u32) -> &mut Self

Indicates the initial window size (in octets) for stream-level flow control for received data.

The initial window of a stream is used as part of flow control. For more details, see FlowControl.

The default value is 65,535.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .initial_window_size(1_000_000)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn initial_connection_window_size(self: &mut Self, size: u32) -> &mut Self

Indicates the initial window size (in octets) for connection-level flow control for received data.

The initial window of a connection is used as part of flow control. For more details, see FlowControl.

The default value is 65,535.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `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)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn max_frame_size(self: &mut Self, max: u32) -> &mut Self

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, but any data larger than max will be broken up into multiple DATA frames.

The value must be between 16,384 and 16,777,215. The default value is 16,384.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .max_frame_size(1_000_000)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

Panics

This function panics if max is not within the legal range specified above.

fn max_header_list_size(self: &mut Self, max: u32) -> &mut Self

Sets the max size of received header frames.

This advisory setting informs a peer of the maximum size of header list that the sender is prepared to accept, in octets. The value is based on the uncompressed size of header fields, including the length of the name and value in octets plus an overhead of 32 octets for each header field.

This setting is also used to limit the maximum amount of data that is buffered to decode HEADERS frames.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .max_header_list_size(16 * 1024)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn max_concurrent_streams(self: &mut Self, max: u32) -> &mut Self

Sets the maximum number of concurrent streams.

The maximum concurrent streams setting only controls the maximum number of streams that can be initiated by the remote peer. In other words, when this setting is set to 100, this does not limit the number of concurrent streams that can be created by the caller.

It is recommended that this value be no smaller than 100, so as to not unnecessarily limit parallelism. However, any value is legal, including 0. If max is set to 0, then the remote will not be permitted to initiate streams.

Note that streams in the reserved state, i.e., push promises that have been reserved but the stream has not started, do not count against this setting.

Also note that if the remote does exceed the value set here, it is not a protocol level error. Instead, the h2 library will immediately reset the stream.

See Section 5.1.2 in the HTTP/2 spec for more details.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .max_concurrent_streams(1000)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn max_concurrent_reset_streams(self: &mut Self, max: usize) -> &mut Self

Sets the maximum number of concurrent locally reset streams.

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 specification requires that any further frames received for that stream must be ignored for "some time".

In order to satisfy the specification, internal state must be maintained to implement the behavior. This state grows linearly with the number of streams that are locally reset.

The max_concurrent_reset_streams setting configures sets an upper bound on the amount of state that is maintained. When this max value is reached, the oldest reset stream is purged from memory.

Once the stream has been fully purged from memory, any additional frames received for that stream will result in a connection level protocol error, forcing the connection to terminate.

The default value is 10.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .max_concurrent_reset_streams(1000)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn max_local_error_reset_streams(self: &mut Self, max: Option<usize>) -> &mut Self

Sets the maximum number of local resets due to protocol errors made by the remote end.

Invalid frames and many other protocol errors will lead to resets being generated for those streams. Too many of these often indicate a malicious client, and there are attacks which can abuse this to DOS servers. This limit protects against these DOS attacks by limiting the amount of resets we can be forced to generate.

When the number of local resets exceeds this threshold, the server will issue GOAWAYs with an error code of ENHANCE_YOUR_CALM to the client.

If you really want to disable this, supply Option::None here. Disabling this is not recommended and may expose you to DOS attacks.

The default value is currently 1024, but could change.

fn max_pending_accept_reset_streams(self: &mut Self, max: usize) -> &mut Self

Sets the maximum number of pending-accept remotely-reset streams.

Streams that have been received by the peer, but not accepted by the user, can also receive a RST_STREAM. This is a legitimate pattern: one could send a request and then shortly after, realize it is not needed, sending a CANCEL.

However, since those streams are now "closed", they don't count towards the max concurrent streams. So, they will sit in the accept queue, using memory.

When the number of remotely-reset streams sitting in the pending-accept queue reaches this maximum value, a connection error with the code of ENHANCE_YOUR_CALM will be sent to the peer, and returned by the Future.

The default value is currently 20, but could change.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .max_pending_accept_reset_streams(100)
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn max_send_buffer_size(self: &mut Self, max: usize) -> &mut Self

Sets the maximum send buffer size per stream.

Once a stream has buffered up to (or over) the maximum, the stream's flow control will not "poll" additional capacity. Once bytes for the stream have been written to the connection, the send buffer capacity will be freed up again.

The default is currently ~400KB, but may change.

Panics

This function panics if max is larger than u32::MAX.

fn reset_stream_duration(self: &mut Self, dur: Duration) -> &mut Self

Sets the maximum number of concurrent locally reset streams.

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 specification requires that any further frames received for that stream must be ignored for "some time".

In order to satisfy the specification, internal state must be maintained to implement the behavior. This state grows linearly with the number of streams that are locally reset.

The reset_stream_duration setting configures the max amount of time this state will be maintained in memory. Once the duration elapses, the stream state is purged from memory.

Once the stream has been fully purged from memory, any additional frames received for that stream will result in a connection level protocol error, forcing the connection to terminate.

The default value is 30 seconds.

Examples

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
# use std::time::Duration;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `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))
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

fn enable_connect_protocol(self: &mut Self) -> &mut Self

Enables the extended CONNECT protocol.

fn handshake<T, B>(self: &Self, io: T) -> Handshake<T, B>
where
    T: AsyncRead + AsyncWrite + Unpin,
    B: Buf

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 handshake. See Handshake for more details.

Returns a future which resolves to the Connection instance 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.

Examples

Basic usage:

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# fn doc<T: AsyncRead + AsyncWrite + Unpin>(my_io: T)
# -> Handshake<T>
# {
// `server_fut` is a future representing the completion of the HTTP/2
// handshake.
let server_fut = Builder::new()
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

Configures the send-payload data type. In this case, the outbound data type will be &'static [u8].

# use tokio::io::{AsyncRead, AsyncWrite};
# use h2::server::*;
#
# 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
// handshake.
let server_fut: Handshake<_, &'static [u8]> = Builder::new()
    .handshake(my_io);
# server_fut
# }
#
# pub fn main() {}

impl Clone for Builder

fn clone(self: &Self) -> Builder

impl Debug for Builder

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

impl Default for Builder

fn default() -> Builder

impl Freeze for Builder

impl RefUnwindSafe for Builder

impl Send for Builder

impl Sync for Builder

impl Unpin for Builder

impl UnsafeUnpin for Builder

impl UnwindSafe for Builder

impl<T> Any for Builder

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Builder

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Builder

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for Builder

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Builder

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Instrument for Builder

impl<T> ToOwned for Builder

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T> WithSubscriber for Builder

impl<T, U> Into for Builder

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Builder

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Builder

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>