Started writing feature docs [UNFINISHED]

src/lib.rs

@@ -1,3 +1,67 @@
+//! Kochab is an ergonomic and intuitive library for quickly building highly functional
+//! and advanced Gemini applications on either SCGI or raw Gemini.
+//!
+//! Originally based on [northstar](https://crates.io/crates/northstar), though now far
+//! divereged, kochab offers many features to help you build your application without any
+//! of the boilerplate or counterintuitive shenanigans.  Kochab centers around it's many
+//! feature flags, which let you pick out exactly the features you need to build your
+//! library, while leaving out features you don't need to keep your application
+//! bloat-free.
+//!
+//! Another central feature of kochab is its multi-protocol abstraction.  An application
+//! built using kochab can easily compile either as a gemini application or as a SCGI
+//! script using only a single feature flag.
+//!
+//! ## Features
+//!
+//! Kochab offers a wide array of features, so don't get overwhelmed.  By default, you
+//! start off with only the `gemini_srv` feature, and you're able to add on more features
+//! as you need them.  All of kochab's features are documented below.
+//!
+//! * `ratelimiting` - The ratelimiting feature adds in the ability to limit how often
+//! users can access certain areas of an application.  This is primarily configured using
+//! the [`Server::ratelimit()`] method.
+//!
+//! * `servedir` - Adds in utilities for serving files & directories from the disk at
+//! runtime.  The easiest way to use this is to pass a [`PathBuf`] to the
+//! [`Server::add_route()`] method, which will either serve a directory or a single file.
+//! Files and directories can also be served using the methods in the [`util`] module.
+//!
+//! * `user_management` - Adds in tools to manage users using a certificate authentication
+//! system.  The user management suite is one of kocab's biggest features.  When active,
+//! kochab will maintain a database of registered users, linking each to a certificate.
+//! Users also have custom data associated with them, which can be retrieved and modified
+//! by the application.
+//!
+//! * `user_management_advanced` - Allows users to set a password and add additional
+//! certificates.  Without this feature, one certificate can only have one linked account,
+//! unless you manually implement an authentication system.  With this feature, kochab
+//! will use argon2 to hash and check user passwords, and store user passwords alongside
+//! the other user data
+//!
+//! * `user_management_routes` - The user management routes feature automates much of the
+//! hard work of connecting the tools provided with the other two features with endpoints
+//! that the user connects to.  Kochab will manage all requests to the `/account` route,
+//! and create pages to allow users to create an account, link new certificates, or
+//! change/set their password.  This also adds the ability to set an authenticated route,
+//! which will automatically prompt the user to sign in, and give your handler access to
+//! the user's data with no added work.  This can be used with either the
+//! `user_management_advanced` feature, or just the basic `user_management` feature
+//!
+//! * `certgen` - Enables automatically generating TLS certificates.  Since only servers
+//! directly using the gemini protocol need TLS certificates, this implies `gemini_srv`,
+//! and should not be used with `scgi_srv`.  By default, kochab will try to generate a
+//! certificate by prompting the user in stdin/stdout, but this behavior can be customized
+//! using [`Server::set_certificate_generation_mode()`].
+//!
+//! * `dashmap` - Enables some minor optimizations within the `user_management_routes`
+//! feature.  Automatically enabled by `ratelimiting`.
+//!
+//! * `gemini_srv`/`scgi_srv` - Switches between serving content using SCGI and serving
+//! content as a raw gemini server.  One and only one of these features must be enabled,
+//! and compilation will fail if both are enabled.  See below for more information.
+
+
 #[macro_use] extern crate log;
 
 #[cfg(all(feature = "gemini_srv", feature = "scgi_srv"))]