Enum Host 

#[non_exhaustive]
pub enum Host {
    Name(Domain),
    Address(IpAddr),
    Uninterpreted(UninterpretedHost),
}

Available on crate feature net only.

Either a Domain, an IpAddr, or UninterpretedHost bytes preserved verbatim from a URI authority.

Uninterpreted covers the RFC 3986 host shapes that aren’t a strict DNS-label-shaped Domain or a recognized IP address — pct-encoded reg-name (exa%6Dple.com), sub-delim hostnames (tag,with,commas), IPvFuture literals ([vN.X]), and raw UTF-8 host bytes preserved under graceful URI / IRI parsing. The variant exists so a proxy receiving wire bytes can forward them faithfully; callers needing a canonical typed form convert via the TryFrom impls on UninterpretedHost.

Equality, hashing, and ordering bridge across variant boundaries per RFC 3986 §6.2.2.2: see HostRef’s type-level docs.

Empty Uninterpreted host

RFC 3986 §3.2.2 reg-name = *(...) permits empty bytes, so URIs like file:///path or unix:///run/x parse with Host::Uninterpreted(b""). This is URI-valid but not network-valid — protocol writers that have no representation for “no host” (SOCKS5, TLS SNI, HTTP Host:) will refuse it. Code dispatching a Host onto a network call must either reject the empty case or substitute a sensible default.

Alternate IPv4 forms (SSRF awareness)

Inputs that look like IP addresses but aren’t accepted by Rust’s Ipv4Addr::from_str — octal (0177.0.0.1), hex (0x7f.0.0.1), 3-part (127.0.1), and integer (2130706433) — parse as Host::Name(Domain) rather than Host::Address, because each label is digit-only and passes the DNS-label byte set. This is RFC 3986 compliant (the strings are reg-names under §3.2.2) but diverges from browsers, which normalise all four to 127.0.0.1.

SSRF caveat: code that filters destination addresses on Host::Address will see 0177.0.0.1 as a Name and bypass IP-based allowlists / blocklists. Either:

• resolve through DNS (loopback returns naturally) before applying the filter, OR
• reject any Name whose labels look digit-only at the policy layer, OR
• call crate::uri::Uri::canonicalize first — it doesn’t promote these to Address (Rust’s strict parser still rejects), so this is informational rather than a fix.

Why #[non_exhaustive]

Variant matching is a footgun on this type: a Domain can live in Name or in Uninterpreted (pct-encoded bytes that decode to a domain), and an IpAddr can live in Address or in Uninterpreted (pct-encoded dotted-quad). External callers that pattern-match on the variant tag will miss the bridged forms. Use try_as_domain / try_as_ip (and the try_into_* consuming counterparts) which bridge across variants.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Name(Domain)

A DNS-label-shaped name (ASCII, IDN normalised to ACE on construction via Domain::try_from).

Address(IpAddr)

A literal IPv4 or IPv6 address.

Uninterpreted(UninterpretedHost)

Host bytes preserved verbatim. See UninterpretedHost.

Implementations

impl Host

pub fn try_as_domain( &self, ) -> Result<Cow<'_, Domain>, Box<dyn Error + Send + Sync>>

Returns true if this is the Host::Name variant. View as a Domain, bridging the Uninterpreted variant. Cow::Borrowed for Name; Cow::Owned for an Uninterpreted whose pct-decoded (and IDN-normalized) bytes parse as a domain. Address and IPvFuture-bracketed Uninterpreted fail.

pub fn try_into_domain(self) -> Result<Domain, Box<dyn Error + Send + Sync>>

Consuming form of try_as_domain.

pub fn try_as_ip(&self) -> Result<IpAddr, Box<dyn Error + Send + Sync>>

View as an IpAddr, bridging the Uninterpreted variant. Returns the address from Address directly; Uninterpreted succeeds when its pct-decoded bytes parse as an IPv4 or IPv6 address. Name and IPvFuture-bracketed Uninterpreted fail.

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

Borrowed view. Same shape as From<&Self> for HostRef but surfaces the borrowed view as an inherent method so call sites don’t need the trait in scope.

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

Returns this host as a string. See HostRef::to_str for the borrow / allocation behavior.

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

Available on crate feature idna only.

Returns the Unicode (display) form of this host. For named hosts, any xn-- A-labels are inverse-encoded via UTS #46. IP addresses are rendered to their standard textual form.

Cow::Borrowed when no conversion is needed; Cow::Owned for IP addresses and IDN A-labels that actually require decoding.

impl Host

pub const LOCALHOST_IPV4: Host

Local loopback address (IPv4)

pub const LOCALHOST_IPV6: Host

Local loopback address (IPv6)

pub const LOCALHOST_NAME: Host

Local loopback name

pub const DEFAULT_IPV4: Host

Default address, not routable

pub const DEFAULT_IPV6: Host

Default address, not routable (IPv6)

pub const BROADCAST_IPV4: Host

Broadcast address (IPv4)

pub const EXAMPLE_NAME: Host

example.com domain name

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

Compile-time constructor for a Domain-shaped host. Panics at compile time when s isn’t a valid domain.

Trait Implementations

impl Clone for Host

fn clone(&self) -> Host

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Host

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Host

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Host

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

Formats the value using the given formatter.

impl DomainLabels for Host

type LabelIter<'a> = HostLabelIter<'a>

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

fn labels(&self) -> <Host 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 parent(&self) -> Option<Domain>

Returns the parent Domain (everything but the leftmost label), or None if self has fewer than two labels.

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 Host> for HostRef<'a>

fn from(h: &'a Host) -> HostRef<'a>

Converts to this type from the input type.

impl From<Authority> for Host

fn from(authority: Authority) -> Host

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<Host> for Authority

fn from(host: Host) -> Authority

Converts to this type from the input type.

impl From<Host> for ForwardedAuthority

fn from(value: Host) -> ForwardedAuthority

Converts to this type from the input type.

impl From<Host> for Host

fn from(host: Host) -> Host

Converts to this type from the input type.

impl From<Host> for Host

fn from(value: Host) -> Host

Converts to this type from the input type.

impl From<Host> for HostWithOptPort

fn from(host: Host) -> HostWithOptPort

Converts to this type from the input type.

impl From<HostWithOptPort> for Host

fn from(hwop: HostWithOptPort) -> Host

Converts to this type from the input type.

impl From<HostWithPort> for Host

fn from(hwp: HostWithPort) -> Host

Converts to this type from the input type.

impl From<IpAddr> for Host

fn from(ip: IpAddr) -> Host

Converts to this type from the input type.

impl From<Ipv4Addr> for Host

fn from(ip: Ipv4Addr) -> Host

Converts to this type from the input type.

impl From<Ipv6Addr> for Host

fn from(ip: Ipv6Addr) -> Host

Converts to this type from the input type.

impl FromStr for Host

type Err = Box<dyn Error + Send + Sync>

The associated error which can be returned from parsing.

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

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

impl Hash for Host

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 IntoCanonicalIpAddr for Host

fn into_canonical_ip_addr(self) -> Host

impl Ord for Host

fn cmp(&self, other: &Host) -> 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 Host

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<Host> for &str

fn eq(&self, other: &Host) -> 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<Host> for IpAddr

fn eq(&self, other: &Host) -> 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<Host> for Ipv4Addr

fn eq(&self, other: &Host) -> 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<Host> for Ipv6Addr

fn eq(&self, other: &Host) -> 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<Host> for String

fn eq(&self, other: &Host) -> 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<Host> for str

fn eq(&self, other: &Host) -> 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<IpAddr> for Host

fn eq(&self, other: &IpAddr) -> 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<Ipv4Addr> for Host

fn eq(&self, other: &Ipv4Addr) -> 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<Ipv6Addr> for Host

fn eq(&self, other: &Ipv6Addr) -> 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 Host

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 Host

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

ASCII-case-insensitive compare against a string, matching Domain / Uri / Eq for Host (RFC 3986 §6.2.2.1).

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 Host

fn eq(&self, other: &Host) -> 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 for Host

fn partial_cmp(&self, other: &Host) -> 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<'a> RamaTryFrom<&'a Host, RamaTlsRustlsCrateMarker> for ServerName<'a>

type Error = Box<dyn Error + Send + Sync>

fn rama_try_from( value: &'a Host, ) -> Result<ServerName<'a>, <ServerName<'a> as RamaTryFrom<&'a Host, RamaTlsRustlsCrateMarker>>::Error>

impl<'a> RamaTryFrom<&ServerName<'a>, RamaTlsRustlsCrateMarker> for Host

type Error = Box<dyn Error + Send + Sync>

fn rama_try_from( value: &ServerName<'a>, ) -> Result<Host, <Host as RamaTryFrom<&ServerName<'a>, RamaTlsRustlsCrateMarker>>::Error>

impl RamaTryFrom<Host, RamaTlsRustlsCrateMarker> for ServerName<'_>

type Error = Box<dyn Error + Send + Sync>

fn rama_try_from( value: Host, ) -> Result<ServerName<'_>, <ServerName<'_> as RamaTryFrom<Host, RamaTlsRustlsCrateMarker>>::Error>

impl<'a> RamaTryFrom<ServerName<'a>, RamaTlsRustlsCrateMarker> for Host

type Error = Box<dyn Error + Send + Sync>

fn rama_try_from( value: ServerName<'a>, ) -> Result<Host, <Host as RamaTryFrom<ServerName<'a>, RamaTlsRustlsCrateMarker>>::Error>

impl Serialize for Host

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 Host

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<<Host 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 TryFrom<&[u8]> for Host

type Error = Box<dyn Error + Send + Sync>

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<&HeaderValue> for Host

Available on crate feature http only.

type Error = Box<dyn Error + Send + Sync>

The type returned in the event of a conversion error.

fn try_from( header: &HeaderValue, ) -> Result<Host, <Host as TryFrom<&HeaderValue>>::Error>

Performs the conversion.

impl TryFrom<&str> for Host

type Error = Box<dyn Error + Send + Sync>

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<HeaderValue> for Host

Available on crate feature http only.

type Error = Box<dyn Error + Send + Sync>

The type returned in the event of a conversion error.

fn try_from( header: HeaderValue, ) -> Result<Host, <Host as TryFrom<HeaderValue>>::Error>

Performs the conversion.

impl TryFrom<String> for Host

type Error = Box<dyn Error + Send + Sync>

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Vec<u8>> for Host

type Error = Box<dyn Error + Send + Sync>

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Eq for Host