Struct TrustRoot 

pub struct TrustRoot { /* private fields */ }

A validated trust root (authority) from an agent URI.

The trust root identifies the authority that vouches for an agent’s identity and capabilities. It consists of a host (domain or IP) and an optional port.

Examples

use agent_uri::TrustRoot;

let root = TrustRoot::parse("anthropic.com").unwrap();
assert_eq!(root.host_str(), "anthropic.com");
assert!(root.port().is_none());

let root = TrustRoot::parse("localhost:8472").unwrap();
assert_eq!(root.host_str(), "localhost");
assert_eq!(root.port(), Some(8472));

Internationalized names

A trust root is ASCII. Converting an internationalized name to A-label form is the caller’s job, and this type will not tell you whether you did it right. Three consequences, none of them accidents:

1. A non-ASCII name is rejected, not converted. münchen.de is an error, not a synonym for xn--mnchen-3ya.de. Doing the conversion here would mean shipping a Unicode normalization table and a version of UTS #46 inside an identity type, and two versions of that table disagreeing would make one name two identities. Refusing is the smaller surface.
2. An xn-- label is opaque ASCII. It is checked as a DNS label and nothing more: no Punycode decode, no IDNA validity check, no bidirectional or script rules. xn--zzzzzz is not valid Punycode and parses anyway. If a name reaches here already broken, it stays broken.
3. Nothing here detects confusables. аpple.com with a Cyrillic а is rejected only because it is not ASCII; its A-label form, xn--pple-43d.com, is accepted and is a different trust root than apple.com. Two names that a person cannot tell apart are two identities, and only the second ever reaches this type. Homograph defence belongs where names are shown to people and where keys are fetched, not in a parser that sees ASCII.

A trailing dot is rejected rather than stripped, so the DNS root-anchored example.com. is not a spelling of example.com; only the latter names that identity. ASCII case is folded, per RFC 4343.

use agent_uri::TrustRoot;

// Convert before you get here.
assert!(TrustRoot::parse("münchen.de").is_err());
assert!(TrustRoot::parse("xn--mnchen-3ya.de").is_ok());

// Which means a name that was converted wrongly is accepted as written.
assert!(TrustRoot::parse("xn--zzzzzz").is_ok());

// And a trailing dot is a different string, so it is not a trust root.
assert!(TrustRoot::parse("example.com.").is_err());

See Section 8.11 of the specification for the threat this leaves to the caller.

Implementations

impl TrustRoot

pub fn parse(input: &str) -> Result<Self, TrustRootError>

Parses a trust root from a string.

Errors

Returns TrustRootError if:

• The input is empty
• The input exceeds 128 characters
• The domain contains invalid characters or labels
• A host of exactly four dotted numeric labels has an IPv4 octet outside 0-255 or an octet with a leading zero; this shape is parsed as IPv4 and is never treated as a domain
• The port is invalid (not numeric or out of range)

pub const fn host(&self) -> &Host

Returns the host portion.

pub fn host_str(&self) -> &str

Returns the host as a string.

pub const fn port(&self) -> Option<u16>

Returns the port, if specified.

pub fn is_localhost(&self) -> bool

Returns true if this is a localhost address.

pub fn as_str(&self) -> &str

Returns the normalized string representation.

pub fn with_port(&self, port: u16) -> Result<Self, TrustRootError>

Returns a new trust root with the given port.

Errors

Returns TrustRootError if the resulting trust root would exceed the maximum length.

Examples

use agent_uri::TrustRoot;

let root = TrustRoot::parse("localhost").unwrap();
let with_port = root.with_port(8472).unwrap();
assert_eq!(with_port.port(), Some(8472));

pub fn without_port(&self) -> Self

Returns a new trust root without a port.

Examples

use agent_uri::TrustRoot;

let root = TrustRoot::parse("localhost:8472").unwrap();
let without_port = root.without_port();
assert!(without_port.port().is_none());

Trait Implementations

impl AsRef<str> for TrustRoot

fn as_ref(&self) -> &str

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

impl Clone for TrustRoot

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 TrustRoot

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for TrustRoot

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for TrustRoot

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

Formats the value using the given formatter.

impl Eq for TrustRoot

impl FromStr for TrustRoot

type Err = TrustRootError

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 Hash for TrustRoot

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

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 TrustRoot

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

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for TrustRoot

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for TrustRoot

fn partial_cmp(&self, other: &Self) -> 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 TrustRoot

Available on crate feature serde only.

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for TrustRoot

impl TryFrom<&str> for TrustRoot

type Error = TrustRootError

The type returned in the event of a conversion error.

fn try_from(s: &str) -> Result<Self, Self::Error>

Performs the conversion.