Skip to content

Commit

Permalink
Add inner-code documentation
Browse files Browse the repository at this point in the history
This is important for developers and it's a 'must' for publish this
crate to crates.io
  • Loading branch information
InfoHunter committed Apr 24, 2024
1 parent b8137eb commit 0dbd171
Show file tree
Hide file tree
Showing 27 changed files with 202 additions and 1 deletion.
9 changes: 9 additions & 0 deletions bin/rusty_vault.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
4 changes: 4 additions & 0 deletions src/cli/command/mod.rs
Original file line number Diff line number Diff line change
@@ -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;
7 changes: 7 additions & 0 deletions src/cli/config.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -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")]
Expand All @@ -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)]
Expand Down Expand Up @@ -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)]
Expand Down
6 changes: 5 additions & 1 deletion src/cli/mod.rs
Original file line number Diff line number Diff line change
@@ -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(
Expand All @@ -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() {
Expand Down
3 changes: 3 additions & 0 deletions src/context.rs
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
9 changes: 9 additions & 0 deletions src/core.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
5 changes: 5 additions & 0 deletions src/errors.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
8 changes: 8 additions & 0 deletions src/handler.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
4 changes: 4 additions & 0 deletions src/http/mod.rs
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
23 changes: 23 additions & 0 deletions src/lib.rs
Original file line number Diff line number Diff line change
@@ -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
extern crate diesel;

pub mod cli;
Expand Down
13 changes: 13 additions & 0 deletions src/logical/mod.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
10 changes: 10 additions & 0 deletions src/module_manager.rs
Original file line number Diff line number Diff line change
@@ -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::{
Expand Down
4 changes: 4 additions & 0 deletions src/modules/auth/mod.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
4 changes: 4 additions & 0 deletions src/modules/credential/mod.rs
Original file line number Diff line number Diff line change
@@ -1,2 +1,6 @@
//! This module provides several authentication methods, such as username/password, certificate
//! , etc.
//!
pub mod userpass;
//pub mod cert;
3 changes: 3 additions & 0 deletions src/modules/kv/mod.rs
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
8 changes: 8 additions & 0 deletions src/modules/mod.rs
Original file line number Diff line number Diff line change
@@ -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};
Expand All @@ -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(())
Expand Down
3 changes: 3 additions & 0 deletions src/modules/pki/mod.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
3 changes: 3 additions & 0 deletions src/modules/system/mod.rs
Original file line number Diff line number Diff line change
@@ -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,
Expand Down
6 changes: 6 additions & 0 deletions src/mount.rs
Original file line number Diff line number Diff line change
@@ -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},
Expand Down
4 changes: 4 additions & 0 deletions src/router.rs
Original file line number Diff line number Diff line change
@@ -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};
Expand Down
29 changes: 29 additions & 0 deletions src/shamir.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
7 changes: 7 additions & 0 deletions src/storage/barrier.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
3 changes: 3 additions & 0 deletions src/storage/barrier_aes_gcm.rs
Original file line number Diff line number Diff line change
@@ -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};

Expand Down
18 changes: 18 additions & 0 deletions src/storage/mod.rs
Original file line number Diff line number Diff line change
@@ -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;
Expand All @@ -8,13 +24,15 @@ pub mod barrier_view;
pub mod physical;
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 {
Expand Down
2 changes: 2 additions & 0 deletions src/storage/mysql/mod.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
//! MySQL storage backend implementations.
use std::collections::HashMap;

use diesel::mysql::MysqlConnection;
Expand Down
5 changes: 5 additions & 0 deletions src/storage/physical/mod.rs
Original file line number Diff line number Diff line change
@@ -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};
Expand All @@ -11,7 +13,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>;
Expand All @@ -25,6 +29,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" => {
Expand Down
3 changes: 3 additions & 0 deletions src/utils/mod.rs
Original file line number Diff line number Diff line change
@@ -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::*;
Expand Down

0 comments on commit 0dbd171

Please sign in to comment.