chore (backend-rs): more documents on NodeInfo

packages/backend-rs/src/federation/nodeinfo/fetch.rs

@@ -1,10 +1,13 @@
 //! NodeInfo fetcher
+//!
+//! ref: <https://nodeinfo.diaspora.software/protocol.html>
 
 use crate::federation::nodeinfo::schema::*;
 use crate::util::http_client;
 use isahc::AsyncReadResponseExt;
 use serde::Deserialize;
 
+/// Errors that can occur while fetching NodeInfo from a remote server
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
     #[error("HTTP client aquisition error: {0}")]
@@ -21,25 +24,23 @@ pub enum Error {
     MissingNodeinfo,
 }
 
+/// Represents the schema of `/.well-known/nodeinfo`.
 #[derive(Deserialize, Debug)]
 pub struct NodeinfoLinks {
     links: Vec<NodeinfoLink>,
 }
 
+/// Represents one entry of `/.well-known/nodeinfo`.
 #[derive(Deserialize, Debug)]
 pub struct NodeinfoLink {
     rel: String,
     href: String,
 }
 
-#[inline]
-fn wellknown_nodeinfo_url(host: &str) -> String {
-    format!("https://{}/.well-known/nodeinfo", host)
-}
-
+/// Fetches `/.well-known/nodeinfo` and parses the result.
 async fn fetch_nodeinfo_links(host: &str) -> Result<NodeinfoLinks, Error> {
     let client = http_client::client()?;
-    let wellknown_url = wellknown_nodeinfo_url(host);
+    let wellknown_url = format!("https://{}/.well-known/nodeinfo", host);
     let mut wellknown_response = client.get_async(&wellknown_url).await?;
 
     if !wellknown_response.status().is_success() {
@@ -54,6 +55,9 @@ async fn fetch_nodeinfo_links(host: &str) -> Result<NodeinfoLinks, Error> {
     Ok(serde_json::from_str(&wellknown_response.text().await?)?)
 }
 
+/// Check if any of the following relations is present in the given [NodeinfoLinks].
+/// * <http://nodeinfo.diaspora.software/ns/schema/2.0>
+/// * <http://nodeinfo.diaspora.software/ns/schema/2.1>
 fn check_nodeinfo_link(links: NodeinfoLinks) -> Result<String, Error> {
     for link in links.links {
         if link.rel == "http://nodeinfo.diaspora.software/ns/schema/2.1"
@@ -66,6 +70,7 @@ fn check_nodeinfo_link(links: NodeinfoLinks) -> Result<String, Error> {
     Err(Error::MissingNodeinfo)
 }
 
+/// Fetches the nodeinfo from the given URL and parses the result.
 async fn fetch_nodeinfo_impl(nodeinfo_link: &str) -> Result<Nodeinfo20, Error> {
     let client = http_client::client()?;
     let mut response = client.get_async(nodeinfo_link).await?;
@@ -85,7 +90,7 @@ async fn fetch_nodeinfo_impl(nodeinfo_link: &str) -> Result<Nodeinfo20, Error> {
 // for napi export
 type Nodeinfo = Nodeinfo20;
 
-/// Fetches and returns the NodeInfo of a remote server.
+/// Fetches and returns the NodeInfo (version 2.0) of a remote server.
 #[crate::export]
 pub async fn fetch_nodeinfo(host: &str) -> Result<Nodeinfo, Error> {
     tracing::info!("fetching from {}", host);

packages/backend-rs/src/federation/nodeinfo/generate.rs

@@ -9,6 +9,7 @@ use sea_orm::{ColumnTrait, DbErr, EntityTrait, PaginatorTrait, QueryFilter};
 use serde_json::json;
 use std::collections::HashMap;
 
+/// Errors that can occur while generating NodeInfo of the local server
 #[derive(thiserror::Error, Debug)]
 pub enum Error {
     #[error("Database error: {0}")]
@@ -19,6 +20,14 @@ pub enum Error {
     Json(#[from] serde_json::Error),
 }
 
+/// Fetches the number of total/active local users and local posts.
+///
+/// # Return value
+/// A tuple containing the following information in this order:
+/// * the total number of local users
+/// * the total number of local users active in the last 6 months
+/// * the total number of local users active in the last month (MAU)
+/// * the total number of posts from local users
 async fn statistics() -> Result<(u64, u64, u64, u64), DbErr> {
     let db = db_conn().await?;
 
@@ -49,6 +58,8 @@ async fn statistics() -> Result<(u64, u64, u64, u64), DbErr> {
     )
 }
 
+/// Generates NodeInfo (version 2.1) of the local server.
+/// This function doesn't use caches and returns the latest information.
 async fn generate_nodeinfo_2_1() -> Result<Nodeinfo21, Error> {
     let (local_users, local_active_halfyear, local_active_month, local_posts) =
         statistics().await?;

packages/backend-rs/src/federation/nodeinfo/mod.rs

@@ -1,4 +1,6 @@
 //! NodeInfo handler
+//!
+//! ref: <https://nodeinfo.diaspora.software/>
 
 pub mod fetch;
 pub mod generate;

packages/backend-rs/src/federation/nodeinfo/schema.rs

@@ -1,4 +1,6 @@
 //! Schema definitions of NodeInfo version 2.0 and 2.1
+//!
+//! ref: <https://nodeinfo.diaspora.software/schema.html>
 
 use serde::{Deserialize, Serialize};
 use std::collections::HashMap;