Update documentation

examples/src/server.rs

@@ -75,8 +75,7 @@ async fn main() {
 
     tokio::task::spawn(async {
         let mut db = AsyncStore::new();
-        let piv: OwnedVid =
-            serde_json::from_str(include_str!("../test/p.json")).unwrap();
+        let piv: OwnedVid = serde_json::from_str(include_str!("../test/p.json")).unwrap();
         db.add_private_vid(piv).unwrap();
         db.verify_vid("did:web:did.tsp-test.org:user:q")
             .await
@@ -98,8 +97,7 @@ async fn main() {
 
     tokio::task::spawn(async {
         let mut db = AsyncStore::new();
-        let piv: OwnedVid =
-            serde_json::from_str(include_str!("../test/q.json")).unwrap();
+        let piv: OwnedVid = serde_json::from_str(include_str!("../test/q.json")).unwrap();
         db.add_private_vid(piv).unwrap();
         db.verify_vid("did:web:did.tsp-test.org:user:p")
             .await

tsp/src/async_store.rs

@@ -9,8 +9,8 @@ use tokio::sync::mpsc::{self, Receiver};
 use url::Url;
 
 /// Holds private ands verified VIDs
-/// A Store contains verified vid's, our relationship status to them,
-/// as well as the private vid's that this application has control over.
+/// A Store contains verified VIDs, our relationship status to them,
+/// as well as the private VIDs that this application has control over.
 ///
 /// # Example
 ///
@@ -42,6 +42,7 @@ pub struct AsyncStore {
 }
 
 impl AsyncStore {
+    /// Create a new and empty store
     pub fn new() -> Self {
         Default::default()
     }
@@ -61,6 +62,7 @@ impl AsyncStore {
         self.inner.set_relation_for_vid(vid, relation_vid)
     }
 
+    /// Sets the relationship status for a VID
     pub(super) fn set_relation_status_for_vid(
         &self,
         vid: &str,
@@ -74,10 +76,12 @@ impl AsyncStore {
         self.inner.set_route_for_vid(vid, route)
     }
 
+    /// Sets the parent for a VID. This is used to create a nested message.
     pub fn set_parent_for_vid(&self, vid: &str, parent: Option<&str>) -> Result<(), Error> {
         self.inner.set_parent_for_vid(vid, parent)
     }
 
+    /// List all VIDs in the database
     pub fn list_vids(&self) -> Result<Vec<String>, Error> {
         self.inner.list_vids()
     }
@@ -267,7 +271,9 @@ impl AsyncStore {
         Ok(())
     }
 
-    // Receive, open and forward a TSP message
+    /// Receive, open and forward a TSP message
+    /// This method is used by intermediary nodes to receive a TSP message,
+    /// open it and forward it to the next hop.
     pub async fn route_message(
         &self,
         sender: &str,

tsp/src/lib.rs

@@ -7,7 +7,7 @@
 //! is used to manage and resolve VIDs, as well as send and receive messages
 //! between them.
 //!
-//! # Example
+//! ## Example
 //!
 //! The following example demonstrates how to send a message from Alice to Bob
 //!
@@ -49,10 +49,23 @@
 //!     Ok(())
 //! }
 //! ```
+//! ## Core protocol
 //!
+//! By default this library comes with methods to send and receive messages
+//! over various transport and code to resolve and verify various VIDs.
+//!
+//! If your use-case only requires the core protocol, you can disable the
+//! `async` feature to remove the transport layer and resolve methods.
+//!
+//! The `AsyncStore` uses the tokio async runtime and offers a high level API.
+//!
+//! The `Store` struct implements managing VIDs and sealing / opening
+//! TSP messages (low level API), it does not require an async runtime.
 pub mod cesr;
 pub mod crypto;
 pub mod definitions;
+mod error;
+mod store;
 pub mod vid;
 
 #[cfg(feature = "async")]
@@ -61,20 +74,14 @@ pub mod transport;
 #[cfg(feature = "async")]
 mod async_store;
 
-mod error;
-mod store;
-
 #[cfg(feature = "async")]
 #[cfg(test)]
 mod test;
 
-pub use crate::{
-    definitions::{Payload, PrivateVid, ReceivedTspMessage, VerifiedVid},
-    vid::{OwnedVid, Vid},
-};
-
 #[cfg(feature = "async")]
 pub use async_store::AsyncStore;
 
+pub use definitions::{Payload, PrivateVid, ReceivedTspMessage, VerifiedVid};
 pub use error::Error;
 pub use store::{ExportVid, Store};
+pub use vid::{OwnedVid, Vid};

tsp/src/store.rs

@@ -46,18 +46,23 @@ pub(crate) struct VidContext {
 }
 
 impl VidContext {
+    /// Set the parent VID for this VID. Used to create a nested TSP message
     fn set_parent_vid(&mut self, parent_vid: Option<&str>) {
         self.parent_vid = parent_vid.map(|r| r.to_string());
     }
 
+    /// Set the relation VID for this VID. The relation VID wil be used as
+    /// sender VID when sending messages to this VID
     fn set_relation_vid(&mut self, relation_vid: Option<&str>) {
         self.relation_vid = relation_vid.map(|r| r.to_string());
     }
 
+    /// Set the relation status for this VID.
     fn set_relation_status(&mut self, relation_status: RelationshipStatus) {
         self.relation_status = relation_status;
     }
 
+    /// Set the route for this VID. The route will be used to send routed messages to this VID
     fn set_route(&mut self, route: &[impl AsRef<str>]) {
         if route.is_empty() {
             self.tunnel = None;
@@ -66,14 +71,17 @@ impl VidContext {
         }
     }
 
+    /// Get the parent VID for this VID
     pub(crate) fn get_parent_vid(&self) -> Option<&str> {
         self.parent_vid.as_deref()
     }
 
+    /// Get the relation VID for this VID
     pub(crate) fn get_relation_vid(&self) -> Option<&str> {
         self.relation_vid.as_deref()
     }
 
+    /// Get the route for this VID
     pub(crate) fn get_route(&self) -> Option<&[String]> {
         self.tunnel.as_deref()
     }
@@ -82,8 +90,10 @@ impl VidContext {
 /// Holds private ands verified VIDs
 /// A Store contains verified vid's, our relationship status to them,
 /// as well as the private vid's that this application has control over.
+///
+/// The struct is the primary interface to the VID database, in a synchronous
+/// context (when no async runtime is available).
 #[derive(Default, Clone)]
-//TODO: refactor into a single HashMap<String, {vid+status}>, since being a 'PrivateVid' is also in some sense a "status"; also see gh #94
 pub struct Store {
     pub(crate) vids: Arc<RwLock<HashMap<String, VidContext>>>,
 }
@@ -171,6 +181,7 @@ impl Store {
         Ok(())
     }
 
+    /// Sets the parent for a VID. This is used to create a nested message.
     pub fn set_parent_for_vid(&self, vid: &str, parent_vid: Option<&str>) -> Result<(), Error> {
         self.modify_vid(vid, |resolved| {
             resolved.set_parent_vid(parent_vid);
@@ -188,10 +199,12 @@ impl Store {
         })
     }
 
+    /// List all VIDs in the database
     pub fn list_vids(&self) -> Result<Vec<String>, Error> {
         Ok(self.vids.read()?.keys().cloned().collect())
     }
 
+    /// Sets the relationship status for a VID
     pub fn set_relation_status_for_vid(
         &self,
         vid: &str,
@@ -249,13 +262,20 @@ impl Store {
         Ok(self.get_vid(vid)?.vid)
     }
 
+    /// Retrieve the [VidContext] identified by `vid` from the database, if it exists.
     pub(super) fn get_vid(&self, vid: &str) -> Result<VidContext, Error> {
         match self.vids.read()?.get(vid) {
             Some(resolved) => Ok(resolved.clone()),
             None => Err(Error::UnverifiedVid(vid.to_string())),
         }
     }
 
+    /// Seal a TSP message.
+    /// The message is encrypted, encoded and signed using the key material
+    /// of the sender and receiver, specified by their VIDs.
+    ///
+    /// Note that the the corresponsing VIDs should first be added and configured
+    /// using this store.
     pub fn seal_message(
         &self,
         sender: &str,
@@ -271,6 +291,7 @@ impl Store {
         )
     }
 
+    /// Seal a TSP message.
     pub(crate) fn seal_message_payload(
         &self,
         sender: &str,
@@ -369,10 +390,12 @@ impl Store {
         Ok((receiver_context.vid.endpoint().clone(), tsp_message))
     }
 
+    /// Sign a unencrypted message, without a specified recipient
     pub fn sign_anycast(&self, sender: &str, message: &[u8]) -> Result<Vec<u8>, Error> {
         self.sign_anycast_payload(sender, Payload::Content(message))
     }
 
+    /// Sign a unencrypted message payload, without a specified recipient
     pub(crate) fn sign_anycast_payload(
         &self,
         sender: &str,
@@ -384,7 +407,7 @@ impl Store {
         Ok(message)
     }
 
-    // Receive, open and forward a TSP message
+    /// Receive, open and forward a TSP message
     pub fn route_message(
         &self,
         sender: &str,