Struct Accept

pub struct Accept(/* private fields */);

Represents a parsed Accept HTTP header.

This struct holds a list of MediaTypeBuf which are sorted based on their specificity and the value of the q (quality) parameter. In the absence of a q parameter, media types are assumed to have the highest priority. When media types have equal quality parameters, they maintain the order in which they were originally specified.

Implementations

impl Accept

pub fn media_types(&self) -> impl Iterator<Item = &MediaTypeBuf>

Creates an iterator over the MediaTypeBuf entries in the Accept header.

The media types are returned in the order determined by their specificity and the value of their q parameter. Media types with the same q value retain their initial relative ordering from the original header.

pub fn negotiate<'a, Available>( &self, available: Available, ) -> Option<&MediaType<'a>>

where Available: IntoIterator<Item = &'a MediaType<'a>>,

Determine the most acceptable media type from a list of media types available from the server.

The intent here is that the server knows what formats it is capable of delivering, and passes that list to this method. The Accept instance knows what types the client is willing to accept, and works through that list in order of quality until a match is found.

If no agreement on a media type can be reached, then this method returns None.

Tiebreaking

Firstly, this method obeys RFC9110 s12.5.1’s rules around media range specificity:

Media ranges can be overridden by more specific media ranges or specific media types. If more than one media range applies to a given type, the most specific reference has precedence.

Next, if two types in the list of acceptable types have the same quality score, and both are in the available list, then the type that is listed first in the list of acceptable types will be chosen. For example, if the client provides Accept: text/html, text/plain, and the available list is application/json, text/plain, text/html, then text/html will be chosen, as it is deemed to be the client’s preferred option, based on the order in the Accept header.

Finally, the order of the types in the available parameter should match the server’s preference for delivery. In the event that two available types match the same entry in the list of acceptable types, then the first entry in the available list will be chosen. For example, if the client provides Accept: text/html, image/*;q=0.8, and the available list is image/png, image/gif, then image/png will be returned, because it is the first entry in the available list.

Caveats

Don’t put wildcard types or the q parameter in the available list; if you do, all bets are off as to what might happen.

Trait Implementations

impl Debug for Accept

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

Formats the value using the given formatter.

impl Display for Accept

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

Formats the value using the given formatter.

impl<'a> FromIterator<MediaType<'a>> for Accept

fn from_iter<T: IntoIterator<Item = MediaType<'a>>>(iter: T) -> Self

Creates a value from an iterator.

impl FromIterator<MediaTypeBuf> for Accept

fn from_iter<T: IntoIterator<Item = MediaTypeBuf>>(iter: T) -> Self

Creates a value from an iterator.

impl FromStr for Accept

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Header for Accept

fn name() -> &'static HeaderName

The name of this header.

fn decode<'i, I>(values: &mut I) -> Result<Self, HeaderError>

where I: Iterator<Item = &'i HeaderValue>,

Decode this type from an iterator of HeaderValues.

fn encode<E>(&self, values: &mut E)

where E: Extend<HeaderValue>,

Encode this type to a HeaderMap.

impl TryFrom<&HeaderValue> for Accept

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: &HeaderValue) -> Result<Self, Self::Error>

Performs the conversion.