Struct trillium::HttpConfig

source ·
pub struct HttpConfig { /* private fields */ }
Expand description

Performance and security parameters for trillium-http.

Trillium’s http implementation is built with sensible defaults, but applications differ in usage and this escape hatch allows an application to be tuned. It is best to tune these parameters in context of realistic benchmarks for your application.

Long term, trillium may export several standard defaults for different constraints and application types. In the distant future, these may turn into initial values and trillium will tune itself based on values seen at runtime.

Performance parameters

response_buffer_len

The initial buffer allocated for the response. Ideally this would be exactly the length of the combined response headers and body, if the body is short. If the value is shorter than the headers plus the body, multiple transport writes will be performed, and if the value is longer, unnecessary memory will be allocated for each conn. Although a tcp packet can be up to 64kb, it is probably better to use a value less than 1.5kb.

Default: 512

Unit: byte count

request_buffer_initial_len

The initial buffer allocated for the request headers. Ideally this is the length of the request headers. It will grow nonlinearly until max_head_len or the end of the headers are reached, whichever happens first.

Default: 128

Unit: byte count

received_body_initial_len

The initial buffer capacity allocated when reading a chunked http body to bytes or string. Ideally this would be the size of the http body, which is highly application dependent. As with other initial buffer lengths, further allocation will be performed until the necessary length is achieved. A smaller number will result in more vec resizing, and a larger number will result in unnecessary allocation.

Default: 128

Unit: byte count

copy_loops_per_yield

A sort of cooperative task yielding knob. Decreasing this number will improve tail latencies at a slight cost to total throughput for fast clients. This will have more of an impact on servers that spend a lot of time in IO compared to app handlers.

Default: 16

Unit: the number of consecutive Poll::Ready async writes to perform before yielding the task back to the runtime.

response_header_initial_capacity

The number of response headers to allocate space for on conn creation. Headers will grow on insertion when they reach this size.

Default: 16

Unit: Header count

received_body_max_preallocate

When we receive a fixed-length (not chunked-encoding) body that is smaller than this size, we can allocate a buffer with exactly the right size before we receive the body. However, if this is unbounded, malicious clients can issue headers with large content-length and then keep the connection open without sending any bytes, allowing them to allocate memory faster than their bandwidth usage. This does not limit the ability to receive fixed-length bodies larger than this, but the memory allocation will grow as with chunked bodies. Note that this has no impact on chunked bodies. If this is set higher than the received_body_max_len, this parameter has no effect. This parameter only impacts [ReceivedBody::read_string] and [ReceivedBody::read_bytes].

Default: 1mb in bytes

Unit: Byte count

Security parameters

These parameters represent worst cases, to delineate between malicious (or malformed) requests and acceptable ones.

head_max_len

The maximum length allowed before the http body begins for a given request.

Default: 8kb in bytes

Unit: Byte count

received_body_max_len

The maximum length of a received body. This applies to both chunked and fixed-length request bodies, and the correct value will be application dependent.

Default: 500mb in bytes

Unit: Byte count

Implementations§

source§

impl HttpConfig

source

pub fn with_response_buffer_len(self, response_buffer_len: usize) -> HttpConfig

source

pub fn with_request_buffer_initial_len( self, request_buffer_initial_len: usize ) -> HttpConfig

source

pub fn with_head_max_len(self, head_max_len: usize) -> HttpConfig

source

pub fn with_response_header_initial_capacity( self, response_header_initial_capacity: usize ) -> HttpConfig

source

pub fn with_copy_loops_per_yield( self, copy_loops_per_yield: usize ) -> HttpConfig

source

pub fn with_received_body_max_len( self, received_body_max_len: u64 ) -> HttpConfig

source

pub fn with_received_body_max_preallocate( self, received_body_max_preallocate: usize ) -> HttpConfig

Trait Implementations§

source§

impl Clone for HttpConfig

source§

fn clone(&self) -> HttpConfig

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for HttpConfig

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for HttpConfig

source§

fn default() -> HttpConfig

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

impl Copy for HttpConfig

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

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

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

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

The type returned in the event of a conversion error.
source§

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

Performs the conversion.