# Struct h2::client::Builder [−] [src]

    pub struct Builder { /* fields omitted */ }

Builds client connections with custom configuration values.

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.

New instances of `Builder` are obtained via `Builder::new`.

See function level documentation for details on the various client configuration settings.

# Examples

        -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .initial_window_size(1_000_000)
        .max_concurrent_streams(1000)
        .handshake(my_io);

## Implementations

### `impl Builder` [src]

#### `pub fn new() -> Builder` [src]

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

Configuration methods can be chained on the return value.

# Examples

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .initial_window_size(1_000_000)
        .max_concurrent_streams(1000)
        .handshake(my_io);

#### `pub fn initial_window_size(&mut self, size: u32) -> &mut Self` [src]

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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .initial_window_size(1_000_000)
        .handshake(my_io);

#### `pub fn initial_connection_window_size(&mut self, size: u32) -> &mut Self` [src]

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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .initial_connection_window_size(1_000_000)
        .handshake(my_io);

#### `pub fn max_frame_size(&mut self, max: u32) -> &mut Self` [src]

Indicates the size (in octets) of the largest HTTP/2.0 frame payload that the configured client 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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .max_frame_size(1_000_000)
        .handshake(my_io);

# Panics

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

#### `pub fn max_header_list_size(&mut self, max: u32) -> &mut Self` [src]

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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .max_header_list_size(16 * 1024)
        .handshake(my_io);

#### `pub fn max_concurrent_streams(&mut self, max: u32) -> &mut Self` [src]

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.0 spec for more details.

# Examples

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .max_concurrent_streams(1000)
        .handshake(my_io);

#### `pub fn initial_max_send_streams(&mut self, initial: usize) -> &mut Self` [src]

Sets the initial maximum of locally initiated (send) streams.

The initial settings will be overwritten by the remote peer when the Settings frame is received. The new value will be set to the `max_concurrent_streams()` from the frame.

This setting prevents the caller from exceeding this number of streams that are counted towards the concurrency limit.

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.

# Examples

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .initial_max_send_streams(1000)
        .handshake(my_io);

#### `pub fn max_concurrent_reset_streams(&mut self, max: usize) -> &mut Self` [src]

Sets the maximum number of concurrent locally reset streams.

When a stream is explicitly reset, the HTTP/2.0 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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .max_concurrent_reset_streams(1000)
        .handshake(my_io);

#### `pub fn reset_stream_duration(&mut self, dur: Duration) -> &mut Self` [src]

Sets the duration to remember locally reset streams.

When a stream is explicitly reset, the HTTP/2.0 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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .reset_stream_duration(Duration::from_secs(10))
        .handshake(my_io);

#### `pub fn enable_push(&mut self, enabled: bool) -> &mut Self` [src]

Enables or disables server push promises.

This value is included in the initial SETTINGS handshake. When set, the server MUST NOT send a push promise. Setting this value to value to 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 connection by sending another settings frame updating the value.

Default value: `true`.

# Examples

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .enable_push(false)
        .handshake(my_io);

#### `pub fn handshake<T, B>(
&self,
io: T
) -> impl Future<Output = Result<(SendRequest<B>, Connection<T, B>), Error>> where
T: AsyncRead + AsyncWrite + Unpin,
B: Buf + 'static,` [src]

Creates a new configured HTTP/2.0 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 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.

This function also allows the caller to configure the send payload data type. See Outbound data type for more details.

# Examples

Basic usage:

        -> Result<((SendRequest<Bytes>, Connection<T, Bytes>)), h2::Error>
    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .handshake(my_io);

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

    // `client_fut` is a future representing the completion of the HTTP/2.0
    // handshake.
    let client_fut = Builder::new()
        .handshake::<_, &'static [u8]>(my_io);

## Trait Implementations

### `impl Clone for Builder` [src]

#### `fn clone(&self) -> Builder` [src]

Returns a copy of the value. Read more

#### `pub fn clone_from(&mut self, source: &Self)`1.0.0 [src]

Performs copy-assignment from `source`. Read more

### `impl Debug for Builder` [src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

### `impl Default for Builder` [src]

#### `fn default() -> Builder` [src]

Returns the “default value” for a type. Read more

## Auto Trait Implementations

### `impl RefUnwindSafe for Builder`

### `impl Send for Builder`

### `impl Sync for Builder`

### `impl Unpin for Builder`

### `impl UnwindSafe for Builder`

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&self) -> &T` [src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut self) -> &mut T` [src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T` [src]

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

### `impl<T> Instrument for T` [src]

#### `pub fn instrument(self, span: Span) -> Instrumented<Self>` [src]

Instruments this type with the provided `Span`, returning an `Instrumented` wrapper. Read more

#### `pub fn in_current_span(self) -> Instrumented<Self>` [src]

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `pub fn to_owned(&self) -> T` [src]

Creates owned data from borrowed data, usually by cloning. Read more

#### `pub fn clone_into(&self, target: &mut T)` [src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.