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

Add some sort of docs

Browse source
This commit is contained in:
Steffo 2024-11-11 08:43:22 +01:00
parent b46a995c09
commit a7d095fee0
Signed by: steffo
GPG key ID: 5ADA3868646C3FC0
2 changed files with 79 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1,7 +1,9 @@
//! Resource descriptior deserializer. //! Resource descriptior deserializer.
//! //!
//! [RFC 6415]: https://datatracker.ietf.org/doc/html/rfc6415 //! # Specification
//! [RFC 7033]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4 //!
//! - <https://datatracker.ietf.org/doc/html/rfc6415>
//! - <https://datatracker.ietf.org/doc/html/rfc7033>
use std::collections::HashMap; use std::collections::HashMap;
@ -9,105 +11,118 @@ use serde::Deserialize;
/// A resource descriptor object. /// A resource descriptor object.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-3>
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4>
/// ///
/// - 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 ResourceDescriptor { pub struct ResourceDescriptor {
/// The resource this document refers to. /// The resource this document refers to.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.1>
/// ///
/// - 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. /// Other names the resource described by this document can be referred to.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.2>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.2
#[serde(alias = "Alias")] #[serde(alias = "Alias")]
pub aliases: Option<Vec<String>>, pub aliases: Option<Vec<String>>,
/// Additional information about the resource described by this document. /// Additional information about the resource described by this document.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3
#[serde(alias = "Property")] #[serde(alias = "Property")]
pub properties: Option<Vec<ResourceDescriptorProperty>>, pub properties: Option<Vec<ResourceDescriptorProperty>>,
/// Links established between the [`Self::subject`] and other resources. /// Links established between the [`Self::subject`] and other resources.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1>
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4>
/// ///
/// - 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: Option<Vec<ResourceDescriptorLink>>, pub links: Option<Vec<ResourceDescriptorLink>>,
} }
/// A link element, which puts the subject resource in relation with another. /// A link element, which puts the subject resource in relation with another.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-3.1.1
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct ResourceDescriptorLink { 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 /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.1>
/// ///
/// 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 media type of the resource put in relation. /// The media type of the resource put in relation.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.2>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.2
#[serde(alias = "@type")] #[serde(alias = "@type")]
pub r#type: Option<String>, pub r#type: Option<String>,
/// URI to the resource put in relation. /// URI to the resource put in relation.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.3>
/// ///
/// - 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>,
/// Titles of the resource put in relation in various languages. /// Titles of the resource put in relation in various languages.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4
pub titles: Option<Vec<HashMap<String, String>>>, pub titles: Option<Vec<HashMap<String, String>>>,
/// Additional information about the resource put in relation. /// Additional information about the resource put in relation.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.5>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.5
pub properties: Option<Vec<ResourceDescriptorProperty>>, pub properties: Option<Vec<ResourceDescriptorProperty>>,
/// Template to fill to get the URL to resource-specific information. /// Template to fill to get the URL to resource-specific information.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-4.2>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-4.2
#[serde(alias = "@template")] #[serde(alias = "@template")]
pub template: Option<String>, pub template: Option<String>,
} }
/// A property element, which describes a certain aspect of the subject resource. /// A property element, which describes a certain aspect of the subject resource.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
pub struct ResourceDescriptorProperty { pub struct ResourceDescriptorProperty {
/// The property identifier, or type. /// The property identifier, or type.
@ -121,11 +136,11 @@ pub struct ResourceDescriptorProperty {
impl ResourceDescriptor { impl ResourceDescriptor {
/// Get a JRD (JSON [`ResourceDescriptor`]). /// Get a JRD (JSON [`ResourceDescriptor`]).
/// ///
/// ## Notes /// # 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.
/// ///
/// ## Examples /// # Examples
/// ///
/// ``` /// ```
/// # tokio_test::block_on(async { /// # tokio_test::block_on(async {
@ -191,11 +206,11 @@ impl ResourceDescriptor {
/// Get a XRD (Extensible [`ResourceDescriptor`]). /// Get a XRD (Extensible [`ResourceDescriptor`]).
/// ///
/// ## Notes /// # 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.
/// ///
/// ## Examples /// # Examples
/// ///
/// ``` /// ```
/// # tokio_test::block_on(async { /// # tokio_test::block_on(async {
@ -210,6 +225,7 @@ impl ResourceDescriptor {
/// .expect("XRD to be processed correctly"); /// .expect("XRD to be processed correctly");
/// # }) /// # })
/// ``` /// ```
///
pub async fn get_xrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, GetXRDError> { pub async fn get_xrd(client: &reqwest::Client, url: reqwest::Url) -> Result<Self, GetXRDError> {
use GetXRDError::*; use GetXRDError::*;
@ -266,18 +282,18 @@ impl ResourceDescriptor {
/// ///
/// 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. [HTTPS] [JRD](Self::get_jrd) with .json path extension /// 3. HTTPS [JRD](Self::get_jrd) with .json path extension
/// 4. [HTTP] [XRD](Self::get_xrd) /// 4. HTTP [XRD](Self::get_xrd)
/// 5. [HTTP] [JRD](Self::get_jrd) /// 5. HTTP [JRD](Self::get_jrd)
/// 6. [HTTP] [JRD](Self::get_jrd) with .json path extension /// 6. HTTP [JRD](Self::get_jrd) with .json path extension
/// ///
/// ## Notes /// # 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.
/// ///
/// ## Examples /// # Examples
/// ///
/// ``` /// ```
/// # tokio_test::block_on(async { /// # tokio_test::block_on(async {
@ -428,14 +444,15 @@ impl ResourceDescriptor {
/// Well-known path for host-meta documents. /// Well-known path for host-meta documents.
/// ///
/// ## Specification /// # Specification
///
/// - <https://datatracker.ietf.org/doc/html/rfc6415#section-2>
/// ///
/// - https://datatracker.ietf.org/doc/html/rfc6415#section-2
pub const WELLKNOWN_HOSTMETA_PATH: &str = "/.well-known/host-meta"; pub const WELLKNOWN_HOSTMETA_PATH: &str = "/.well-known/host-meta";
/// Attempt to discover a host-meta document at the given base URL. /// Attempt to discover a host-meta document at the given base URL.
/// ///
/// ## Examples /// # Examples
/// ///
/// ``` /// ```
/// # tokio_test::block_on(async { /// # tokio_test::block_on(async {

30
acrate-nodeinfo/src/lib.rs
View file

@ -1,14 +1,18 @@
//! Serde-based NodeInfo fetcher and loose parser. //! Serde-based NodeInfo fetcher and loose parser.
//! //!
//! > NodeInfo is an effort to create a standardized way of exposing metadata about a server running one of the distributed social networks. //! > 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>
use serde::Deserialize; use serde::Deserialize;
/// A variant of a NodeInfo document. /// A variant of a NodeInfo document.
/// ///
/// ## Specification /// # Specification
/// ///
/// - https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md /// - <https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md>
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub enum NodeInfo { pub enum NodeInfo {
V1(NodeInfo1), V1(NodeInfo1),
@ -17,10 +21,10 @@ pub enum NodeInfo {
/// A NodeInfo document at version 1.X. /// A NodeInfo document at version 1.X.
/// ///
/// ## Specification /// # Specification
/// ///
/// - https://github.com/jhass/nodeinfo/blob/main/schemas/1.0/schema.json /// - <https://github.com/jhass/nodeinfo/blob/main/schemas/1.0/schema.json>
/// - https://github.com/jhass/nodeinfo/blob/main/schemas/1.1/schema.json /// - <https://github.com/jhass/nodeinfo/blob/main/schemas/1.1/schema.json>
/// ///
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
@ -51,11 +55,11 @@ pub struct NodeInfo1 {
/// A NodeInfo document at version 2.X. /// A NodeInfo document at version 2.X.
/// ///
/// ## Specification /// # Specification
/// ///
/// - https://github.com/jhass/nodeinfo/blob/main/schemas/2.0/schema.json /// - <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.1/schema.json>
/// - https://github.com/jhass/nodeinfo/blob/main/schemas/2.2/schema.json /// - <https://github.com/jhass/nodeinfo/blob/main/schemas/2.2/schema.json>
/// ///
#[derive(Debug, Clone, Deserialize)] #[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "camelCase")] #[serde(rename_all = "camelCase")]
@ -163,14 +167,14 @@ pub struct NodeInfo2Instance {
impl NodeInfo { impl NodeInfo {
/// Well-known path for NodeInfo documents. /// Well-known path for NodeInfo documents.
/// ///
/// ## Specification /// # Specification
/// ///
/// - https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md#discovery /// - <https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md#discovery>
pub const WELLKNOWN_NODEINFO_PATH: &str = "/.well-known/nodeinfo"; pub const WELLKNOWN_NODEINFO_PATH: &str = "/.well-known/nodeinfo";
/// Discover and get the latest NodeInfo version available given a certain base URL. /// Discover and get the latest NodeInfo version available given a certain base URL.
/// ///
/// ## Examples /// # Examples
/// ///
/// ``` /// ```
/// # tokio_test::block_on(async { /// # tokio_test::block_on(async {
@ -371,7 +375,7 @@ impl NodeInfo1 {
impl NodeInfo2 { impl NodeInfo2 {
/// Get a NodeInfo v2.X document. /// Get a NodeInfo v2.X document.
/// ///
/// ## Examples /// # Examples
/// ///
/// ``` /// ```
/// # tokio_test::block_on(async { /// # tokio_test::block_on(async {