Add inner-code documentation for crate rusty_vault (#52)

* Add inner-code documentation

This is important for developers and it's a 'must' for publish this
crate to crates.io

* Add documentation build in CI

Build inner code document only for rusty_vault crate and rvault binary,
so option --no-deps is passed to cargo doc command.

.github/workflows/rust.yml

@@ -50,6 +50,8 @@ jobs:
       run: cargo build --features storage_mysql --verbose
     - name: Run tests
       run: cargo test --verbose
+    - name: Build crate doc
+      run: cargo doc --no-deps
 
 
   windows-default-test:
@@ -112,3 +114,5 @@ jobs:
       run: cargo build --features storage_mysql --verbose
     - name: Run tests
       run: cargo test --verbose
+    - name: Build crate doc
+      run: cargo doc --no-deps

bin/rusty_vault.rs

@@ -1,3 +1,12 @@
+//! This is the 'application' part of RustyVault, a Rust replica of Hashicorp Vault.
+//! The code here will be built into a binary (with a main function which utilize the
+//! `rusty_vault::cli` module to run the application).
+//!
+//! This document is generated for the application part of RustyVault. But we don't organize the
+//! real doc here, please go to RustyVault's [documentation site]
+//!
+//! [documentation site]: https://www.tongsuo.net
+
 use std::process::ExitCode;
 
 use clap::Command;

src/cli/command/mod.rs

@@ -1,2 +1,6 @@
+//! This module provides different commands for the RustyVault application.
+//! For instance, we have a 'server' command to indicate the application running in the server mode
+//! and starts to accept HTTP request to do real RustyVault functionality.
+
 pub mod server;
 pub mod status;

src/cli/config.rs

@@ -1,3 +1,7 @@
+//! This module defines and handles the config file options for RustyVault application.
+//! For instance, the IP address and port for the RustyVault to listen on is handled in this
+//! module.
+
 use std::{collections::HashMap, fmt, fs, path::Path};
 
 use openssl::ssl::SslVersion;
@@ -9,6 +13,7 @@ use serde_json::Value;
 
 use crate::errors::RvError;
 
+/// A struct that contains several configurable options of RustyVault server
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Config {
     #[serde(deserialize_with = "validate_listener")]
@@ -33,6 +38,7 @@ pub struct Config {
     pub daemon_group: String,
 }
 
+/// A struct that contains several configurable options for networking stuffs
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Listener {
     #[serde(default)]
@@ -66,6 +72,7 @@ pub struct Listener {
     pub tls_cipher_suites: String,
 }
 
+/// A struct that contains several configurable options for storage stuffs
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Storage {
     #[serde(default)]

src/cli/mod.rs

@@ -1,10 +1,13 @@
+//! The `rusty_vault::cli` module is used to serve the RustyVault application.
+//! This module basically accepts options from command-line and starts a server up.
+
 use clap::{Arg, ArgAction, ArgMatches, Command};
 use sysexits::ExitCode;
 
 pub mod command;
 pub mod config;
 
-/// Defines command line options
+/// Defines command line options.
 pub fn define_command_line_options(mut app: Command) -> Command {
     app = app.subcommands([
         Command::new("server").about("Start a rusty_vault server").arg(
@@ -23,6 +26,7 @@ pub fn define_command_line_options(mut app: Command) -> Command {
     app
 }
 
+/// Do real jobs.
 #[inline]
 pub fn run(matches: &ArgMatches) -> ExitCode {
     match matches.subcommand() {

src/context.rs

@@ -1,3 +1,6 @@
+//! The `rusty_vault::context` module is intent to provide a generic key value storage.
+//! This module is currently not used by any other part of `crate::rusty_vault`.
+
 use std::{
     any::Any,
     cell::RefCell,

src/core.rs

@@ -1,3 +1,12 @@
+//! The `rusty_vault::core` module implements several key functions that are
+//! in charge of the whole process of RustyVault. For instance, to seal or unseal the RustyVault we
+//! have the `seal()` and `unseal()` functions in this module. Also, the `handle_request()`
+//! function in this module is to route an API call to its correct backend and get the result back
+//! to the caller.
+//!
+//! This module is very low-level and usually it should not disturb end users and module developers
+//! of RustyVault.
+
 use std::{
     collections::HashMap,
     sync::{Arc, Mutex, RwLock},

src/errors.rs

@@ -1,3 +1,8 @@
+//! The `rusty_vault::errors` module defines an enumeration of various error code, and implements
+//! neccessary traits against it.
+//!
+//! The error code defined in this module are used widely in RustyVault.
+
 use std::{
     io,
     sync::{PoisonError, RwLockReadGuard, RwLockWriteGuard},

src/handler.rs

@@ -1,3 +1,11 @@
+//! The `rusty_vault::handler` module basically defines the `Handler` trait.
+//!
+//! The `Handler` trait includes a set of 'hook points' that are performed during the process of an
+//! API request from the user.
+//!
+//! The `Handler` trait should be implemented in other module, such as the `rusty_vault::router`
+//! for instance.
+
 use crate::{
     errors::RvError,
     logical::{request::Request, response::Response},

src/http/mod.rs

@@ -1,3 +1,7 @@
+//! This module handles almost everything related to RustyVault's HTTP(S) server, including basic
+//! connection, HTTP request reading, HTTP response writing, data encoding/decoding, TLS stuffs, etc.
+//! This module utilize `actix_web` crate as the underlying provider.
+
 use std::{
     any::Any,
     net::SocketAddr,

src/lib.rs

@@ -1,3 +1,26 @@
+//! This crate is the 'library' part of RustyVault, a Rust and real free replica of Hashicorp Vault.
+//! RustyVault is focused on identity-based secrets management and works in two ways independently:
+//!
+//! 1. A standalone application serving secrets management via RESTful API;
+//! 2. A Rust crate that provides same features for other application to integrate.
+//!
+//! This document is only about the crate part of RustyVault. For the first working mode,
+//! please go to RustyVault's [RESTful API documentation], which documents all RustyVault's RESTful API.
+//! Users can use an HTTP client tool (curl, e.g.) to send commands to a running RustyVault server and
+//! then have relevant secret management features.
+//!
+//! The second working mode, which works as a typical Rust crate called `rusty_vault`, allows Rust
+//! application developers to integrate RustyVault easily into their own applications to have the
+//! ability of secrets management such as secure key/vaule storage, public key cryptography, data
+//! encryption and so forth.
+//!
+//! This is the official documentation of crate `rusty_vault`, and it's mainly for developers.
+//! Once again, if you are looking for how to use the RustyVault server via a set of RESTful API,
+//! then you may prefer the RustyVault's [RESTful API documentation].
+//!
+//! [Hashicorp Vault]: https://www.hashicorp.com/products/vault
+//! [RESTful API documentation]: https://www.tongsuo.net
+
 #[cfg(feature = "storage_mysql")]
 extern crate diesel;
 

src/logical/mod.rs

@@ -1,3 +1,16 @@
+//! The `rusty_vault::logical` is a low level module that defines 'backend' and relevant data
+//! structures such as `Path`, `Request`, etc and traits.
+//!
+//! The term 'backend' is generic in RustyVault. It represents for a module that provides real
+//! features, as what you can see in the modules directory. The `Backend` trait in this module is
+//! designed to represent the concept of backend. Modules of RustyVault need to implement this
+//! trait for their own types.
+//!
+//! Since modules may have common attributes, a specific data structure named `LogicalBackend` is
+//! also defined in this module. Other RustyVault modules can instantiate a `LogicalBackend`
+//! object and implement `rusty_vault::logical::Backend` trait for it. Thus, this module can be
+//! included in the API routing process.
+
 use std::sync::Arc;
 
 use enum_map::Enum;

src/module_manager.rs

@@ -1,3 +1,13 @@
+//! RustyVault is consisted of many modules. Modules are the real components that implement the
+//! features that users need. All modules in RustyVault are managed by `rusty_vault::module_manager`.
+//!
+//! In details, the module manager is able to organize, add, remove, setup, initialize, cleanup
+//! other RustyVault modules.
+//!
+//! Do not mix up the RustyVault module with the concept of a Rust module. A RustyVault module is a
+//! piece of code that implements some functionality. Although usually that piece of code is
+//! organized in the form of a module of crate `rusty_vault` in Rust language concept.
+
 use std::sync::{Arc, RwLock};
 
 use crate::{

src/modules/auth/mod.rs

@@ -1,3 +1,7 @@
+//! This module provides the 'auth/' path and relevant authentication features.
+//!
+//! After a successful authentication, a client will be granted a token for further operations.
+
 use std::{
     collections::HashMap,
     sync::{Arc, Mutex, RwLock},

src/modules/credential/mod.rs

@@ -1,2 +1,6 @@
+//! This module provides several authentication methods, such as username/password, certificate
+//! , etc.
+//!
+
 pub mod userpass;
 //pub mod cert;

src/modules/kv/mod.rs

@@ -1,3 +1,6 @@
+//! The secure key-value object storage module. The user can use this module to store arbitary data
+//! into RustyVault. The data stored in RustyVault is encrypted.
+
 use std::{
     collections::HashMap,
     ops::Deref,

src/modules/mod.rs

@@ -1,3 +1,10 @@
+//! `rusty_vault::modules` contains a set of real RustyVault modules. Each sub module needs to
+//! implement the `rusty_vault::modules::Module` trait defined here and then the module
+//! could be added to module manager.
+//!
+//! It's important for the developers who want to implement a new RustyVault module themselves to
+//! get the `trait Module` implemented correctly.
+
 use as_any::AsAny;
 
 use crate::{core::Core, errors::RvError};
@@ -9,6 +16,7 @@ pub mod pki;
 pub mod system;
 
 pub trait Module: AsAny + Send + Sync {
+    //! Description for a trait itself.
     fn name(&self) -> String;
     fn init(&mut self, _core: &Core) -> Result<(), RvError> {
         Ok(())

src/modules/pki/mod.rs

@@ -1,3 +1,6 @@
+//! The `rusty_vault::pki` module implements public key cryptography features, including
+//! manipulating certificates as a CA or encrypting a piece of data by using a public key.
+
 use std::{
     ops::Deref,
     sync::{atomic::AtomicU64, Arc, RwLock},

src/modules/system/mod.rs

@@ -1,3 +1,6 @@
+//! The system module is mainly used to configure RustyVault itself. For instance, the 'mount/'
+//! path is provided here to support mounting new modules in RustyVault via RESTful HTTP request.
+
 use std::{
     collections::HashMap,
     ops::Deref,

src/mount.rs

@@ -1,3 +1,9 @@
+//! Simply speaking, the `rusty_vault::mount` module manages the relationship between a 'path' and
+//! the real RustyVault module which is responsible for that feature. In RustyVault, everything is
+//! exposed to outside by RESTful API, which is defined by 'path'.
+//!
+//! The binding logic here is managed by `MountEntry` struct.
+
 use std::{
     collections::HashMap,
     sync::{Arc, RwLock},

src/router.rs

@@ -1,3 +1,7 @@
+//! The `rusty_vault::router` module contains the functions that are used to do the routing work.
+//! All router entries are organized in a Trie structure which is suitable for locating prefix.
+//! The core router is the final 'glue' that mounts the pieces together for RustyVault's API.
+
 use std::sync::{Arc, RwLock};
 
 use radix_trie::{Trie, TrieCommon};

src/shamir.rs

@@ -1,3 +1,32 @@
+//! A Shamir threshold algorithm implementaion which is used to derive the RustyVault master key.
+//!
+//! This code is originated from Chris MacNaughton, we modified it to be compatible with Vault's
+//! Shamir algorithm.
+//!
+//! The original MIT license is as follows:
+//!
+//! The MIT License (MIT)
+//!
+//! Copyright (c) 2016 Chris MacNaughton
+//!
+//! Permission is hereby granted, free of charge, to any person obtaining a copy
+//! of this software and associated documentation files (the "Software"), to deal
+//! in the Software without restriction, including without limitation the rights
+//! to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+//! copies of the Software, and to permit persons to whom the Software is
+//! furnished to do so, subject to the following conditions:
+//!
+//! The above copyright notice and this permission notice shall be included in all
+//! copies or substantial portions of the Software.
+//!
+//! THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+//! IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+//! FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+//! AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+//! LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+//! OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+//! SOFTWARE.
+
 use rand::{thread_rng, RngCore};
 
 use crate::errors::RvError;

src/storage/barrier.rs

@@ -1,3 +1,10 @@
+//! Defines the `SecurityBarrier` trait for different barrier types.
+//!
+//! Specific barriers in RustyVault need to implement this trait and the `Storage` trait.
+//!
+//! It usually means a different symmetric encryption algorithm is going to be supported,
+//! if a new barrier is under development.
+
 use super::Storage;
 use crate::errors::RvError;
 use zeroize::Zeroizing;

src/storage/barrier_aes_gcm.rs

@@ -1,3 +1,6 @@
+//! This is the implementation of aes-gcm barrier, which uses aes-gcm block cipher to encrypt or
+//! decrypt data before writing or reading data to or from specific storage backend.
+
 use std::sync::{Arc, RwLock};
 use std::ops::{Deref, DerefMut};
 

src/storage/mod.rs

@@ -1,3 +1,19 @@
+//! This module manages all storage related code by defining a 'barrier' concept and a 'backend'
+//! concept.
+//!
+//! Each different storage type needs to implement the `backend` trait to complete the support.
+//!
+//! Each barrier represents a specific cryptography method for ecrypting or decrypting data before
+//! the data connects to a specific backend. A barrier is defined by implementing the `SecurityBarrier`
+//! trait.
+//!
+//! So one example of a whole data path could be something like this:
+//!
+//! HTTP API -> some module (e.g. KV) -> barrier -> backend -> real storage (file, MySQL...)
+//!
+//! Typical storage types may be direct file, databases, remote network filesystem and etc.
+//! Different strage types are all as sub-module of this module.
+
 use serde::{Deserialize, Serialize};
 
 use crate::errors::RvError;
@@ -9,13 +25,15 @@ pub mod physical;
 #[cfg(feature = "storage_mysql")]
 pub mod mysql;
 
+/// A trait that abstracts core methods for all storage barrier types.
 pub trait Storage {
     fn list(&self, prefix: &str) -> Result<Vec<String>, RvError>;
     fn get(&self, key: &str) -> Result<Option<StorageEntry>, RvError>;
     fn put(&self, entry: &StorageEntry) -> Result<(), RvError>;
     fn delete(&self, key: &str) -> Result<(), RvError>;
 }
 
+/// This struct is used to describe a specific storage entry
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct StorageEntry {

src/storage/mysql/mod.rs

@@ -1,3 +1,5 @@
+//! MySQL storage backend implementations.
+
 use std::collections::HashMap;
 
 use diesel::mysql::MysqlConnection;

src/storage/physical/mod.rs

@@ -1,3 +1,5 @@
+//! The `rusty_vault::storage::physical` module supports to physical file storage.
+
 use std::{collections::HashMap, sync::Arc};
 
 use serde::{Deserialize, Serialize};
@@ -12,7 +14,9 @@ use super::mysql::mysql_backend::MysqlBackend;
 pub mod file;
 pub mod mock;
 
+// TODO: this trait definition should be moved to an upper layer, e.g., in the storage/mod.rs
 pub trait Backend: Send + Sync {
+    //! This trait decsribes the general methods that a storage backend needs to implement.
     fn list(&self, prefix: &str) -> Result<Vec<String>, RvError>;
     fn get(&self, key: &str) -> Result<Option<BackendEntry>, RvError>;
     fn put(&self, entry: &BackendEntry) -> Result<(), RvError>;
@@ -26,6 +30,7 @@ pub struct BackendEntry {
     pub value: Vec<u8>,
 }
 
+// TODO: this is a common function needed by all storage backend. Should be moved out of this file.
 pub fn new_backend(t: &str, conf: &HashMap<String, Value>) -> Result<Arc<dyn Backend>, RvError> {
     match t {
         "file" => {

src/utils/mod.rs

@@ -1,3 +1,6 @@
+//! Miscellaneous public handy functions are collected here, such as cryptography tools,
+//! uuid generator, etc.
+
 use std::time::{Duration, SystemTime};
 
 use chrono::prelude::*;