splorm documentation

1 files changed, 45 insertions, 4 deletions

diff --git a/splorm/src/handler/mod.rs b/splorm/src/handler/mod.rs
index 00ef78f..bac5c5c 100644
--- a/splorm/src/handler/mod.rs
+++ b/splorm/src/handler/mod.rs
@@ -1,3 +1,15 @@
+//! Route handlers
+//!
+//! All route handlers live here.
+//!
+//! | Handler | Route |
+//! | - | - |
+//! | [`index`] | GET `/` |
+//! | [`static_path`] | GET `/{*path}` |
+//! | | |
+//! | [`api`] | Nested under `/api` |
+//! | [`quark`] | Nested under `/quark` |
+
 use std::sync::Arc;
 
 use axum::{
@@ -17,8 +29,18 @@ mod templated;
 
 use crate::{RuntimeError, config::Settings, fs::RequestPath, state::SplormState};
 
-/// Log runtime errors using a middleware layer. Very much based on the [axum
-/// error_handling example][axum_errorhandling]
+/// `Result<AxumResponse, RuntimeError>`
+///
+/// Convenience type for use in routes return types.
+/// See [Axum's `Response`][response-axum], [`RuntimeError`]
+///
+/// [response-axum]: https://docs.rs/axum/latest/axum/response/type.Response.html
+type FallibleResponse = Result<axum::response::Response, crate::RuntimeError>;
+
+/// log runtime errors using a middleware layer.
+///
+/// Very much based on the [axum error_handling example][axum_errorhandling]
+///
 /// [axum_errorhandling]: https://github.com/tokio-rs/axum/blob/3696bfe5f1c30ee57f39dfb992b01bbf57bf2c1f/examples/error-handling/src/main.rs
 pub async fn log_errors(mut request: Request, next: Next) -> Response {
 	let ctx = request.extract_parts::<RequestContext>().await;
@@ -34,17 +56,33 @@ pub async fn log_errors(mut request: Request, next: Next) -> Response {
 }
 
 /// GET /
+///
+/// Assumes the index is a template called "home.html" in the webroot.
+/// Internally uses [`templated::send_file()`]
 pub async fn index(
 	State(state): State<SplormState>,
 	Extension(settings): Extension<Settings>,
 	ctx: RequestContext,
-) -> Result<Response, RuntimeError> {
+) -> FallibleResponse {
 	tracing::info!("{ctx} GET /");
 	let rqp = RequestPath::verify_safe(settings.root(), "home.html")?;
 	templated::send_file(rqp, state, &settings).await
 }
 
 /// GET /{*path}
+///
+/// Routes not caught by handlers. Tries to read the path from the filesystem,
+/// using the [`Mime`] to determine how to treat the file.
+///
+/// If the path, after made-safe with [`RequestPath::verify_safe()`] points
+/// to a directory, but does not end in a slash, sends a permanent redirect
+/// to `{path}/`
+///
+/// **[`Mime`] of `"text/html"`**
+/// Assumes the path is a template, and tries to send it with [`templated::send_file()`]
+///
+/// **Otherwise**
+/// Attempts to send the file using [`staticfile::send_or_stream_file()`]
 pub async fn static_path(
 	State(state): State<SplormState>,
 	Extension(settings): Extension<Settings>,
@@ -66,14 +104,16 @@ pub async fn static_path(
 	}
 }
 
+/// Creates a response for 308 Permanent Redirect
 async fn permanent_redirect(path: String) -> Result<Response, RuntimeError> {
 	Response::builder()
-		.status(301)
+		.status(StatusCode::PERMANENT_REDIRECT)
 		.header("Location", path)
 		.body(Body::from("redirecting..."))
 		.map_err(|_| RuntimeError::Unknown)
 }
 
+/// Creates a response for 307 Temporary Redirect
 async fn temporary_redirect(path: String) -> Result<Response, RuntimeError> {
 	Response::builder()
 		.status(StatusCode::TEMPORARY_REDIRECT)
@@ -82,6 +122,7 @@ async fn temporary_redirect(path: String) -> Result<Response, RuntimeError> {
 		.map_err(|_| RuntimeError::Unknown)
 }
 
+/// Creates a response for 303 See Other
 async fn see_other(path: String) -> Result<Response, RuntimeError> {
 	Response::builder()
 		.status(StatusCode::SEE_OTHER)