tirocinio-canali-steffo-acrate/acrate-hostmeta/src/xrd.rs

use serde::{Serialize, Deserialize};
use thiserror::Error;
use crate::jrd::{ResourceDescriptorJRD, ResourceDescriptorLinkJRD};

/// A resource descriptor object in XRD format.
///
/// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-3>
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4>
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceDescriptorXRD {
	/// The resource this document refers to.
	///
	/// # Specification
	///
	/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.1>
	///
	#[serde(rename = "Subject")]
	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(rename = "Alias")]
	#[serde(default)]
	pub aliases: Vec<String>,
	
	/// Additional information about the resource described by this document.
	///
	/// # Specification
	///
	/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3>
	///
	#[serde(rename = "Property")]
	#[serde(default)]
	pub properties: Vec<ResourceDescriptorPropertyXRD>,
	
	/// 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(rename = "Link")]
	#[serde(default)]
	pub links: Vec<ResourceDescriptorLinkXRD>,
}

/// A link element, which puts the subject resource in relation with another.
///
/// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1>
///
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceDescriptorLinkXRD {
	/// 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(rename = "@rel")]
	pub rel: String,
	
	/// The media type of the resource put in relation.
	///
	/// # Specification
	///
	/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.2>
	///
	#[serde(rename = "@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(rename = "@href")]
	pub href: Option<String>,
	
	/// Titles of the resource put in relation in various languages.
	///
	/// # Specification
	///
	/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4>
	///
	#[serde(default)]
	pub titles: Vec<ResourceDescriptorTitleXRD>,
	
	/// Additional information about the resource put in relation.
	///
	/// # Specification
	///
	/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.5>
	///
	#[serde(default)]
	pub properties: Vec<ResourceDescriptorPropertyXRD>,
	
	/// Template to fill to get the URL to resource-specific information.
	///
	/// # Specification
	///
	/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-4.2>
	///
	#[serde(rename = "@template")]
	pub template: Option<String>,
}

/// A title of the resource put in relation.
///
/// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4>
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceDescriptorTitleXRD {
	/// The language of the title.
	#[serde(rename = "@lang")]
	pub language: String,
	
	/// The title itself.
	pub value: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResourceDescriptorPropertyXRD {
	/// The property identifier, or type.
	#[serde(alias = "@type")]
	pub r#type: String,
	
	/// The property value.
	pub value: Option<String>,
}


impl ResourceDescriptorXRD {
	/// Get a [`ResourceDescriptorXRD`] from an URL.
	///
	/// # Notes
	///
	/// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info.
	///
	/// # Examples
	///
	/// ```
	/// # tokio_test::block_on(async {
	/// use acrate_hostmeta::xrd::ResourceDescriptorXRD;
	///
	/// let client = reqwest::Client::new();
	/// let url: reqwest::Url = "https://junimo.party/.well-known/host-meta".parse()
	/// 	.expect("URL to be valid");
	///
	/// let rd = ResourceDescriptorXRD::get(&client, url)
	/// 	.await
	/// 	.expect("XRD to be processed correctly");
	/// # })
	/// ```
	///
	pub async fn get(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, GetXRDError> {
		use GetXRDError::*;
		
		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 `Content-Type` of the response...");
		let content_type = response
			.headers()
			.get(reqwest::header::CONTENT_TYPE)
			.ok_or(ContentTypeMissing)?;
		
		log::trace!("Extracting MIME type from the `Content-Type` header...");
		let mime_type = crate::utils::extract_mime_from_content_type(content_type)
			.ok_or(ContentTypeInvalid)?;
		
		log::trace!("Ensuring MIME type is acceptable for XRD parsing...");
		if mime_type != "application/xrd+xml" {
			log::error!("MIME type `{mime_type}` is not acceptable for XRD parsing.");
			return Err(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)
	}
}

impl From<ResourceDescriptorJRD> for ResourceDescriptorXRD {
	fn from(value: ResourceDescriptorJRD) -> Self {
		Self {
			subject: value.subject,
			aliases: value.aliases,
			properties: value.properties.into_iter()
				.map(From::from)
				.collect(),
			links: value.links.into_iter()
				.map(From::from)
				.collect(),
		}
	}
}

impl From<(String, Option<String>)> for ResourceDescriptorPropertyXRD {
	fn from(value: (String, Option<String>)) -> Self {
		Self {
			r#type: value.0,
			value: value.1,
		}
	}
}

impl From<ResourceDescriptorLinkJRD> for ResourceDescriptorLinkXRD {
	fn from(value: ResourceDescriptorLinkJRD) -> Self {
		Self {
			rel: value.rel,
			r#type: value.r#type,
			href: value.href,
			titles: value.titles.into_iter()
				.map(From::from)
				.collect(),
			properties: value.properties.into_iter()
				.map(From::from)
				.collect(),
			template: value.template,
		}
	}
}

impl From<(String, String)> for ResourceDescriptorTitleXRD {
	fn from(value: (String, String)) -> Self {
		Self {
			language: value.0,
			value: value.1,
		}
	}
}


/// Error occurred during [`ResourceDescriptor::get_xrd`].
#[derive(Debug, Error)]
pub enum GetXRDError {
	/// The HTTP request failed.
	#[error("the HTTP request failed")]
	Request(reqwest::Error),
	
	/// The `Content-Type` header of the response is missing.
	#[error("the Content-Type header of the response is missing")]
	ContentTypeMissing,
	
	/// The `Content-Type` header of the response is invalid.
	#[error("the Content-Type header of the response is invalid")]
	ContentTypeInvalid,
	
	/// The document failed to be decoded as text.
	#[error("the document failed to be decoded as text")]
	Decode(reqwest::Error),
	
	/// The document failed to be parsed as XML by [`quick_xml`].
	#[error("the document failed to be parsed as XML")]
	Parse(quick_xml::DeError),
}