Added unstable doc attributes to generate fancy docs
This commit is contained in:
parent
2501c9021a
commit
6a7a65d929
|
@ -58,3 +58,6 @@ required-features = ["serve_dir"]
|
|||
[[example]]
|
||||
name = "ratelimiting"
|
||||
required-features = ["ratelimiting"]
|
||||
|
||||
[package.metadata.docs.rs]
|
||||
rustc-args = ["--cfg", "docsrs"]
|
||||
|
|
|
@ -26,6 +26,7 @@ use rustls::*;
|
|||
|
||||
#[derive(Clone, Debug)]
|
||||
#[cfg(feature = "certgen")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "certgen")))]
|
||||
/// The mode to use for determining the domains to use for a new certificate.
|
||||
///
|
||||
/// Used to configure a [`Server`] using [`set_certificate_generation_mode()`]
|
||||
|
@ -45,6 +46,7 @@ pub enum CertGenMode {
|
|||
}
|
||||
|
||||
#[cfg(feature = "certgen")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "certgen")))]
|
||||
impl CertGenMode {
|
||||
/// Generate a new self-signed certificate
|
||||
///
|
||||
|
|
|
@ -56,6 +56,7 @@ pub enum Handler {
|
|||
StaticHandler(Response),
|
||||
|
||||
#[cfg(feature = "serve_dir")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "serve_dir")))]
|
||||
/// A handler that serves a directory, including a directory listing
|
||||
///
|
||||
/// Most often created with [`From<PathBuf>`]
|
||||
|
@ -208,6 +209,7 @@ impl From<&Document> for Handler {
|
|||
}
|
||||
|
||||
#[cfg(feature = "serve_dir")]
|
||||
#[doc(cfg(feature = "serve_dir"))]
|
||||
impl From<PathBuf> for Handler {
|
||||
/// Serve files from a directory
|
||||
///
|
||||
|
|
10
src/lib.rs
10
src/lib.rs
|
@ -237,6 +237,7 @@ pub mod routing;
|
|||
#[cfg(feature = "ratelimiting")]
|
||||
mod ratelimiting;
|
||||
#[cfg(feature = "user_management")]
|
||||
#[doc(cfg(feature = "user_management"))]
|
||||
pub mod user_management;
|
||||
#[cfg(feature = "gemini_srv")]
|
||||
mod cert;
|
||||
|
@ -244,6 +245,7 @@ mod cert;
|
|||
#[cfg(feature="user_management")]
|
||||
use user_management::UserManager;
|
||||
#[cfg(feature = "certgen")]
|
||||
#[doc(cfg(feature = "certgen"))]
|
||||
pub use cert::CertGenMode;
|
||||
|
||||
pub use uriparse::URIReference;
|
||||
|
@ -708,6 +710,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature="user_management")]
|
||||
#[doc(cfg(feature = "user_management"))]
|
||||
/// Sets the directory to store user data in
|
||||
///
|
||||
/// This will only be used if a database is not provided with [`set_database()`].
|
||||
|
@ -721,6 +724,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature="user_management")]
|
||||
#[doc(cfg(feature = "user_management"))]
|
||||
/// Sets a specific database to use
|
||||
///
|
||||
/// This opens to trees within the database, both namespaced to avoid collisions.
|
||||
|
@ -735,6 +739,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature="certgen")]
|
||||
#[doc(cfg(feature = "certgen"))]
|
||||
/// Determine where certificate config comes from, if generation is required
|
||||
///
|
||||
/// If a certificate & keyfile are not available on the provided path, they can be
|
||||
|
@ -747,6 +752,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature = "gemini_srv")]
|
||||
#[doc(cfg(feature = "gemini_srv"))]
|
||||
/// Sets the directory that kochab should look for TLS certs and keys into
|
||||
///
|
||||
/// Northstar will look for files called `cert.pem` and `key.pem` in the provided
|
||||
|
@ -763,6 +769,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature = "gemini_srv")]
|
||||
#[doc(cfg(feature = "gemini_srv"))]
|
||||
/// Set the path to the TLS certificate kochab will use
|
||||
///
|
||||
/// This defaults to `cert/cert.pem`.
|
||||
|
@ -775,6 +782,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature = "gemini_srv")]
|
||||
#[doc(cfg(feature = "gemini_srv"))]
|
||||
/// Set the path to the ertificate key kochab will use
|
||||
///
|
||||
/// This defaults to `cert/key.pem`.
|
||||
|
@ -860,6 +868,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature="ratelimiting")]
|
||||
#[doc(cfg(feature = "ratelimiting"))]
|
||||
/// Add a rate limit to a route
|
||||
///
|
||||
/// The server will allow at most `burst` connections to any endpoints under this
|
||||
|
@ -983,6 +992,7 @@ impl Server {
|
|||
}
|
||||
|
||||
#[cfg(feature = "scgi_srv")]
|
||||
#[doc(cfg(feature = "scgi_srv"))]
|
||||
/// Start serving requests on a given unix socket
|
||||
///
|
||||
/// Requires an address in the form of a path to bind to. This is only available when
|
||||
|
|
|
@ -27,6 +27,7 @@ pub enum Body {
|
|||
impl Body {
|
||||
/// Called by [`Response::rewrite_all`]
|
||||
#[cfg(feature="scgi_srv")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "scgi_srv")))]
|
||||
pub (crate) async fn rewrite_all(&mut self, based_on: &crate::Request) -> std::io::Result<bool> {
|
||||
let bytes = match self {
|
||||
Self::Bytes(bytes) => {
|
||||
|
@ -101,6 +102,7 @@ impl<'a> From<&'a str> for Body {
|
|||
}
|
||||
|
||||
#[cfg(feature="serve_dir")]
|
||||
#[cfg_attr(docsrs, doc(cfg(feature = "serve_dir")))]
|
||||
impl From<File> for Body {
|
||||
fn from(file: File) -> Self {
|
||||
Self::Reader(Box::new(file))
|
||||
|
|
|
@ -209,6 +209,7 @@ impl Request {
|
|||
}
|
||||
|
||||
#[cfg(feature="scgi_srv")]
|
||||
#[doc(cfg(feature = "scgi_srv"))]
|
||||
/// View any headers sent by the SCGI client
|
||||
///
|
||||
/// When an SCGI client delivers a request (e.g. when your gemini server sends a
|
||||
|
@ -252,6 +253,7 @@ impl Request {
|
|||
}
|
||||
|
||||
#[cfg(feature="user_management")]
|
||||
#[doc(cfg(feature = "user_management"))]
|
||||
/// Attempt to determine the user who sent this request
|
||||
///
|
||||
/// May return a variant depending on if the client used a client certificate, and if
|
||||
|
@ -264,6 +266,7 @@ impl Request {
|
|||
}
|
||||
|
||||
#[cfg(feature="user_management")]
|
||||
#[doc(cfg(feature = "user_management"))]
|
||||
/// Expose the server's UserManager
|
||||
///
|
||||
/// Can be used to query users, or directly access the database
|
||||
|
|
|
@ -23,6 +23,7 @@ mod manager;
|
|||
#[cfg(feature = "user_management_routes")]
|
||||
mod routes;
|
||||
#[cfg(feature = "user_management_routes")]
|
||||
#[doc(cfg(feature = "user_management_routes"))]
|
||||
pub use routes::UserManagementRoutes;
|
||||
pub use manager::UserManager;
|
||||
pub use user::User;
|
||||
|
@ -71,6 +72,7 @@ pub enum UserManagerError {
|
|||
DeserializeUtf8Error(std::str::Utf8Error),
|
||||
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(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
|
||||
|
@ -103,6 +105,7 @@ impl From<std::str::Utf8Error> for UserManagerError {
|
|||
}
|
||||
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
impl From<argon2::Error> for UserManagerError {
|
||||
fn from(error: argon2::Error) -> Self {
|
||||
Self::Argon2Error(error)
|
||||
|
@ -117,6 +120,7 @@ impl std::error::Error for UserManagerError {
|
|||
Self::DeserializeBincodeError(e) => Some(e),
|
||||
Self::DeserializeUtf8Error(e) => Some(e),
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
Self::Argon2Error(e) => Some(e),
|
||||
_ => None
|
||||
}
|
||||
|
@ -139,6 +143,7 @@ impl std::fmt::Display for UserManagerError {
|
|||
Self::DeserializeUtf8Error(e) =>
|
||||
write!(f, "Recieved invalid UTF-8 from database, possible corruption: {}", e),
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
Self::Argon2Error(e) =>
|
||||
write!(f, "Argon2 Error, likely malformed password hash, possible database corruption: {}", e),
|
||||
}
|
||||
|
|
|
@ -141,6 +141,7 @@ impl NotSignedInUser {
|
|||
}
|
||||
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
/// Attach this certificate to an existing user
|
||||
///
|
||||
/// Try to add this certificate to another user using a username and password. If
|
||||
|
@ -252,6 +253,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
|
|||
}
|
||||
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
/// Check a password against the user's password hash
|
||||
///
|
||||
/// # Errors
|
||||
|
@ -274,6 +276,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
|
|||
}
|
||||
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
/// Set's the password for this user
|
||||
///
|
||||
/// By default, users have no password, meaning the cannot add any certificates beyond
|
||||
|
@ -364,6 +367,7 @@ impl<UserData: Serialize + DeserializeOwned> RegisteredUser<UserData> {
|
|||
}
|
||||
|
||||
#[cfg(feature = "user_management_advanced")]
|
||||
#[doc(cfg(feature = "user_management_advanced"))]
|
||||
/// Check if the user has a password set
|
||||
///
|
||||
/// Since authentication is done using client certificates, users aren't required to
|
||||
|
|
|
@ -16,6 +16,7 @@ use crate::types::{Document, document::HeadingLevel::*};
|
|||
use crate::types::Response;
|
||||
|
||||
#[cfg(feature="serve_dir")]
|
||||
#[doc(cfg(feature = "serve_dir"))]
|
||||
pub async fn serve_file<P: AsRef<Path>>(path: P, mime: &str) -> Response {
|
||||
let path = path.as_ref();
|
||||
|
||||
|
@ -34,6 +35,7 @@ pub async fn serve_file<P: AsRef<Path>>(path: P, mime: &str) -> Response {
|
|||
}
|
||||
|
||||
#[cfg(feature="serve_dir")]
|
||||
#[doc(cfg(feature = "serve_dir"))]
|
||||
pub async fn serve_dir<D: AsRef<Path>, P: AsRef<Path>>(dir: D, virtual_path: &[P]) -> Response {
|
||||
debug!("Dir: {}", dir.as_ref().display());
|
||||
let dir = dir.as_ref();
|
||||
|
@ -129,6 +131,7 @@ async fn serve_dir_listing<P: AsRef<Path>, B: AsRef<Path>>(path: P, virtual_path
|
|||
}
|
||||
|
||||
#[cfg(feature="serve_dir")]
|
||||
#[doc(cfg(feature = "serve_dir"))]
|
||||
pub fn guess_mime_from_path<P: AsRef<Path>>(path: P) -> &'static str {
|
||||
let path = path.as_ref();
|
||||
let extension = path.extension().and_then(|s| s.to_str());
|
||||
|
|
Loading…
Reference in New Issue