Struct Link 

pub struct Link {
    pub rel: Rel,
    pub type: Option<String>,
    pub href: Option<JrdUri>,
    pub template: Option<String>,
    pub titles: Option<BTreeMap<String, String>>,
    pub properties: Option<BTreeMap<JrdUri, Option<String>>>,
}

A link in the WebFinger response.

Link objects describe related resources for the JRD subject. RFC 7033 gives each link a required rel member and optional type, href, titles, and properties members. Some WebFinger profiles also use the JRD template member from RFC 6415 link templates.

The Rust fields mirror the JRD JSON shape:

• rel is a Rel so the required relation string is validated as one relation type.
• href is a JrdUri because RFC 7033 defines it as a URI string.
• template is a URI template string.
• titles is a language-keyed object, matching the RFC JSON form.
• properties uses JrdUri keys and Option<String> values so JSON null is representable.

Use Link::builder for ordinary construction from string literals or application values. Use Link::new when you already have a validated Rel.

See RFC 7033 section 4.4.4.

Examples

use webfinger_rs::Link;

let link = Link::builder("http://webfinger.net/rel/profile-page")
    .href("https://example.com/profile/carol")
    .r#type("text/html")
    .title("en-us", "Carol's profile")
    .property("https://example.com/ns/verified", "true")
    .null_property("https://example.com/ns/old-profile")
    .build();

assert_eq!(link.rel.as_ref(), "http://webfinger.net/rel/profile-page");

Fields

rel: Rel

The relation type of the link.

This member is required by RFC 7033 section 4.4.4.1. It uses Rel instead of String so deserialization and builder construction both reject empty or malformed relation values.

type: Option<String>

The media type of the link.

RFC 7033 leaves this as a media type string. The crate stores it as String because it is advisory metadata for the linked representation, not one of the WebFinger URI-valued fields.

See RFC 7033 section 4.4.4.2.

href: Option<JrdUri>

The target URI of the link.

RFC 7033 defines href as a URI string. The field uses JrdUri rather than String so relative references are rejected when links are deserialized or built through the builder.

See RFC 7033 section 4.4.4.3.

template: Option<String>

A URI template for the link.

RFC 6415 defines template as an optional JRD link member for link templates. The crate stores it as a string because WebFinger servers do not need to parse or expand the template expression before serializing it.

See RFC 6415 appendix A.

titles: Option<BTreeMap<String, String>>

The titles of the link.

RFC 7033 models titles as a JSON object whose keys are language tags and whose values are title strings. The crate uses a BTreeMap so direct struct construction preserves that JSON object shape and gets deterministic ordering for comparisons, hashing, and rendered output.

Use LinkBuilder::title for one title at a time or LinkBuilder::titles to set a full language map.

See RFC 7033 section 4.4.4.4.

properties: Option<BTreeMap<JrdUri, Option<String>>>

The properties of the link.

Link properties are a JSON object whose property identifiers are URI strings. Values may be strings or JSON null, so the Rust value type is Option<String>. None serializes as a property value of null; it does not omit the property from the map.

Use LinkBuilder::property for string-valued properties and LinkBuilder::null_property for JSON null values.

See RFC 7033 section 4.4.4.5.

Implementations

impl Link

pub fn new(rel: Rel) -> Self

Creates a link from an already validated relation type.

The returned link has no optional members set. This is useful when relation validation happens separately, for example when reusing a Rel from a request filter. Use Link::builder when constructing a link directly from strings.

pub fn builder<R: AsRef<str>>(rel: R) -> LinkBuilder

Creates a LinkBuilder with the given relation type.

The builder accepts a string-like value for the common case and validates it into Rel. Invalid values panic through Rel::new; use Rel::try_new and Link::new when the relation comes from untrusted input.

Examples found in repository

examples/actix.rs (line 80)

async fn webfinger(request: WebFingerRequest) -> actix_web::Result<WebFingerResponse> {
    info!("fetching webfinger resource: {:?}", request);
    let subject = request.resource.to_string();
    if subject != SUBJECT {
        let message = format!("{subject} does not exist");
        return Err(actix_web::error::ErrorNotFound(message))?;
    }
    let mut links = Vec::new();

    let profile_rel = Rel::new(PROFILE_PAGE_REL);
    if request.rels.is_empty() || request.rels.contains(&profile_rel) {
        links.push(
            Link::builder(profile_rel)
                .href(PROFILE_HREF)
                .title("en", "Carol's profile")
                .build(),
        );
    }

    let avatar_rel = Rel::new(AVATAR_REL);
    if request.rels.is_empty() || request.rels.contains(&avatar_rel) {
        links.push(
            Link::builder(avatar_rel)
                .href(AVATAR_HREF)
                .r#type("image/png")
                .build(),
        );
    }

    let response = WebFingerResponse::builder(subject)
        .alias(PROFILE_HREF)
        .property(ROLE_PROPERTY, "maintainer")
        .links(links)
        .build();
    Ok(response)
}

examples/axum.rs (line 83)

async fn webfinger(request: WebFingerRequest) -> axum::response::Result<WebFingerResponse> {
    info!("fetching webfinger resource: {:?}", request);
    let subject = request.resource.to_string();
    if subject != SUBJECT {
        let message = format!("{subject} does not exist");
        return Err((StatusCode::NOT_FOUND, message).into());
    }
    let mut links = Vec::new();

    let profile_rel = Rel::new(PROFILE_PAGE_REL);
    if request.rels.is_empty() || request.rels.contains(&profile_rel) {
        links.push(
            Link::builder(profile_rel)
                .href(PROFILE_HREF)
                .title("en", "Carol's profile")
                .build(),
        );
    }

    let avatar_rel = Rel::new(AVATAR_REL);
    if request.rels.is_empty() || request.rels.contains(&avatar_rel) {
        links.push(
            Link::builder(avatar_rel)
                .href(AVATAR_HREF)
                .r#type("image/png")
                .build(),
        );
    }

    let response = WebFingerResponse::builder(subject)
        .alias(PROFILE_HREF)
        .property(ROLE_PROPERTY, "maintainer")
        .links(links)
        .build();
    Ok(response)
}

Trait Implementations

impl Clone for Link

fn clone(&self) -> Link

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Link

Custom debug implementation to avoid printing None fields

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Link

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for Link

impl From<LinkBuilder> for Link

fn from(builder: LinkBuilder) -> Self

Converts to this type from the input type.

impl Hash for Link

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 Link

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

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

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

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 Link