Add some sort of docs
This commit is contained in:
parent
b46a995c09
commit
a7d095fee0
GPG key ID:
5ADA3868646C3FC0
2 changed files with 79 additions and 58 deletions
|
|
@ -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
|
||||
//!
|
||||
//! - <https://datatracker.ietf.org/doc/html/rfc6415>
|
||||
//! - <https://datatracker.ietf.org/doc/html/rfc7033>
|
||||
|
||||
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>
|
||||
///
|
||||
/// - 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>
|
||||
///
|
||||
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.1
|
||||
#[serde(alias = "Subject")]
|
||||
pub subject: Option<String>,
|
||||
|
||||
/// 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")]
|
||||
pub aliases: Option<Vec<String>>,
|
||||
|
||||
/// 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")]
|
||||
pub properties: Option<Vec<ResourceDescriptorProperty>>,
|
||||
|
||||
/// 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")]
|
||||
pub links: Option<Vec<ResourceDescriptorLink>>,
|
||||
}
|
||||
|
||||
/// 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)]
|
||||
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>
|
||||
///
|
||||
/// 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>
|
||||
///
|
||||
/// - https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.2
|
||||
#[serde(alias = "@type")]
|
||||
pub r#type: Option<String>,
|
||||
|
||||
/// 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")]
|
||||
pub href: Option<String>,
|
||||
|
||||
/// 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>>>,
|
||||
|
||||
/// 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>>,
|
||||
|
||||
/// 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")]
|
||||
pub template: Option<String>,
|
||||
}
|
||||
|
||||
/// 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)]
|
||||
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<Self, GetXRDError> {
|
||||
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>
|
||||
///
|
||||
/// - 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 {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
//!
|
||||
//! - <https://github.com/jhass/nodeinfo/blob/main/PROTOCOL.md>
|
||||
|
||||
use serde::Deserialize;
|
||||
|
||||
/// 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)]
|
||||
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
|
||||
/// - <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
|
||||
/// - <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
|
||||
/// - <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 {
|
||||
|
|
|
|||
Loading…
Reference in a new issue