diff --git a/acrate-hostmeta/src/lib.rs b/acrate-hostmeta/src/lib.rs index 81dcb55..57ecd2b 100644 --- a/acrate-hostmeta/src/lib.rs +++ b/acrate-hostmeta/src/lib.rs @@ -1,7 +1,9 @@ //! Resource descriptior deserializer. //! -//! [RFC 6415]: https://datatracker.ietf.org/doc/html/rfc6415 -//! [RFC 7033]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4 +//! # Specification +//! +//! - +//! - use std::collections::HashMap; @@ -9,105 +11,118 @@ use serde::Deserialize; /// 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 #[derive(Debug, Clone, Deserialize)] pub struct ResourceDescriptor { /// The resource this document refers to. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.1 #[serde(alias = "Subject")] pub subject: Option, /// 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 #[serde(alias = "Alias")] pub aliases: Option>, /// Additional information about the resource described by this document. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.3 #[serde(alias = "Property")] pub properties: Option>, /// 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 #[serde(alias = "Link")] pub links: Option>, } /// 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 #[derive(Debug, Clone, Deserialize)] pub struct ResourceDescriptorLink { /// 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 #[serde(alias = "@rel")] pub rel: String, /// The media type of the resource put in relation. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.2 #[serde(alias = "@type")] pub r#type: Option, /// URI to the resource put in relation. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.3 #[serde(alias = "@href")] pub href: Option, /// Titles of the resource put in relation in various languages. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4 pub titles: Option>>, /// Additional information about the resource put in relation. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.5 pub properties: Option>, /// Template to fill to get the URL to resource-specific information. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc6415#section-4.2 #[serde(alias = "@template")] pub template: Option, } /// 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 #[derive(Debug, Clone, Deserialize)] pub struct ResourceDescriptorProperty { /// The property identifier, or type. @@ -121,11 +136,11 @@ pub struct ResourceDescriptorProperty { impl ResourceDescriptor { /// Get a JRD (JSON [`ResourceDescriptor`]). /// - /// ## Notes + /// # Notes /// /// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info. /// - /// ## Examples + /// # Examples /// /// ``` /// # tokio_test::block_on(async { @@ -191,11 +206,11 @@ impl ResourceDescriptor { /// Get a XRD (Extensible [`ResourceDescriptor`]). /// - /// ## Notes + /// # Notes /// /// This follows redirects until the redirect chain is 10 hops; see [`reqwest::redirect`] for more info. /// - /// ## Examples + /// # Examples /// /// ``` /// # tokio_test::block_on(async { @@ -210,6 +225,7 @@ impl ResourceDescriptor { /// .expect("XRD to be processed correctly"); /// # }) /// ``` + /// pub async fn get_xrd(client: &reqwest::Client, url: reqwest::Url) -> Result { use GetXRDError::*; @@ -266,18 +282,18 @@ impl ResourceDescriptor { /// /// In order, this method attempts: /// - /// 1. [HTTPS] [XRD](Self::get_xrd) - /// 2. [HTTPS] [JRD](Self::get_jrd) - /// 3. [HTTPS] [JRD](Self::get_jrd) with .json path extension - /// 4. [HTTP] [XRD](Self::get_xrd) - /// 5. [HTTP] [JRD](Self::get_jrd) - /// 6. [HTTP] [JRD](Self::get_jrd) with .json path extension + /// 1. HTTPS [XRD](Self::get_xrd) + /// 2. HTTPS [JRD](Self::get_jrd) + /// 3. HTTPS [JRD](Self::get_jrd) with .json path extension + /// 4. HTTP [XRD](Self::get_xrd) + /// 5. HTTP [JRD](Self::get_jrd) + /// 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. /// - /// ## Examples + /// # Examples /// /// ``` /// # tokio_test::block_on(async { @@ -428,14 +444,15 @@ impl ResourceDescriptor { /// Well-known path for host-meta documents. /// - /// ## Specification + /// # Specification + /// + /// - /// - /// - https://datatracker.ietf.org/doc/html/rfc6415#section-2 pub const WELLKNOWN_HOSTMETA_PATH: &str = "/.well-known/host-meta"; /// Attempt to discover a host-meta document at the given base URL. /// - /// ## Examples + /// # Examples /// /// ``` /// # tokio_test::block_on(async { diff --git a/acrate-nodeinfo/src/lib.rs b/acrate-nodeinfo/src/lib.rs index fe8ea02..0123a3d 100644 --- a/acrate-nodeinfo/src/lib.rs +++ b/acrate-nodeinfo/src/lib.rs @@ -1,14 +1,18 @@ //! 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. +//! +//! # Specification +//! +//! - use serde::Deserialize; /// A variant of a NodeInfo document. /// -/// ## Specification +/// # Specification /// -/// - https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md +/// - #[derive(Debug, Clone)] pub enum NodeInfo { V1(NodeInfo1), @@ -17,10 +21,10 @@ pub enum NodeInfo { /// 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.1/schema.json +/// - +/// - /// #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] @@ -51,11 +55,11 @@ pub struct NodeInfo1 { /// 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.1/schema.json -/// - https://github.com/jhass/nodeinfo/blob/main/schemas/2.2/schema.json +/// - +/// - +/// - /// #[derive(Debug, Clone, Deserialize)] #[serde(rename_all = "camelCase")] @@ -163,14 +167,14 @@ pub struct NodeInfo2Instance { impl NodeInfo { /// Well-known path for NodeInfo documents. /// - /// ## Specification + /// # Specification /// - /// - https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md#discovery + /// - pub const WELLKNOWN_NODEINFO_PATH: &str = "/.well-known/nodeinfo"; /// Discover and get the latest NodeInfo version available given a certain base URL. /// - /// ## Examples + /// # Examples /// /// ``` /// # tokio_test::block_on(async { @@ -371,7 +375,7 @@ impl NodeInfo1 { impl NodeInfo2 { /// Get a NodeInfo v2.X document. /// - /// ## Examples + /// # Examples /// /// ``` /// # tokio_test::block_on(async {