Struct RequestHeader 

pub struct RequestHeader { /* private fields */ }

The HTTP request header type.

This type is similar to http::request::Parts but preserves header name case. It also preserves request path even if it is not UTF-8.

RequestHeader implements Deref for http::request::Parts so it can be used as it in most places. Mutable access to the underlying parts is intentionally not provided because header and URI mutations must use methods on RequestHeader to preserve its internal state.

use pingora_http::RequestHeader;

let mut request = RequestHeader::build("GET", b"/", None).unwrap();
request.headers.remove("user-agent");

Implementations

impl RequestHeader

pub fn build( method: impl TryInto<Method>, path: &[u8], size_hint: Option<usize>, ) -> Result<Self>

Create a new RequestHeader with the given method and path.

The path can be non UTF-8.

pub fn build_no_case( method: impl TryInto<Method>, path: &[u8], size_hint: Option<usize>, ) -> Result<Self>

Create a new RequestHeader with the given method and path without preserving header case.

A RequestHeader created from this type is more space efficient than those from Self::build().

Use this method if reading from or writing to HTTP/2 sessions where header case doesn’t matter anyway.

pub fn append_header( &mut self, name: impl IntoCaseHeaderName, value: impl TryInto<HeaderValue>, ) -> Result<bool>

Append the header name and value to self.

If there are already some headers under the same name, a new value will be added without any others being removed.

pub fn insert_header( &mut self, name: impl IntoCaseHeaderName, value: impl TryInto<HeaderValue>, ) -> Result<()>

Insert the header name and value to self.

Different from Self::append_header(), this method will replace all other existing headers under the same name (case-insensitive).

pub fn remove_header<'a, N: ?Sized>( &mut self, name: &'a N, ) -> Option<HeaderValue>

where &'a N: 'a + AsHeaderName,

Remove all headers under the name

pub fn header_to_h1_wire(&self, buf: &mut impl BufMut)

Write the header to the buf in HTTP/1.1 wire format.

The header case will be preserved.

pub fn case_header_iter( &self, ) -> impl Iterator<Item = (&CaseHeaderName, &HeaderValue)> + '_

If case sensitivity is enabled, returns an iterator to iterate over case-sensitive header names and values. Otherwise returns an empty iterator.

Headers of the same name are visited in insertion order.

pub fn has_case(&self) -> bool

Returns true if the request has case-sensitive headers.

pub fn map<F: FnMut(HeaderNameVariant<'_>, &HeaderValue) -> Result<()>>( &self, f: F, ) -> Result<()>

pub fn extensions_mut(&mut self) -> &mut Extensions

Return mutable access to the request extensions.

pub fn set_method(&mut self, method: Method)

Set the request method

pub fn set_uri(&mut self, uri: Uri)

Set the request URI

pub fn set_raw_path(&mut self, path: &[u8]) -> Result<()>

Set the request target directly via raw bytes.

Generally prefer Self::set_uri() to modify the header’s URI if able.

This API is to allow supporting non UTF-8 cases, and request-targets that are not in origin-form (RFC 9112 section 3.2).

Origin-form and asterisk-form targets round-trip through the URI. Absolute-form and the authority-form CONNECT target do not, so they are additionally kept verbatim for Self::raw_path(). For those two forms the URI carries only the path component, which means http::Uri::path() returns a path rather than a whole URL and http::Uri::authority() is left unset.

Any fragment is dropped: it is not part of the request-target and must not be sent upstream.

pub fn set_send_end_stream(&mut self, send_end_stream: bool)

Set whether we send an END_STREAM on H2 request HEADERS if body is empty.

pub fn send_end_stream(&self) -> Option<bool>

Returns if we support sending an END_STREAM on H2 request HEADERS if body is empty, returns None if not H2.

pub fn raw_path(&self) -> &[u8]

Return the request target in its raw format, as it should appear on the wire.

For origin-form and asterisk-form this is the path and query. For absolute-form and the authority-form CONNECT target it is the whole target as received, less any fragment.

Non-UTF8 is supported; Self::raw_path_is_utf8() reports whether these bytes are valid UTF-8 or were replaced lossily in the URI.

pub fn raw_path_is_utf8(&self) -> bool

Whether Self::raw_path is valid UTF-8 without lossy replacement.

pub fn uri_file_extension(&self) -> Option<&str>

Return the file extension of the path

pub fn set_version(&mut self, version: Version)

Set http version

pub fn as_owned_parts(&self) -> ReqParts

Clone self into http::request::Parts.

ReqParts has nowhere to keep a request-target that does not round-trip through the URI, so an absolute-form or CONNECT target does not survive the conversion: rebuilding a RequestHeader from the result serializes the URI’s origin-form path instead of the original bytes. Clone keeps it; Self::set_raw_path() restores it.

Trait Implementations

impl AsRef<Parts> for RequestHeader

fn as_ref(&self) -> &ReqParts

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

impl Clone for RequestHeader

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RequestHeader

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

Formats the value using the given formatter.

impl Deref for RequestHeader

type Target = Parts

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl From<Parts> for RequestHeader

Header case is not recovered, because ReqParts keeps none, and neither is a request-target that does not round-trip through the URI: the target is taken from the URI rather than the absolute-form or CONNECT bytes a RequestHeader preserves. Set one with Self::set_raw_path().

fn from(parts: ReqParts) -> RequestHeader

Converts to this type from the input type.

impl From<RequestHeader> for Parts

fn from(resp: RequestHeader) -> ReqParts

Converts to this type from the input type.