nodeinfo: Add two basic (failing) tests

.editorconfig

@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = tab
+insert_final_newline = true
+tab_width = 4
+
+[*.yml]
+indent_size = 2
+indent_style = space
+
+[*.md]
+indent_size = 3
+indent_style = space
+
+[*.rst]
+indent_size = 3
+indent_style = space

acrate-nodeinfo/Cargo.toml

@@ -4,3 +4,12 @@ version = "0.1.0"
 edition = "2021"
 
 [dependencies]
+log = "0.4.22"
+quick-xml = { version = "0.37.0", features = ["overlapped-lists", "serialize"] }
+reqwest = { version = "0.12.9", features = ["json", "stream"] }
+serde = { version = "1.0.214", features = ["derive"] }
+serde_json = "1.0.132"
+
+[dev-dependencies]
+pretty_env_logger = "0.5.0"
+tokio = { version = "1.41.1", features = ["macros", "rt-multi-thread"] }

acrate-nodeinfo/src/lib.rs

@@ -1,14 +1,305 @@
-pub fn add(left: u64, right: u64) -> u64 {
+//! Serde-based [RFC 6415] `host-meta` parser.
-    left + right
+//! 
+//! [RFC 6415]: https://datatracker.ietf.org/doc/html/rfc6415
+
+use serde::{Serialize, Deserialize};
+
+/// A [host-meta document].
+/// 
+/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "PascalCase")]
+pub struct HostMetaDocument {
+	/// The resource this document refers to.
+	pub subject: Option<String>,
+
+	/// Links established between the [`Self::subject`] and other resources.
+	pub links: Vec<HostMetaLink>,
 }
 
-#[cfg(test)]
+/// A [host-meta Link Element], which puts the subject resource in relation with another.
-mod tests {
+/// 
-    use super::*;
+/// [host-meta Link Element]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HostMetaLink {
+	/// The kind of relation established by the subject with the attached resource.
+	pub rel: String,
 
-    #[test]
+	/// The resource put in relation with the subject resource.
-    fn it_works() {
+	pub href: String,
-        let result = add(2, 2);
+}
-        assert_eq!(result, 4);
+
+impl HostMetaDocument {
+	/// Get an [host-meta document] in the [JRD format].
+	/// 
+	/// 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
+	/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415
+	pub async fn get_jrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, HostMetaGetJRDError> {
+		use HostMetaGetJRDError::*;
+
+		log::debug!("Getting host-meta JRD document at: {url}");
+
+		log::trace!("Building request...");
+		let request = {
+			log::trace!("Creating new request...");
+			let mut request = reqwest::Request::new(reqwest::Method::GET, url);
+
+			log::trace!("Setting request headers...");
+			let headers = request.headers_mut();
+
+			log::trace!("Setting `Accept: application/json`...");
+			let _ = headers.insert(reqwest::header::ACCEPT, "application/json".parse().unwrap());
+
+			request
+		};
+
+		log::trace!("Sending request...");
+		let response = client.execute(request)
+			.await
+			.map_err(Request)?;
+
+		log::trace!("Checking headers of the response...");
+		response
+			.headers()
+			.get("Content-Type")
+			.ok_or(ContentTypeMissing)?
+			.eq("application/json")
+			.then_some(())
+			.ok_or(ContentTypeInvalid)?;
+
+		log::trace!("Attempting to parse response as JSON...");
+		let data = response.json::<Self>()
+			.await
+			.map_err(Parse)?;
+
+		Ok(data)
+	}
+
+	/// Get an [host-meta document] in the [XRD format].
+	/// 
+	/// 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
+	/// [host-meta document]: https://datatracker.ietf.org/doc/html/rfc6415
+	pub async fn get_xrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, HostMetaGetXRDError> {
+		use HostMetaGetXRDError::*;
+
+		log::debug!("Getting host-meta XRD document at: {url}");
+
+		log::trace!("Building request...");
+		let request = {
+			log::trace!("Creating new request...");
+			let mut request = reqwest::Request::new(reqwest::Method::GET, url);
+
+			log::trace!("Setting request headers...");
+			let headers = request.headers_mut();
+
+			log::trace!("Setting `Accept: application/xrd+xml`...");
+			let _ = headers.insert(reqwest::header::ACCEPT, "application/xrd+xml".parse().unwrap());
+
+			request
+		};
+
+		log::trace!("Sending request...");
+		let response = client.execute(request)
+			.await
+			.map_err(Request)?;
+
+		log::trace!("Checking headers of the response...");
+		response
+			.headers()
+			.get("Content-Type")
+			.ok_or(ContentTypeMissing)?
+			.eq("application/xrd+json")
+			.then_some(())
+			.ok_or(ContentTypeInvalid)?;
+
+		log::trace!("Attempting to parse response as text...");
+		let data = response.text()
+			.await
+			.map_err(Decode)?;
+
+		log::trace!("Parsing response as XML...");
+		let data = quick_xml::de::from_str::<Self>(&data)
+			.map_err(Parse)?;
+
+		Ok(data)
+	}
+	
+	/// Attempt to discover the [host-meta document] at the given URL in various ways.
+	/// 
+	/// In order, this method attempts:
+	/// 1. [HTTPS] [XRD](Self::get_xrd)
+	/// 2. [HTTPS] [JRD](Self::get_jrd)
+	/// 3. [HTTP] [XRD](Self::get_xrd)
+	/// 4. [HTTP] [JRD](Self::get_jrd)
+	/// 
+	/// 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
+	/// [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
+	pub async fn discover(client: &reqwest::Client, mut url: reqwest::Url) -> Result<Self, HostMetaDiscoverError> {
+		use HostMetaDiscoverError::*;
+
+		log::debug!("Discovering host-meta document at base: {url}");
+
+		log::trace!("Unsetting URL query...");
+		url.set_query(None);
+
+		log::trace!("Unsetting URL fragment...");
+		url.set_fragment(None);
+
+		log::trace!("Setting URL scheme to HTTPS...");
+		url.set_scheme("https")
+			.map_err(UrlManipulation)?;
+
+		log::trace!("Attempting to retrieve XRD host-meta via HTTPS...");
+		let https_xrd = match Self::get_xrd(client, url.clone()).await {
+			Ok(data) => {
+				log::trace!("HTTPS XRD retrieval was successful, returning...");
+				return Ok(data)
+			}
+			Err(err) => {
+				log::trace!("HTTPS XRD retrieval failed.");
+				err
+			}
+		};
+
+		log::trace!("Attempting to retrieve JRD host-meta via HTTPS...");
+		let https_jrd = match Self::get_jrd(client, url.clone()).await {
+			Ok(data) => {
+				log::trace!("HTTPS JRD retrieval was successful, returning...");
+				return Ok(data)
+			}
+			Err(err) => {
+				log::trace!("HTTPS JRD retrieval failed.");
+				err
+			}
+		};
+
+		log::trace!("Setting URL scheme to HTTP...");
+		url.set_scheme("http")
+			.map_err(UrlManipulation)?;
+
+		log::trace!("Attempting to retrieve XRD host-meta via HTTP...");
+		let http_xrd = match Self::get_xrd(client, url.clone()).await {
+			Ok(data) => {
+				log::trace!("HTTP XRD retrieval was successful, returning...");
+				return Ok(data)
+			}
+			Err(err) => {
+				log::trace!("HTTP XRD retrieval failed.");
+				err
+			}
+		};
+
+		log::trace!("Attempting to retrieve JRD host-meta via HTTP...");
+		let http_jrd = match Self::get_jrd(client, url.clone()).await {
+			Ok(data) => {
+				log::trace!("HTTP JRD retrieval was successful, returning...");
+				return Ok(data)
+			}
+			Err(err) => {
+				log::trace!("HTTP JRD retrieval failed.");
+				err
+			}
+		};
+
+		Err(
+			HostMetaDiscoverError::Fetch(
+				HostMetaDiscoveryAttemptsErrors { 
+					https_xrd,
+					https_jrd,
+					http_xrd,
+					http_jrd,
+				}
+			)
+		)
+	}
+
+	const WELLKNOWN_NODEINFO_PATH: &str = "/.well-known/nodeinfo";
+
+	pub async fn discover_nodeinfo(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, HostMetaDiscoverError> {
+		base.set_path(Self::WELLKNOWN_NODEINFO_PATH);
+
+		Self::discover(client, base)
+			.await
+	}
+
+	const WELLKNOWN_HOSTMETA_PATH: &str = "/.well-known/host-meta";
+
+	pub async fn discover_hostmeta(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, HostMetaDiscoverError> {
+		base.set_path(Self::WELLKNOWN_HOSTMETA_PATH);
+
+		Self::discover(client, base)
+			.await
 	}
 }
+
+#[derive(Debug)]
+pub enum HostMetaDiscoverError {
+	/// Manipulation of the URL scheme of the given base failed.
+	/// 
+	/// See [reqwest::Url::set_scheme] for possible causes.
+	UrlManipulation(()),
+
+	/// All attempts of fetching the host-meta document failed.
+	Fetch(HostMetaDiscoveryAttemptsErrors),
+}
+
+#[derive(Debug)]
+pub struct HostMetaDiscoveryAttemptsErrors {
+	/// The error that occoured when trying to fetch the host-meta document in [XRD format] via [HTTPS].
+	/// 
+	/// [HTTPS]: https://datatracker.ietf.org/doc/html/rfc2818
+	/// [XRD format]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1
+	pub https_xrd: HostMetaGetXRDError,
+
+	/// The error that occoured when trying to fetch the host-meta document in [JRD format] via [HTTPS].
+	/// 
+	/// [HTTPS]: https://datatracker.ietf.org/doc/html/rfc2818
+	/// [JRD format]: https://datatracker.ietf.org/doc/html/rfc6415#appendix-A
+	pub https_jrd: HostMetaGetJRDError,
+
+	/// The error that occoured when trying to fetch the host-meta document in [XRD format] via [HTTP].
+	/// 
+	/// [HTTP]: https://datatracker.ietf.org/doc/html/rfc2616
+	/// [XRD format]: https://datatracker.ietf.org/doc/html/rfc6415#section-3.1
+	pub http_xrd: HostMetaGetXRDError,
+
+	/// The error that occoured when trying to fetch the host-meta document in [JRD format] via [HTTP].
+	/// 
+	/// [HTTP]: https://datatracker.ietf.org/doc/html/rfc2616
+	/// [JRD format]: https://datatracker.ietf.org/doc/html/rfc6415#appendix-A
+	pub http_jrd: HostMetaGetJRDError,
+}
+
+#[derive(Debug)]
+pub enum HostMetaGetXRDError {
+	/// The HTTP request failed.
+	Request(reqwest::Error),
+	/// The `Content-Type` header of the response is missing.
+	ContentTypeMissing,
+	/// The `Content-Type` header of the response is invalid.
+	ContentTypeInvalid,
+	/// The document failed to be read as text.
+	Decode(reqwest::Error),
+	/// The document failed to be parsed as XML by [`quick_xml`].
+	Parse(quick_xml::DeError),
+}
+
+#[derive(Debug)]
+pub enum HostMetaGetJRDError {
+	/// The HTTP request failed.
+	Request(reqwest::Error),
+	/// The `Content-Type` header of the response is missing.
+	ContentTypeMissing,
+	/// The `Content-Type` header of the response is invalid.
+	ContentTypeInvalid,
+	/// The document failed to be parsed as JSON by [`reqwest`].
+	Parse(reqwest::Error),
+}

acrate-nodeinfo/tests/discover_test.rs

@@ -0,0 +1,26 @@
+#![allow(non_snake_case)]
+
+use acrate_nodeinfo::*;
+
+
+#[tokio::test]
+async fn discover_hostmeta__junimo_party() {
+	let client = reqwest::Client::new();
+	let base: reqwest::Url = "https://junimo.party".parse()
+		.expect("a valid URL");
+
+	HostMetaDocument::discover_hostmeta(&client, base)
+		.await
+		.expect("host-meta discovery to succeed");
+}
+
+#[tokio::test]
+async fn discover_nodeinfo__junimo_party() {
+	let client = reqwest::Client::new();
+	let base: reqwest::Url = "https://junimo.party".parse()
+		.expect("a valid URL");
+
+	HostMetaDocument::discover_nodeinfo(&client, base)
+		.await
+		.expect("nodeinfo discovery to succeed");
+}