Struct Negotiator

Source

pub struct Negotiator { /* private fields */ }

Expand description

The configurable form of the best_* functions.

§Examples

use parse_net::negotiate::{LanguageMatching, MalformedPolicy, Negotiator, Outcome};

let n = Negotiator::new().language_matching(LanguageMatching::BasicFilter);
assert_eq!(n.language(Some(b"en"), &["fr", "en-GB"]).index(), Some(1));
let strict = Negotiator::new().on_malformed(MalformedPolicy::Refuse);
assert!(matches!(strict.media(Some(b"text/html;q=2"), &["text/html"]), Outcome::Refused(_)));

Implementations§

Source §

impl Negotiator

Source

pub const fn new() -> Self

Default limits, RFC 4647 lookup, malformed headers treated as absent.

§Examples

use parse_net::negotiate::Negotiator;

let n = Negotiator::new();
assert_eq!(n, Negotiator::default());
assert_eq!(n.media(None, &["text/html", "text/plain"]).index(), Some(0));

Source

pub const fn limits(self, l: Limits) -> Self

Sets the limits the request headers are parsed with.

§Examples

use parse_net::{negotiate::{Negotiator, Outcome}, Limits};

let n = Negotiator::new().limits(Limits::DEFAULT.max_list_members(1));
assert_eq!(n.media(Some(b"text/plain, text/html"), &["text/html"]), Outcome::HeaderIgnored { index: 0 });

Source

pub const fn language_matching(self, m: LanguageMatching) -> Self

Sets how language ranges are matched.

§Examples

use parse_net::negotiate::{LanguageMatching, Negotiator};

let n = Negotiator::new().language_matching(LanguageMatching::BasicFilter);
assert_eq!(n.language(Some(b"de"), &["fr", "de-AT"]).index(), Some(1));

Source

pub const fn on_malformed(self, p: MalformedPolicy) -> Self

Sets what happens with a header that does not parse.

§Examples

use parse_net::{negotiate::{MalformedPolicy, Negotiator, Outcome}, ErrorKind};

let n = Negotiator::new().on_malformed(MalformedPolicy::Refuse);
let out = n.encoding(Some(b"gzip;q=2"), &["gzip"]);
assert!(matches!(out, Outcome::Refused(e) if e.kind() == ErrorKind::InvalidQValue));

Source

pub fn media(&self, accept: Option<&[u8]>, offers: &[&str]) -> Outcome

Selects the best of offers (media types such as "text/html") for Accept.

An offer’s weight is the q of the most specific matching range (RFC 9110 section 12.5.1); q=0 means not acceptable; ties go to the earlier offer. An absent header makes every offer acceptable, so the first wins. An offer that is not a valid media type is never chosen.

§Examples

use parse_net::{negotiate::{Negotiator, Outcome}, QValue};

let n = Negotiator::new();
let accept = Some(&b"text/*;q=0.5, text/html"[..]);
assert_eq!(n.media(accept, &["text/plain", "text/html"]), Outcome::Chosen { index: 1, weight: QValue::ONE });
assert_eq!(n.media(accept, &["image/png"]), Outcome::NoneAcceptable);

Source

pub fn media_lines<'a, I>(&self, lines: I, offers: &[&str]) -> Outcome
where I: IntoIterator<Item = &'a [u8]>, I::IntoIter: Clone,

As media, for several Accept field lines read as one list.

§Examples

use parse_net::negotiate::Negotiator;

let lines: [&[u8]; 2] = [b"text/plain;q=0.5", b"application/json"];
assert_eq!(Negotiator::new().media_lines(lines, &["text/plain", "application/json"]).index(), Some(1));

Source

pub fn language(&self, value: Option<&[u8]>, offers: &[&str]) -> Outcome

Selects the best of offers (language tags such as "fr-CA") for Accept-Language.

With LanguageMatching::Lookup (the default), a range matches an offer equal to it or reached by removing subtags from the range’s end, and the exact match has precedence over a shortened one; with LanguageMatching::BasicFilter, a range matches an offer equal to it or starting with it and -, the longest range having precedence. * matches every offer at the lowest precedence. The highest weight wins; between equal weights the closer match (as lookup returns the longest truncation), then the earlier offer. Tags compare ASCII case-insensitively.

§Examples

use parse_net::{negotiate::{Negotiator, Outcome}, QValue};

let n = Negotiator::new();
assert_eq!(n.language(Some(b"fr-CA, en;q=0.8"), &["en", "fr"]), Outcome::Chosen { index: 1, weight: QValue::ONE });

Source

pub fn encoding(&self, value: Option<&[u8]>, offers: &[&str]) -> Outcome

Selects the best of offers (content codings such as "br") for Accept-Encoding (RFC 9110 section 12.5.3).

identity is acceptable unless identity;q=0, or *;q=0 without an explicit identity; an empty field value means only identity is acceptable; x-gzip equals gzip and x-compress equals compress.

§Examples

use parse_net::negotiate::{Negotiator, Outcome};

let n = Negotiator::new();
assert_eq!(n.encoding(Some(b"x-gzip"), &["br", "gzip"]).index(), Some(1));
assert_eq!(n.encoding(Some(b"*;q=0"), &["gzip", "identity"]), Outcome::NoneAcceptable);

Source

pub fn charset(&self, value: Option<&[u8]>, offers: &[&str]) -> Outcome

Selects the best of offers (charsets such as "utf-8") for Accept-Charset: as encoding, without the identity rule.

§Examples

use parse_net::negotiate::{Negotiator, Outcome};

let n = Negotiator::new();
assert_eq!(n.charset(Some(b"utf-8, *;q=0.1"), &["iso-8859-1", "utf-8"]).index(), Some(1));
assert_eq!(n.charset(Some(b"utf-8"), &["iso-8859-1"]), Outcome::NoneAcceptable);