Document a few more types in the UserManagement module

This commit is contained in:
Emi Tatsuo 2020-12-08 11:01:07 -05:00
parent 6b30521c77
commit 6c3eeb1db2
Signed by: Emi
GPG key ID: 68FAB2E2E6DFC98B
2 changed files with 47 additions and 0 deletions

View file

@ -8,6 +8,18 @@ use crate::user_management::user::{RegisteredUser, NotSignedInUser, PartialUser}
///
/// Wraps a [`sled::Db`]
pub struct UserManager {
/// Allows access to the [`sled::Db`] used by the UserManager to store user data.
///
/// Do not try to use this database to access user information, and instead prefer
/// methods such as [`lookup_user()`] and [`lookup_certificate()`].
///
/// However, you're welcome to use the database to store you own data without needing
/// to run parallel sled databases. It's recommended that any trees you open be
/// namespaced like `tld.yourdomain.projectname.treename` in order to prevent
/// conflict.
///
/// [`lookup_user()`]: Self::lookup_user
/// [`lookup_certificate()`]: Self::lookup_certificate
pub db: sled::Db,
pub (crate) users: sled::Tree, // user_id:String maps to data:UserData
pub (crate) certificates: sled::Tree, // certificate:u64 maps to data:CertificateData

View file

@ -33,14 +33,48 @@ use user::{NotSignedInUser, RegisteredUser};
use crate::types::Request;
#[derive(Debug)]
/// An error that occured in the user manager
pub enum UserManagerError {
/// Tried to set a user's username to a username that already exists
///
/// Recommended handling: Explicitly catch the error, and display a custom warning to
/// the user before asking them to try another username
UsernameNotUnique,
/// Attempted to validate the user's password, but they haven't set one yet
///
/// Recommended handling: Inform the user that either their username or password was
/// incorrect.
PasswordNotSet,
/// There was an error connecting to sled
///
/// Recommended handling: Log a visible error for the sysadmin to see, and exit
DatabaseError(sled::Error),
/// There was an error running a database transaction
///
/// Recommended handling: Same as [`UserManagerError::DatabaseError`]
DatabaseTransactionError(sled::transaction::TransactionError),
/// There was an error deserializing from the database
///
/// This likely indicates that the database was generated with
/// a different version of the software than is curretly being used, either because
/// the UserData struct has changed, or because kochab itself has updated it's schema.
///
/// Recommended handling: Log a visible error and exit. Recommend seeking a database
/// migration script or deleting the database
DeserializeBincodeError(bincode::Error),
/// A different version of [`UserManagerError::DeserializeBincodeError`]
DeserializeUtf8Error(std::str::Utf8Error),
#[cfg(feature = "user_management_advanced")]
/// There was an error hashing or checking the user's password.
///
/// This likely indicates database corruption, and should be handled in the same way
/// as a [`UserManagerError::DeserializeBincodeError`]
Argon2Error(argon2::Error),
}
@ -111,4 +145,5 @@ impl std::fmt::Display for UserManagerError {
}
}
/// A result type returned by many methods within the [`user_management`] module
pub type Result<T> = std::result::Result<T, UserManagerError>;