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