From 303ba5ea88d1fd1ed2ffe2392c1bb21b92dbcb1c Mon Sep 17 00:00:00 2001 From: Jordan Santell Date: Tue, 1 Nov 2022 13:52:55 -0700 Subject: [PATCH] chore: Follow up documentation fixes for noosphere_ns --- rust/noosphere-ns/src/dht/processor.rs | 1 - rust/noosphere-ns/src/name_system.rs | 15 +++++++++++---- rust/noosphere-ns/src/records.rs | 22 ++++++++++++---------- 3 files changed, 23 insertions(+), 15 deletions(-) diff --git a/rust/noosphere-ns/src/dht/processor.rs b/rust/noosphere-ns/src/dht/processor.rs index 590a31482..8b3e94c24 100644 --- a/rust/noosphere-ns/src/dht/processor.rs +++ b/rust/noosphere-ns/src/dht/processor.rs @@ -197,7 +197,6 @@ impl DHTProcessor { publisher: None, expires: None, }; - info!("PUTTING RECORD {:#?}", record); store_request!(self, message, behaviour.kad.put_record(record, Quorum::One)); } }; diff --git a/rust/noosphere-ns/src/name_system.rs b/rust/noosphere-ns/src/name_system.rs index e975f79e0..66d9f3f95 100644 --- a/rust/noosphere-ns/src/name_system.rs +++ b/rust/noosphere-ns/src/name_system.rs @@ -9,10 +9,17 @@ use libp2p::Multiaddr; use std::collections::HashMap; use ucan_key_support::ed25519::Ed25519KeyMaterial; -/// The [NameSystem] is responsible for both propagating and resolving address records -/// in the Noosphere DHT. Hosted records can be set via `set_record(identity, link)`, propagating the -/// record immediately, and repropagated every `propagation_interval` seconds. Records -/// can be resolved via `get_record(identity)`. +/// The [NameSystem] is responsible for both propagating and resolving Sphere DIDs +/// into [NSRecord]s, containing data to find an authenticated [Cid] link to the +/// sphere's content. These records are propagated and resolved via the +/// Noosphere NS distributed network, built on [libp2p](https://libp2p.io)'s +/// [Kademlia DHT specification](https://github.com/libp2p/specs/blob/master/kad-dht/README.md). +/// +/// Hosted records can be set via [NameSystem::set_record], propagating the +/// record immediately, and repropagated every `ttl` seconds. Records +/// can be resolved via [NameSystem::get_record]. +/// +/// New [NameSystem] instances can be created via [crate::NameSystemBuilder]. pub struct NameSystem<'a> { /// Bootstrap peers for the DHT network. pub(crate) bootstrap_peers: Option<&'a Vec>, diff --git a/rust/noosphere-ns/src/records.rs b/rust/noosphere-ns/src/records.rs index c5dbfa64a..a863ada35 100644 --- a/rust/noosphere-ns/src/records.rs +++ b/rust/noosphere-ns/src/records.rs @@ -13,7 +13,7 @@ use std::{ }; /// An [NSRecord] is a struct representing a record stored in the -/// Noosphere Name System's DHT containing a [cid::Cid] of the +/// Noosphere Name System's DHT containing a [Cid] of the /// result, as well as a TTL expiration as seconds from Unix epoch. /// /// # Serialization @@ -23,17 +23,16 @@ use std::{ /// and [NSRecord::from_bytes] methods respectively handle the /// serialization and deserialization in this format. /// -/// Fields are mapped by: +/// Fields are mapped to the corresponding properties and JSON types: /// -/// `cid` => `"cid": String` -/// `expires` => `"exp": Number` +/// * `cid` => `"cid" as String` +/// * `expires` => `"exp" as Number` /// /// An example of the serialized payload structure and /// conversion looks like: /// /// ``` -/// use noosphere_ns::NSRecord; -/// use cid::{Cid, multihash::{Code, MultihashDigest}}; +/// use noosphere_ns::{Cid, NSRecord}; /// use std::str::FromStr; /// /// let cid_str = "bafkreibme22gw2h7y2h7tg2fhqotaqjucnbc24deqo72b6mkl2egezxhvy"; @@ -44,12 +43,15 @@ use std::{ /// assert_eq!(record.expires, expires); /// /// let bytes = record.to_bytes().unwrap(); -/// assert_eq!(&String::from_utf8(bytes.clone()).unwrap(), "{\"cid\":\"bafkreibme22gw2h7y2h7tg2fhqotaqjucnbc24deqo72b6mkl2egezxhvy\",\"exp\":1667262626}"); +/// let record_str = "{\"cid\":\"bafkreibme22gw2h7y2h7tg2fhqotaqjucnbc24deqo72b6mkl2egezxhvy\",\"exp\":1667262626}"; +/// assert_eq!(&String::from_utf8(bytes.clone()).unwrap(), record_str); /// assert_eq!(NSRecord::from_bytes(bytes).unwrap(), record); /// ``` #[derive(Debug, Eq, PartialEq, Clone)] pub struct NSRecord { + /// The link to the resolved sphere's content. pub cid: Cid, + /// TTL expiration time as seconds from Unix epoch. pub expires: u64, } @@ -103,7 +105,7 @@ impl fmt::Display for NSRecord { } } -/// Serialization for NSRecords. While [cid::Cid] has built-in serde +/// Serialization for NSRecords. While [Cid] has built-in serde /// support under a feature flag, we roll our own to store the Cid /// as a string rather than bytes. impl Serialize for NSRecord { @@ -118,10 +120,10 @@ impl Serialize for NSRecord { } } -/// Deserialization for NSRecords. While [cid::Cid] has built-in serde +/// Deserialization for NSRecords. While [Cid] has built-in serde /// support under a feature flag, we roll our own to store the Cid /// as a string rather than bytes. -/// For more details on custom deserialization: https://serde.rs/deserialize-struct.html +/// For more details on custom deserialization: impl<'de> Deserialize<'de> for NSRecord { fn deserialize(deserializer: D) -> Result where