unimore/tirocinio-canali-steffo-acrate
unimore/tirocinio-canali-steffo-acrate
1
Fork 0
Code Pull requests Activity

hostmeta: Integrate webfinger specification

Browse source
This commit is contained in:
Steffo 2024-11-11 06:07:24 +01:00
parent 13f6a4e4c7
commit 3d8f34a84c
Signed by: steffo
GPG key ID: 5ADA3868646C3FC0
3 changed files with 307 additions and 84 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
acrate-hostmeta/Cargo.toml
View file

@ -13,5 +13,7 @@ serde_json = "1.0.132"
[dev-dependencies] [dev-dependencies]
pretty_env_logger = "0.5.0" pretty_env_logger = "0.5.0"
tokio = { version = "1.41.1", features = ["macros", "rt-multi-thread"] } tokio = { version = "1.41.1", features = ["macros", "rt-multi-thread"] }
tokio-test = "0.4.4"
[lints.clippy] [lints.clippy]
tabs-in-doc-comments = "allow" tabs-in-doc-comments = "allow"

385
acrate-hostmeta/src/lib.rs
View file

@ -1,56 +1,150 @@
//! Serde-based [RFC 6415] `host-meta` parser. //! Resource descriptior deserializer.
//! //!
//! [RFC 6415]: https://datatracker.ietf.org/doc/html/rfc6415 //! [RFC 6415]: https://datatracker.ietf.org/doc/html/rfc6415
//! [RFC 7033]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4
use std::collections::HashMap;
use serde::Deserialize; use serde::Deserialize;
/// A [host-meta document] in JRD representation. /// A resource descriptor object.
/// ///
/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415 /// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-3
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct HostMetaDocument { pub struct ResourceDescriptor {
/// The resource this document refers to. /// The resource this document refers to.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.1
#[serde(alias = "Subject")] #[serde(alias = "Subject")]
pub subject: Option<String>, pub subject: Option<String>,
/// Other names the resource described by this document can be referred to.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.2
#[serde(alias = "Alias")]
pub aliases: Option<Vec<String>>,
/// Additional information about the resource described by this document.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3
#[serde(alias = "Property")]
pub properties: Option<Vec<ResourceDescriptorProperty>>,
/// Links established between the [`Self::subject`] and other resources. /// Links established between the [`Self::subject`] and other resources.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4
#[serde(alias = "Link")] #[serde(alias = "Link")]
pub links: Vec<HostMetaLink>, pub links: Option<Vec<ResourceDescriptorLink>>,
} }
/// A [host-meta Link Element], which puts the subject resource in relation with another. /// A link element, which puts the subject resource in relation with another.
/// ///
/// [host-meta Link Element]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1 /// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct HostMetaLink { pub struct ResourceDescriptorLink {
/// The kind of relation established by the subject with the attached resource. /// The kind of relation established by the subject with the attached resource.
///
/// ## Specification
///
/// https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.1
#[serde(alias = "@rel")] #[serde(alias = "@rel")]
pub rel: String, pub rel: String,
/// The resource put in relation with the subject resource. /// The media type of the resource put in relation.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.2
#[serde(alias = "@type")]
pub r#type: Option<String>,
/// URI to the resource put in relation.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.3
#[serde(alias = "@href")] #[serde(alias = "@href")]
pub href: Option<String>, pub href: Option<String>,
/// Template to fill to get the resource put in relation with the subject resource. /// Titles of the resource put in relation in various languages.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4
pub titles: Option<Vec<HashMap<String, String>>>,
/// Additional information about the resource put in relation.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.5
pub properties: Option<Vec<ResourceDescriptorProperty>>,
/// Template to fill to get the URL to resource-specific information.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-4.2
#[serde(alias = "@template")] #[serde(alias = "@template")]
pub template: Option<String>, pub template: Option<String>,
/// The `Content-Type` of the resource put in relation.
#[serde(alias = "@type")]
pub r#type: Option<String>,
} }
impl HostMetaDocument { /// A property element, which describes a certain aspect of the subject resource.
/// Get an [host-meta document] in the [JRD format]. ///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3
#[derive(Debug, Clone, Deserialize)]
pub struct ResourceDescriptorProperty {
/// The property identifier, or type.
#[serde(alias = "@type")]
pub r#type: String,
/// The property value.
pub value: Option<String>,
}
impl ResourceDescriptor {
/// Get a JRD (JSON [`ResourceDescriptor`]).
///
/// ## Notes
/// ///
/// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info. /// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info.
/// ///
/// [JRD format]: https://datatracker.ietf.org/doc/html/rfc6415#appendix-A /// ## Examples
/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415 ///
/// ```
/// # tokio_test::block_on(async {
/// use acrate_hostmeta::ResourceDescriptor;
///
/// let client = reqwest::Client::new();
/// let url: reqwest::Url = "https://junimo.party/.well-known/nodeinfo".parse()
/// .expect("URL to be valid");
///
/// let rd = ResourceDescriptor::get_jrd(&client, url)
/// .await
/// .expect("JRD to be processed correctly");
/// # })
/// ```
///
pub async fn get_jrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, HostMetaGetJRDError> { pub async fn get_jrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, HostMetaGetJRDError> {
use HostMetaGetJRDError::*; use HostMetaGetJRDError::*;
log::debug!("Getting host-meta JRD document at: {url}"); log::debug!("Getting JRD document at: {url}");
log::trace!("Building request..."); log::trace!("Building request...");
let request = { let request = {
@ -82,10 +176,7 @@ impl HostMetaDocument {
.ok_or(ContentTypeInvalid)?; .ok_or(ContentTypeInvalid)?;
log::trace!("Ensuring MIME type is acceptable for JRD parsing..."); log::trace!("Ensuring MIME type is acceptable for JRD parsing...");
if mime_type == "application/jrd+json" { if !(mime_type == "application/json" || mime_type == "application/jrd+json") {
log::warn!("MIME type `{mime_type}` would not be acceptable for JRD parsing, but is temporarily allowed anyways due to widespread use.")
}
else if mime_type != "application/json" {
log::error!("MIME type `{mime_type}` is not acceptable for JRD parsing."); log::error!("MIME type `{mime_type}` is not acceptable for JRD parsing.");
return Err(ContentTypeInvalid) return Err(ContentTypeInvalid)
} }
@ -98,12 +189,27 @@ impl HostMetaDocument {
Ok(data) Ok(data)
} }
/// Get an [host-meta document] in the [XRD format]. /// Get a XRD (Extensible [`ResourceDescriptor`]).
///
/// ## Notes
/// ///
/// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info. /// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info.
/// ///
/// [XRD format]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1 /// ## Examples
/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415 ///
/// ```
/// # tokio_test::block_on(async {
/// use acrate_hostmeta::ResourceDescriptor;
///
/// let client = reqwest::Client::new();
/// let url: reqwest::Url = "https://junimo.party/.well-known/host-meta".parse()
/// .expect("URL to be valid");
///
/// let rd = ResourceDescriptor::get_xrd(&client, url)
/// .await
/// .expect("XRD to be processed correctly");
/// # })
/// ```
pub async fn get_xrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, HostMetaGetXRDError> { pub async fn get_xrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, HostMetaGetXRDError> {
use HostMetaGetXRDError::*; use HostMetaGetXRDError::*;
@ -156,24 +262,41 @@ impl HostMetaDocument {
Ok(data) Ok(data)
} }
/// Attempt to discover the [host-meta document] at the given URL in various ways. /// Attempt to discover a [`ResourceDescriptor`] at the given URL in various ways.
/// ///
/// In order, this method attempts: /// In order, this method attempts:
///
/// 1. [HTTPS] [XRD](Self::get_xrd) /// 1. [HTTPS] [XRD](Self::get_xrd)
/// 2. [HTTPS] [JRD](Self::get_jrd) /// 2. [HTTPS] [JRD](Self::get_jrd)
/// 3. [HTTP] [XRD](Self::get_xrd) /// 3. [HTTPS] [JRD](Self::get_jrd) with .json path extension
/// 4. [HTTP] [JRD](Self::get_jrd) /// 4. [HTTP] [XRD](Self::get_xrd)
/// 5. [HTTP] [JRD](Self::get_jrd)
/// 6. [HTTP] [JRD](Self::get_jrd) with .json path extension
///
/// ## Notes
/// ///
/// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info. /// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info.
/// ///
/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415 /// ## Examples
/// [HTTPS]: https://datatracker.ietf.org/doc/html/rfc2818 ///
/// [HTTP]: https://datatracker.ietf.org/doc/html/rfc2616 /// ```
/// [JRD]: https://datatracker.ietf.org/doc/html/rfc6415#appendix-A /// # tokio_test::block_on(async {
pub async fn discover(client: &reqwest::Client, mut url: reqwest::Url) -> Result<Self, HostMetaDiscoverError> { /// use acrate_hostmeta::ResourceDescriptor;
use HostMetaDiscoverError::*; ///
/// let client = reqwest::Client::new();
/// let url: reqwest::Url = "https://junimo.party/.well-known/host-meta".parse()
/// .expect("URL to be valid");
///
/// let rd = ResourceDescriptor::discover(&client, url)
/// .await
/// .expect("resource descriptor to be discovered correctly");
/// # })
/// ```
///
pub async fn discover(client: &reqwest::Client, mut url: reqwest::Url) -> Result<Self, ResourceDescriptorDiscoveryError> {
use ResourceDescriptorDiscoveryError::*;
log::debug!("Discovering host-meta document at base: {url}"); log::debug!("Discovering resource descriptor document at: {url}");
log::trace!("Unsetting URL query..."); log::trace!("Unsetting URL query...");
url.set_query(None); url.set_query(None);
@ -185,26 +308,52 @@ impl HostMetaDocument {
url.set_scheme("https") url.set_scheme("https")
.map_err(UrlManipulation)?; .map_err(UrlManipulation)?;
log::trace!("Attempting to retrieve XRD host-meta via HTTPS..."); log::trace!("Cloning URL for HTTPS XRD retrieval...");
let https_xrd = match Self::get_xrd(client, url.clone()).await { let https_xrd_url = url.clone();
log::trace!("Attempting HTTPS XRD retrieval...");
let https_xrd = match Self::get_xrd(client, https_xrd_url).await {
Ok(data) => { Ok(data) => {
log::trace!("HTTPS XRD retrieval was successful, returning..."); log::trace!("HTTPS XRD retrieval was successful, returning...");
return Ok(data) return Ok(data)
} }
Err(err) => { Err(err) => {
log::trace!("HTTPS XRD retrieval failed."); log::warn!("HTTPS XRD retrieval failed.");
err err
} }
}; };
log::trace!("Attempting to retrieve JRD host-meta via HTTPS..."); log::trace!("Cloning URL for HTTPS JRD retrieval...");
let https_jrd = match Self::get_jrd(client, url.clone()).await { let https_jrd_url = url.clone();
log::trace!("Attempting HTTPS JRD retrieval...");
let https_jrd = match Self::get_jrd(client, https_jrd_url).await {
Ok(data) => { Ok(data) => {
log::trace!("HTTPS JRD retrieval was successful, returning..."); log::trace!("HTTPS JRD retrieval was successful, returning...");
return Ok(data) return Ok(data)
} }
Err(err) => { Err(err) => {
log::trace!("HTTPS JRD retrieval failed."); log::warn!("HTTPS JRD retrieval failed.");
err
}
};
log::trace!("Cloning URL for HTTPS JRD .json retrieval...");
let mut https_jrdj_url = url.clone();
log::trace!("Altering URL path for HTTPS JRD .json retrieval...");
https_jrdj_url.set_path(
&format!("{}.json", https_jrdj_url.path())
);
log::trace!("Attempting HTTPS JRD .json retrieval...");
let https_jrdj = match Self::get_jrd(client, https_jrdj_url).await {
Ok(data) => {
log::trace!("HTTPS JRD .json retrieval was successful, returning...");
return Ok(data)
}
Err(err) => {
log::warn!("HTTPS JRD .json retrieval failed.");
err err
} }
}; };
@ -213,99 +362,170 @@ impl HostMetaDocument {
url.set_scheme("http") url.set_scheme("http")
.map_err(UrlManipulation)?; .map_err(UrlManipulation)?;
log::trace!("Attempting to retrieve XRD host-meta via HTTP..."); log::trace!("Cloning URL for HTTP XRD retrieval...");
let http_xrd = match Self::get_xrd(client, url.clone()).await { let http_xrd_url = url.clone();
log::trace!("Attempting HTTP XRD retrieval...");
let http_xrd = match Self::get_xrd(client, http_xrd_url).await {
Ok(data) => { Ok(data) => {
log::trace!("HTTP XRD retrieval was successful, returning..."); log::trace!("HTTP XRD retrieval was successful, returning...");
return Ok(data) return Ok(data)
} }
Err(err) => { Err(err) => {
log::trace!("HTTP XRD retrieval failed."); log::warn!("HTTP XRD retrieval failed.");
err err
} }
}; };
log::trace!("Attempting to retrieve JRD host-meta via HTTP..."); log::trace!("Cloning URL for HTTP JRD retrieval...");
let http_jrd = match Self::get_jrd(client, url.clone()).await { let http_jrd_url = url.clone();
log::trace!("Attempting HTTP JRD retrieval...");
let http_jrd = match Self::get_jrd(client, http_jrd_url).await {
Ok(data) => { Ok(data) => {
log::trace!("HTTP JRD retrieval was successful, returning..."); log::trace!("HTTP JRD retrieval was successful, returning...");
return Ok(data) return Ok(data)
} }
Err(err) => { Err(err) => {
log::trace!("HTTP JRD retrieval failed."); log::warn!("HTTP JRD retrieval failed.");
err
}
};
log::trace!("Cloning URL for HTTP JRD .json retrieval...");
let mut http_jrdj_url = url.clone();
log::trace!("Altering URL path for HTTPS JRD .json retrieval...");
http_jrdj_url.set_path(
&format!("{}.json", http_jrdj_url.path())
);
log::trace!("Attempting HTTP JRD .json retrieval...");
let http_jrdj = match Self::get_jrd(client, http_jrdj_url).await {
Ok(data) => {
log::trace!("HTTP JRD .json retrieval was successful, returning...");
return Ok(data)
}
Err(err) => {
log::warn!("HTTP JRD .json retrieval failed.");
err err
} }
}; };
Err( Err(
HostMetaDiscoverError::Fetch( ResourceDescriptorDiscoveryError::Fetch(
HostMetaDiscoveryAttemptsErrors { ResourceDescriptorDiscoveryFailures {
https_xrd, https_xrd,
https_jrd, https_jrd,
https_jrdj,
http_xrd, http_xrd,
http_jrd, http_jrd,
http_jrdj,
} }
) )
) )
} }
const WELLKNOWN_NODEINFO_PATH: &str = "/.well-known/nodeinfo"; /// Well-known path for host-meta documents.
///
/// ## Specification
///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-2
pub const WELLKNOWN_HOSTMETA_PATH: &str = "/.well-known/host-meta";
pub async fn discover_nodeinfo(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, HostMetaDiscoverError> { /// Attempt to discover a host-meta document at the given base URL.
base.set_path(Self::WELLKNOWN_NODEINFO_PATH); ///
/// ## Examples
Self::discover(client, base) ///
.await /// ```
} /// # tokio_test::block_on(async {
/// use acrate_hostmeta::ResourceDescriptor;
const WELLKNOWN_HOSTMETA_PATH: &str = "/.well-known/host-meta"; ///
/// let client = reqwest::Client::new();
pub async fn discover_hostmeta(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, HostMetaDiscoverError> { /// let base: reqwest::Url = "https://junimo.party".parse()
/// .expect("URL to be valid");
///
/// let rd = ResourceDescriptor::discover_hostmeta(&client, base)
/// .await
/// .expect("host-meta to be discovered correctly");
/// })
/// ```
///
pub async fn discover_hostmeta(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, ResourceDescriptorDiscoveryError> {
base.set_path(Self::WELLKNOWN_HOSTMETA_PATH); base.set_path(Self::WELLKNOWN_HOSTMETA_PATH);
Self::discover(client, base) Self::discover(client, base)
.await .await
} }
/// Well-known path for NodeInfo documents.
///
/// ## Specification
///
/// - https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md#discovery
pub const WELLKNOWN_NODEINFO_PATH: &str = "/.well-known/nodeinfo";
/// Attempt to discover a NodeInfo document at the given base URL.
///
/// ## Examples
///
/// ```
/// # tokio_test::block_on(async {
/// use acrate_hostmeta::ResourceDescriptor;
///
/// let client = reqwest::Client::new();
/// let base: reqwest::Url = "https://junimo.party".parse()
/// .expect("URL to be valid");
///
/// let rd = ResourceDescriptor::discover_nodeinfo(&client, base)
/// .await
/// .expect("NodeInfo to be discovered correctly");
/// # })
/// ```
///
pub async fn discover_nodeinfo(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, ResourceDescriptorDiscoveryError> {
base.set_path(Self::WELLKNOWN_NODEINFO_PATH);
Self::discover(client, base)
.await
}
} }
/// Error occurred during [`ResourceDescriptor::discover`].
#[derive(Debug)] #[derive(Debug)]
pub enum HostMetaDiscoverError { pub enum ResourceDescriptorDiscoveryError {
/// Manipulation of the URL scheme of the given base failed. /// Manipulation of the provided base [`reqwest::Url`] failed.
/// ///
/// See [reqwest::Url::set_scheme] for possible causes. /// See [reqwest::Url::set_scheme] for possible causes.
UrlManipulation(()), UrlManipulation(()),
/// All attempts of fetching the host-meta document failed. /// All attempts of fetching a resource descriptor document failed.
Fetch(HostMetaDiscoveryAttemptsErrors), Fetch(ResourceDescriptorDiscoveryFailures),
} }
/// Request errors occurred during [`ResourceDescriptor::discover`].
#[derive(Debug)] #[derive(Debug)]
pub struct HostMetaDiscoveryAttemptsErrors { pub struct ResourceDescriptorDiscoveryFailures {
/// The error that occoured when trying to fetch the host-meta document in [XRD format] via [HTTPS]. /// HTTPS XRD retrieval.
///
/// [HTTPS]: https://datatracker.ietf.org/doc/html/rfc2818
/// [XRD format]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1
pub https_xrd: HostMetaGetXRDError, pub https_xrd: HostMetaGetXRDError,
/// The error that occoured when trying to fetch the host-meta document in [JRD format] via [HTTPS]. /// HTTPS JRD retrieval.
///
/// [HTTPS]: https://datatracker.ietf.org/doc/html/rfc2818
/// [JRD format]: https://datatracker.ietf.org/doc/html/rfc6415#appendix-A
pub https_jrd: HostMetaGetJRDError, pub https_jrd: HostMetaGetJRDError,
/// The error that occoured when trying to fetch the host-meta document in [XRD format] via [HTTP]. /// HTTPS JRD with .json extension retrieval.
/// pub https_jrdj: HostMetaGetJRDError,
/// [HTTP]: https://datatracker.ietf.org/doc/html/rfc2616
/// [XRD format]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1 /// HTTPS XRD retrieval.
pub http_xrd: HostMetaGetXRDError, pub http_xrd: HostMetaGetXRDError,
/// The error that occoured when trying to fetch the host-meta document in [JRD format] via [HTTP]. /// HTTP JRD retrieval.
///
/// [HTTP]: https://datatracker.ietf.org/doc/html/rfc2616
/// [JRD format]: https://datatracker.ietf.org/doc/html/rfc6415#appendix-A
pub http_jrd: HostMetaGetJRDError, pub http_jrd: HostMetaGetJRDError,
/// HTTP JRD with .json extension retrieval.
pub http_jrdj: HostMetaGetJRDError,
} }
/// Error occurred during [`ResourceDescriptor::get_xrd`].
#[derive(Debug)] #[derive(Debug)]
pub enum HostMetaGetXRDError { pub enum HostMetaGetXRDError {
/// The HTTP request failed. /// The HTTP request failed.
@ -320,6 +540,7 @@ pub enum HostMetaGetXRDError {
Parse(quick_xml::DeError), Parse(quick_xml::DeError),
} }
/// Error occurred during [`ResourceDescriptor::get_jrd`].
#[derive(Debug)] #[derive(Debug)]
pub enum HostMetaGetJRDError { pub enum HostMetaGetJRDError {
/// The HTTP request failed. /// The HTTP request failed.

4
acrate-hostmeta/tests/hostmeta_tests.rs
View file

@ -40,7 +40,7 @@ macro_rules! test {
let base: reqwest::Url = $url.parse() let base: reqwest::Url = $url.parse()
.expect("a valid URL"); .expect("a valid URL");
let doc = HostMetaDocument::discover_hostmeta(&client, base) let doc = ResourceDescriptor::discover_hostmeta(&client, base)
.await .await
.expect("host-meta discovery to succeed"); .expect("host-meta discovery to succeed");
@ -56,7 +56,7 @@ macro_rules! test {
let base: reqwest::Url = $url.parse() let base: reqwest::Url = $url.parse()
.expect("a valid URL"); .expect("a valid URL");
let doc = HostMetaDocument::discover_nodeinfo(&client, base) let doc = ResourceDescriptor::discover_nodeinfo(&client, base)
.await .await
.expect("nodeinfo discovery to succeed"); .expect("nodeinfo discovery to succeed");