Struct WebFingerResponse 

pub struct WebFingerResponse {
    pub subject: JrdUri,
    pub aliases: Option<Vec<JrdUri>>,
    pub properties: Option<BTreeMap<JrdUri, Option<String>>>,
    pub links: Vec<Link>,
}

A WebFinger response.

This is the JSON Resource Descriptor (JRD) returned by a WebFinger server. The Rust fields map directly to the top-level members from RFC 7033:

• subject is required and uses JrdUri because the RFC defines it as the URI of the resource described by the JRD.
• aliases is an optional list of URI strings, also represented as JrdUri.
• properties is an optional object with URI property identifiers and string-or-null values.
• links is the JRD link array. Missing links deserializes as an empty vector.

The response serializes to the RFC JSON shape. It uses typed wrappers for URI-valued and relation-valued fields while keeping builder methods string-friendly for application code.

See RFC 7033 section 4.4.

Examples

Constructing a response with builders keeps common server code concise:

use webfinger_rs::{Link, WebFingerResponse};

let avatar = Link::builder("http://webfinger.net/rel/avatar")
    .href("https://example.com/avatar.png")
    .build();
let profile = Link::builder("http://webfinger.net/rel/profile-page")
    .href("https://example.com/profile/carol")
    .build();
let response = WebFingerResponse::builder("acct:carol@example.com")
    .alias("https://example.com/profile/carol")
    .property("https://example.com/ns/role", "developer")
    .link(avatar)
    .link(profile)
    .build();

JSON null property values are represented with null_property on the builder:

use webfinger_rs::{Link, WebFingerResponse};

let response = WebFingerResponse::builder("acct:carol@example.com")
    .property("https://example.com/ns/role", "developer")
    .null_property("https://example.com/ns/previous-role")
    .link(
        Link::builder("author")
            .href("https://example.com/people/carol")
            .null_property("https://example.com/ns/legacy-page"),
    )
    .build();

let json = serde_json::to_value(response)?;
assert_eq!(
    json["properties"]["https://example.com/ns/previous-role"],
    serde_json::Value::Null,
);

Response can be used as a response in Axum handlers as it implements axum::response::IntoResponse.

use axum::response::IntoResponse;
use webfinger_rs::{Link, WebFingerRequest, WebFingerResponse};

async fn handler(request: WebFingerRequest) -> WebFingerResponse {
    // ... handle the request ...
    WebFingerResponse::builder("acct:carol@example.com")
        .alias("https://example.com/profile/carol")
        .property("https://example.com/ns/role", "developer")
        .link(
            Link::builder("http://webfinger.net/rel/avatar")
                .href("https://example.com/avatar.png"),
        )
        .build()
}

Fields

subject: JrdUri

The subject of the response.

This is the URI of the resource that the JRD describes. RFC 7033 makes it required when a response is returned, so the Rust field is not optional.

JrdUri is used instead of String so relative references are rejected during deserialization and builder construction.

See RFC 7033 section 4.4.1.

aliases: Option<Vec<JrdUri>>

The aliases of the response.

Aliases are additional URI strings for the same subject. The field is optional because the JSON member may be absent. Each value is a JrdUri for the same reason as Response::subject.

See RFC 7033 section 4.4.2.

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

The properties of the response.

JRD properties are a JSON object whose names 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.

A BTreeMap is used for deterministic ordering and to support the standard ordering and hashing traits on Response.

See RFC 7033 section 4.4.3.

links: Vec<Link>

The links of the response.

This is the JRD links array. A missing JSON member deserializes to an empty vector so code can iterate links without handling a separate absent state.

See RFC 7033 section 4.4.4 and Link.

Implementations

impl WebFingerResponse

pub async fn try_from_reqwest( response: Response, ) -> Result<WebFingerResponse, Error>

Available on crate feature reqwest only.

Converts a completed reqwest::Response into a WebFingerResponse.

This is useful when you execute the HTTP request yourself, but still want this crate’s WebFinger response parsing behavior.

The conversion:

1. Rejects non-success HTTP statuses with reqwest::Response::error_for_status.
2. Deserializes the response body as JSON into WebFingerResponse.

Both status failures and JSON decoding failures surface as crate::Error::Reqwest.

Examples

use reqwest::Client;
use webfinger_rs::{WebFingerRequest, WebFingerResponse};

let client = Client::new();
let request = WebFingerRequest::builder("acct:carol@example.com")?
    .host("example.com")
    .build()
    .try_into_reqwest()?;

let response = client.execute(request).await?;
let webfinger = WebFingerResponse::try_from_reqwest(response).await?;
println!("{webfinger:#?}");

Examples found in repository

examples/client.rs (line 26)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();

    let request = WebFingerRequest::builder(SUBJECT)?
        .host(HOST)
        .rel(PROFILE_PAGE_REL)
        .rel(AVATAR_REL)
        .build();

    let reqwest_request = request.try_into_reqwest()?;
    eprintln!("GET {}", reqwest_request.url());

    let client = reqwest::Client::builder()
        .danger_accept_invalid_certs(true)
        .https_only(true)
        .build()?;
    let response = client.execute(reqwest_request).await?;
    let response = WebFingerResponse::try_from_reqwest(response).await?;

    println!("Subject: {}", response.subject);
    for rel in [PROFILE_PAGE_REL, AVATAR_REL] {
        if let Some(href) = response
            .links
            .iter()
            .find(|link| link.rel.as_ref() == rel)
            .and_then(|link| link.href.as_ref().map(|href| href.as_ref()))
        {
            println!("{rel}: {href}");
        }
    }
    println!("{}", serde_json::to_string_pretty(&response)?);
    Ok(())
}

impl Response

pub fn new<S: AsRef<str>>(subject: S) -> Self

Creates a response with the given subject and no optional JRD members.

This constructor is intended for application-controlled subject strings. It validates the subject as a JrdUri and panics if the string is not an absolute URI. Use Response::try_builder when the subject comes from external input.

pub fn builder<S: AsRef<str>>(subject: S) -> Builder

Creates a Builder with the given subject.

The builder accepts strings at the API boundary and stores typed JRD values internally. This keeps straightforward server responses concise while still producing the RFC-shaped JSON object.

Examples

use webfinger_rs::{Link, WebFingerResponse};

let avatar =
    Link::builder("http://webfinger.net/rel/avatar").href("https://example.com/avatar.png");
let response = WebFingerResponse::builder("acct:carol@example.com")
    .alias("https://example.com/profile/carol")
    .property("https://example.com/ns/role", "developer")
    .link(avatar)
    .build();

Examples found in repository

examples/actix.rs (line 97)

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 100)

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)
}

pub fn try_builder<S: AsRef<str>>(subject: S) -> Result<Builder, Error>

Tries to create a new Builder with the given subject.

Use this when the subject string has not already been validated by application logic. The returned builder has the same methods as Response::builder.

Examples

use webfinger_rs::WebFingerResponse;

assert!(WebFingerResponse::try_builder("acct:carol@example.com").is_ok());
assert!(WebFingerResponse::try_builder("/users/carol").is_err());

Trait Implementations

impl Clone for Response

fn clone(&self) -> Response

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Response

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 Response

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Response

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

Formats the value using the given formatter.

impl Eq for Response

impl Hash for Response

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 IntoResponse for WebFingerResponse

Available on crate feature axum only.

fn into_response(self) -> AxumResponse

Converts a WebFingerResponse into an Axum response.

This serializes the body as JSON, sets the Content-Type header to application/jrd+json, and allows cross-origin browser requests with Access-Control-Allow-Origin: * as recommended by RFC 7033 section 5.

Handlers can therefore return WebFingerResponse directly without manually wrapping it in axum::Json or setting the response header themselves.

Mount the route at crate::WELL_KNOWN_PATH so the handler matches the standard WebFinger endpoint path.

See also the crate::axum module docs and the Axum example.

Example

use axum::{Router, routing::get};
use http::StatusCode;
use webfinger_rs::{Link, Rel, WELL_KNOWN_PATH, WebFingerRequest, WebFingerResponse};

async fn webfinger(request: WebFingerRequest) -> axum::response::Result<WebFingerResponse> {
    let subject = request.resource.to_string();
    if subject != "acct:carol@example.com" {
        return Err((StatusCode::NOT_FOUND, "not found").into());
    }

    let rel = Rel::new("http://webfinger.net/rel/profile-page");
    let response = if request.rels.is_empty() || request.rels.contains(&rel) {
        let link = Link::builder(rel).href("https://example.com/users/carol");
        WebFingerResponse::builder(subject).link(link).build()
    } else {
        WebFingerResponse::builder(subject).build()
    };
    Ok(response)
}

let app = Router::<()>::new().route(WELL_KNOWN_PATH, get(webfinger));

impl Ord for Response

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

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

fn partial_cmp(&self, other: &Response) -> 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 Responder for WebFingerResponse

Available on crate feature actix only.

type Body = <Json<Response> as Responder>::Body

Converts a WebFingerResponse into an Actix response.

This serializes the body as JSON and sets the Content-Type header to application/jrd+json, which is the JRD media type used by WebFinger. It also sets Access-Control-Allow-Origin: * as recommended by RFC 7033 section 5.

Handlers can therefore return WebFingerResponse directly without manually wrapping it in actix_web::web::Json or setting the response header themselves.

See also the crate::actix module docs and the Actix example.

Example

use actix_web::{get, App};
use webfinger_rs::{Link, Rel, WebFingerRequest, WebFingerResponse};

#[get("/.well-known/webfinger")]
async fn webfinger(request: WebFingerRequest) -> actix_web::Result<WebFingerResponse> {
    let subject = request.resource.to_string();
    let rel = Rel::new("http://webfinger.net/rel/profile-page");
    let response = if request.rels.is_empty() || request.rels.contains(&rel) {
        let link = Link::builder(rel).href("https://example.com/users/carol");
        WebFingerResponse::builder(subject).link(link).build()
    } else {
        WebFingerResponse::builder(subject).build()
    };
    Ok(response)
}

let app = App::new().service(webfinger);

fn respond_to(self, request: &HttpRequest) -> HttpResponse<Self::Body>

Convert self to HttpResponse.

fn customize(self) -> CustomizeResponder<Self>

where Self: Sized,

Wraps responder to allow alteration of its response.

impl Serialize for Response

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 Response

impl TryFrom<&Response> for Response<()>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(_: &WebFingerResponse) -> Result<Response<()>, Error>

Performs the conversion.

impl TryFrom<Response> for WebFingerResponse

Available on crate feature reqwest only.

type Error = Error

The type returned in the event of a conversion error.

fn try_from<'async_trait>( response: Response, ) -> Pin<Box<dyn Future<Output = Result<WebFingerResponse, Error>> + Send + 'async_trait>>

Performs the conversion.