Started writing feature docs [UNFINISHED]

This commit is contained in:
Emi Tatsuo 2020-12-03 00:53:05 -05:00
parent 73da764a8f
commit fa8adbd265
Signed by: Emi
GPG key ID: 68FAB2E2E6DFC98B

View file

@ -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"))]