From 78a434af998e299c90f82d193fc10f34e43958c5 Mon Sep 17 00:00:00 2001 From: Erik Hollensbe Date: Sat, 22 Jan 2022 11:50:39 -0800 Subject: [PATCH] Documented, ready for release almost Signed-off-by: Erik Hollensbe --- src/app.rs | 1 + src/handler.rs | 31 ++++++++++++++++++++++++++++++- src/lib.rs | 4 +++- src/macros.rs | 12 ++++++------ 4 files changed, 40 insertions(+), 8 deletions(-) diff --git a/src/app.rs b/src/app.rs index 222dc44..ddfc3da 100644 --- a/src/app.rs +++ b/src/app.rs @@ -47,6 +47,7 @@ use crate::{handler::Handler, router::Router, Error, ServerError}; /// Variadic path components are accessible through the [crate::Params] implementation. Paths are /// typically used through [crate::app::App] methods that use a string form of the Path. /// +/// Requests are routed through paths to [crate::handler::HandlerFunc]s. #[derive(Clone)] pub struct App { router: Router, diff --git a/src/handler.rs b/src/handler.rs index 92ebe36..bde4a8f 100644 --- a/src/handler.rs +++ b/src/handler.rs @@ -7,7 +7,29 @@ use http::{Request, Response}; use hyper::Body; /// HandlerFunc is the type signature of all handlers. All handlers must conform to this pattern to -/// be used with `compose_handler!`. +/// be used with [crate::compose_handler!]. +/// +/// Example: +/// +/// ``` +/// use ratpack::prelude::*; +/// +/// async fn hello( +/// req: Request, +/// _resp: Option>, +/// params: Params, +/// _app: App<()>, +/// ) -> HTTPResult { +/// let name = params.get("name").unwrap(); +/// let bytes = Body::from(format!("hello, {}!\n", name)); +/// +/// return Ok(( +/// req, +/// Some(Response::builder().status(200).body(bytes).unwrap()), +/// )); +/// } +/// ``` +/// pub type HandlerFunc = fn( req: Request, response: Option>, @@ -15,6 +37,10 @@ pub type HandlerFunc = fn( app: App, ) -> PinBox + Send>; +/// Handler is the structure of the handler. Typically, you will not use this directly, and instead +/// interact with the [crate::compose_handler!] macro. That said, if you wanted to define your own +/// macros or otherwise compose more complicated structures for your handlers, this is available to +/// you. #[derive(Clone)] pub struct Handler { handler: HandlerFunc, @@ -26,6 +52,8 @@ where Self: Send, S: Clone + Send, { + /// Construct a new handler composed of a HandlerFunc with state, and an optional next handler + /// in the chain. pub fn new(handler: HandlerFunc, next: Option>) -> Self { Self { handler, @@ -33,6 +61,7 @@ where } } + /// Perform the function, this will recursively execute all handlers in the chain. #[async_recursion] pub async fn perform( &self, diff --git a/src/lib.rs b/src/lib.rs index 52e3687..9c8fc66 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -71,7 +71,9 @@ where /// HTTPResult is the return type for handlers. If a handler terminates at the end of its chain /// with [std::option::Option::None] as the [http::Response], a 500 Internal Server Error will be -/// returned. +/// returned. If you wish to return Err(), a [http::StatusCode] or [std::string::String] can be +/// returned, the former is resolved to its status with an empty body, and the latter corresponds +/// to a 500 Internal Server Error with the body set to the string. pub type HTTPResult = Result<(Request, Option>), Error>; /// A convenience import to gather all of `ratpack`'s dependencies in one easy place. diff --git a/src/macros.rs b/src/macros.rs index 22ad2a9..1f19c01 100644 --- a/src/macros.rs +++ b/src/macros.rs @@ -1,9 +1,9 @@ -/// compose_handler allows you to combine [crate::handler::HandlerFunc] functions into a single [crate::handler::Handler], so that -/// they cascade through a chain of responsibility. This means that each handler will feed its -/// output into the input of the next. To start, the first [http::Response] is -/// [std::option::Option::None], and the final return Response must be non-None otherwise a 500 -/// Internal Server Error is returned. Handlers may do anything they wish to the [http::Request] between -/// processing periods, including replacing the request entirely. +/// compose_handler allows you to combine multiple [crate::handler::HandlerFunc] functions into a +/// single [crate::handler::Handler], so that they cascade through a chain of responsibility. This +/// means that each handler will feed its output into the input of the next. To start, the first +/// [http::Response] is [std::option::Option::None], and the final return Response must be +/// non-None; otherwise a 500 Internal Server Error is returned. Handlers may do anything they wish +/// to the [http::Request] between processing periods, including replacing the request entirely. #[macro_export] macro_rules! compose_handler { ($( $x:path ),*) => {