Struct Resource 

pub struct Resource { /* private fields */ }

A WebFinger resource URI.

RFC 7033 uses the resource query parameter for the query target, which is a URI rather than a relative reference. Resource stores that URI text after checking the URI syntax that this crate relies on at request boundaries.

Validation is intentionally conservative:

• the value must start with an RFC 3986 URI scheme;
• the value must contain only raw RFC 3986 URI characters;
• every % must start a complete percent escape;
• raw non-ASCII text must already be percent-encoded; and
• http and https resources must use the //authority form before their host is exposed through Resource::host.

Common valid resources include acct:carol@example.com and https://example.org/users/carol.

Examples

Parse a valid acct: resource:

use webfinger_rs::Resource;

let resource = "acct:carol@example.com".parse::<Resource>()?;
assert_eq!(resource.as_str(), "acct:carol@example.com");

Raw characters outside the URI character set are rejected. Percent-encode them inside the resource URI before putting that URI in the outer WebFinger query string:

use webfinger_rs::{Resource, ResourceError};

let error = "acct:carol{admin}@example.com"
    .parse::<Resource>()
    .unwrap_err();
assert!(matches!(error, ResourceError::InvalidCharacters));

let resource = "acct:carol%7Badmin%7D@example.com".parse::<Resource>()?;
assert_eq!(resource.as_str(), "acct:carol%7Badmin%7D@example.com");

HTTP(S) resources must include an authority so host inference cannot treat opaque URI text as a host:

use webfinger_rs::{Resource, ResourceError};

let error = "https:example.org/profile"
    .parse::<Resource>()
    .unwrap_err();
assert!(matches!(error, ResourceError::MissingHttpAuthority));

let resource = "https://example.org/profile".parse::<Resource>()?;
assert_eq!(resource.host(), Some("example.org"));

See RFC 7033 section 4.1 for the resource parameter, RFC 3986 section 2.1 for percent encoding, RFC 3986 section 2.2 for reserved characters, RFC 3986 section 2.3 for unreserved characters, RFC 3986 section 3.1 for URI schemes, and RFC 3986 section 3.2 for authority.

Implementations

impl Resource

pub fn as_str(&self) -> &str

Returns the resource URI as a string slice.

pub fn uri(&self) -> Option<Uri>

Returns the resource as an http::Uri when it fits that representation.

WebFinger resources can use schemes such as acct: that are valid URI strings but do not expose a host through http::Uri. This accessor is mainly useful for hierarchical resources such as https://example.org/users/carol.

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

Returns the host from the resource’s http::Uri representation, when present.

URI schemes such as acct: do not have a host in http::Uri, so this returns None for those resources.

Trait Implementations

impl AsRef<str> for Resource

fn as_ref(&self) -> &str

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

impl Clone for Resource

fn clone(&self) -> Resource

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Resource

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

Formats the value using the given formatter.

impl Display for Resource

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

Formats the value using the given formatter.

impl Eq for Resource

impl FromStr for Resource

type Err = ResourceError

The associated error which can be returned from parsing.

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

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

impl Hash for Resource

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 Resource

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

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

fn partial_cmp(&self, other: &Resource) -> 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 StructuralPartialEq for Resource

impl TryFrom<&str> for Resource

type Error = ResourceError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<String> for Resource

type Error = ResourceError

The type returned in the event of a conversion error.

fn try_from(resource: String) -> Result<Self, Self::Error>

Performs the conversion.