Add a whole bunch of comments to the examples

This commit is contained in:
Emi Tatsuo 2020-12-16 11:38:29 -05:00
parent 2ae721f131
commit 4911f8f2d9
Signed by: Emi
GPG Key ID: 68FAB2E2E6DFC98B
4 changed files with 75 additions and 12 deletions

View File

@ -4,17 +4,32 @@ use log::LevelFilter;
use kochab::{Request, Response, Server};
#[tokio::main]
/// This is a super quick demonstration of how you can check user certificates with kochab
///
/// The goal of this example is just to read the user's certificate and tell them their
/// certificate fingerprint, or if they aren't using a certificate, just tell them that
/// they didn't provide one.
///
/// You can of course require a certificate by sending a [`Response::client_certificate_required()`].
/// But, if you're interested in more advanced user management features, like letting
/// users create an account and persist data, you might want to check out the
/// user_management feature.
async fn main() -> Result<()> {
// We set up logging so we can see what's happening. This isn't technically required,
// and you can use a simpler solution (like env_logger::init()) during production
env_logger::builder()
.filter_module("kochab", LevelFilter::Debug)
.init();
Server::new()
.add_route("/", handle_request)
.serve_ip("localhost:1965")
Server::new() // Create a new server
.add_route("/", handle_request) // Bind our handling function to the root path
.serve_ip("localhost:1965") // Start serving content on the default gemini port
.await
}
/// This is the actual handler that does most of the actual work.
/// It'll be called by the server when we receive a request
async fn handle_request(request: Request) -> Result<Response> {
if let Some(fingerprint) = request.fingerprint() {

View File

@ -5,18 +5,35 @@ use log::LevelFilter;
use kochab::{Server, Request, Response, Document};
#[tokio::main]
/// An ultra-simple ratelimiting example
///
/// We set up two pages:
/// * `/*` which can be accessed as much as the user wants
/// * /limit/*` which can only be accessed twice every 10 seconds
///
/// Once we tell it what needs to be ratelimited, kochab will automatically handle keeping
/// track of what users have and have not visited that page and how often. A very small
/// concurrent background task is in charge of cleaning the in-memory database every so
/// often so that a memory leak doesn't form.
async fn main() -> Result<()> {
// We set up logging so we can see what's happening. This isn't technically required,
// and you can use a simpler solution (like env_logger::init()) during production
env_logger::builder()
.filter_module("kochab", LevelFilter::Debug)
.init();
Server::new()
.add_route("/", handle_request)
.ratelimit("/limit", 2, Duration::from_secs(10))
.serve_ip("localhost:1965")
Server::new() // Create a server
.add_route("/", handle_request) // Create a page, content doesn't matter
.ratelimit("/limit", 2, Duration::from_secs(10)) // Set the ratelimit to 2 / 10s
.serve_ip("localhost:1965") // Start the server
.await
}
/// Render a simple page based on the current URL
///
/// The actual content of the response, and really anything in this section, doesn't
/// actually affect the ratelimit, but it's nice to have a usable demo, so we set up a
/// couple nice pages
async fn handle_request(request: Request) -> Result<Response> {
let mut document = Document::new();

View File

@ -3,16 +3,32 @@ use log::LevelFilter;
use kochab::{Document, document::HeadingLevel, Request, Response};
#[tokio::main]
/// A quick demo to show off how an app can have multiple handlers on diffrent routes
///
/// We set up three different routes:
/// * `/route/long/*`
/// * `/route/*`
/// * `/*` which matches any other route
///
/// Each route generates a slightly different page, although they all use the same layout
/// through the [`generate_doc()`] method. Each page states which route was matched, and
/// all the trailing path segments.
///
/// For example, a request to `/route/trail` would be matched by the short route
/// (`/route/*`) with the trailing path segment `["trail"]`
async fn main() -> Result<()> {
// We set up logging so we can see what's happening. This isn't technically required,
// and you can use a simpler solution (like env_logger::init()) during production
env_logger::builder()
.filter_module("kochab", LevelFilter::Debug)
.init();
kochab::Server::new()
.add_route("/", handle_base)
.add_route("/route", handle_short)
.add_route("/route/long", handle_long)
.serve_ip("localhost:1965")
kochab::Server::new() // Create a new server
.add_route("/", handle_base) // Register the base route (order irrelevant)
.add_route("/route", handle_short) // Reigster the short route
.add_route("/route/long", handle_long) // Register the long route
.serve_ip("localhost:1965") // Start the server
.await
}
@ -32,7 +48,11 @@ async fn handle_long(req: Request) -> Result<Response> {
}
fn generate_doc(route_name: &str, req: &Request) -> Document {
// Trailing segments comes in as a Vec of segments, so we join them together for
// display purposes
let trailing = req.trailing_segments().join("/");
let mut doc = Document::new();
doc.add_heading(HeadingLevel::H1, "Routing Demo")
.add_text(&format!("You're currently on the {} route", route_name))

View File

@ -5,7 +5,18 @@ use log::LevelFilter;
use kochab::Server;
#[tokio::main]
/// Serving some static content from the filesystem is easy with Kochab
///
/// This example serves from the `./public` directory on the base route, and adds a
/// special one-page bind to `/about` that always serves `README.md`
///
/// Note, use this module with a little bit of caution. The directory serving feature is
/// currently unfinished, and the API is subject to change dramatically in future updates.
/// It should be secure, but you may need to do some refactoring in coming updates.
async fn main() -> Result<()> {
// We set up logging so we can see what's happening. This isn't technically required,
// and you can use a simpler solution (like env_logger::init()) during production
env_logger::builder()
.filter_module("kochab", LevelFilter::Debug)
.init();