Struct Domain 

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

Available on crate feature net only.

A domain.

Remarks

The validation of domains created by this type is very shallow. Proper validation is offloaded to other services such as DNS resolvers.

Storage is Bytes so that domain values can share allocations with the buffers they were parsed from (e.g. URI byte buffers) at zero copy cost. The validator only accepts ASCII bytes, so the contents are always valid UTF-8.

Implementations

impl Domain

pub const MAX_LEN: usize = MAX_NAME_LEN

Maximum byte length of a fully-qualified domain name (RFC 1035). Inputs longer than this fail validation.

pub const fn from_static(s: &'static str) -> Domain

Creates a domain at compile time.

This function requires the static string to be a valid domain

Panics

This function panics at compile time when the static string is not a valid domain.

pub const fn example() -> Domain

Creates the example `Domain.

pub const fn tld_private() -> Domain

Create an new apex Domain (TLD) meant for loopback purposes.

As proposed in https://itp.cdn.icann.org/en/files/security-and-stability-advisory-committee-ssac-reports/sac-113-en.pdf.

In specific this means that it will match on any domain with the TLD .internal.

pub const fn tld_localhost() -> Domain

Creates the localhost Domain.

pub const fn into_host(self) -> Host

Consumes the domain as a host.

pub fn is_fqdn(&self) -> bool

Returns true if this domain is a Fully Qualified Domain Name.

pub fn is_wildcard(&self) -> bool

Returns true if this domain is a wildcard domain (i.e. its leftmost label is "*").

Label-based — agrees with Self::as_wildcard_parent for inputs like ".*.example.com" where a leading FQDN dot precedes the wildcard.

pub fn is_tld(&self) -> bool

Returns true if this domain is Top-Level Domain (TLD).

Note that we consider a country-level TLD (ccTLD) such as org.uk also a TLD. That is we consider any ccTLD also TLD. While not technically correct, in practice it is at least for the purposes that we are aware of a non-meaningful distinction to make.

Example

use rama_net::address::Domain;

assert!(Domain::from_static("com").is_tld());
assert!(Domain::from_static(".com").is_tld());
assert!(Domain::from_static("co.uk").is_tld());

assert!(!Domain::from_static("example.com").is_tld());
assert!(!Domain::from_static("example.co.uk").is_tld());

pub fn is_sld(&self) -> bool

Returns true if this domain is Second-Level Domain (SLD).

Example

use rama_net::address::Domain;

assert!(!Domain::from_static("com").is_sld());
assert!(!Domain::from_static(".com").is_sld());
assert!(!Domain::from_static("co.uk").is_sld());
assert!(!Domain::from_static(".co.uk").is_sld());

assert!(Domain::from_static(".example.com").is_sld());
assert!(Domain::from_static(".example.co.uk").is_sld());

assert!(!Domain::from_static("foo.example.com").is_sld());
assert!(!Domain::from_static("foo.example.co.uk").is_sld());

pub fn as_wildcard_parent(&self) -> Option<Domain>

Returns the parent of this wildcard domain, or None if self is not a wildcard.

Equivalent to DomainLabels::parent when Self::is_wildcard. Use Self::is_wildcard alone if you only need the predicate; it doesn’t allocate.

pub fn try_as_sub(&self, sub: impl AsDomainRef) -> Result<Domain, PushError>

Try to create a subdomain from the current Domain with the given subdomain prefixed to it.

Errors

Returns PushError if any segment of sub is not a valid label or the combined name would exceed MAX_NAME_LEN.

pub fn try_as_wildcard(&self) -> Result<Domain, PushError>

Promote this Domain to a wildcard.

E.g. turn example.com in *.example.com.

Errors

Returns PushError if the resulting name would exceed MAX_NAME_LEN.

pub fn strip_sub(&self, prefix: impl AsDomainRef) -> Option<Domain>

Try to strip the subdomain (prefix) from the current domain.

prefix is matched label-by-label, case-insensitively. Returns Some(remainder) if every label of prefix matches the corresponding leftmost label of self and at least one label remains; otherwise None.

Behavior note

Prior to the move to label-based matching, this performed a raw case-sensitive string strip_prefix. The current implementation is label-aware and case-insensitive, which is consistent with the rest of the type (Eq/Hash/Ord are also case-insensitive).

pub fn is_sub_of(&self, other: &Domain) -> bool

Returns true if self is a sub-domain of (or equal to) other.

Pure delegation to DomainLabels::is_subdomain_of; kept as an inherent method for source-compat.

pub fn is_parent_of(&self, other: &Domain) -> bool

Returns true if self is a parent of (or equal to) other.

pub fn have_same_registrable_domain(&self, other: &Domain) -> bool

Compare the registrable domain

Example

use rama_net::address::Domain;

assert!(Domain::from_static("www.example.com")
    .have_same_registrable_domain(&Domain::from_static("example.com")));

assert!(Domain::from_static("example.com")
    .have_same_registrable_domain(&Domain::from_static("www.example.com")));

assert!(Domain::from_static("a.example.com")
    .have_same_registrable_domain(&Domain::from_static("b.example.com")));

assert!(Domain::from_static("example.com")
    .have_same_registrable_domain(&Domain::from_static("example.com")));

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

Get the public suffix of the domain

Example

use rama_net::address::Domain;

assert_eq!(Some("com"), Domain::from_static("www.example.com").suffix());
assert_eq!(Some("co.uk"), Domain::from_static("site.co.uk").suffix());

pub fn len(&self) -> usize

Gets the length of domain

pub fn as_str(&self) -> &str

Gets the domain name as reference.

pub fn view(&self) -> DomainRef<'_>

Borrowed view.

pub fn as_unicode(&self) -> Cow<'_, str>

Available on crate feature idna only.

Returns the Unicode (display) form of the domain. See DomainRef::as_unicode for borrow / allocation behavior.

Trait Implementations

impl AsDomainRef for Domain

fn as_wildcard_parent(&self) -> Option<Domain>

fn to_domain(&self) -> Domain

Return an owned Domain.

fn to_wildcard(&self) -> Result<Domain, PushError>

Return this value in wildcard form (*.x).

fn as_wildcard(&self) -> Option<Domain>

If self is already in wildcard form, return it as an owned Domain; otherwise return None.

impl AsRef<str> for Domain

fn as_ref(&self) -> &str

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

impl Clone for Domain

fn clone(&self) -> Domain

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Domain

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Domain

fn deserialize<D>( deserializer: D, ) -> Result<Domain, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Domain

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

Formats the value using the given formatter.

impl DomainLabels for Domain

fn parent(&self) -> Option<Domain>

Domain-specialized fast path: slices the underlying buffer instead of collecting labels into a Vec and join-ing them.

type LabelIter<'a> = DomainLabelIter<'a>

Iterator over the labels of self, yielded most-specific-first ("www.example.com".labels() yields www, example, com).

fn labels(&self) -> <Domain as DomainLabels>::LabelIter<'_>

Returns an iterator over the labels of self.

fn label_count(&self) -> usize

Returns the number of labels.

fn starts_with<D>(&self, prefix: &D) -> bool

where D: DomainLabels + ?Sized,

Returns true if self’s labels start with prefix’s labels (most-specific-end).

fn ends_with<D>(&self, suffix: &D) -> bool

where D: DomainLabels + ?Sized,

Returns true if self’s labels end with suffix’s labels (TLD-end).

fn is_subdomain_of<D>(&self, parent: &D) -> bool

where D: DomainLabels + ?Sized,

Returns true if self is a subdomain of parent (or equal to it).

fn suffix_iter(&self) -> SuffixIter<'_, Self>

where Self: Sized,

Iterator over self and each successive parent, ending just before the empty domain. For "a.b.c" yields "a.b.c", "b.c", "c".

impl<'a> From<&'a Domain> for DomainRef<'a>

fn from(d: &'a Domain) -> DomainRef<'a>

Converts to this type from the input type.

impl From<Domain> for ForwardedAuthority

fn from(value: Domain) -> ForwardedAuthority

Converts to this type from the input type.

impl From<Domain> for Host

fn from(domain: Domain) -> Host

Converts to this type from the input type.

impl From<Domain> for HostSource

fn from(host: Domain) -> HostSource

Converts to this type from the input type.

impl From<Domain> for NodeId

fn from(domain: Domain) -> NodeId

Converts to this type from the input type.

impl From<Domain> for SourceExpression

fn from(d: Domain) -> SourceExpression

Converts to this type from the input type.

impl FromStr for Domain

type Err = DomainParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Domain, <Domain as FromStr>::Err>

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

impl Hash for Domain

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Domain

fn cmp(&self, other: &Domain) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<&str> for Domain

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Domain> for &str

fn eq(&self, other: &Domain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Domain> for String

fn eq(&self, other: &Domain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Domain> for str

fn eq(&self, other: &Domain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<String> for Domain

fn eq(&self, other: &String) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Domain

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Domain

fn eq(&self, other: &Domain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<&str> for Domain

fn partial_cmp(&self, other: &&str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Domain> for &str

fn partial_cmp(&self, other: &Domain) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Domain> for String

fn partial_cmp(&self, other: &Domain) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Domain> for str

fn partial_cmp(&self, other: &Domain) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<String> for Domain

fn partial_cmp(&self, other: &String) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<str> for Domain

fn partial_cmp(&self, other: &str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for Domain

fn partial_cmp(&self, other: &Domain) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Domain

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TraceField for Domain

type Ref<'a> = &'a str

The zero-copy decoded form of this field.

fn field_type() -> FieldType

fn encode<W>(&self, enc: &mut EventEncoder<'_, W>) -> Result<(), Error>

where W: Write,

Encode this field’s value into the event encoder.

fn decode_ref<'a>( val: &FieldValueRef<'a>, ) -> Option<<Domain as TraceField>::Ref<'a>>

Extract this field’s value from a zero-copy FieldValueRef.

fn is_optional() -> bool

Whether this field is optional on the wire (high-bit modifier).

fn decode_missing<'a>() -> Option<Self::Ref<'a>>

Called when the field is absent from the wire data (not in the schema). Returns None for required fields (decode failure) and Some(None) for optional fields.

impl<'a> TryFrom<&'a [u8]> for Domain

type Error = DomainParseError

The type returned in the event of a conversion error.

fn try_from( name: &'a [u8], ) -> Result<Domain, <Domain as TryFrom<&'a [u8]>>::Error>

Performs the conversion.

impl TryFrom<&UninterpretedHost> for Domain

type Error = DomainParseError

The type returned in the event of a conversion error.

fn try_from( host: &UninterpretedHost, ) -> Result<Domain, <Domain as TryFrom<&UninterpretedHost>>::Error>

Performs the conversion.

impl<'a> TryFrom<&'a str> for Domain

type Error = DomainParseError

The type returned in the event of a conversion error.

fn try_from( name: &'a str, ) -> Result<Domain, <Domain as TryFrom<&'a str>>::Error>

Performs the conversion.

impl TryFrom<String> for Domain

type Error = DomainParseError

The type returned in the event of a conversion error.

fn try_from(name: String) -> Result<Domain, <Domain as TryFrom<String>>::Error>

Performs the conversion.

impl TryFrom<UninterpretedHost> for Domain

type Error = DomainParseError

The type returned in the event of a conversion error.

fn try_from( host: UninterpretedHost, ) -> Result<Domain, <Domain as TryFrom<UninterpretedHost>>::Error>

Performs the conversion.

impl<'a> TryFrom<UninterpretedHostRef<'a>> for Domain

fn try_from( host: UninterpretedHostRef<'a>, ) -> Result<Domain, <Domain as TryFrom<UninterpretedHostRef<'a>>>::Error>

Pct-decodes the bytes and, with the idna feature, applies UTS #46 normalization to ACE. Returns a DomainParseError tagged with the “bracketed IP-literal” kind for bracketed inputs — IP-literals are a different grammatical category and have no domain interpretation.

type Error = DomainParseError

The type returned in the event of a conversion error.

impl TryFrom<Vec<u8>> for Domain

type Error = DomainParseError

The type returned in the event of a conversion error.

fn try_from( name: Vec<u8>, ) -> Result<Domain, <Domain as TryFrom<Vec<u8>>>::Error>

Performs the conversion.

impl Eq for Domain

impl IntoDomain for Domain