Struct HttpConfig 

pub struct HttpConfig { /* private fields */ }

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.

Implementations

impl HttpConfig

pub fn head_max_len(&self) -> usize

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

Default: 8kb in bytes

Unit: Byte count

pub fn head_max_len_mut(&mut self) -> &mut usize

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

Default: 8kb in bytes

Unit: Byte count

pub fn set_head_max_len(&mut self, head_max_len: usize) -> &mut HttpConfig

Sets The maximum length allowed before the http body begins for a given request., returning &mut Self for chaining

Default: 8kb in bytes

Unit: Byte count

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

Owned chainable setter for The maximum length allowed before the http body begins for a given request., returning Self

Default: 8kb in bytes

Unit: Byte count

pub fn received_body_max_len(&self) -> u64

Returns a copy of The maximum length of a received body

This limit applies regardless of whether the body is read all at once or streamed incrementally, and regardless of transfer encoding (chunked or fixed-length). The correct value will be application dependent.

Default: 10mb in bytes

Unit: Byte count

pub fn received_body_max_len_mut(&mut self) -> &mut u64

Mutably borrow The maximum length of a received body

This limit applies regardless of whether the body is read all at once or streamed incrementally, and regardless of transfer encoding (chunked or fixed-length). The correct value will be application dependent.

Default: 10mb in bytes

Unit: Byte count

pub fn set_received_body_max_len( &mut self, received_body_max_len: u64, ) -> &mut HttpConfig

Sets The maximum length of a received body, returning &mut Self for chaining

This limit applies regardless of whether the body is read all at once or streamed incrementally, and regardless of transfer encoding (chunked or fixed-length). The correct value will be application dependent.

Default: 10mb in bytes

Unit: Byte count

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

Owned chainable setter for The maximum length of a received body, returning Self

This limit applies regardless of whether the body is read all at once or streamed incrementally, and regardless of transfer encoding (chunked or fixed-length). The correct value will be application dependent.

Default: 10mb in bytes

Unit: Byte count

pub fn response_buffer_len(&self) -> usize

Returns a copy of 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

pub fn response_buffer_len_mut(&mut self) -> &mut usize

Mutably borrow 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

pub fn set_response_buffer_len( &mut self, response_buffer_len: usize, ) -> &mut HttpConfig

Sets The initial buffer allocated for the response., returning &mut Self for chaining

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

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

Owned chainable setter for The initial buffer allocated for the response., returning Self

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

pub fn response_buffer_max_len(&self) -> usize

Returns a copy of Maximum size the response buffer may grow to absorb backpressure.

When the transport cannot accept data as fast as the response body is produced, the buffer absorbs the remainder up to this limit. Once the limit is reached, writes apply backpressure to the body source. This prevents a slow client from causing unbounded memory growth.

Default: 2mb in bytes

Unit: byte count

pub fn response_buffer_max_len_mut(&mut self) -> &mut usize

Mutably borrow Maximum size the response buffer may grow to absorb backpressure.

When the transport cannot accept data as fast as the response body is produced, the buffer absorbs the remainder up to this limit. Once the limit is reached, writes apply backpressure to the body source. This prevents a slow client from causing unbounded memory growth.

Default: 2mb in bytes

Unit: byte count

pub fn set_response_buffer_max_len( &mut self, response_buffer_max_len: usize, ) -> &mut HttpConfig

Sets Maximum size the response buffer may grow to absorb backpressure., returning &mut Self for chaining

When the transport cannot accept data as fast as the response body is produced, the buffer absorbs the remainder up to this limit. Once the limit is reached, writes apply backpressure to the body source. This prevents a slow client from causing unbounded memory growth.

Default: 2mb in bytes

Unit: byte count

pub fn with_response_buffer_max_len( self, response_buffer_max_len: usize, ) -> HttpConfig

Owned chainable setter for Maximum size the response buffer may grow to absorb backpressure., returning Self

When the transport cannot accept data as fast as the response body is produced, the buffer absorbs the remainder up to this limit. Once the limit is reached, writes apply backpressure to the body source. This prevents a slow client from causing unbounded memory growth.

Default: 2mb in bytes

Unit: byte count

pub fn request_buffer_initial_len(&self) -> usize

Returns a copy of 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

pub fn request_buffer_initial_len_mut(&mut self) -> &mut usize

Mutably borrow 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

pub fn set_request_buffer_initial_len( &mut self, request_buffer_initial_len: usize, ) -> &mut HttpConfig

Sets The initial buffer allocated for the request headers., returning &mut Self for chaining

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

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

Owned chainable setter for The initial buffer allocated for the request headers., returning Self

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

pub fn response_header_initial_capacity(&self) -> usize

Returns a copy of 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

pub fn response_header_initial_capacity_mut(&mut self) -> &mut usize

Mutably borrow 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

pub fn set_response_header_initial_capacity( &mut self, response_header_initial_capacity: usize, ) -> &mut HttpConfig

Sets The number of response headers to allocate space for on conn creation., returning &mut Self for chaining

Headers will grow on insertion when they reach this size.

Default: 16

Unit: Header count

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

Owned chainable setter for The number of response headers to allocate space for on conn creation., returning Self

Headers will grow on insertion when they reach this size.

Default: 16

Unit: Header count

pub fn copy_loops_per_yield(&self) -> usize

Returns a copy of 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.

pub fn copy_loops_per_yield_mut(&mut self) -> &mut usize

Mutably borrow 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.

pub fn set_copy_loops_per_yield( &mut self, copy_loops_per_yield: usize, ) -> &mut HttpConfig

Sets A sort of cooperative task yielding knob., returning &mut Self for chaining

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.

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

Owned chainable setter for A sort of cooperative task yielding knob., returning Self

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.

pub fn received_body_initial_len(&self) -> usize

Returns a copy of 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

pub fn received_body_initial_len_mut(&mut self) -> &mut usize

Mutably borrow 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

pub fn set_received_body_initial_len( &mut self, received_body_initial_len: usize, ) -> &mut HttpConfig

Sets The initial buffer capacity allocated when reading a chunked http body to bytes or string., returning &mut Self for chaining

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

pub fn with_received_body_initial_len( self, received_body_initial_len: usize, ) -> HttpConfig

Owned chainable setter for The initial buffer capacity allocated when reading a chunked http body to bytes or string., returning Self

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

pub fn received_body_max_preallocate(&self) -> usize

Returns a copy of Maximum size to pre-allocate based on content-length for buffering a complete request body

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

pub fn received_body_max_preallocate_mut(&mut self) -> &mut usize

Mutably borrow Maximum size to pre-allocate based on content-length for buffering a complete request body

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

pub fn set_received_body_max_preallocate( &mut self, received_body_max_preallocate: usize, ) -> &mut HttpConfig

Sets Maximum size to pre-allocate based on content-length for buffering a complete request body, returning &mut Self for chaining

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

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

Owned chainable setter for Maximum size to pre-allocate based on content-length for buffering a complete request body, returning Self

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

pub fn h3_max_field_section_size(&self) -> u64

Returns a copy of The maximum size of a field section (header block) the peer may send in HTTP/3

This is a protocol-level setting and is communicated to the peer.

Default: 8kb

Unit: Byte count

pub fn h3_max_field_section_size_mut(&mut self) -> &mut u64

Mutably borrow The maximum size of a field section (header block) the peer may send in HTTP/3

This is a protocol-level setting and is communicated to the peer.

Default: 8kb

Unit: Byte count

pub fn set_h3_max_field_section_size( &mut self, h3_max_field_section_size: u64, ) -> &mut HttpConfig

Sets The maximum size of a field section (header block) the peer may send in HTTP/3, returning &mut Self for chaining

This is a protocol-level setting and is communicated to the peer.

Default: 8kb

Unit: Byte count

pub fn with_h3_max_field_section_size( self, h3_max_field_section_size: u64, ) -> HttpConfig

Owned chainable setter for The maximum size of a field section (header block) the peer may send in HTTP/3, returning Self

This is a protocol-level setting and is communicated to the peer.

Default: 8kb

Unit: Byte count

pub fn h3_datagrams_enabled(&self) -> bool

Returns a copy of whether datagrams are enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer as well as enforced.

Default: false

pub fn h3_datagrams_enabled_mut(&mut self) -> &mut bool

Mutably borrow whether datagrams are enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer as well as enforced.

Default: false

pub fn set_h3_datagrams_enabled( &mut self, h3_datagrams_enabled: bool, ) -> &mut HttpConfig

Sets whether datagrams are enabled for HTTP/3, returning &mut Self for chaining

This is a protocol-level setting and is communicated to the peer as well as enforced.

Default: false

pub fn with_h3_datagrams_enabled(self) -> HttpConfig

Owned chainable setter for whether datagrams are enabled for HTTP/3, returning Self

This is a protocol-level setting and is communicated to the peer as well as enforced.

Default: false

pub fn without_h3_datagrams_enabled(self) -> HttpConfig

Owned chainable setter for whether datagrams are enabled for HTTP/3, returning Self

This is a protocol-level setting and is communicated to the peer as well as enforced.

Default: false

pub fn webtransport_enabled(&self) -> bool

Returns a copy of whether webtransport (draft-ietf-webtrans-http3) is enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer. You do not need to manually configure this if using trillium-webtransport

Default: false

pub fn webtransport_enabled_mut(&mut self) -> &mut bool

Mutably borrow whether webtransport (draft-ietf-webtrans-http3) is enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer. You do not need to manually configure this if using trillium-webtransport

Default: false

pub fn set_webtransport_enabled( &mut self, webtransport_enabled: bool, ) -> &mut HttpConfig

Sets whether webtransport, returning &mut Self for chaining (draft-ietf-webtrans-http3) is enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer. You do not need to manually configure this if using trillium-webtransport

Default: false

pub fn with_webtransport_enabled(self) -> HttpConfig

Owned chainable setter for whether webtransport, returning Self (draft-ietf-webtrans-http3) is enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer. You do not need to manually configure this if using trillium-webtransport

Default: false

pub fn without_webtransport_enabled(self) -> HttpConfig

Owned chainable setter for whether webtransport, returning Self (draft-ietf-webtrans-http3) is enabled for HTTP/3

This is a protocol-level setting and is communicated to the peer. You do not need to manually configure this if using trillium-webtransport

Default: false

pub fn panic_on_invalid_response_headers(&self) -> bool

Returns a copy of whether to panic when a response header with an invalid value (containing \r, \n, or \0) is encountered.

Invalid header values are always skipped to prevent header injection. When this is true, Trillium will additionally panic, surfacing the bug loudly. When false, the skip is only logged (to the log backend) at error level.

Default: true when compiled with debug_assertions (i.e. debug builds), false in release builds. Override to true in release if you want strict production behavior, or to false in debug if you prefer not to panic during development.

pub fn panic_on_invalid_response_headers_mut(&mut self) -> &mut bool

Mutably borrow whether to panic when a response header with an invalid value (containing \r, \n, or \0) is encountered.

Invalid header values are always skipped to prevent header injection. When this is true, Trillium will additionally panic, surfacing the bug loudly. When false, the skip is only logged (to the log backend) at error level.

Default: true when compiled with debug_assertions (i.e. debug builds), false in release builds. Override to true in release if you want strict production behavior, or to false in debug if you prefer not to panic during development.

pub fn set_panic_on_invalid_response_headers( &mut self, panic_on_invalid_response_headers: bool, ) -> &mut HttpConfig

Sets whether to panic when a response header with an invalid value (containing \r, \n, or, returning &mut Self for chaining \0) is encountered.

Invalid header values are always skipped to prevent header injection. When this is true, Trillium will additionally panic, surfacing the bug loudly. When false, the skip is only logged (to the log backend) at error level.

Default: true when compiled with debug_assertions (i.e. debug builds), false in release builds. Override to true in release if you want strict production behavior, or to false in debug if you prefer not to panic during development.

pub fn with_panic_on_invalid_response_headers(self) -> HttpConfig

Owned chainable setter for whether to panic when a response header with an invalid value (containing \r, \n, or, returning Self \0) is encountered.

Invalid header values are always skipped to prevent header injection. When this is true, Trillium will additionally panic, surfacing the bug loudly. When false, the skip is only logged (to the log backend) at error level.

Default: true when compiled with debug_assertions (i.e. debug builds), false in release builds. Override to true in release if you want strict production behavior, or to false in debug if you prefer not to panic during development.

pub fn without_panic_on_invalid_response_headers(self) -> HttpConfig

Owned chainable setter for whether to panic when a response header with an invalid value (containing \r, \n, or, returning Self \0) is encountered.

Invalid header values are always skipped to prevent header injection. When this is true, Trillium will additionally panic, surfacing the bug loudly. When false, the skip is only logged (to the log backend) at error level.

Default: true when compiled with debug_assertions (i.e. debug builds), false in release builds. Override to true in release if you want strict production behavior, or to false in debug if you prefer not to panic during development.

impl HttpConfig

pub const DEFAULT: HttpConfig

Default Config

Trait Implementations

impl AsRef<HttpConfig> for HttpContext

fn as_ref(&self) -> &HttpConfig

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for HttpConfig

fn clone(&self) -> HttpConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HttpConfig

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

Formats the value using the given formatter.

impl Default for HttpConfig

fn default() -> HttpConfig

Returns the “default value” for a type.

impl Copy for HttpConfig