499 lines
15 KiB
Rust
499 lines
15 KiB
Rust
//! Rust typing and utilities for the NodeInfo format.
|
|
//!
|
|
//! > NodeInfo is an effort to create a standardized way of exposing metadata about a server running one of the distributed social networks.
|
|
//!
|
|
//! # Specification
|
|
//!
|
|
//! - <https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md>
|
|
//! - <https://codeberg.org/fediverse/fep/src/branch/main/fep/f1d5/fep-f1d5.md>
|
|
//!
|
|
|
|
use mediatype::MediaTypeBuf;
|
|
use serde::Deserialize;
|
|
use thiserror::Error;
|
|
|
|
/// A variant of a NodeInfo document.
|
|
///
|
|
/// # Specification
|
|
///
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md>
|
|
///
|
|
#[derive(Debug, Clone)]
|
|
pub enum NodeInfo {
|
|
V1(NodeInfo1),
|
|
V2(NodeInfo2),
|
|
}
|
|
|
|
/// A NodeInfo document at version 1.X.
|
|
///
|
|
/// # Specification
|
|
///
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/schemas/1.0/schema.json>
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/schemas/1.1/schema.json>
|
|
///
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo1 {
|
|
/// The schema version.
|
|
pub version: String,
|
|
|
|
/// Metadata about server software in use.
|
|
pub software: NodeInfo1Software,
|
|
|
|
/// The protocols supported on this server.
|
|
pub protocols: Option<NodeInfo1Protocols>,
|
|
|
|
/// The third party sites this server can connect to via their application API.
|
|
pub services: Option<NodeInfo1Services>,
|
|
|
|
/// Whether this server allows open self-registration.
|
|
pub open_registrations: Option<bool>,
|
|
|
|
/// Usage statistics for this server.
|
|
pub usage: Option<NodeInfo1Usage>,
|
|
|
|
/// Free form key value pairs for software specific values.
|
|
///
|
|
/// Clients should not rely on any specific key present.
|
|
pub metadata: serde_json::Value,
|
|
}
|
|
|
|
/// A NodeInfo document at version 2.X.
|
|
///
|
|
/// # Specification
|
|
///
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/schemas/2.0/schema.json>
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/schemas/2.1/schema.json>
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/schemas/2.2/schema.json>
|
|
///
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo2 {
|
|
/// The schema version.
|
|
pub version: String,
|
|
|
|
/// Metadata specific to the instance. An instance is a the concrete installation of a software running on a server.
|
|
pub instance: Option<NodeInfo2Instance>,
|
|
|
|
/// Metadata about server software in use.
|
|
pub software: Option<NodeInfo1Software>,
|
|
|
|
/// The protocols supported on this server.
|
|
pub protocols: Option<Vec<String>>,
|
|
|
|
/// The third party sites this server can connect to via their application API.
|
|
pub services: Option<NodeInfo1Services>,
|
|
|
|
/// Whether this server allows open self-registration.
|
|
pub open_registrations: Option<bool>,
|
|
|
|
/// Usage statistics for this server.
|
|
pub usage: Option<NodeInfo1Usage>,
|
|
|
|
/// Free form key value pairs for software specific values.
|
|
///
|
|
/// Clients should not rely on any specific key present.
|
|
pub metadata: serde_json::Value,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo1Software {
|
|
/// The canonical name of this server software.
|
|
pub name: String,
|
|
|
|
/// The version of this server software.
|
|
pub version: String,
|
|
|
|
pub repository: Option<String>,
|
|
|
|
pub homepage: Option<String>,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo1Protocols {
|
|
/// The protocols this server can receive traffic for.
|
|
pub inbound: Vec<String>,
|
|
|
|
/// The protocols this server can generate traffic for.
|
|
pub outbound: Vec<String>,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo1Services {
|
|
/// The third party sites this server can retrieve messages from for combined display with regular traffic.
|
|
pub inbound: Vec<String>,
|
|
|
|
/// The third party sites this server can publish messages to on the behalf of a user.
|
|
pub outbound: Vec<String>,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo1Usage {
|
|
/// Statistics about the users of this server.
|
|
pub users: Option<NodeInfo1UsageUsers>,
|
|
|
|
/// The amount of posts that were made by users that are registered on this server.
|
|
pub local_posts: Option<i32>,
|
|
|
|
/// The amount of comments that were made by users that are registered on this server.
|
|
pub local_comments: Option<i32>,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo1UsageUsers {
|
|
/// The total amount of on this server registered users.
|
|
pub total: Option<i32>,
|
|
|
|
/// The amount of users that signed in at least once in the last 180 days.
|
|
pub active_halfyear: Option<i32>,
|
|
|
|
/// The amount of users that signed in at least once in the last 30 days.
|
|
pub active_month: Option<i32>,
|
|
|
|
/// The amount of users that signed in at least once in the last 7 days.
|
|
pub active_week: Option<i32>,
|
|
}
|
|
|
|
#[derive(Debug, Clone, Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct NodeInfo2Instance {
|
|
/// If supported by the software, the administrator-configured name of this instance.
|
|
pub name: String,
|
|
|
|
/// If supported by the software, the administrator-configured long form description of this instance.
|
|
pub description: Option<String>,
|
|
}
|
|
|
|
impl NodeInfo {
|
|
/// Well-known path for NodeInfo documents.
|
|
///
|
|
/// # Specification
|
|
///
|
|
/// - <https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md#discovery>
|
|
pub const WELLKNOWN_NODEINFO_PATH: &'static str = "/.well-known/nodeinfo";
|
|
|
|
/// Discover and get the latest NodeInfo version available given a certain base URL.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// # tokio_test::block_on(async {
|
|
/// use acrate_nodeinfo::NodeInfo;
|
|
///
|
|
/// let client = reqwest::Client::new();
|
|
/// let url: reqwest::Url = "https://mastodon.online".parse()
|
|
/// .expect("URL to be valid");
|
|
///
|
|
/// let ni = NodeInfo::get_latest_wellknown(&client, url)
|
|
/// .await
|
|
/// .expect("NodeInfo to be processed correctly");
|
|
///
|
|
/// let version = match ni {
|
|
/// NodeInfo::V1(ni) => ni.version,
|
|
/// NodeInfo::V2(ni) => ni.version,
|
|
/// };
|
|
///
|
|
/// assert_eq!(version, "2.0");
|
|
/// # })
|
|
pub async fn get_latest_wellknown(client: &reqwest::Client, mut base: reqwest::Url) -> Result<Self, NodeInfoGetWellknownError> {
|
|
use NodeInfoGetWellknownError::*;
|
|
|
|
log::debug!("Getting well-known NodeInfo document at base: {base}");
|
|
|
|
log::trace!("Setting URL path to the well-known NodeInfo value...");
|
|
base.set_path(Self::WELLKNOWN_NODEINFO_PATH);
|
|
|
|
log::trace!("Discovering NodeInfo document locations...");
|
|
let discovery = acrate_rd::any::ResourceDescriptor::get(client, base)
|
|
.await
|
|
.map_err(Get)?
|
|
.jrd();
|
|
|
|
log::trace!("Getting a list of NodeInfo document links...");
|
|
let mut links = discovery.links;
|
|
links.sort_unstable_by_key(|o| o.rel.clone()); // TODO: Performance can be improved.
|
|
links.reverse();
|
|
|
|
for link in links.into_iter() {
|
|
|
|
log::trace!("Checking discovered link href...");
|
|
let url = match link.href {
|
|
None => {
|
|
log::warn!("Discovered link does not have an href, skipping...");
|
|
continue
|
|
},
|
|
Some(href) => {
|
|
log::trace!("Discovered link has an href, processing...");
|
|
href
|
|
},
|
|
};
|
|
|
|
log::trace!("Parsing discovered link href...");
|
|
let url: reqwest::Url = match url.parse() {
|
|
Err(e) => {
|
|
log::warn!("Discovered link has an invalid URL as href, skipping: {e:#?}");
|
|
continue
|
|
},
|
|
Ok(url) => {
|
|
log::trace!("Discovered link has a valid URL, processing...");
|
|
url
|
|
},
|
|
};
|
|
|
|
let rel = link.rel;
|
|
|
|
let nodeinfo = match rel.as_str() {
|
|
"http://nodeinfo.diaspora.software/ns/schema/1.0" => match NodeInfo1::get(client, url).await {
|
|
Err(e) => {
|
|
log::warn!("Failed to get NodeInfo v1.0 document, skipping: {e:#?}");
|
|
continue;
|
|
},
|
|
Ok(nodeinfo) => {
|
|
log::trace!("Successfully processed NodeInfo v1.0 document!");
|
|
Self::V1(nodeinfo)
|
|
}
|
|
}
|
|
"http://nodeinfo.diaspora.software/ns/schema/1.1" => match NodeInfo1::get(client, url).await {
|
|
Err(e) => {
|
|
log::warn!("Failed to get NodeInfo v1.1 document, skipping: {e:#?}");
|
|
continue;
|
|
},
|
|
Ok(nodeinfo) => {
|
|
log::trace!("Successfully processed NodeInfo v1.1 document!");
|
|
Self::V1(nodeinfo)
|
|
}
|
|
}
|
|
"http://nodeinfo.diaspora.software/ns/schema/2.0" => match NodeInfo2::get(client, url).await {
|
|
Err(e) => {
|
|
log::warn!("Failed to get NodeInfo v2.0 document, skipping: {e:#?}");
|
|
continue;
|
|
},
|
|
Ok(nodeinfo) => {
|
|
log::trace!("Successfully processed NodeInfo v2.0 document!");
|
|
Self::V2(nodeinfo)
|
|
}
|
|
}
|
|
"http://nodeinfo.diaspora.software/ns/schema/2.1" => match NodeInfo2::get(client, url).await {
|
|
Err(e) => {
|
|
log::warn!("Failed to get NodeInfo v2.1 document, skipping: {e:#?}");
|
|
continue;
|
|
},
|
|
Ok(nodeinfo) => {
|
|
log::trace!("Successfully processed NodeInfo v2.1 document!");
|
|
Self::V2(nodeinfo)
|
|
}
|
|
}
|
|
"http://nodeinfo.diaspora.software/ns/schema/2.2" => match NodeInfo2::get(client, url).await {
|
|
Err(e) => {
|
|
log::warn!("Failed to get NodeInfo v2.2 document, skipping: {e:#?}");
|
|
continue;
|
|
},
|
|
Ok(nodeinfo) => {
|
|
log::trace!("Successfully processed NodeInfo v2.2 document!");
|
|
Self::V2(nodeinfo)
|
|
}
|
|
}
|
|
_ => {
|
|
log::warn!("Discovered link has unknown rel `{rel}`, skipping.");
|
|
continue;
|
|
},
|
|
};
|
|
|
|
log::trace!("Successfully retrieved latest NodeInfo: {nodeinfo:#?}");
|
|
return Ok(nodeinfo);
|
|
}
|
|
|
|
log::warn!("Ran out of possible NodeInfo sources, returning an Unsupported error.");
|
|
Err(Unsupported)
|
|
}
|
|
}
|
|
|
|
/// An error occurred during [`NodeInfo::get_latest_wellknown`].
|
|
#[derive(Debug, Error)]
|
|
pub enum NodeInfoGetWellknownError {
|
|
/// The discovery of possible locations for NodeInfo documents failed.
|
|
#[error("the discovery of possible locations for NodeInfo documents failed")]
|
|
Get(acrate_rd::any::GetError),
|
|
/// No compatible NodeInfo documents were detected at the given URL.
|
|
#[error("no compatible NodeInfo documents were detected at the given URL")]
|
|
Unsupported,
|
|
}
|
|
|
|
impl NodeInfo1 {
|
|
/// Get a NodeInfo v1.X document.
|
|
pub async fn get(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, NodeInfoGetError> {
|
|
use NodeInfoGetError::*;
|
|
|
|
log::debug!("Getting NodeInfo v1.X 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 `Content-Type` of the response...");
|
|
let content_type = response
|
|
.headers()
|
|
.get(reqwest::header::CONTENT_TYPE)
|
|
.ok_or(ContentTypeMissing)?;
|
|
|
|
log::trace!("Extracting media type from the `Content-Type` header: {content_type:?}");
|
|
let media_type: MediaTypeBuf = content_type
|
|
.to_str()
|
|
.map_err(ContentTypeUnprintable)?
|
|
.parse()
|
|
.map_err(ContentTypeInvalid)?;
|
|
|
|
log::trace!("Checking if media type is supported: {media_type:?}");
|
|
|
|
let mime_is_json = media_type.essence().eq(&"application/json".parse::<MediaTypeBuf>().unwrap());
|
|
log::trace!("Is media type `application/json`? {mime_is_json:?}");
|
|
|
|
if !mime_is_json {
|
|
log::error!("Media type `{media_type}` is not acceptable for NodeInfo parsing.");
|
|
return Err(ContentTypeUnsupported);
|
|
}
|
|
|
|
log::trace!("Attempting to parse response as JSON...");
|
|
let data = response.json::<Self>()
|
|
.await
|
|
.map_err(Parse)?;
|
|
|
|
log::trace!("Making sure version is compatible with 1.X...");
|
|
if !data.version.starts_with("1.") {
|
|
return Err(Version);
|
|
}
|
|
|
|
Ok(data)
|
|
}
|
|
}
|
|
|
|
impl NodeInfo2 {
|
|
/// Get a NodeInfo v2.X document.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// # tokio_test::block_on(async {
|
|
/// use acrate_nodeinfo::NodeInfo2;
|
|
///
|
|
/// let client = reqwest::Client::new();
|
|
/// let url: reqwest::Url = "https://junimo.party/nodeinfo/2.1.json".parse()
|
|
/// .expect("URL to be valid");
|
|
///
|
|
/// let rd = NodeInfo2::get(&client, url)
|
|
/// .await
|
|
/// .expect("NodeInfo to be obtained correctly");
|
|
/// # })
|
|
/// ```
|
|
pub async fn get(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, NodeInfoGetError> {
|
|
use NodeInfoGetError::*;
|
|
|
|
log::debug!("Getting NodeInfo v2.X 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 `Content-Type` of the response...");
|
|
let content_type = response
|
|
.headers()
|
|
.get(reqwest::header::CONTENT_TYPE)
|
|
.ok_or(ContentTypeMissing)?;
|
|
|
|
log::trace!("Extracting media type from the `Content-Type` header: {content_type:?}");
|
|
let media_type: MediaTypeBuf = content_type
|
|
.to_str()
|
|
.map_err(ContentTypeUnprintable)?
|
|
.parse()
|
|
.map_err(ContentTypeInvalid)?;
|
|
|
|
log::trace!("Checking if media type is supported: {media_type:?}");
|
|
|
|
let mime_is_json = media_type.essence().eq(&"application/json".parse::<MediaTypeBuf>().unwrap());
|
|
log::trace!("Is media type `application/json`? {mime_is_json:?}");
|
|
|
|
if !mime_is_json {
|
|
log::error!("Media type `{media_type}` is not acceptable for NodeInfo parsing.");
|
|
return Err(ContentTypeUnsupported);
|
|
}
|
|
|
|
log::trace!("Attempting to parse response as JSON...");
|
|
let data = response.json::<Self>()
|
|
.await
|
|
.map_err(Parse)?;
|
|
|
|
log::trace!("Making sure version is compatible with 2.X...");
|
|
if !data.version.starts_with("2.") {
|
|
return Err(Version)
|
|
}
|
|
|
|
Ok(data)
|
|
}
|
|
}
|
|
|
|
/// An error encountered during [`NodeInfo1::get`] or [`NodeInfo2::get`].
|
|
#[derive(Debug, Error)]
|
|
pub enum NodeInfoGetError {
|
|
/// 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 can't be converted to a [`str`].
|
|
#[error("the Content-Type header of the response cannot be converted to a &str")]
|
|
ContentTypeUnprintable(reqwest::header::ToStrError),
|
|
|
|
/// The `Content-Type` header of the response is not a valid [`mime::Mime`] type.
|
|
#[error("the Content-Type header of the response is not a valid media type")]
|
|
ContentTypeInvalid(mediatype::MediaTypeError),
|
|
|
|
/// The `Content-Type` header of the response is not a supported [`mime::Mime`] type.
|
|
#[error("the Content-Type header of the response is not a supported media type")]
|
|
ContentTypeUnsupported,
|
|
|
|
/// The document failed to be parsed as JSON by [`reqwest`].
|
|
#[error("the document failed to be parsed as JSON")]
|
|
Parse(reqwest::Error),
|
|
|
|
/// The returned NodeInfo version would not match the version of the called method.
|
|
#[error("the returned NodeInfo version would not match the version of the called method")]
|
|
Version,
|
|
}
|